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