← Back to branch summary

~ubuntu-branches/ubuntu/trusty/gnutls26/trusty

« back to all changes in this revision

Viewing changes to doc/cha-functions.texi

  • Committer: Package Import Robot
  • Author(s): Andreas Metzler
  • Date: 2011-10-01 15:28:13 UTC
  • mfrom: (12.1.20 sid)
  • Revision ID: package-import@ubuntu.com-20111001152813-yygm1c4cxonfxhzy
http://bugs.debian.org/640639
* New upstream version.
  + Allow CA importing of 0 certificates to succeed. Closes: #640639
* Add libp11-kit-dev to libgnutls-dev dependencies. (see #643811)
* [20_guiledocstring.diff] guile: Fix docstring extraction with CPP 4.5+.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/cha-functions.texi
 
1
@node Function reference
 
2
@chapter Function Reference
 
3
@cindex Function reference
 
4
 
 
5
@menu
 
6
* Core functions::
 
7
* X.509 certificate functions::
 
8
* GnuTLS-extra functions::
 
9
* OpenPGP functions::
 
10
* TLS Inner Application (TLS/IA) functions::
 
11
* Error codes and descriptions::
 
12
@end menu
 
13
 
 
14
@node Core functions
 
15
@section Core Functions
 
16
 
 
17
The prototypes for the following functions lie in
 
18
@file{gnutls/gnutls.h}.
 
19
 
 
20
@include gnutls-api.texi
 
21
 
 
22
@node X.509 certificate functions
 
23
@section @acronym{X.509} Certificate Functions
 
24
@anchor{sec:x509api}
 
25
@cindex @acronym{X.509} Functions
 
26
 
 
27
The following functions are to be used for @acronym{X.509} certificate handling.
 
28
Their prototypes lie in @file{gnutls/x509.h}.
 
29
 
 
30
@include x509-api.texi
 
31
 
 
32
@node GnuTLS-extra functions
 
33
@section @acronym{GnuTLS-extra} Functions
 
34
@cindex @acronym{GnuTLS-extra} functions
 
35
 
 
36
These functions are only available in the GPLv3+ version of the
 
37
library called @code{gnutls-extra}. The prototypes for this library
 
38
lie in @file{gnutls/extra.h}.
 
39
 
 
40
@include extra-api.texi
 
41
 
 
42
@node OpenPGP functions
 
43
@section @acronym{OpenPGP} Functions
 
44
@cindex @acronym{OpenPGP} functions
 
45
@anchor{sec:openpgpapi}
 
46
 
 
47
The following functions are to be used for @acronym{OpenPGP}
 
48
certificate handling.  Their prototypes lie in
 
49
@file{gnutls/openpgp.h}.
 
50
 
 
51
@include pgp-api.texi
 
52
 
 
53
@node TLS Inner Application (TLS/IA) functions
 
54
@section @acronym{TLS} Inner Application (@acronym{TLS/IA}) Functions
 
55
@cindex @acronym{TLS} Inner Application (@acronym{TLS/IA}) functions
 
56
@cindex Inner Application (@acronym{TLS/IA}) functions
 
57
 
 
58
The following functions are used for @acronym{TLS} Inner Application
 
59
(@acronym{TLS/IA}).  Their prototypes lie in @file{gnutls/extra.h}.
 
60
You need to link with @file{libgnutls-extra} to be able to use these
 
61
functions (@pxref{GnuTLS-extra functions}).
 
62
 
 
63
The typical control flow in an TLS/IA client (that would not require
 
64
an Application Phase for resumed sessions) would be similar to the
 
65
following:
 
66
 
 
67
@example
 
68
int client_avp (gnuls_session_t *session, void *ptr,
 
69
                const char *last, size_t lastlen,
 
70
                char **new, size_t *newlen)
 
71
@{
 
72
...
 
73
@}
 
74
...
 
75
int main ()
 
76
@{
 
77
  gnutls_ia_client_credentials_t iacred;
 
78
...
 
79
  gnutls_init (&session, GNUTLS_CLIENT);
 
80
...
 
81
  /* Enable TLS/IA. */
 
82
  gnutls_ia_allocate_client_credentials(&iacred);
 
83
  gnutls_ia_set_client_avp_function(iacred, client_avp);
 
84
  gnutls_credentials_set (session, GNUTLS_CRD_IA, iacred);
 
85
...
 
86
  ret = gnutls_handshake (session);
 
87
  // Error handling...
 
88
...
 
89
  if (gnutls_ia_handshake_p (session))
 
90
    @{
 
91
      ret = gnutls_ia_handshake (session);
 
92
      // Error handling...
 
93
...
 
94
@end example
 
95
 
 
96
See below for detailed descriptions of all the functions used above.
 
97
 
 
98
The function @code{client_avp} would have to be implemented by your
 
99
application.  The function is responsible for handling the AVP data.
 
100
See @code{gnutls_ia_set_client_avp_function} below for more
 
101
information on how that function should be implemented.
 
102
 
 
103
The control flow in a typical server is similar to the above, use
 
104
@code{gnutls_ia_server_credentials_t} instead of
 
105
@code{gnutls_ia_client_credentials_t}, and replace the call to the
 
106
client functions with the corresponding server functions.
 
107
 
 
108
@include ia-api.texi
 
109
 
 
110
@node Error codes and descriptions
 
111
@section Error Codes and Descriptions
 
112
@anchor{Error Codes}
 
113
@cindex Error codes
 
114
 
 
115
The error codes used throughout the library are described below.  The
 
116
return code @code{GNUTLS_E_SUCCESS} indicate successful operation, and
 
117
is guaranteed to have the value 0, so you can use it in logical
 
118
expressions.
 
119
 
 
120
@include error_codes.texi