Adding upstream version 3.7.9.upstream/3.7.9upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 7184 insertions, 0 deletions

diff --git a/doc/gnutls.info-2 b/doc/gnutls.info-2
new file mode 100644
index 0000000..65ff97b
--- /dev/null
+++ b/doc/gnutls.info-2
@@ -0,0 +1,7184 @@
+This is gnutls.info, produced by makeinfo version 6.8 from gnutls.texi.
+
+This manual is last updated 9 February 2023 for version 3.7.9 of GnuTLS.
+
+Copyright (C) 2001-2023 Free Software Foundation, Inc.\\ Copyright (C)
+2001-2023 Nikos Mavrogiannopoulos
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU Free Documentation License,
+     Version 1.3 or any later version published by the Free Software
+     Foundation; with no Invariant Sections, no Front-Cover Texts, and
+     no Back-Cover Texts.  A copy of the license is included in the
+     section entitled "GNU Free Documentation License".
+INFO-DIR-SECTION Software libraries
+START-INFO-DIR-ENTRY
+* GnuTLS: (gnutls).		GNU Transport Layer Security Library.
+END-INFO-DIR-ENTRY
+
+INFO-DIR-SECTION System Administration
+START-INFO-DIR-ENTRY
+* certtool: (gnutls)certtool Invocation.	Manipulate certificates and keys.
+* gnutls-serv: (gnutls)gnutls-serv Invocation.	GnuTLS test server.
+* gnutls-cli: (gnutls)gnutls-cli Invocation.	GnuTLS test client.
+* gnutls-cli-debug: (gnutls)gnutls-cli-debug Invocation.	GnuTLS debug client.
+* psktool: (gnutls)psktool Invocation.	Simple TLS-Pre-Shared-Keys manager.
+* srptool: (gnutls)srptool Invocation.	Simple SRP password tool.
+END-INFO-DIR-ENTRY
+
+
+File: gnutls.info,  Node: Trusted Platform Module,  Prev: Smart cards and HSMs,  Up: Hardware security modules and abstract key types
+
+5.4 Trusted Platform Module (TPM)
+=================================
+
+In this section we present the Trusted Platform Module (TPM) support in
+GnuTLS.  Note that we recommend against using TPM with this API because
+it is restricted to TPM 1.2.  We recommend instead to use PKCS#11
+wrappers for TPM such as CHAPS(1) or opencryptoki(2).  These will allow
+using the standard smart card and HSM functionality (see *note Smart
+cards and HSMs::) for TPM keys.
+
+There was a big hype when the TPM chip was introduced into computers.
+Briefly it is a co-processor in your PC that allows it to perform
+calculations independently of the main processor.  This has good and bad
+side-effects.  In this section we focus on the good ones; these are the
+fact that you can use the TPM chip to perform cryptographic operations
+on keys stored in it, without accessing them.  That is very similar to
+the operation of a PKCS #11 smart card.  The chip allows for storage and
+usage of RSA keys, but has quite some operational differences from PKCS
+#11 module, and thus require different handling.  The basic TPM
+operations supported and used by GnuTLS, are key generation and signing.
+That support is currently limited to TPM 1.2.
+
+The next sections assume that the TPM chip in the system is already
+initialized and in a operational state.  If not, ensure that the TPM
+chip is enabled by your BIOS, that the 'tcsd' daemon is running, and
+that TPM ownership is set (by running 'tpm_takeownership').
+
+In GnuTLS the TPM functionality is available in 'gnutls/tpm.h'.
+
+* Menu:
+
+* Keys in TPM::
+* Key generation::
+* Using keys::
+* tpmtool Invocation::
+
+   ---------- Footnotes ----------
+
+   (1) <https://github.com/google/chaps-linux>
+
+   (2) <https://sourceforge.net/projects/opencryptoki/>
+
+
+File: gnutls.info,  Node: Keys in TPM,  Next: Key generation,  Up: Trusted Platform Module
+
+5.4.1 Keys in TPM
+-----------------
+
+The RSA keys in the TPM module may either be stored in a flash memory
+within TPM or stored in a file in disk.  In the former case the key can
+provide operations as with PKCS #11 and is identified by a URL. The URL
+is described in [*note TPMURI::] and is of the following form.
+tpmkey:uuid=42309df8-d101-11e1-a89a-97bb33c23ad1;storage=user
+
+It consists from a unique identifier of the key as well as the part of
+the flash memory the key is stored at.  The two options for the storage
+field are 'user' and 'system'.  The user keys are typically only
+available to the generating user and the system keys to all users.  The
+stored in TPM keys are called registered keys.
+
+The keys that are stored in the disk are exported from the TPM but in an
+encrypted form.  To access them two passwords are required.  The first
+is the TPM Storage Root Key (SRK), and the other is a key-specific
+password.  Also those keys are identified by a URL of the form:
+tpmkey:file=/path/to/file
+
+When objects require a PIN to be accessed the same callbacks as with
+PKCS #11 objects are expected (see *note Accessing objects that require
+a PIN::).  Note that the PIN function may be called multiple times to
+unlock the SRK and the specific key in use.  The label in the key
+function will then be set to 'SRK' when unlocking the SRK key, or to
+'TPM' when unlocking any other key.
+
+
+File: gnutls.info,  Node: Key generation,  Next: Using keys,  Prev: Keys in TPM,  Up: Trusted Platform Module
+
+5.4.2 Key generation
+--------------------
+
+All keys used by the TPM must be generated by the TPM. This can be done
+using *note gnutls_tpm_privkey_generate::.
+
+ -- Function: int gnutls_tpm_privkey_generate (gnutls_pk_algorithm_t PK,
+          unsigned int BITS, const char * SRK_PASSWORD, const char *
+          KEY_PASSWORD, gnutls_tpmkey_fmt_t FORMAT,
+          gnutls_x509_crt_fmt_t PUB_FORMAT, gnutls_datum_t * PRIVKEY,
+          gnutls_datum_t * PUBKEY, unsigned int FLAGS)
+     PK: the public key algorithm
+
+     BITS: the security bits
+
+     SRK_PASSWORD: a password to protect the exported key (optional)
+
+     KEY_PASSWORD: the password for the TPM (optional)
+
+     FORMAT: the format of the private key
+
+     PUB_FORMAT: the format of the public key
+
+     PRIVKEY: the generated key
+
+     PUBKEY: the corresponding public key (may be null)
+
+     FLAGS: should be a list of GNUTLS_TPM_* flags
+
+     This function will generate a private key in the TPM chip.  The
+     private key will be generated within the chip and will be exported
+     in a wrapped with TPM's master key form.  Furthermore the wrapped
+     key can be protected with the provided 'password' .
+
+     Note that bits in TPM is quantized value.  If the input value is
+     not one of the allowed values, then it will be quantized to one of
+     512, 1024, 2048, 4096, 8192 and 16384.
+
+     Allowed flags are:
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise a negative error value.
+
+     *Since:* 3.1.0
+
+'INT *note gnutls_tpm_get_registered:: (gnutls_tpm_key_list_t * LIST)'
+'VOID *note gnutls_tpm_key_list_deinit:: (gnutls_tpm_key_list_t LIST)'
+'INT *note gnutls_tpm_key_list_get_url:: (gnutls_tpm_key_list_t LIST, unsigned int IDX, char ** URL, unsigned int FLAGS)'
+
+ -- Function: int gnutls_tpm_privkey_delete (const char * URL, const
+          char * SRK_PASSWORD)
+     URL: the URL describing the key
+
+     SRK_PASSWORD: a password for the SRK key
+
+     This function will unregister the private key from the TPM chip.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise a negative error value.
+
+     *Since:* 3.1.0
+
+
+File: gnutls.info,  Node: Using keys,  Next: tpmtool Invocation,  Prev: Key generation,  Up: Trusted Platform Module
+
+5.4.3 Using keys
+----------------
+
+Importing keys
+..............
+
+The TPM keys can be used directly by the abstract key types and do not
+require any special structures.  Moreover functions like *note
+gnutls_certificate_set_x509_key_file2:: can access TPM URLs.
+
+'INT *note gnutls_privkey_import_tpm_raw:: (gnutls_privkey_t PKEY, const gnutls_datum_t * FDATA, gnutls_tpmkey_fmt_t FORMAT, const char * SRK_PASSWORD, const char * KEY_PASSWORD, unsigned int FLAGS)'
+'INT *note gnutls_pubkey_import_tpm_raw:: (gnutls_pubkey_t PKEY, const gnutls_datum_t * FDATA, gnutls_tpmkey_fmt_t FORMAT, const char * SRK_PASSWORD, unsigned int FLAGS)'
+
+ -- Function: int gnutls_privkey_import_tpm_url (gnutls_privkey_t PKEY,
+          const char * URL, const char * SRK_PASSWORD, const char *
+          KEY_PASSWORD, unsigned int FLAGS)
+     PKEY: The private key
+
+     URL: The URL of the TPM key to be imported
+
+     SRK_PASSWORD: The password for the SRK key (optional)
+
+     KEY_PASSWORD: A password for the key (optional)
+
+     FLAGS: One of the GNUTLS_PRIVKEY_* flags
+
+     This function will import the given private key to the abstract
+     'gnutls_privkey_t' type.
+
+     Note that unless 'GNUTLS_PRIVKEY_DISABLE_CALLBACKS' is specified,
+     if incorrect (or NULL) passwords are given the PKCS11 callback
+     functions will be used to obtain the correct passwords.  Otherwise
+     if the SRK password is wrong 'GNUTLS_E_TPM_SRK_PASSWORD_ERROR' is
+     returned and if the key password is wrong or not provided then
+     'GNUTLS_E_TPM_KEY_PASSWORD_ERROR' is returned.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise a negative error value.
+
+     *Since:* 3.1.0
+
+ -- Function: int gnutls_pubkey_import_tpm_url (gnutls_pubkey_t PKEY,
+          const char * URL, const char * SRK_PASSWORD, unsigned int
+          FLAGS)
+     PKEY: The public key
+
+     URL: The URL of the TPM key to be imported
+
+     SRK_PASSWORD: The password for the SRK key (optional)
+
+     FLAGS: should be zero
+
+     This function will import the given private key to the abstract
+     'gnutls_privkey_t' type.
+
+     Note that unless 'GNUTLS_PUBKEY_DISABLE_CALLBACKS' is specified, if
+     incorrect (or NULL) passwords are given the PKCS11 callback
+     functions will be used to obtain the correct passwords.  Otherwise
+     if the SRK password is wrong 'GNUTLS_E_TPM_SRK_PASSWORD_ERROR' is
+     returned.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise a negative error value.
+
+     *Since:* 3.1.0
+
+Listing and deleting keys
+.........................
+
+The registered keys (that are stored in the TPM) can be listed using one
+of the following functions.  Those keys are unfortunately only
+identified by their UUID and have no label or other human friendly
+identifier.  Keys can be deleted from permanent storage using *note
+gnutls_tpm_privkey_delete::.
+
+'INT *note gnutls_tpm_get_registered:: (gnutls_tpm_key_list_t * LIST)'
+'VOID *note gnutls_tpm_key_list_deinit:: (gnutls_tpm_key_list_t LIST)'
+'INT *note gnutls_tpm_key_list_get_url:: (gnutls_tpm_key_list_t LIST, unsigned int IDX, char ** URL, unsigned int FLAGS)'
+
+ -- Function: int gnutls_tpm_privkey_delete (const char * URL, const
+          char * SRK_PASSWORD)
+     URL: the URL describing the key
+
+     SRK_PASSWORD: a password for the SRK key
+
+     This function will unregister the private key from the TPM chip.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise a negative error value.
+
+     *Since:* 3.1.0
+
+
+File: gnutls.info,  Node: tpmtool Invocation,  Prev: Using keys,  Up: Trusted Platform Module
+
+5.4.4 Invoking tpmtool
+----------------------
+
+Program that allows handling cryptographic data from the TPM chip.
+
+tpmtool help/usage ('-?')
+.........................
+
+The text printed is the same whether selected with the 'help' option
+('--help') or the 'more-help' option ('--more-help').  'more-help' will
+print the usage text by passing it through a pager program.  'more-help'
+is disabled on platforms without a working 'fork(2)' function.  The
+'PAGER' environment variable is used to select the program, defaulting
+to 'more'.  Both will exit with a status code of 0.
+
+     tpmtool - GnuTLS TPM tool
+     Usage:  tpmtool [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
+
+     None:
+
+        -d, --debug=num            Enable debugging
+     				- it must be in the range:
+     				  0 to 9999
+            --infile=file          Input file
+     				- file must pre-exist
+            --outfile=str          Output file
+            --generate-rsa         Generate an RSA private-public key pair
+            --register             Any generated key will be registered in the TPM
+     				- requires the option 'generate-rsa'
+            --signing              Any generated key will be a signing key
+     				- prohibits the option 'legacy'
+     				- requires the option 'generate-rsa'
+            --legacy               Any generated key will be a legacy key
+     				- prohibits the option 'signing'
+     				- requires the option 'generate-rsa'
+            --user                 Any registered key will be a user key
+     				- prohibits the option 'system'
+     				- requires the option 'register'
+            --system               Any registered key will be a system key
+     				- prohibits the option 'user'
+     				- requires the option 'register'
+            --pubkey=str           Prints the public key of the provided key
+            --list                 Lists all stored keys in the TPM
+            --delete=str           Delete the key identified by the given URL (UUID)
+            --test-sign=str        Tests the signature operation of the provided object
+            --sec-param=str        Specify the security level [low, legacy, medium, high, ultra]
+            --bits=num             Specify the number of bits for key generate
+            --inder                Use the DER format for keys
+            --outder               Use DER format for output keys
+            --srk-well-known       SRK has well known password (20 bytes of zeros)
+
+     Version, usage and configuration options:
+
+        -v, --version[=arg]        output version information and exit
+        -h, --help                 display extended usage information and exit
+        -!, --more-help            extended usage information passed thru pager
+
+     Options are specified by doubled hyphens and their name or by a single
+     hyphen and the flag character.
+
+     Program that allows handling cryptographic data from the TPM chip.
+
+     Please send bug reports to:  <bugs@gnutls.org>
+
+
+debug option (-d).
+..................
+
+This is the "enable debugging" option.  This option takes a
+ArgumentType.NUMBER argument.  Specifies the debug level.
+
+generate-rsa option.
+....................
+
+This is the "generate an rsa private-public key pair" option.  Generates
+an RSA private-public key pair in the TPM chip.  The key may be stored
+in file system and protected by a PIN, or stored (registered) in the TPM
+chip flash.
+
+user option.
+............
+
+This is the "any registered key will be a user key" option.
+
+This option has some usage constraints.  It:
+   * must not appear in combination with any of the following options:
+     system.
+   * must appear in combination with the following options: register.
+
+The generated key will be stored in a user specific persistent storage.
+
+system option.
+..............
+
+This is the "any registered key will be a system key" option.
+
+This option has some usage constraints.  It:
+   * must not appear in combination with any of the following options:
+     user.
+   * must appear in combination with the following options: register.
+
+The generated key will be stored in system persistent storage.
+
+test-sign option.
+.................
+
+This is the "tests the signature operation of the provided object"
+option.  This option takes a ArgumentType.STRING argument 'url'.  It can
+be used to test the correct operation of the signature operation.  This
+operation will sign and verify the signed data.
+
+sec-param option.
+.................
+
+This is the "specify the security level [low, legacy, medium, high,
+ultra]" option.  This option takes a ArgumentType.STRING argument
+'Security parameter'.  This is alternative to the bits option.  Note
+however that the values allowed by the TPM chip are quantized and given
+values may be rounded up.
+
+inder option.
+.............
+
+This is the "use the der format for keys" option.  The input files will
+be assumed to be in the portable DER format of TPM. The default format
+is a custom format used by various TPM tools
+
+outder option.
+..............
+
+This is the "use der format for output keys" option.  The output will be
+in the TPM portable DER format.
+
+version option (-v).
+....................
+
+This is the "output version information and exit" option.  This option
+takes a ArgumentType.KEYWORD argument.  Output version of program and
+exit.  The default mode is 'v', a simple version.  The 'c' mode will
+print copyright information and 'n' will print the full copyright
+notice.
+
+help option (-h).
+.................
+
+This is the "display extended usage information and exit" option.
+Display usage information and exit.
+
+more-help option (-!).
+......................
+
+This is the "extended usage information passed thru pager" option.  Pass
+the extended usage information through a pager.
+
+tpmtool exit status
+...................
+
+One of the following exit values will be returned:
+'0 (EXIT_SUCCESS)'
+     Successful program execution.
+'1 (EXIT_FAILURE)'
+     The operation failed or the command syntax was not valid.
+
+tpmtool See Also
+................
+
+p11tool (1), certtool (1)
+
+tpmtool Examples
+................
+
+To generate a key that is to be stored in file system use:
+     $ tpmtool --generate-rsa --bits 2048 --outfile tpmkey.pem
+
+To generate a key that is to be stored in TPM's flash use:
+     $ tpmtool --generate-rsa --bits 2048 --register --user
+
+To get the public key of a TPM key use:
+     $ tpmtool --pubkey tpmkey:uuid=58ad734b-bde6-45c7-89d8-756a55ad1891;storage=user \
+               --outfile pubkey.pem
+
+or if the key is stored in the file system:
+     $ tpmtool --pubkey tpmkey:file=tmpkey.pem --outfile pubkey.pem
+
+To list all keys stored in TPM use:
+     $ tpmtool --list
+
+
+File: gnutls.info,  Node: How to use GnuTLS in applications,  Next: GnuTLS application examples,  Prev: Hardware security modules and abstract key types,  Up: Top
+
+6 How to use GnuTLS in applications
+***********************************
+
+* Menu:
+
+* Introduction to the library::
+* Preparation::
+* Session initialization::
+* Associating the credentials::
+* Setting up the transport layer::
+* TLS handshake::
+* Data transfer and termination::
+* Buffered data transfer::
+* Handling alerts::
+* Priority Strings::
+* Selecting cryptographic key sizes::
+* Advanced topics::
+
+
+File: gnutls.info,  Node: Introduction to the library,  Next: Preparation,  Up: How to use GnuTLS in applications
+
+6.1 Introduction
+================
+
+This chapter tries to explain the basic functionality of the current
+GnuTLS library.  Note that there may be additional functionality not
+discussed here but included in the library.  Checking the header files
+in '/usr/include/gnutls/' and the manpages is recommended.
+
+* Menu:
+
+* General idea::
+* Error handling::
+* Common types::
+* Debugging and auditing::
+* Thread safety::
+* Running in a sandbox::
+* Sessions and fork::
+* Callback functions::
+
+
+File: gnutls.info,  Node: General idea,  Next: Error handling,  Up: Introduction to the library
+
+6.1.1 General idea
+------------------
+
+A brief description of how GnuTLS sessions operate is shown at *note
+Figure 6.1: fig-gnutls-design.  This section will become more clear when
+it is completely read.  As shown in the figure, there is a read-only
+global state that is initialized once by the global initialization
+function.  This global structure, among others, contains the memory
+allocation functions used, structures needed for the ASN.1 parser and
+depending on the system's CPU, pointers to hardware accelerated
+encryption functions.  This structure is never modified by any GnuTLS
+function, except for the deinitialization function which frees all
+allocated memory and must be called after the program has permanently
+finished using GnuTLS.
+
+
+
+
+
+Figure 6.1: High level design of GnuTLS.
+
+The credentials structures are used by the authentication methods, such
+as certificate authentication.  They store certificates, privates keys,
+and other information that is needed to prove the identity to the peer,
+and/or verify the identity of the peer.  The information stored in the
+credentials structures is initialized once and then can be shared by
+many TLS sessions.
+
+A GnuTLS session contains all the required state and information to
+handle one secure connection.  The session communicates with the peers
+using the provided functions of the transport layer.  Every session has
+a unique session ID shared with the peer.
+
+Since TLS sessions can be resumed, servers need a database back-end to
+hold the session's parameters.  Every GnuTLS session after a successful
+handshake calls the appropriate back-end function (see *note resume::)
+to store the newly negotiated session.  The session database is examined
+by the server just after having received the client hello(1), and if the
+session ID sent by the client, matches a stored session, the stored
+session will be retrieved, and the new session will be a resumed one,
+and will share the same session ID with the previous one.
+
+   ---------- Footnotes ----------
+
+   (1) The first message in a TLS handshake
+
+
+File: gnutls.info,  Node: Error handling,  Next: Common types,  Prev: General idea,  Up: Introduction to the library
+
+6.1.2 Error handling
+--------------------
+
+There two types of GnuTLS functions.  The first type returns a boolean
+value, true (non-zero) or false (zero) value; these functions are
+defined to return an unsigned integer type.  The other type returns a
+signed integer type with zero (or a positive number) indicating success
+and a negative value indicating failure.  For the latter type it is
+recommended to check for errors as following.
+         ret = gnutls_function();
+         if (ret < 0) {
+             return -1;
+         }
+The above example checks for a failure condition rather than for
+explicit success (e.g., equality to zero).  That has the advantage that
+future extensions of the API can be extended to provide additional
+information via positive returned values (see for example *note
+gnutls_certificate_set_x509_key_file::).
+
+For certain operations such as TLS handshake and TLS packet receive
+there is the notion of fatal and non-fatal error codes.  Fatal errors
+terminate the TLS session immediately and further sends and receives
+will be disallowed.  Such an example is 'GNUTLS_E_DECRYPTION_FAILED'.
+Non-fatal errors may warn about something, i.e., a warning alert was
+received, or indicate the some action has to be taken.  This is the case
+with the error code 'GNUTLS_E_REHANDSHAKE' returned by *note
+gnutls_record_recv::.  This error code indicates that the server
+requests a re-handshake.  The client may ignore this request, or may
+reply with an alert.  You can test if an error code is a fatal one by
+using the *note gnutls_error_is_fatal::.  All errors can be converted to
+a descriptive string using *note gnutls_strerror::.
+
+If any non fatal errors, that require an action, are to be returned by a
+function, these error codes will be documented in the function's
+reference.  For example the error codes
+'GNUTLS_E_WARNING_ALERT_RECEIVED' and 'GNUTLS_E_FATAL_ALERT_RECEIVED'
+that may returned when receiving data, should be handled by notifying
+the user of the alert (as explained in *note Handling alerts::).  See
+*note Error codes::, for a description of the available error codes.
+
+
+File: gnutls.info,  Node: Common types,  Next: Debugging and auditing,  Prev: Error handling,  Up: Introduction to the library
+
+6.1.3 Common types
+------------------
+
+All strings that are to provided as input to GnuTLS functions should be
+in UTF-8 unless otherwise specified.  Output strings are also in UTF-8
+format unless otherwise specified.  When functions take as input
+passwords, they will normalize them using [*note RFC7613::] rules (since
+GnuTLS 3.5.7).
+
+When data of a fixed size are provided to GnuTLS functions then the
+helper structure 'gnutls_datum_t' is often used.  Its definition is
+shown below.
+  typedef struct
+  {
+    unsigned char *data;
+    unsigned int size;
+  } gnutls_datum_t;
+
+In functions where this structure is a returned type, if the function
+succeeds, it is expected from the caller to use 'gnutls_free()' to
+deinitialize the data element after use, unless otherwise specified.  If
+the function fails, the contents of the 'gnutls_datum_t' should be
+considered undefined and must not be deinitialized.
+
+Other functions that require data for scattered read use a structure
+similar to 'struct iovec' typically used by 'readv'.  It is shown below.
+  typedef struct
+  {
+    void *iov_base;             /* Starting address */
+    size_t iov_len;             /* Number of bytes to transfer */
+  } giovec_t;
+
+
+File: gnutls.info,  Node: Debugging and auditing,  Next: Thread safety,  Prev: Common types,  Up: Introduction to the library
+
+6.1.4 Debugging and auditing
+----------------------------
+
+In many cases things may not go as expected and further information, to
+assist debugging, from GnuTLS is desired.  Those are the cases where the
+*note gnutls_global_set_log_level:: and *note
+gnutls_global_set_log_function:: are to be used.  Those will print
+verbose information on the GnuTLS functions internal flow.
+
+'VOID *note gnutls_global_set_log_level:: (int LEVEL)'
+'VOID *note gnutls_global_set_log_function:: (gnutls_log_func LOG_FUNC)'
+
+Alternatively the environment variable 'GNUTLS_DEBUG_LEVEL' can be set
+to a logging level and GnuTLS will output debugging output to standard
+error.  Other available environment variables are shown in *note Table
+6.1: tab:environment.
+
+Variable               Purpose
+                       
+--------------------------------------------------------------------------
+'GNUTLS_DEBUG_LEVEL'   When set to a numeric value, it sets the default
+                       debugging level for GnuTLS applications.
+                       
+'SSLKEYLOGFILE'        When set to a filename, GnuTLS will append to it
+                       the session keys in the NSS Key Log format.
+                       That format can be read by wireshark and will
+                       allow decryption of the session for debugging.
+                       
+'GNUTLS_CPUID_OVERRIDE'That environment variable can be used to
+                       explicitly enable/disable the use of certain CPU
+                       capabilities.  Note that CPU detection cannot be
+                       overridden, i.e., VIA options cannot be enabled
+                       on an Intel CPU. The currently available options
+                       are:
+                          * 0x1: Disable all run-time detected
+                            optimizations
+                          * 0x2: Enable AES-NI
+                          * 0x4: Enable SSSE3
+                          * 0x8: Enable PCLMUL
+                          * 0x10: Enable AVX
+                          * 0x20: Enable SHA_NI
+                          * 0x100000: Enable VIA padlock
+                          * 0x200000: Enable VIA PHE
+                          * 0x400000: Enable VIA PHE SHA512
+                       
+'GNUTLS_FORCE_FIPS_MODE'In setups where GnuTLS is compiled with support
+                       for FIPS140-2 (see *note FIPS140-2 mode::) if
+                       set to one it will force the FIPS mode
+                       enablement.
+                       
+
+
+Table 6.1: Environment variables used by the library.
+
+When debugging is not required, important issues, such as detected
+attacks on the protocol still need to be logged.  This is provided by
+the logging function set by *note
+gnutls_global_set_audit_log_function::.  The provided function will
+receive an message and the corresponding TLS session.  The session
+information might be used to derive IP addresses or other information
+about the peer involved.
+
+ -- Function: void gnutls_global_set_audit_log_function
+          (gnutls_audit_log_func LOG_FUNC)
+     LOG_FUNC: it is the audit log function
+
+     This is the function to set the audit logging function.  This is a
+     function to report important issues, such as possible attacks in
+     the protocol.  This is different from
+     'gnutls_global_set_log_function()' because it will report also
+     session-specific events.  The session parameter will be null if
+     there is no corresponding TLS session.
+
+     'gnutls_audit_log_func' is of the form, void
+     (*gnutls_audit_log_func)( gnutls_session_t, const char*);
+
+     *Since:* 3.0
+
+
+File: gnutls.info,  Node: Thread safety,  Next: Running in a sandbox,  Prev: Debugging and auditing,  Up: Introduction to the library
+
+6.1.5 Thread safety
+-------------------
+
+The GnuTLS library is thread safe by design, meaning that objects of the
+library such as TLS sessions, can be safely divided across threads as
+long as a single thread accesses a single object.  This is sufficient to
+support a server which handles several sessions per thread.  Read-only
+access to objects, for example the credentials holding structures, is
+also thread-safe.
+
+A 'gnutls_session_t' object could also be shared by two threads, one
+sending, the other receiving.  However, care must be taken on the
+following use cases:
+   * The re-handshake process in TLS 1.2 or earlier must be handled only
+     in a single thread and no other thread may be performing any
+     operation.
+   * The flag 'GNUTLS_AUTO_REAUTH' cannot be used safely in this mode of
+     operation.
+   * Any other operation which may send or receive data, like key update
+     (c.f., *note gnutls_session_key_update::), must not be performed
+     while threads are receiving or writing.
+   * The termination of a session should be handled, either by a single
+     thread being active, or by the sender thread using *note
+     gnutls_bye:: with 'GNUTLS_SHUT_WR' and the receiving thread waiting
+     for a return value of zero (or timeout on certain servers which do
+     not respond).
+   * The functions *note gnutls_transport_set_errno:: and *note
+     gnutls_record_get_direction:: should not be relied during parallel
+     operation.
+
+For several aspects of the library (e.g., the random generator, PKCS#11
+operations), the library may utilize mutex locks (e.g., pthreads on
+GNU/Linux and CriticalSection on Windows) which are transparently setup
+on library initialization.  Prior to version 3.3.0 these were setup by
+explicitly calling *note gnutls_global_init::.(1)
+
+Note that, on Glibc systems, unless the application is explicitly linked
+with the libpthread library, no mutex locks are used and setup by
+GnuTLS. It will use the Glibc mutex stubs.
+
+   ---------- Footnotes ----------
+
+   (1) On special systems you could manually specify the locking system
+using the function *note gnutls_global_set_mutex:: before calling any
+other GnuTLS function.  Setting mutexes manually is not recommended.
+
+
+File: gnutls.info,  Node: Running in a sandbox,  Next: Sessions and fork,  Prev: Thread safety,  Up: Introduction to the library
+
+6.1.6 Running in a sandbox
+--------------------------
+
+Given that TLS protocol handling as well as X.509 certificate parsing
+are complicated processes involving several thousands lines of code, it
+is often desirable (and recommended) to run the TLS session handling in
+a sandbox like seccomp.  That has to be allowed by the overall software
+design, but if available, it adds an additional layer of protection by
+preventing parsing errors from becoming vessels for further security
+issues such as code execution.
+
+GnuTLS requires the following system calls to be available for its
+proper operation.
+
+   * nanosleep
+   * time
+   * gettimeofday
+   * clock_gettime
+   * getrusage
+   * getpid
+   * send
+   * recv
+   * sendmsg
+   * read (to read from /dev/urandom)
+   * getrandom (this is Linux-kernel specific)
+   * poll
+
+As well as any calls needed for memory allocation to work.  Note
+however, that GnuTLS depends on libc for the system calls, and there is
+no guarantee that libc will call the expected system call.  For that it
+is recommended to test your program in all the targeted platforms when
+filters like seccomp are in place.
+
+An example with a seccomp filter from GnuTLS' test suite is at:
+<https://gitlab.com/gnutls/gnutls/blob/master/tests/seccomp.c>.
+
+
+File: gnutls.info,  Node: Sessions and fork,  Next: Callback functions,  Prev: Running in a sandbox,  Up: Introduction to the library
+
+6.1.7 Sessions and fork
+-----------------------
+
+A 'gnutls_session_t' object can be shared by two processes after a fork,
+one sending, the other receiving.  In that case rehandshakes, cannot and
+must not be performed.  As with threads, the termination of a session
+should be handled by the sender process using *note gnutls_bye:: with
+'GNUTLS_SHUT_WR' and the receiving process waiting for a return value of
+zero.
+
+
+File: gnutls.info,  Node: Callback functions,  Prev: Sessions and fork,  Up: Introduction to the library
+
+6.1.8 Callback functions
+------------------------
+
+There are several cases where GnuTLS may need out of band input from
+your program.  This is now implemented using some callback functions,
+which your program is expected to register.
+
+An example of this type of functions are the push and pull callbacks
+which are used to specify the functions that will retrieve and send data
+to the transport layer.
+
+'VOID *note gnutls_transport_set_push_function:: (gnutls_session_t SESSION, gnutls_push_func PUSH_FUNC)'
+'VOID *note gnutls_transport_set_pull_function:: (gnutls_session_t SESSION, gnutls_pull_func PULL_FUNC)'
+
+Other callback functions may require more complicated input and data to
+be allocated.  Such an example is *note
+gnutls_srp_set_server_credentials_function::.  All callbacks should
+allocate and free memory using 'gnutls_malloc' and 'gnutls_free'.
+
+
+File: gnutls.info,  Node: Preparation,  Next: Session initialization,  Prev: Introduction to the library,  Up: How to use GnuTLS in applications
+
+6.2 Preparation
+===============
+
+To use GnuTLS, you have to perform some changes to your sources and your
+build system.  The necessary changes are explained in the following
+subsections.
+
+* Menu:
+
+* Headers::
+* Initialization::
+* Version check::
+* Building the source::
+
+
+File: gnutls.info,  Node: Headers,  Next: Initialization,  Up: Preparation
+
+6.2.1 Headers
+-------------
+
+All the data types and functions of the GnuTLS library are defined in
+the header file 'gnutls/gnutls.h'.  This must be included in all
+programs that make use of the GnuTLS library.
+
+
+File: gnutls.info,  Node: Initialization,  Next: Version check,  Prev: Headers,  Up: Preparation
+
+6.2.2 Initialization
+--------------------
+
+The GnuTLS library is initialized on load; prior to 3.3.0 was
+initialized by calling *note gnutls_global_init::(1).  *note
+gnutls_global_init:: in versions after 3.3.0 is thread-safe (see *note
+Thread safety::).
+
+The initialization typically enables CPU-specific acceleration, performs
+any required precalculations needed, opens any required system devices
+(e.g., /dev/urandom on Linux) and initializes subsystems that could be
+used later.
+
+The resources allocated by the initialization process will be released
+on library deinitialization.
+
+Note that on certain systems file descriptors may be kept open by GnuTLS
+(e.g.  /dev/urandom) on library load.  Applications closing all unknown
+file descriptors must immediately call *note gnutls_global_init::, after
+that, to ensure they don't disrupt GnuTLS' operation.
+
+   ---------- Footnotes ----------
+
+   (1) The original behavior of requiring explicit initialization can
+obtained by setting the GNUTLS_NO_IMPLICIT_INIT environment variable to
+1, or by using the macro GNUTLS_SKIP_GLOBAL_INIT in a global section of
+your program -the latter works in systems with support for weak symbols
+only.
+
+
+File: gnutls.info,  Node: Version check,  Next: Building the source,  Prev: Initialization,  Up: Preparation
+
+6.2.3 Version check
+-------------------
+
+It is often desirable to check that the version of 'gnutls' used is
+indeed one which fits all requirements.  Even with binary compatibility
+new features may have been introduced but due to problem with the
+dynamic linker an old version is actually used.  So you may want to
+check that the version is okay right after program start-up.  See the
+function *note gnutls_check_version::.
+
+On the other hand, it is often desirable to support more than one
+versions of the library.  In that case you could utilize compile-time
+feature checks using the 'GNUTLS_VERSION_NUMBER' macro.  For example, to
+conditionally add code for GnuTLS 3.2.1 or later, you may use:
+     #if GNUTLS_VERSION_NUMBER >= 0x030201
+      ...
+     #endif
+
+
+File: gnutls.info,  Node: Building the source,  Prev: Version check,  Up: Preparation
+
+6.2.4 Building the source
+-------------------------
+
+If you want to compile a source file including the 'gnutls/gnutls.h'
+header file, you must make sure that the compiler can find it in the
+directory hierarchy.  This is accomplished by adding the path to the
+directory in which the header file is located to the compilers include
+file search path (via the '-I' option).
+
+However, the path to the include file is determined at the time the
+source is configured.  To solve this problem, the library uses the
+external package 'pkg-config' that knows the path to the include file
+and other configuration options.  The options that need to be added to
+the compiler invocation at compile time are output by the '--cflags'
+option to 'pkg-config gnutls'.  The following example shows how it can
+be used at the command line:
+
+     gcc -c foo.c `pkg-config gnutls --cflags`
+
+Adding the output of 'pkg-config gnutls --cflags' to the compilers
+command line will ensure that the compiler can find the
+'gnutls/gnutls.h' header file.
+
+A similar problem occurs when linking the program with the library.
+Again, the compiler has to find the library files.  For this to work,
+the path to the library files has to be added to the library search path
+(via the '-L' option).  For this, the option '--libs' to 'pkg-config
+gnutls' can be used.  For convenience, this option also outputs all
+other options that are required to link the program with the library
+(for instance, the '-ltasn1' option).  The example shows how to link
+'foo.o' with the library to a program 'foo'.
+
+     gcc -o foo foo.o `pkg-config gnutls --libs`
+
+Of course you can also combine both examples to a single command by
+specifying both options to 'pkg-config':
+
+     gcc -o foo foo.c `pkg-config gnutls --cflags --libs`
+
+When a program uses the GNU autoconf system, then the following line or
+similar can be used to detect the presence of GnuTLS.
+
+     PKG_CHECK_MODULES([LIBGNUTLS], [gnutls >= 3.3.0])
+
+     AC_SUBST([LIBGNUTLS_CFLAGS])
+     AC_SUBST([LIBGNUTLS_LIBS])
+
+
+File: gnutls.info,  Node: Session initialization,  Next: Associating the credentials,  Prev: Preparation,  Up: How to use GnuTLS in applications
+
+6.3 Session initialization
+==========================
+
+In the previous sections we have discussed the global initialization
+required for GnuTLS as well as the initialization required for each
+authentication method's credentials (see *note Authentication::).  In
+this section we elaborate on the TLS or DTLS session initiation.  Each
+session is initialized using *note gnutls_init:: which among others is
+used to specify the type of the connection (server or client), and the
+underlying protocol type, i.e., datagram (UDP) or reliable (TCP).
+
+ -- Function: int gnutls_init (gnutls_session_t * SESSION, unsigned int
+          FLAGS)
+     SESSION: is a pointer to a 'gnutls_session_t' type.
+
+     FLAGS: indicate if this session is to be used for server or client.
+
+     This function initializes the provided session.  Every session must
+     be initialized before use, and must be deinitialized after used by
+     calling 'gnutls_deinit()' .
+
+     'flags' can be any combination of flags from 'gnutls_init_flags_t'
+     .
+
+     Note that since version 3.1.2 this function enables some common TLS
+     extensions such as session tickets and OCSP certificate status
+     request in client side by default.  To prevent that use the
+     'GNUTLS_NO_EXTENSIONS' flag.
+
+     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
+
+'GNUTLS_SERVER'
+     Connection end is a server.
+'GNUTLS_CLIENT'
+     Connection end is a client.
+'GNUTLS_DATAGRAM'
+     Connection is datagram oriented (DTLS). Since 3.0.0.
+'GNUTLS_NONBLOCK'
+     Connection should not block.  Since 3.0.0.
+'GNUTLS_NO_EXTENSIONS'
+     Do not enable any TLS extensions by default (since 3.1.2).  As TLS
+     1.2 and later require extensions this option is considered obsolete
+     and should not be used.
+'GNUTLS_NO_REPLAY_PROTECTION'
+     Disable any replay protection in DTLS. This must only be used if
+     replay protection is achieved using other means.  Since 3.2.2.
+'GNUTLS_NO_SIGNAL'
+     In systems where SIGPIPE is delivered on send, it will be disabled.
+     That flag has effect in systems which support the MSG_NOSIGNAL
+     sockets flag (since 3.4.2).
+'GNUTLS_ALLOW_ID_CHANGE'
+     Allow the peer to replace its certificate, or change its ID during
+     a rehandshake.  This change is often used in attacks and thus
+     prohibited by default.  Since 3.5.0.
+'GNUTLS_ENABLE_FALSE_START'
+     Enable the TLS false start on client side if the negotiated
+     ciphersuites allow it.  This will enable sending data prior to the
+     handshake being complete, and may introduce a risk of crypto
+     failure when combined with certain key exchanged; for that GnuTLS
+     may not enable that option in ciphersuites that are known to be not
+     safe for false start.  Since 3.5.0.
+'GNUTLS_FORCE_CLIENT_CERT'
+     When in client side and only a single cert is specified, send that
+     certificate irrespective of the issuers expected by the server.
+     Since 3.5.0.
+'GNUTLS_NO_TICKETS'
+     Flag to indicate that the session should not use resumption with
+     session tickets.
+'GNUTLS_KEY_SHARE_TOP'
+     Generate key share for the first group which is enabled.  For
+     example x25519.  This option is the most performant for client
+     (less CPU spent generating keys), but if the server doesn't support
+     the advertized option it may result to more roundtrips needed to
+     discover the server's choice.
+'GNUTLS_KEY_SHARE_TOP2'
+     Generate key shares for the top-2 different groups which are
+     enabled.  For example (ECDH + x25519).  This is the default.
+'GNUTLS_KEY_SHARE_TOP3'
+     Generate key shares for the top-3 different groups which are
+     enabled.  That is, as each group is associated with a key type (EC,
+     finite field, x25519), generate three keys using 'GNUTLS_PK_DH' ,
+     'GNUTLS_PK_EC' , 'GNUTLS_PK_ECDH_X25519' if all of them are
+     enabled.
+'GNUTLS_POST_HANDSHAKE_AUTH'
+     Enable post handshake authentication for server and client.  When
+     set and a server requests authentication after handshake
+     'GNUTLS_E_REAUTH_REQUEST' will be returned by
+     'gnutls_record_recv()' .  A client should then call
+     'gnutls_reauth()' to re-authenticate.
+'GNUTLS_NO_AUTO_REKEY'
+     Disable auto-rekeying under TLS1.3.  If this option is not
+     specified gnutls will force a rekey after 2^24 records have been
+     sent.
+'GNUTLS_SAFE_PADDING_CHECK'
+     Flag to indicate that the TLS 1.3 padding check will be done in a
+     safe way which doesn't leak the pad size based on GnuTLS processing
+     time.  This is of use to applications which hide the length of
+     transferred data via the TLS1.3 padding mechanism and are already
+     taking steps to hide the data processing time.  This comes at a
+     performance penalty.
+'GNUTLS_ENABLE_EARLY_START'
+     Under TLS1.3 allow the server to return earlier than the full
+     handshake finish; similarly to false start the handshake will be
+     completed once data are received by the client, while the server is
+     able to transmit sooner.  This is not enabled by default as it
+     could break certain existing server assumptions and use-cases.
+     Since 3.6.4.
+'GNUTLS_ENABLE_RAWPK'
+     Allows raw public-keys to be negotiated during the handshake.
+     Since 3.6.6.
+'GNUTLS_AUTO_REAUTH'
+     Enable transparent re-authentication in client side when the server
+     requests to.  That is, reauthentication is handled within
+     'gnutls_record_recv()' , and the 'GNUTLS_E_REHANDSHAKE' or
+     'GNUTLS_E_REAUTH_REQUEST' are not returned.  This must be enabled
+     with 'GNUTLS_POST_HANDSHAKE_AUTH' for TLS1.3.  Enabling this flag
+     requires to restore interrupted calls to 'gnutls_record_recv()'
+     based on the output of 'gnutls_record_get_direction()' , since
+     'gnutls_record_recv()' could be interrupted when sending when this
+     flag is enabled.  Note this flag may not be used if you are using
+     the same session for sending and receiving in different threads.
+'GNUTLS_ENABLE_EARLY_DATA'
+     Under TLS1.3 allow the server to receive early data sent as part of
+     the initial ClientHello (0-RTT). This can also be used to
+     explicitly indicate that the client will send early data.  This is
+     not enabled by default as early data has weaker security properties
+     than other data.  Since 3.6.5.
+'GNUTLS_NO_AUTO_SEND_TICKET'
+     Under TLS1.3 disable auto-sending of session tickets during the
+     handshake.
+'GNUTLS_NO_END_OF_EARLY_DATA'
+     Under TLS1.3 suppress sending EndOfEarlyData message.  Since 3.7.2.
+'GNUTLS_NO_TICKETS_TLS12'
+     Flag to indicate that the session should not use resumption with
+     session tickets.  This flag only has effect if TLS 1.2 is used.
+
+
+Figure 6.2: The 'gnutls_init_flags_t' enumeration.
+
+After the session initialization details on the allowed ciphersuites and
+protocol versions should be set using the priority functions such as
+*note gnutls_priority_set:: and *note gnutls_priority_set_direct::.  We
+elaborate on them in *note Priority Strings::.  The credentials used for
+the key exchange method, such as certificates or usernames and passwords
+should also be associated with the session current session using *note
+gnutls_credentials_set::.
+
+ -- Function: int gnutls_credentials_set (gnutls_session_t SESSION,
+          gnutls_credentials_type_t TYPE, void * CRED)
+     SESSION: is a 'gnutls_session_t' type.
+
+     TYPE: is the type of the credentials
+
+     CRED: the credentials to set
+
+     Sets the needed credentials for the specified type.  E.g.
+     username, password - or public and private keys etc.  The 'cred'
+     parameter is a structure that depends on the specified type and on
+     the current session (client or server).
+
+     In order to minimize memory usage, and share credentials between
+     several threads gnutls keeps a pointer to cred, and not the whole
+     cred structure.  Thus you will have to keep the structure allocated
+     until you call 'gnutls_deinit()' .
+
+     For 'GNUTLS_CRD_ANON' , 'cred' should be
+     'gnutls_anon_client_credentials_t' in case of a client.  In case of
+     a server it should be 'gnutls_anon_server_credentials_t' .
+
+     For 'GNUTLS_CRD_SRP' , 'cred' should be
+     'gnutls_srp_client_credentials_t' in case of a client, and
+     'gnutls_srp_server_credentials_t' , in case of a server.
+
+     For 'GNUTLS_CRD_CERTIFICATE' , 'cred' should be
+     'gnutls_certificate_credentials_t' .
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise a negative error code is returned.
+
+
+File: gnutls.info,  Node: Associating the credentials,  Next: Setting up the transport layer,  Prev: Session initialization,  Up: How to use GnuTLS in applications
+
+6.4 Associating the credentials
+===============================
+
+* Menu:
+
+* Certificate credentials::
+* Raw public-key credentials::
+* SRP credentials::
+* PSK credentials::
+* Anonymous credentials::
+
+Each authentication method is associated with a key exchange method, and
+a credentials type.  The contents of the credentials is
+method-dependent, e.g.  certificates for certificate authentication and
+should be initialized and associated with a session (see *note
+gnutls_credentials_set::).  A mapping of the key exchange methods with
+the credential types is shown in *note Table 6.2: tab:key-exchange-cred.
+
+Authentication     Key exchange       Client         Server
+method                                credentials    credentials
+                                                     
+--------------------------------------------------------------------
+Certificate and    'KX_RSA',          'CRD_CERTIFICATE''CRD_CERTIFICATE'
+Raw public-key     'KX_DHE_RSA',                     
+                   'KX_DHE_DSS',
+                   'KX_ECDHE_RSA',
+                   'KX_ECDHE_ECDSA'
+Password and       'KX_SRP_RSA',      'CRD_SRP'      'CRD_CERTIFICATE',
+certificate        'KX_SRP_DSS'                      'CRD_SRP'
+                                                     
+Password           'KX_SRP'           'CRD_SRP'      'CRD_SRP'
+                                                     
+Anonymous          'KX_ANON_DH',      'CRD_ANON'     'CRD_ANON'
+                   'KX_ANON_ECDH'                    
+Pre-shared key     'KX_PSK',          'CRD_PSK'      'CRD_PSK'
+                   'KX_DHE_PSK',                     
+                   'KX_ECDHE_PSK'
+
+
+Table 6.2: Key exchange algorithms and the corresponding credential
+types.
+
+
+File: gnutls.info,  Node: Certificate credentials,  Next: Raw public-key credentials,  Up: Associating the credentials
+
+6.4.1 Certificates
+------------------
+
+Server certificate authentication
+.................................
+
+When using certificates the server is required to have at least one
+certificate and private key pair.  Clients may not hold such a pair, but
+a server could require it.  In this section we discuss general issues
+applying to both client and server certificates.  The next section will
+elaborate on issues arising from client authentication only.
+
+In order to use certificate credentials one must first initialize a
+credentials structure of type 'gnutls_certificate_credentials_t'.  After
+use this structure must be freed.  This can be done with the following
+functions.
+
+'INT *note gnutls_certificate_allocate_credentials:: (gnutls_certificate_credentials_t * RES)'
+'VOID *note gnutls_certificate_free_credentials:: (gnutls_certificate_credentials_t SC)'
+
+After the credentials structures are initialized, the certificate and
+key pair must be loaded.  This occurs before any TLS session is
+initialized, and the same structures are reused for multiple sessions.
+Depending on the certificate type different loading functions are
+available, as shown below.  For X.509 certificates, the functions will
+accept and use a certificate chain that leads to a trusted authority.
+The certificate chain must be ordered in such way that every certificate
+certifies the one before it.  The trusted authority's certificate need
+not to be included since the peer should possess it already.
+
+'INT *note gnutls_certificate_set_x509_key_file2:: (gnutls_certificate_credentials_t RES, const char * CERTFILE, const char * KEYFILE, gnutls_x509_crt_fmt_t TYPE, const char * PASS, unsigned int FLAGS)'
+'INT *note gnutls_certificate_set_x509_key_mem2:: (gnutls_certificate_credentials_t RES, const gnutls_datum_t * CERT, const gnutls_datum_t * KEY, gnutls_x509_crt_fmt_t TYPE, const char * PASS, unsigned int FLAGS)'
+'INT *note gnutls_certificate_set_x509_key:: (gnutls_certificate_credentials_t RES, gnutls_x509_crt_t * CERT_LIST, int CERT_LIST_SIZE, gnutls_x509_privkey_t KEY)'
+
+It is recommended to use the higher level functions such as *note
+gnutls_certificate_set_x509_key_file2:: which accept not only file names
+but URLs that specify objects stored in token, or system certificates
+and keys (see *note Application-specific keys::).  For these cases,
+another important function is *note
+gnutls_certificate_set_pin_function::, that allows setting a callback
+function to retrieve a PIN if the input keys are protected by PIN.
+
+ -- Function: void gnutls_certificate_set_pin_function
+          (gnutls_certificate_credentials_t CRED, gnutls_pin_callback_t
+          FN, void * USERDATA)
+     CRED: is a 'gnutls_certificate_credentials_t' type.
+
+     FN: A PIN callback
+
+     USERDATA: Data to be passed in the callback
+
+     This function will set a callback function to be used when required
+     to access a protected object.  This function overrides any other
+     global PIN functions.
+
+     Note that this function must be called right after initialization
+     to have effect.
+
+     *Since:* 3.1.0
+
+If the imported keys and certificates need to be accessed before any TLS
+session is established, it is convenient to use *note
+gnutls_certificate_set_key:: in combination with *note
+gnutls_pcert_import_x509_raw:: and *note
+gnutls_privkey_import_x509_raw::.
+
+ -- Function: int gnutls_certificate_set_key
+          (gnutls_certificate_credentials_t RES, const char ** NAMES,
+          int NAMES_SIZE, gnutls_pcert_st * PCERT_LIST, int
+          PCERT_LIST_SIZE, gnutls_privkey_t KEY)
+     RES: is a 'gnutls_certificate_credentials_t' type.
+
+     NAMES: is an array of DNS names belonging to the public-key (NULL
+     if none)
+
+     NAMES_SIZE: holds the size of the names list
+
+     PCERT_LIST: contains a certificate list (chain) or raw public-key
+
+     PCERT_LIST_SIZE: holds the size of the certificate list
+
+     KEY: is a 'gnutls_privkey_t' key corresponding to the first
+     public-key in pcert_list
+
+     This function sets a public/private key pair in the
+     gnutls_certificate_credentials_t type.  The given public key may be
+     encapsulated in a certificate or can be given as a raw key.  This
+     function may be called more than once, in case multiple key pairs
+     exist for the server.  For clients that want to send more than
+     their own end- entity certificate (e.g., also an intermediate CA
+     cert), the full certificate chain must be provided in 'pcert_list'
+     .
+
+     Note that the 'key' will become part of the credentials structure
+     and must not be deallocated.  It will be automatically deallocated
+     when the 'res' structure is deinitialized.
+
+     If this function fails, the 'res' structure is at an undefined
+     state and it must not be reused to load other keys or certificates.
+
+     Note that, this function by default returns zero on success and a
+     negative value on error.  Since 3.5.6, when the flag
+     'GNUTLS_CERTIFICATE_API_V2' is set using
+     'gnutls_certificate_set_flags()' it returns an index (greater or
+     equal to zero).  That index can be used for other functions to
+     refer to the added key-pair.
+
+     Since GnuTLS 3.6.6 this function also handles raw public keys.
+
+     *Returns:* On success this functions returns zero, and otherwise a
+     negative value on error (see above for modifying that behavior).
+
+     *Since:* 3.0
+
+If multiple certificates are used with the functions above each client's
+request will be served with the certificate that matches the requested
+name (see *note Server name indication::).
+
+As an alternative to loading from files or buffers, a callback may be
+used for the server or the client to specify the certificate and the key
+at the handshake time.  In that case a certificate should be selected
+according the peer's signature algorithm preferences.  To get those
+preferences use *note gnutls_sign_algorithm_get_requested::.  Both
+functions are shown below.
+
+'VOID *note gnutls_certificate_set_retrieve_function:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function * FUNC)'
+'VOID *note gnutls_certificate_set_retrieve_function2:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function2 * FUNC)'
+'VOID *note gnutls_certificate_set_retrieve_function3:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function3 * FUNC)'
+'INT *note gnutls_sign_algorithm_get_requested:: (gnutls_session_t SESSION, size_t INDX, gnutls_sign_algorithm_t * ALGO)'
+
+The functions above do not handle the requested server name
+automatically.  A server would need to check the name requested by the
+client using *note gnutls_server_name_get::, and serve the appropriate
+certificate.  Note that some of these functions require the
+'gnutls_pcert_st' structure to be filled in.  Helper functions to fill
+in the structure are listed below.
+
+typedef struct gnutls_pcert_st
+{
+  gnutls_pubkey_t pubkey;
+  gnutls_datum_t cert;
+  gnutls_certificate_type_t type;
+} gnutls_pcert_st;
+
+'INT *note gnutls_pcert_import_x509:: (gnutls_pcert_st * PCERT, gnutls_x509_crt_t CRT, unsigned int FLAGS)'
+'INT *note gnutls_pcert_import_x509_raw:: (gnutls_pcert_st * PCERT, const gnutls_datum_t * CERT, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)'
+'VOID *note gnutls_pcert_deinit:: (gnutls_pcert_st * PCERT)'
+
+In a handshake, the negotiated cipher suite depends on the certificate's
+parameters, so some key exchange methods might not be available with all
+certificates.  GnuTLS will disable ciphersuites that are not compatible
+with the key, or the enabled authentication methods.  For example keys
+marked as sign-only, will not be able to access the plain RSA
+ciphersuites, that require decryption.  It is not recommended to use RSA
+keys for both signing and encryption.  If possible use a different key
+for the 'DHE-RSA' which uses signing and 'RSA' that requires decryption.
+All the key exchange methods shown in *note Table 4.1: tab:key-exchange.
+are available in certificate authentication.
+
+Client certificate authentication
+.................................
+
+If a certificate is to be requested from the client during the
+handshake, the server will send a certificate request message.  This
+behavior is controlled by *note gnutls_certificate_server_set_request::.
+The request contains a list of the by the server accepted certificate
+signers.  This list is constructed using the trusted certificate
+authorities of the server.  In cases where the server supports a large
+number of certificate authorities it makes sense not to advertise all of
+the names to save bandwidth.  That can be controlled using the function
+*note gnutls_certificate_send_x509_rdn_sequence::.  This however will
+have the side-effect of not restricting the client to certificates
+signed by server's acceptable signers.
+
+ -- Function: void gnutls_certificate_server_set_request
+          (gnutls_session_t SESSION, gnutls_certificate_request_t REQ)
+     SESSION: is a 'gnutls_session_t' type.
+
+     REQ: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE,
+     GNUTLS_CERT_IGNORE
+
+     This function specifies if we (in case of a server) are going to
+     send a certificate request message to the client.  If 'req' is
+     GNUTLS_CERT_REQUIRE then the server will return the
+     'GNUTLS_E_NO_CERTIFICATE_FOUND' error if the peer does not provide
+     a certificate.  If you do not call this function then the client
+     will not be asked to send a certificate.  Invoking the function
+     with 'req' GNUTLS_CERT_IGNORE has the same effect.
+
+ -- Function: void gnutls_certificate_send_x509_rdn_sequence
+          (gnutls_session_t SESSION, int STATUS)
+     SESSION: a 'gnutls_session_t' type.
+
+     STATUS: is 0 or 1
+
+     If status is non zero, this function will order gnutls not to send
+     the rdnSequence in the certificate request message.  That is the
+     server will not advertise its trusted CAs to the peer.  If status
+     is zero then the default behaviour will take effect, which is to
+     advertise the server's trusted CAs.
+
+     This function has no effect in clients, and in authentication
+     methods other than certificate with X.509 certificates.
+
+On the client side, it needs to set its certificates on the credentials
+structure, similarly to server side from a file, or via a callback.
+Once the certificates are available in the credentials structure, the
+client will send them if during the handshake the server requests a
+certificate signed by the issuer of its CA.
+
+In the case a single certificate is available and the server does not
+specify a signer's list, then that certificate is always sent.  It is,
+however possible, to send a certificate even when the advertised CA list
+by the server contains CAs other than its signer.  That can be achieved
+using the 'GNUTLS_FORCE_CLIENT_CERT' flag in *note gnutls_init::.
+
+'INT *note gnutls_certificate_set_x509_key_file:: (gnutls_certificate_credentials_t RES, const char * CERTFILE, const char * KEYFILE, gnutls_x509_crt_fmt_t TYPE)'
+'INT *note gnutls_certificate_set_x509_simple_pkcs12_file:: (gnutls_certificate_credentials_t RES, const char * PKCS12FILE, gnutls_x509_crt_fmt_t TYPE, const char * PASSWORD)'
+'VOID *note gnutls_certificate_set_retrieve_function2:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function2 * FUNC)'
+
+Client or server certificate verification
+.........................................
+
+Certificate verification is possible by loading the trusted authorities
+into the credentials structure by using the following functions,
+applicable to X.509 certificates.  In modern systems it is recommended
+to utilize *note gnutls_certificate_set_x509_system_trust:: which will
+load the trusted authorities from the system store.
+
+ -- Function: int gnutls_certificate_set_x509_system_trust
+          (gnutls_certificate_credentials_t CRED)
+     CRED: is a 'gnutls_certificate_credentials_t' type.
+
+     This function adds the system's default trusted CAs in order to
+     verify client or server certificates.
+
+     In the case the system is currently unsupported
+     'GNUTLS_E_UNIMPLEMENTED_FEATURE' is returned.
+
+     *Returns:* the number of certificates processed or a negative error
+     code on error.
+
+     *Since:* 3.0.20
+'INT *note gnutls_certificate_set_x509_trust_file:: (gnutls_certificate_credentials_t CRED, const char * CAFILE, gnutls_x509_crt_fmt_t TYPE)'
+'INT *note gnutls_certificate_set_x509_trust_dir:: (gnutls_certificate_credentials_t CRED, const char * CA_DIR, gnutls_x509_crt_fmt_t TYPE)'
+
+The peer's certificate will be automatically verified if *note
+gnutls_session_set_verify_cert:: is called prior to handshake.
+
+Alternatively, one must set a callback function during the handshake
+using *note gnutls_certificate_set_verify_function::, which will verify
+the peer's certificate once received.  The verification should happen
+using *note gnutls_certificate_verify_peers3:: within the callback.  It
+will verify the certificate's signature and the owner of the
+certificate.  That will provide a brief verification output.  If a
+detailed output is required one should call *note
+gnutls_certificate_get_peers:: to obtain the raw certificate of the peer
+and verify it using the functions discussed in *note X.509
+certificates::.
+
+In both the automatic and the manual cases, the verification status
+returned can be printed using *note
+gnutls_certificate_verification_status_print::.
+
+ -- Function: void gnutls_session_set_verify_cert (gnutls_session_t
+          SESSION, const char * HOSTNAME, unsigned FLAGS)
+     SESSION: is a gnutls session
+
+     HOSTNAME: is the expected name of the peer; may be 'NULL'
+
+     FLAGS: flags for certificate verification -
+     'gnutls_certificate_verify_flags'
+
+     This function instructs GnuTLS to verify the peer's certificate
+     using the provided hostname.  If the verification fails the
+     handshake will also fail with
+     'GNUTLS_E_CERTIFICATE_VERIFICATION_ERROR' .  In that case the
+     verification result can be obtained using
+     'gnutls_session_get_verify_cert_status()' .
+
+     The 'hostname' pointer provided must remain valid for the lifetime
+     of the session.  More precisely it should be available during any
+     subsequent handshakes.  If no hostname is provided, no hostname
+     verification will be performed.  For a more advanced verification
+     function check 'gnutls_session_set_verify_cert2()' .
+
+     If 'flags' is provided which contain a profile, this function
+     should be called after any session priority setting functions.
+
+     The 'gnutls_session_set_verify_cert()' function is intended to be
+     used by TLS clients to verify the server's certificate.
+
+     *Since:* 3.4.6
+
+'INT *note gnutls_certificate_verify_peers3:: (gnutls_session_t SESSION, const char * HOSTNAME, unsigned int * STATUS)'
+'VOID *note gnutls_certificate_set_verify_function:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_verify_function * FUNC)'
+
+Note that when using raw public-keys verification will not work because
+there is no corresponding certificate body belonging to the raw key that
+can be verified.  In that case the *note
+gnutls_certificate_verify_peers:: family of functions will return a
+GNUTLS_E_INVALID_REQUEST error code.  For authenticating raw public-keys
+one must use an out-of-band mechanism, e.g.  by comparing hashes or
+using trust on first use (see *note Verifying a certificate using trust
+on first use authentication::).
+
+
+File: gnutls.info,  Node: Raw public-key credentials,  Next: SRP credentials,  Prev: Certificate credentials,  Up: Associating the credentials
+
+6.4.2 Raw public-keys
+---------------------
+
+As of version 3.6.6 GnuTLS supports *note Raw public-keys::.  With raw
+public-keys only the public-key part (that is normally embedded in a
+certificate) is transmitted to the peer.  In order to load a raw
+public-key and its corresponding private key in a credentials structure
+one can use the following functions.
+
+'INT *note gnutls_certificate_set_key:: (gnutls_certificate_credentials_t RES, const char ** NAMES, int NAMES_SIZE, gnutls_pcert_st * PCERT_LIST, int PCERT_LIST_SIZE, gnutls_privkey_t KEY)'
+'INT *note gnutls_certificate_set_rawpk_key_mem:: (gnutls_certificate_credentials_t CRED, const gnutls_datum_t* SPKI, const gnutls_datum_t* PKEY, gnutls_x509_crt_fmt_t FORMAT, const char* PASS, unsigned int KEY_USAGE, const char ** NAMES, unsigned int NAMES_LENGTH, unsigned int FLAGS)'
+'INT *note gnutls_certificate_set_rawpk_key_file:: (gnutls_certificate_credentials_t CRED, const char* RAWPKFILE, const char* PRIVKEYFILE, gnutls_x509_crt_fmt_t FORMAT, const char * PASS, unsigned int KEY_USAGE, const char ** NAMES, unsigned int NAMES_LENGTH, unsigned int PRIVKEY_FLAGS, unsigned int PKCS11_FLAGS)'
+
+
+File: gnutls.info,  Node: SRP credentials,  Next: PSK credentials,  Prev: Raw public-key credentials,  Up: Associating the credentials
+
+6.4.3 SRP
+---------
+
+The initialization functions in SRP credentials differ between client
+and server.  Clients supporting SRP should set the username and password
+prior to connection, to the credentials structure.  Alternatively *note
+gnutls_srp_set_client_credentials_function:: may be used instead, to
+specify a callback function that should return the SRP username and
+password.  The callback is called once during the TLS handshake.
+
+'INT *note gnutls_srp_allocate_server_credentials:: (gnutls_srp_server_credentials_t * SC)'
+'INT *note gnutls_srp_allocate_client_credentials:: (gnutls_srp_client_credentials_t * SC)'
+'VOID *note gnutls_srp_free_server_credentials:: (gnutls_srp_server_credentials_t SC)'
+'VOID *note gnutls_srp_free_client_credentials:: (gnutls_srp_client_credentials_t SC)'
+'INT *note gnutls_srp_set_client_credentials:: (gnutls_srp_client_credentials_t RES, const char * USERNAME, const char * PASSWORD)'
+
+ -- Function: void gnutls_srp_set_client_credentials_function
+          (gnutls_srp_client_credentials_t CRED,
+          gnutls_srp_client_credentials_function * FUNC)
+     CRED: is a 'gnutls_srp_server_credentials_t' type.
+
+     FUNC: is the callback function
+
+     This function can be used to set a callback to retrieve the
+     username and password for client SRP authentication.  The
+     callback's function form is:
+
+     int (*callback)(gnutls_session_t, char** username, char**password);
+
+     The 'username' and 'password' must be allocated using
+     'gnutls_malloc()' .
+
+     The 'username' should be an ASCII string or UTF-8 string.  In case
+     of a UTF-8 string it is recommended to be following the PRECIS
+     framework for usernames (rfc8265).  The password can be in ASCII
+     format, or normalized using 'gnutls_utf8_password_normalize()' .
+
+     The callback function will be called once per handshake before the
+     initial hello message is sent.
+
+     The callback should not return a negative error code the second
+     time called, since the handshake procedure will be aborted.
+
+     The callback function should return 0 on success.  -1 indicates an
+     error.
+
+In server side the default behavior of GnuTLS is to read the usernames
+and SRP verifiers from password files.  These password file format is
+compatible the with the _Stanford srp libraries_ format.  If a different
+password file format is to be used, then *note
+gnutls_srp_set_server_credentials_function:: should be called, to set an
+appropriate callback.
+
+ -- Function: int gnutls_srp_set_server_credentials_file
+          (gnutls_srp_server_credentials_t RES, const char *
+          PASSWORD_FILE, const char * PASSWORD_CONF_FILE)
+     RES: is a 'gnutls_srp_server_credentials_t' type.
+
+     PASSWORD_FILE: is the SRP password file (tpasswd)
+
+     PASSWORD_CONF_FILE: is the SRP password conf file (tpasswd.conf)
+
+     This function sets the password files, in a
+     'gnutls_srp_server_credentials_t' type.  Those password files hold
+     usernames and verifiers and will be used for SRP authentication.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
+     error code.
+
+ -- Function: void gnutls_srp_set_server_credentials_function
+          (gnutls_srp_server_credentials_t CRED,
+          gnutls_srp_server_credentials_function * FUNC)
+     CRED: is a 'gnutls_srp_server_credentials_t' type.
+
+     FUNC: is the callback function
+
+     This function can be used to set a callback to retrieve the user's
+     SRP credentials.  The callback's function form is:
+
+     int (*callback)(gnutls_session_t, const char* username,
+     gnutls_datum_t *salt, gnutls_datum_t *verifier, gnutls_datum_t
+     *generator, gnutls_datum_t *prime);
+
+     'username' contains the actual username.  The 'salt' , 'verifier' ,
+     'generator' and 'prime' must be filled in using the
+     'gnutls_malloc()' .  For convenience 'prime' and 'generator' may
+     also be one of the static parameters defined in gnutls.h.
+
+     Initially, the data field is NULL in every 'gnutls_datum_t'
+     structure that the callback has to fill in.  When the callback is
+     done GnuTLS deallocates all of those buffers which are non-NULL,
+     regardless of the return value.
+
+     In order to prevent attackers from guessing valid usernames, if a
+     user does not exist, g and n values should be filled in using a
+     random user's parameters.  In that case the callback must return
+     the special value (1).  See 'gnutls_srp_set_server_fake_salt_seed'
+     too.  If this is not required for your application, return a
+     negative number from the callback to abort the handshake.
+
+     The callback function will only be called once per handshake.  The
+     callback function should return 0 on success, while -1 indicates an
+     error.
+
+
+File: gnutls.info,  Node: PSK credentials,  Next: Anonymous credentials,  Prev: SRP credentials,  Up: Associating the credentials
+
+6.4.4 PSK
+---------
+
+The initialization functions in PSK credentials differ between client
+and server.
+
+'INT *note gnutls_psk_allocate_server_credentials:: (gnutls_psk_server_credentials_t * SC)'
+'INT *note gnutls_psk_allocate_client_credentials:: (gnutls_psk_client_credentials_t * SC)'
+'VOID *note gnutls_psk_free_server_credentials:: (gnutls_psk_server_credentials_t SC)'
+'VOID *note gnutls_psk_free_client_credentials:: (gnutls_psk_client_credentials_t SC)'
+
+Clients supporting PSK should supply the username and key before a TLS
+session is established.  Alternatively *note
+gnutls_psk_set_client_credentials_function:: can be used to specify a
+callback function.  This has the advantage that the callback will be
+called only if PSK has been negotiated.
+
+'INT *note gnutls_psk_set_client_credentials:: (gnutls_psk_client_credentials_t RES, const char * USERNAME, const gnutls_datum_t * KEY, gnutls_psk_key_flags FLAGS)'
+
+ -- Function: void gnutls_psk_set_client_credentials_function
+          (gnutls_psk_client_credentials_t CRED,
+          gnutls_psk_client_credentials_function * FUNC)
+     CRED: is a 'gnutls_psk_server_credentials_t' type.
+
+     FUNC: is the callback function
+
+     This function can be used to set a callback to retrieve the
+     username and password for client PSK authentication.  The
+     callback's function form is: int (*callback)(gnutls_session_t,
+     char** username, gnutls_datum_t* key);
+
+     The 'username' and 'key' ->data must be allocated using
+     'gnutls_malloc()' .  The 'username' should be an ASCII string or
+     UTF-8 string.  In case of a UTF-8 string it is recommended to be
+     following the PRECIS framework for usernames (rfc8265).
+
+     The callback function will be called once per handshake.
+
+     The callback function should return 0 on success.  -1 indicates an
+     error.
+
+In server side the default behavior of GnuTLS is to read the usernames
+and PSK keys from a password file.  The password file should contain
+usernames and keys in hexadecimal format.  The name of the password file
+can be stored to the credentials structure by calling *note
+gnutls_psk_set_server_credentials_file::.  If a different password file
+format is to be used, then a callback should be set instead by *note
+gnutls_psk_set_server_credentials_function::.
+
+The server can help the client chose a suitable username and password,
+by sending a hint.  Note that there is no common profile for the PSK
+hint and applications are discouraged to use it.  A server, may specify
+the hint by calling *note gnutls_psk_set_server_credentials_hint::.  The
+client can retrieve the hint, for example in the callback function,
+using *note gnutls_psk_client_get_hint::.
+
+ -- Function: int gnutls_psk_set_server_credentials_file
+          (gnutls_psk_server_credentials_t RES, const char *
+          PASSWORD_FILE)
+     RES: is a 'gnutls_psk_server_credentials_t' type.
+
+     PASSWORD_FILE: is the PSK password file (passwd.psk)
+
+     This function sets the password file, in a
+     'gnutls_psk_server_credentials_t' type.  This password file holds
+     usernames and keys and will be used for PSK authentication.
+
+     Each entry in the file consists of a username, followed by a colon
+     (':') and a hex-encoded key.  If the username contains a colon or
+     any other special character, it can be hex-encoded preceded by a
+     '#'.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise an error code is returned.
+
+'VOID *note gnutls_psk_set_server_credentials_function:: (gnutls_psk_server_credentials_t CRED, gnutls_psk_server_credentials_function * FUNC)'
+'INT *note gnutls_psk_set_server_credentials_hint:: (gnutls_psk_server_credentials_t RES, const char * HINT)'
+'CONST CHAR * *note gnutls_psk_client_get_hint:: (gnutls_session_t SESSION)'
+
+
+File: gnutls.info,  Node: Anonymous credentials,  Prev: PSK credentials,  Up: Associating the credentials
+
+6.4.5 Anonymous
+---------------
+
+The key exchange methods for anonymous authentication since GnuTLS 3.6.0
+will utilize the RFC7919 parameters, unless explicit parameters have
+been provided and associated with an anonymous credentials structure.
+Check *note Parameter generation:: for more information.  The
+initialization functions for the credentials are shown below.
+
+'INT *note gnutls_anon_allocate_server_credentials:: (gnutls_anon_server_credentials_t * SC)'
+'INT *note gnutls_anon_allocate_client_credentials:: (gnutls_anon_client_credentials_t * SC)'
+'VOID *note gnutls_anon_free_server_credentials:: (gnutls_anon_server_credentials_t SC)'
+'VOID *note gnutls_anon_free_client_credentials:: (gnutls_anon_client_credentials_t SC)'
+
+
+File: gnutls.info,  Node: Setting up the transport layer,  Next: TLS handshake,  Prev: Associating the credentials,  Up: How to use GnuTLS in applications
+
+6.5 Setting up the transport layer
+==================================
+
+The next step is to setup the underlying transport layer details.  The
+Berkeley sockets are implicitly used by GnuTLS, thus a call to *note
+gnutls_transport_set_int:: would be sufficient to specify the socket
+descriptor.
+
+'VOID *note gnutls_transport_set_int:: (gnutls_session_t SESSION, int FD)'
+'VOID *note gnutls_transport_set_int2:: (gnutls_session_t SESSION, int RECV_FD, int SEND_FD)'
+
+If however another transport layer than TCP is selected, then a pointer
+should be used instead to express the parameter to be passed to custom
+functions.  In that case the following functions should be used instead.
+
+'VOID *note gnutls_transport_set_ptr:: (gnutls_session_t SESSION, gnutls_transport_ptr_t PTR)'
+'VOID *note gnutls_transport_set_ptr2:: (gnutls_session_t SESSION, gnutls_transport_ptr_t RECV_PTR, gnutls_transport_ptr_t SEND_PTR)'
+
+Moreover all of the following push and pull callbacks should be set.
+
+ -- Function: void gnutls_transport_set_push_function (gnutls_session_t
+          SESSION, gnutls_push_func PUSH_FUNC)
+     SESSION: is a 'gnutls_session_t' type.
+
+     PUSH_FUNC: a callback function similar to 'write()'
+
+     This is the function where you set a push function for gnutls to
+     use in order to send data.  If you are going to use berkeley style
+     sockets, you do not need to use this function since the default
+     send(2) will probably be ok.  Otherwise you should specify this
+     function for gnutls to be able to send data.  The callback should
+     return a positive number indicating the bytes sent, and -1 on
+     error.
+
+     'push_func' is of the form, ssize_t
+     (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
+
+ -- Function: void gnutls_transport_set_vec_push_function
+          (gnutls_session_t SESSION, gnutls_vec_push_func VEC_FUNC)
+     SESSION: is a 'gnutls_session_t' type.
+
+     VEC_FUNC: a callback function similar to 'writev()'
+
+     Using this function you can override the default writev(2) function
+     for gnutls to send data.  Setting this callback instead of
+     'gnutls_transport_set_push_function()' is recommended since it
+     introduces less overhead in the TLS handshake process.
+
+     'vec_func' is of the form, ssize_t (*gnutls_vec_push_func)
+     (gnutls_transport_ptr_t, const giovec_t * iov, int iovcnt);
+
+     *Since:* 2.12.0
+
+ -- Function: void gnutls_transport_set_pull_function (gnutls_session_t
+          SESSION, gnutls_pull_func PULL_FUNC)
+     SESSION: is a 'gnutls_session_t' type.
+
+     PULL_FUNC: a callback function similar to 'read()'
+
+     This is the function where you set a function for gnutls to receive
+     data.  Normally, if you use berkeley style sockets, do not need to
+     use this function since the default recv(2) will probably be ok.
+     The callback should return 0 on connection termination, a positive
+     number indicating the number of bytes received, and -1 on error.
+
+     'gnutls_pull_func' is of the form, ssize_t
+     (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t);
+
+ -- Function: void gnutls_transport_set_pull_timeout_function
+          (gnutls_session_t SESSION, gnutls_pull_timeout_func FUNC)
+     SESSION: is a 'gnutls_session_t' type.
+
+     FUNC: a callback function
+
+     This is the function where you set a function for gnutls to know
+     whether data are ready to be received.  It should wait for data a
+     given time frame in milliseconds.  The callback should return 0 on
+     timeout, a positive number if data can be received, and -1 on
+     error.  You'll need to override this function if 'select()' is not
+     suitable for the provided transport calls.
+
+     As with 'select()' , if the timeout value is zero the callback
+     should return zero if no data are immediately available.  The
+     special value 'GNUTLS_INDEFINITE_TIMEOUT' indicates that the
+     callback should wait indefinitely for data.
+
+     'gnutls_pull_timeout_func' is of the form, int
+     (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int
+     ms);
+
+     This callback is necessary when 'gnutls_handshake_set_timeout()' or
+     'gnutls_record_set_timeout()' are set, under TLS1.3 and for
+     enforcing the DTLS mode timeouts when in blocking mode.
+
+     For compatibility with future GnuTLS versions this callback must be
+     set when a custom pull function is registered.  The callback will
+     not be used when the session is in TLS mode with non-blocking
+     sockets.  That is, when 'GNUTLS_NONBLOCK' is specified for a TLS
+     session in 'gnutls_init()' .
+
+     The helper function 'gnutls_system_recv_timeout()' is provided to
+     simplify writing callbacks.
+
+     *Since:* 3.0
+
+The functions above accept a callback function which should return the
+number of bytes written, or -1 on error and should set 'errno'
+appropriately.  In some environments, setting 'errno' is unreliable.
+For example Windows have several errno variables in different CRTs, or
+in other systems it may be a non thread-local variable.  If this is a
+concern to you, call *note gnutls_transport_set_errno:: with the
+intended errno value instead of setting 'errno' directly.
+
+ -- Function: void gnutls_transport_set_errno (gnutls_session_t SESSION,
+          int ERR)
+     SESSION: is a 'gnutls_session_t' type.
+
+     ERR: error value to store in session-specific errno variable.
+
+     Store 'err' in the session-specific errno variable.  Useful values
+     for 'err' are EINTR, EAGAIN and EMSGSIZE, other values are treated
+     will be treated as real errors in the push/pull function.
+
+     This function is useful in replacement push and pull functions set
+     by 'gnutls_transport_set_push_function()' and
+     'gnutls_transport_set_pull_function()' under Windows, where the
+     replacements may not have access to the same 'errno' variable that
+     is used by GnuTLS (e.g., the application is linked to msvcr71.dll
+     and gnutls is linked to msvcrt.dll).
+
+     This function is unreliable if you are using the same 'session' in
+     different threads for sending and receiving.
+
+GnuTLS currently only interprets the EINTR, EAGAIN and EMSGSIZE errno
+values and returns the corresponding GnuTLS error codes:
+   * 'GNUTLS_E_INTERRUPTED'
+   * 'GNUTLS_E_AGAIN'
+   * 'GNUTLS_E_LARGE_PACKET'
+The EINTR and EAGAIN values are returned by interrupted system calls, or
+when non blocking IO is used.  All GnuTLS functions can be resumed
+(called again), if any of the above error codes is returned.  The
+EMSGSIZE value is returned when attempting to send a large datagram.
+
+In the case of DTLS it is also desirable to override the generic
+transport functions with functions that emulate the operation of
+'recvfrom' and 'sendto'.  In addition DTLS requires timers during the
+receive of a handshake message, set using the *note
+gnutls_transport_set_pull_timeout_function:: function.  To check the
+retransmission timers the function *note gnutls_dtls_get_timeout:: is
+provided, which returns the time remaining until the next
+retransmission, or better the time until *note gnutls_handshake:: should
+be called again.
+
+ -- Function: void gnutls_transport_set_pull_timeout_function
+          (gnutls_session_t SESSION, gnutls_pull_timeout_func FUNC)
+     SESSION: is a 'gnutls_session_t' type.
+
+     FUNC: a callback function
+
+     This is the function where you set a function for gnutls to know
+     whether data are ready to be received.  It should wait for data a
+     given time frame in milliseconds.  The callback should return 0 on
+     timeout, a positive number if data can be received, and -1 on
+     error.  You'll need to override this function if 'select()' is not
+     suitable for the provided transport calls.
+
+     As with 'select()' , if the timeout value is zero the callback
+     should return zero if no data are immediately available.  The
+     special value 'GNUTLS_INDEFINITE_TIMEOUT' indicates that the
+     callback should wait indefinitely for data.
+
+     'gnutls_pull_timeout_func' is of the form, int
+     (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int
+     ms);
+
+     This callback is necessary when 'gnutls_handshake_set_timeout()' or
+     'gnutls_record_set_timeout()' are set, under TLS1.3 and for
+     enforcing the DTLS mode timeouts when in blocking mode.
+
+     For compatibility with future GnuTLS versions this callback must be
+     set when a custom pull function is registered.  The callback will
+     not be used when the session is in TLS mode with non-blocking
+     sockets.  That is, when 'GNUTLS_NONBLOCK' is specified for a TLS
+     session in 'gnutls_init()' .
+
+     The helper function 'gnutls_system_recv_timeout()' is provided to
+     simplify writing callbacks.
+
+     *Since:* 3.0
+
+ -- Function: unsigned int gnutls_dtls_get_timeout (gnutls_session_t
+          SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     This function will return the milliseconds remaining for a
+     retransmission of the previously sent handshake message.  This
+     function is useful when DTLS is used in non-blocking mode, to
+     estimate when to call 'gnutls_handshake()' if no packets have been
+     received.
+
+     *Returns:* the remaining time in milliseconds.
+
+     *Since:* 3.0
+
+* Menu:
+
+* Asynchronous operation::
+* Reducing round-trips::
+* Zero-roundtrip mode::
+* Anti-replay protection::
+* DTLS sessions::
+* DTLS and SCTP::
+
+
+File: gnutls.info,  Node: Asynchronous operation,  Next: Reducing round-trips,  Up: Setting up the transport layer
+
+6.5.1 Asynchronous operation
+----------------------------
+
+GnuTLS can be used with asynchronous socket or event-driven programming.
+The approach is similar to using Berkeley sockets under such an
+environment.  The blocking, due to network interaction, calls such as
+*note gnutls_handshake::, *note gnutls_record_recv::, can be set to
+non-blocking by setting the underlying sockets to non-blocking.  If
+other push and pull functions are setup, then they should behave the
+same way as 'recv' and 'send' when used in a non-blocking way, i.e.,
+return -1 and set errno to 'EAGAIN'.  Since, during a TLS protocol
+session GnuTLS does not block except for network interaction, the non
+blocking 'EAGAIN' errno will be propagated and GnuTLS functions will
+return the 'GNUTLS_E_AGAIN' error code.  Such calls can be resumed the
+same way as a system call would.  The only exception is *note
+gnutls_record_send::, which if interrupted subsequent calls need not to
+include the data to be sent (can be called with NULL argument).
+
+When using the 'poll' or 'select' system calls though, one should
+remember that they only apply to the kernel sockets API. To check for
+any available buffered data in a GnuTLS session, utilize *note
+gnutls_record_check_pending::, either before the 'poll' system call, or
+after a call to *note gnutls_record_recv::.  Data queued by *note
+gnutls_record_send:: (when interrupted) can be discarded using *note
+gnutls_record_discard_queued::.
+
+An example of GnuTLS' usage with asynchronous operation can be found in
+'doc/examples/tlsproxy'.
+
+The following paragraphs describe the detailed requirements for
+non-blocking operation when using the TLS or DTLS protocols.
+
+6.5.1.1 TLS protocol
+....................
+
+There are no special requirements for the TLS protocol operation in
+non-blocking mode if a non-blocking socket is used.
+
+It is recommended, however, for future compatibility, when in
+non-blocking mode, to call the *note gnutls_init:: function with the
+'GNUTLS_NONBLOCK' flag set (see *note Session initialization::).
+
+6.5.1.2 Datagram TLS protocol
+.............................
+
+When in non-blocking mode the function, the *note gnutls_init:: function
+must be called with the 'GNUTLS_NONBLOCK' flag set (see *note Session
+initialization::).
+
+In contrast with the TLS protocol, the pull timeout function is
+required, but will only be called with a timeout of zero.  In that case
+it should indicate whether there are data to be received or not.  When
+not using the default pull function, then *note
+gnutls_transport_set_pull_timeout_function:: should be called.
+
+Although in the TLS protocol implementation each call to receive or send
+function implies to restoring the same function that was interrupted, in
+the DTLS protocol this requirement isn't true.  There are cases where a
+retransmission is required, which are indicated by a received message
+and thus *note gnutls_record_get_direction:: must be called to decide
+which direction to check prior to restoring a function call.
+
+ -- Function: int gnutls_record_get_direction (gnutls_session_t SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     This function is useful to determine whether a GnuTLS function was
+     interrupted while sending or receiving, so that 'select()' or
+     'poll()' may be called appropriately.
+
+     It provides information about the internals of the record protocol
+     and is only useful if a prior gnutls function call, e.g.
+     'gnutls_handshake()' , was interrupted and returned
+     'GNUTLS_E_INTERRUPTED' or 'GNUTLS_E_AGAIN' .  After such an
+     interrupt applications may call 'select()' or 'poll()' before
+     restoring the interrupted GnuTLS function.
+
+     This function's output is unreliable if you are using the same
+     'session' in different threads for sending and receiving.
+
+     *Returns:* 0 if interrupted while trying to read data, or 1 while
+     trying to write data.
+
+When calling *note gnutls_handshake:: through a multi-plexer, to be able
+to handle properly the DTLS handshake retransmission timers, the
+function *note gnutls_dtls_get_timeout:: should be used to estimate when
+to call *note gnutls_handshake:: if no data have been received.
+
+
+File: gnutls.info,  Node: Reducing round-trips,  Next: Zero-roundtrip mode,  Prev: Asynchronous operation,  Up: Setting up the transport layer
+
+6.5.2 Reducing round-trips
+--------------------------
+
+The full TLS 1.2 handshake requires 2 round-trips to complete, and when
+combined with TCP's SYN and SYN-ACK negotiation it extends to 3 full
+round-trips.  While, TLS 1.3 reduces that to two round-trips when under
+TCP, it still adds considerable latency, making the protocol unsuitable
+for certain applications.
+
+To optimize the handshake latency, in client side, it is possible to
+take advantage of the TCP fast open [*note RFC7413::] mechanism on
+operating systems that support it.  That can be done either by manually
+crafting the push and pull callbacks, or by utilizing *note
+gnutls_transport_set_fastopen::.  In that case the initial TCP handshake
+is eliminated, reducing the TLS 1.2 handshake round-trip to 2, and the
+TLS 1.3 handshake to a single round-trip.  Note, that when this function
+is used, any connection failures will be reported during the *note
+gnutls_handshake:: function call with error code 'GNUTLS_E_PUSH_ERROR'.
+
+ -- Function: void gnutls_transport_set_fastopen (gnutls_session_t
+          SESSION, int FD, struct sockaddr * CONNECT_ADDR, socklen_t
+          CONNECT_ADDRLEN, unsigned int FLAGS)
+     SESSION: is a 'gnutls_session_t' type.
+
+     FD: is the session's socket descriptor
+
+     CONNECT_ADDR: is the address we want to connect to
+
+     CONNECT_ADDRLEN: is the length of 'connect_addr'
+
+     FLAGS: must be zero
+
+     Enables TCP Fast Open (TFO) for the specified TLS client session.
+     That means that TCP connection establishment and the transmission
+     of the first TLS client hello packet are combined.  The peer's
+     address must be specified in 'connect_addr' and 'connect_addrlen' ,
+     and the socket specified by 'fd' should not be connected.
+
+     TFO only works for TCP sockets of type AF_INET and AF_INET6.  If
+     the OS doesn't support TCP fast open this function will result to
+     gnutls using 'connect()' transparently during the first write.
+
+     *Note:* This function overrides all the transport callback
+     functions.  If this is undesirable, TCP Fast Open must be
+     implemented on the user callback functions without calling this
+     function.  When using this function, transport callbacks must not
+     be set, and 'gnutls_transport_set_ptr()' or
+     'gnutls_transport_set_int()' must not be called.
+
+     On GNU/Linux TFO has to be enabled at the system layer, that is in
+     /proc/sys/net/ipv4/tcp_fastopen, bit 0 has to be set.
+
+     This function has no effect on server sessions.
+
+     *Since:* 3.5.3
+
+When restricted to TLS 1.2, and non-resumed sessions, it is possible to
+further reduce the round-trips to a single one by taking advantage of
+the *note False Start:: TLS extension.  This can be enabled by setting
+the GNUTLS_ENABLE_FALSE_START flag on *note gnutls_init::.
+
+Under TLS 1.3, the server side can start transmitting before the
+handshake is complete (i.e., while the client Finished message is still
+in flight), when no client certificate authentication is requested.
+This, unlike false start, is part of protocol design with no known
+security implications.  It can be enabled by setting the
+GNUTLS_ENABLE_EARLY_START on *note gnutls_init::, and the *note
+gnutls_handshake:: function will return early, allowing the server to
+send data earlier.
+
+
+File: gnutls.info,  Node: Zero-roundtrip mode,  Next: Anti-replay protection,  Prev: Reducing round-trips,  Up: Setting up the transport layer
+
+6.5.3 Zero-roundtrip mode
+-------------------------
+
+Under TLS 1.3, when the client has already connected to the server and
+is resuming a session, it can start transmitting application data during
+handshake.  This is called zero round-trip time (0-RTT) mode, and the
+application data sent in this mode is called early data.  The client can
+send early data with *note gnutls_record_send_early_data::.  The client
+should call this function before calling *note gnutls_handshake:: and
+after calling *note gnutls_session_set_data::.
+
+Note, however, that early data has weaker security properties than
+normal application data sent after handshake, such as lack of forward
+secrecy, no guarantees of non-replay between connections.  Thus it is
+disabled on the server side by default.  To enable it, the server needs
+to:
+  1. Set GNUTLS_ENABLE_EARLY_DATA on *note gnutls_init::.  Note that
+     this option only has effect on server.
+
+  2. Enable anti-replay measure.  See *note Anti-replay protection:: for
+     the details.
+
+The server caches the received early data until it is read.  To set the
+maximum amount of data to be stored in the cache, use *note
+gnutls_record_set_max_early_data_size::.  After receiving the
+EndOfEarlyData handshake message, the server can start retrieving the
+received data with *note gnutls_record_recv_early_data::.  You can call
+the function either after the handshake is complete, or through a
+handshake hook (*note gnutls_handshake_set_hook_function::).
+
+When sending early data, the client should respect the maximum amount of
+early data, which may have been previously advertised by the server.  It
+can be checked using *note gnutls_record_get_max_early_data_size::,
+right after calling *note gnutls_session_set_data::.
+
+After sending early data, to check whether the sent early data was
+accepted by the server, use *note gnutls_session_get_flags:: and compare
+the result with GNUTLS_SFLAGS_EARLY_DATA.  Similarly, on the server
+side, the same function and flag can be used to check whether it has
+actually accepted early data.
+
+
+File: gnutls.info,  Node: Anti-replay protection,  Next: DTLS sessions,  Prev: Zero-roundtrip mode,  Up: Setting up the transport layer
+
+6.5.4 Anti-replay protection
+----------------------------
+
+When 0-RTT mode is used, the server must protect itself from replay
+attacks, where adversary client reuses duplicate session ticket to send
+early data, before the server authenticates the client.
+
+GnuTLS provides a simple mechanism against replay attacks, following the
+method called ClientHello recording.  When a session ticket is accepted,
+the server checks if the ClientHello message has been already seen.  If
+there is a duplicate, the server rejects early data.
+
+The problem of this approach is that the number of recorded messages
+grows indefinitely.  To prevent that, the server can limit the recording
+to a certain time window, which can be configured with *note
+gnutls_anti_replay_set_window::.
+
+The anti-replay mechanism shall be globally initialized with *note
+gnutls_anti_replay_init::, and then attached to a session using *note
+gnutls_anti_replay_enable::.  It can be deinitialized with *note
+gnutls_anti_replay_deinit::.
+
+The server must also set up a database back-end to store ClientHello
+messages.  That can be achieved using *note
+gnutls_anti_replay_set_add_function:: and *note
+gnutls_anti_replay_set_ptr::.
+
+Note that, if the back-end stores arbitrary number of ClientHello, it
+needs to periodically clean up the stored entries based on the time
+window set with *note gnutls_anti_replay_set_window::.  The cleanup can
+be implemented by iterating through the database entries and calling
+*note gnutls_db_check_entry_expire_time::.  This is similar to session
+database cleanup used by TLS1.2 sessions.
+
+The full set up of the server using early data would be like the
+following example:
+     #define MAX_EARLY_DATA_SIZE 16384
+
+     static int
+     db_add_func(void *dbf, gnutls_datum_t key, gnutls_datum_t data)
+     {
+         /* Return GNUTLS_E_DB_ENTRY_EXISTS, if KEY is found in the database.
+          * Otherwise, store it and return 0.
+          */
+     }
+
+     static int
+     handshake_hook_func(gnutls_session_t session, unsigned int htype,
+                         unsigned when, unsigned int incoming, const gnutls_datum_t *msg)
+     {
+         int ret;
+         char buf[MAX_EARLY_DATA_SIZE];
+
+         assert(htype == GNUTLS_HANDSHAKE_END_OF_EARLY_DATA);
+         assert(when == GNUTLS_HOOK_POST);
+
+         if (gnutls_session_get_flags(session) & GNUTLS_SFLAGS_EARLY_DATA) {
+             ret = gnutls_record_recv_early_data(session, buf, sizeof(buf));
+             assert(ret >= 0);
+         }
+
+         return ret;
+     }
+
+     int main()
+     {
+       ...
+       /* Initialize anti-replay measure, which can be shared
+        * among multiple sessions.
+        */
+       gnutls_anti_replay_init(&anti_replay);
+
+       /* Set the database back-end function for the anti-replay data. */
+       gnutls_anti_replay_set_add_function(anti_replay, db_add_func);
+       gnutls_anti_replay_set_ptr(anti_replay, NULL);
+
+       ...
+
+       gnutls_init(&server, GNUTLS_SERVER | GNUTLS_ENABLE_EARLY_DATA);
+       gnutls_record_set_max_early_data_size(server, MAX_EARLY_DATA_SIZE);
+
+       ...
+
+       /* Set the anti-replay measure to the session.
+        */
+       gnutls_anti_replay_enable(server, anti_replay);
+       ...
+
+       /* Retrieve early data in a handshake hook;
+        * you can also do that after handshake.
+        */
+       gnutls_handshake_set_hook_function(server, GNUTLS_HANDSHAKE_END_OF_EARLY_DATA,
+                                          GNUTLS_HOOK_POST, handshake_hook_func);
+       ...
+     }
+
+
+File: gnutls.info,  Node: DTLS sessions,  Next: DTLS and SCTP,  Prev: Anti-replay protection,  Up: Setting up the transport layer
+
+6.5.5 DTLS sessions
+-------------------
+
+Because datagram TLS can operate over connections where the client
+cannot be reliably verified, functionality in the form of cookies, is
+available to prevent denial of service attacks to servers.  GnuTLS
+requires a server to generate a secret key that is used to sign a
+cookie(1).  That cookie is sent to the client using *note
+gnutls_dtls_cookie_send::, and the client must reply using the correct
+cookie.  The server side should verify the initial message sent by
+client using *note gnutls_dtls_cookie_verify::.  If successful the
+session should be initialized and associated with the cookie using *note
+gnutls_dtls_prestate_set::, before proceeding to the handshake.
+
+'INT *note gnutls_key_generate:: (gnutls_datum_t * KEY, unsigned int KEY_SIZE)'
+'INT *note gnutls_dtls_cookie_send:: (gnutls_datum_t * KEY, void * CLIENT_DATA, size_t CLIENT_DATA_SIZE, gnutls_dtls_prestate_st * PRESTATE, gnutls_transport_ptr_t PTR, gnutls_push_func PUSH_FUNC)'
+'INT *note gnutls_dtls_cookie_verify:: (gnutls_datum_t * KEY, void * CLIENT_DATA, size_t CLIENT_DATA_SIZE, void * _MSG, size_t MSG_SIZE, gnutls_dtls_prestate_st * PRESTATE)'
+'VOID *note gnutls_dtls_prestate_set:: (gnutls_session_t SESSION, gnutls_dtls_prestate_st * PRESTATE)'
+
+Note that the above apply to server side only and they are not mandatory
+to be used.  Not using them, however, allows denial of service attacks.
+The client side cookie handling is part of *note gnutls_handshake::.
+
+Datagrams are typically restricted by a maximum transfer unit (MTU). For
+that both client and server side should set the correct maximum transfer
+unit for the layer underneath GnuTLS.  This will allow proper
+fragmentation of DTLS messages and prevent messages from being silently
+discarded by the transport layer.  The "correct" maximum transfer unit
+can be obtained through a path MTU discovery mechanism [*note
+RFC4821::].
+
+'VOID *note gnutls_dtls_set_mtu:: (gnutls_session_t SESSION, unsigned int MTU)'
+'UNSIGNED INT *note gnutls_dtls_get_mtu:: (gnutls_session_t SESSION)'
+'UNSIGNED INT *note gnutls_dtls_get_data_mtu:: (gnutls_session_t SESSION)'
+
+   ---------- Footnotes ----------
+
+   (1) A key of 128 bits or 16 bytes should be sufficient for this
+purpose.
+
+
+File: gnutls.info,  Node: DTLS and SCTP,  Prev: DTLS sessions,  Up: Setting up the transport layer
+
+6.5.6 DTLS and SCTP
+-------------------
+
+Although DTLS can run under any reliable or unreliable layer, there are
+special requirements for SCTP according to [*note RFC6083::].  We
+summarize the most important below, however for a full treatment we
+refer to [*note RFC6083::].
+
+   * The MTU set via *note gnutls_dtls_set_mtu:: must be 2^14.
+   * Replay detection must be disabled; use the flag
+     'GNUTLS_NO_REPLAY_PROTECTION' with *note gnutls_init::.
+   * Retransmission of messages must be disabled; use *note
+     gnutls_dtls_set_timeouts:: with a retransmission timeout larger
+     than the total.
+   * Handshake, Alert and ChangeCipherSpec messages must be sent over
+     stream 0 with unlimited reliability and with the ordered delivery
+     feature.
+   * During a rehandshake, the caching of messages with unknown epoch is
+     not handled by GnuTLS; this must be implemented in a special pull
+     function.
+
+
+File: gnutls.info,  Node: TLS handshake,  Next: Data transfer and termination,  Prev: Setting up the transport layer,  Up: How to use GnuTLS in applications
+
+6.6 TLS handshake
+=================
+
+Once a session has been initialized and a network connection has been
+set up, TLS and DTLS protocols perform a handshake.  The handshake is
+the actual key exchange.
+
+ -- Function: int gnutls_handshake (gnutls_session_t SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     This function performs the handshake of the TLS/SSL protocol, and
+     initializes the TLS session parameters.
+
+     The non-fatal errors expected by this function are:
+     'GNUTLS_E_INTERRUPTED' , 'GNUTLS_E_AGAIN' ,
+     'GNUTLS_E_WARNING_ALERT_RECEIVED' .  When this function is called
+     for re-handshake under TLS 1.2 or earlier, the non-fatal error code
+     'GNUTLS_E_GOT_APPLICATION_DATA' may also be returned.
+
+     The former two interrupt the handshake procedure due to the
+     transport layer being interrupted, and the latter because of a
+     "warning" alert that was sent by the peer (it is always a good idea
+     to check any received alerts).  On these non-fatal errors call this
+     function again, until it returns 0; cf.
+     'gnutls_record_get_direction()' and 'gnutls_error_is_fatal()' .  In
+     DTLS sessions the non-fatal error 'GNUTLS_E_LARGE_PACKET' is also
+     possible, and indicates that the MTU should be adjusted.
+
+     When this function is called by a server after a rehandshake
+     request under TLS 1.2 or earlier the
+     'GNUTLS_E_GOT_APPLICATION_DATA' error code indicates that some data
+     were pending prior to peer initiating the handshake.  Under TLS 1.3
+     this function when called after a successful handshake, is a no-op
+     and always succeeds in server side; in client side this function is
+     equivalent to 'gnutls_session_key_update()' with 'GNUTLS_KU_PEER'
+     flag.
+
+     This function handles both full and abbreviated TLS handshakes
+     (resumption).  For abbreviated handshakes, in client side, the
+     'gnutls_session_set_data()' should be called prior to this function
+     to set parameters from a previous session.  In server side,
+     resumption is handled by either setting a DB back-end, or setting
+     up keys for session tickets.
+
+     *Returns:* 'GNUTLS_E_SUCCESS' on a successful handshake, otherwise
+     a negative error code.
+
+ -- Function: void gnutls_handshake_set_timeout (gnutls_session_t
+          SESSION, unsigned int MS)
+     SESSION: is a 'gnutls_session_t' type.
+
+     MS: is a timeout value in milliseconds
+
+     This function sets the timeout for the TLS handshake process to the
+     provided value.  Use an 'ms' value of zero to disable timeout, or
+     'GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT' for a reasonable default value.
+     For the DTLS protocol, the more detailed
+     'gnutls_dtls_set_timeouts()' is provided.
+
+     This function requires to set a pull timeout callback.  See
+     'gnutls_transport_set_pull_timeout_function()' .
+
+     *Since:* 3.1.0
+
+In GnuTLS 3.5.0 and later it is recommended to use *note
+gnutls_session_set_verify_cert:: for the handshake process to ensure the
+verification of the peer's identity.  That will verify the peer's
+certificate, against the trusted CA store while accounting for stapled
+OCSP responses during the handshake; any error will be returned as a
+handshake error.
+
+In older GnuTLS versions it is required to verify the peer's certificate
+during the handshake by setting a callback with *note
+gnutls_certificate_set_verify_function::, and then using *note
+gnutls_certificate_verify_peers3:: from it.  See *note Certificate
+authentication:: for more information.
+
+'VOID *note gnutls_session_set_verify_cert:: (gnutls_session_t SESSION, const char * HOSTNAME, unsigned FLAGS)'
+'INT *note gnutls_certificate_verify_peers3:: (gnutls_session_t SESSION, const char * HOSTNAME, unsigned int * STATUS)'
+
+
+File: gnutls.info,  Node: Data transfer and termination,  Next: Buffered data transfer,  Prev: TLS handshake,  Up: How to use GnuTLS in applications
+
+6.7 Data transfer and termination
+=================================
+
+Once the handshake is complete and peer's identity has been verified
+data can be exchanged.  The available functions resemble the POSIX
+'recv' and 'send' functions.  It is suggested to use *note
+gnutls_error_is_fatal:: to check whether the error codes returned by
+these functions are fatal for the protocol or can be ignored.
+
+ -- Function: ssize_t gnutls_record_send (gnutls_session_t SESSION,
+          const void * DATA, size_t DATA_SIZE)
+     SESSION: is a 'gnutls_session_t' type.
+
+     DATA: contains the data to send
+
+     DATA_SIZE: is the length of the data
+
+     This function has the similar semantics with 'send()' .  The only
+     difference is that it accepts a GnuTLS session, and uses different
+     error codes.  Note that if the send buffer is full, 'send()' will
+     block this function.  See the 'send()' documentation for more
+     information.
+
+     You can replace the default push function which is 'send()' , by
+     using 'gnutls_transport_set_push_function()' .
+
+     If the EINTR is returned by the internal push function then
+     'GNUTLS_E_INTERRUPTED' will be returned.  If 'GNUTLS_E_INTERRUPTED'
+     or 'GNUTLS_E_AGAIN' is returned, you must call this function again
+     with the exact same parameters, or provide a 'NULL' pointer for
+     'data' and 0 for 'data_size' , in order to write the same data as
+     before.  If you wish to discard the previous data instead of
+     retrying, you must call 'gnutls_record_discard_queued()' before
+     calling this function with different parameters.  Note that the
+     latter works only on special transports (e.g., UDP). cf.
+     'gnutls_record_get_direction()' .
+
+     Note that in DTLS this function will return the
+     'GNUTLS_E_LARGE_PACKET' error code if the send data exceed the data
+     MTU value - as returned by 'gnutls_dtls_get_data_mtu()' .  The
+     errno value EMSGSIZE also maps to 'GNUTLS_E_LARGE_PACKET' .  Note
+     that since 3.2.13 this function can be called under cork in DTLS
+     mode, and will refuse to send data over the MTU size by returning
+     'GNUTLS_E_LARGE_PACKET' .
+
+     *Returns:* The number of bytes sent, or a negative error code.  The
+     number of bytes sent might be less than 'data_size' .  The maximum
+     number of bytes this function can send in a single call depends on
+     the negotiated maximum record size.
+
+ -- Function: ssize_t gnutls_record_recv (gnutls_session_t SESSION, void
+          * DATA, size_t DATA_SIZE)
+     SESSION: is a 'gnutls_session_t' type.
+
+     DATA: the buffer that the data will be read into
+
+     DATA_SIZE: the number of requested bytes
+
+     This function has the similar semantics with 'recv()' .  The only
+     difference is that it accepts a GnuTLS session, and uses different
+     error codes.  In the special case that the peer requests a
+     renegotiation, the caller will receive an error code of
+     'GNUTLS_E_REHANDSHAKE' .  In case of a client, this message may be
+     simply ignored, replied with an alert 'GNUTLS_A_NO_RENEGOTIATION' ,
+     or replied with a new handshake, depending on the client's will.  A
+     server receiving this error code can only initiate a new handshake
+     or terminate the session.
+
+     If 'EINTR' is returned by the internal pull function (the default
+     is 'recv()' ) then 'GNUTLS_E_INTERRUPTED' will be returned.  If
+     'GNUTLS_E_INTERRUPTED' or 'GNUTLS_E_AGAIN' is returned, you must
+     call this function again to get the data.  See also
+     'gnutls_record_get_direction()' .
+
+     *Returns:* The number of bytes received and zero on EOF (for stream
+     connections).  A negative error code is returned in case of an
+     error.  The number of bytes received might be less than the
+     requested 'data_size' .
+
+ -- Function: int gnutls_error_is_fatal (int ERROR)
+     ERROR: is a GnuTLS error code, a negative error code
+
+     If a GnuTLS function returns a negative error code you may feed
+     that value to this function to see if the error condition is fatal
+     to a TLS session (i.e., must be terminated).
+
+     Note that you may also want to check the error code manually, since
+     some non-fatal errors to the protocol (such as a warning alert or a
+     rehandshake request) may be fatal for your program.
+
+     This function is only useful if you are dealing with errors from
+     functions that relate to a TLS session (e.g., record layer or
+     handshake layer handling functions).
+
+     *Returns:* Non-zero value on fatal errors or zero on non-fatal.
+
+Although, in the TLS protocol the receive function can be called at any
+time, when DTLS is used the GnuTLS receive functions must be called once
+a message is available for reading, even if no data are expected.  This
+is because in DTLS various (internal) actions may be required due to
+retransmission timers.  Moreover, an extended receive function is shown
+below, which allows the extraction of the message's sequence number.
+Due to the unreliable nature of the protocol, this field allows
+distinguishing out-of-order messages.
+
+ -- Function: ssize_t gnutls_record_recv_seq (gnutls_session_t SESSION,
+          void * DATA, size_t DATA_SIZE, unsigned char * SEQ)
+     SESSION: is a 'gnutls_session_t' type.
+
+     DATA: the buffer that the data will be read into
+
+     DATA_SIZE: the number of requested bytes
+
+     SEQ: is the packet's 64-bit sequence number.  Should have space for
+     8 bytes.
+
+     This function is the same as 'gnutls_record_recv()' , except that
+     it returns in addition to data, the sequence number of the data.
+     This is useful in DTLS where record packets might be received
+     out-of-order.  The returned 8-byte sequence number is an integer in
+     big-endian format and should be treated as a unique message
+     identification.
+
+     *Returns:* The number of bytes received and zero on EOF. A negative
+     error code is returned in case of an error.  The number of bytes
+     received might be less than 'data_size' .
+
+     *Since:* 3.0
+
+The *note gnutls_record_check_pending:: helper function is available to
+allow checking whether data are available to be read in a GnuTLS session
+buffers.  Note that this function complements but does not replace
+'poll', i.e., *note gnutls_record_check_pending:: reports no data to be
+read, 'poll' should be called to check for data in the network buffers.
+
+ -- Function: size_t gnutls_record_check_pending (gnutls_session_t
+          SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     This function checks if there are unread data in the gnutls
+     buffers.  If the return value is non-zero the next call to
+     'gnutls_record_recv()' is guaranteed not to block.
+
+     *Returns:* Returns the size of the data or zero.
+'INT *note gnutls_record_get_direction:: (gnutls_session_t SESSION)'
+
+Once a TLS or DTLS session is no longer needed, it is recommended to use
+*note gnutls_bye:: to terminate the session.  That way the peer is
+notified securely about the intention of termination, which allows
+distinguishing it from a malicious connection termination.  A session
+can be deinitialized with the *note gnutls_deinit:: function.
+
+ -- Function: int gnutls_bye (gnutls_session_t SESSION,
+          gnutls_close_request_t HOW)
+     SESSION: is a 'gnutls_session_t' type.
+
+     HOW: is an integer
+
+     Terminates the current TLS/SSL connection.  The connection should
+     have been initiated using 'gnutls_handshake()' .  'how' should be
+     one of 'GNUTLS_SHUT_RDWR' , 'GNUTLS_SHUT_WR' .
+
+     In case of 'GNUTLS_SHUT_RDWR' the TLS session gets terminated and
+     further receives and sends will be disallowed.  If the return value
+     is zero you may continue using the underlying transport layer.
+     'GNUTLS_SHUT_RDWR' sends an alert containing a close request and
+     waits for the peer to reply with the same message.
+
+     In case of 'GNUTLS_SHUT_WR' the TLS session gets terminated and
+     further sends will be disallowed.  In order to reuse the connection
+     you should wait for an EOF from the peer.  'GNUTLS_SHUT_WR' sends
+     an alert containing a close request.
+
+     Note that not all implementations will properly terminate a TLS
+     connection.  Some of them, usually for performance reasons, will
+     terminate only the underlying transport layer, and thus not
+     distinguishing between a malicious party prematurely terminating
+     the connection and normal termination.
+
+     This function may also return 'GNUTLS_E_AGAIN' or
+     'GNUTLS_E_INTERRUPTED' ; cf.  'gnutls_record_get_direction()' .
+
+     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code, see
+     function documentation for entire semantics.
+
+ -- Function: void gnutls_deinit (gnutls_session_t SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     This function clears all buffers associated with the 'session' .
+     This function will also remove session data from the session
+     database if the session was terminated abnormally.
+
+
+File: gnutls.info,  Node: Buffered data transfer,  Next: Handling alerts,  Prev: Data transfer and termination,  Up: How to use GnuTLS in applications
+
+6.8 Buffered data transfer
+==========================
+
+Although *note gnutls_record_send:: is sufficient to transmit data to
+the peer, when many small chunks of data are to be transmitted it is
+inefficient and wastes bandwidth due to the TLS record overhead.  In
+that case it is preferable to combine the small chunks before
+transmission.  The following functions provide that functionality.
+
+ -- Function: void gnutls_record_cork (gnutls_session_t SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     If called, 'gnutls_record_send()' will no longer send any records.
+     Any sent records will be cached until 'gnutls_record_uncork()' is
+     called.
+
+     This function is safe to use with DTLS after GnuTLS 3.3.0.
+
+     *Since:* 3.1.9
+
+ -- Function: int gnutls_record_uncork (gnutls_session_t SESSION,
+          unsigned int FLAGS)
+     SESSION: is a 'gnutls_session_t' type.
+
+     FLAGS: Could be zero or 'GNUTLS_RECORD_WAIT'
+
+     This resets the effect of 'gnutls_record_cork()' , and flushes any
+     pending data.  If the 'GNUTLS_RECORD_WAIT' flag is specified then
+     this function will block until the data is sent or a fatal error
+     occurs (i.e., the function will retry on 'GNUTLS_E_AGAIN' and
+     'GNUTLS_E_INTERRUPTED' ).
+
+     If the flag 'GNUTLS_RECORD_WAIT' is not specified and the function
+     is interrupted then the 'GNUTLS_E_AGAIN' or 'GNUTLS_E_INTERRUPTED'
+     errors will be returned.  To obtain the data left in the corked
+     buffer use 'gnutls_record_check_corked()' .
+
+     *Returns:* On success the number of transmitted data is returned,
+     or otherwise a negative error code.
+
+     *Since:* 3.1.9
+
+
+File: gnutls.info,  Node: Handling alerts,  Next: Priority Strings,  Prev: Buffered data transfer,  Up: How to use GnuTLS in applications
+
+6.9 Handling alerts
+===================
+
+During a TLS connection alert messages may be exchanged by the two
+peers.  Those messages may be fatal, meaning the connection must be
+terminated afterwards, or warning when something needs to be reported to
+the peer, but without interrupting the session.  The error codes
+'GNUTLS_E_WARNING_ALERT_RECEIVED' or 'GNUTLS_E_FATAL_ALERT_RECEIVED'
+signal those alerts when received, and may be returned by all GnuTLS
+functions that receive data from the peer, being *note
+gnutls_handshake:: and *note gnutls_record_recv::.
+
+If those error codes are received the alert and its level should be
+logged or reported to the peer using the functions below.
+
+ -- Function: gnutls_alert_description_t gnutls_alert_get
+          (gnutls_session_t SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     This function will return the last alert number received.  This
+     function should be called when 'GNUTLS_E_WARNING_ALERT_RECEIVED' or
+     'GNUTLS_E_FATAL_ALERT_RECEIVED' errors are returned by a gnutls
+     function.  The peer may send alerts if he encounters an error.  If
+     no alert has been received the returned value is undefined.
+
+     *Returns:* the last alert received, a 'gnutls_alert_description_t'
+     value.
+
+ -- Function: const char * gnutls_alert_get_name
+          (gnutls_alert_description_t ALERT)
+     ALERT: is an alert number.
+
+     This function will return a string that describes the given alert
+     number, or 'NULL' .  See 'gnutls_alert_get()' .
+
+     *Returns:* string corresponding to 'gnutls_alert_description_t'
+     value.
+
+The peer may also be warned or notified of a fatal issue by using one of
+the functions below.  All the available alerts are listed in *note The
+Alert Protocol::.
+
+ -- Function: int gnutls_alert_send (gnutls_session_t SESSION,
+          gnutls_alert_level_t LEVEL, gnutls_alert_description_t DESC)
+     SESSION: is a 'gnutls_session_t' type.
+
+     LEVEL: is the level of the alert
+
+     DESC: is the alert description
+
+     This function will send an alert to the peer in order to inform him
+     of something important (eg.  his Certificate could not be
+     verified).  If the alert level is Fatal then the peer is expected
+     to close the connection, otherwise he may ignore the alert and
+     continue.
+
+     The error code of the underlying record send function will be
+     returned, so you may also receive 'GNUTLS_E_INTERRUPTED' or
+     'GNUTLS_E_AGAIN' as well.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise an error code is returned.
+
+ -- Function: int gnutls_error_to_alert (int ERR, int * LEVEL)
+     ERR: is a negative integer
+
+     LEVEL: the alert level will be stored there
+
+     Get an alert depending on the error code returned by a gnutls
+     function.  All alerts sent by this function should be considered
+     fatal.  The only exception is when 'err' is 'GNUTLS_E_REHANDSHAKE'
+     , where a warning alert should be sent to the peer indicating that
+     no renegotiation will be performed.
+
+     If there is no mapping to a valid alert the alert to indicate
+     internal error ('GNUTLS_A_INTERNAL_ERROR' ) is returned.
+
+     *Returns:* the alert code to use for a particular error code.
+
+
+File: gnutls.info,  Node: Priority Strings,  Next: Selecting cryptographic key sizes,  Prev: Handling alerts,  Up: How to use GnuTLS in applications
+
+6.10 Priority strings
+=====================
+
+How to use Priority Strings
+---------------------------
+
+The GnuTLS priority strings specify the TLS session's handshake
+algorithms and options in a compact, easy-to-use format.  These strings
+are intended as a user-specified override of the library defaults.
+
+That is, we recommend applications using the default settings (c.f.
+*note gnutls_set_default_priority:: or *note
+gnutls_set_default_priority_append::), and provide the user with access
+to priority strings for overriding the default behavior, on
+configuration files, or other UI. Following such a principle, makes the
+GnuTLS library as the default settings provider.  That is necessary and
+a good practice, because TLS protocol hardening and phasing out of
+legacy algorithms, is easier to coordinate when happens in a single
+library.
+
+'INT *note gnutls_set_default_priority:: (gnutls_session_t SESSION)'
+'INT *note gnutls_set_default_priority_append:: (gnutls_session_t SESSION, const char * ADD_PRIO, const char ** ERR_POS, unsigned FLAGS)'
+'INT *note gnutls_priority_set_direct:: (gnutls_session_t SESSION, const char * PRIORITIES, const char ** ERR_POS)'
+
+The priority string translation to the internal GnuTLS form requires
+processing and the generated internal form also occupies some memory.
+For that, it is recommended to do that processing once in server side,
+and share the generated data across sessions.  The following functions
+allow the generation of a "priority cache" and the sharing of it across
+sessions.
+
+'INT *note gnutls_priority_init2:: (gnutls_priority_t * PRIORITY_CACHE, const char * PRIORITIES, const char ** ERR_POS, unsigned FLAGS)'
+'INT *note gnutls_priority_init:: (gnutls_priority_t * PRIORITY_CACHE, const char * PRIORITIES, const char ** ERR_POS)'
+'INT *note gnutls_priority_set:: (gnutls_session_t SESSION, gnutls_priority_t PRIORITY)'
+'VOID *note gnutls_priority_deinit:: (gnutls_priority_t PRIORITY_CACHE)'
+
+Using Priority Strings
+----------------------
+
+A priority string string may contain a single initial keyword such as in
+*note Table 6.3: tab:prio-keywords. and may be followed by additional
+algorithm or special keywords.  Note that their description is
+intentionally avoiding specific algorithm details, as the priority
+strings are not constant between gnutls versions (they are periodically
+updated to account for cryptographic advances while providing
+compatibility with old clients and servers).
+
+Keyword        Description
+------------------------------------------------------------------
+@KEYWORD       Means that a compile-time specified system
+               configuration file (see
+               *note System-wide configuration of the library::)
+               will be used to expand the provided keyword.
+               That is used to impose system-specific policies.
+               It may be followed by additional options that
+               will be appended to the system string (e.g.,
+               "@SYSTEM:+SRP"). The system file should have the
+               format 'KEYWORD=VALUE', e.g.,
+               'SYSTEM=NORMAL:+ARCFOUR-128'.
+               
+               Since version 3.5.1 it is allowed to specify
+               fallback keywords such as @KEYWORD1,@KEYWORD2,
+               and the first valid keyword will be used.
+               
+PERFORMANCE    All the known to be secure ciphersuites are
+               enabled, limited to 128 bit ciphers and sorted
+               by terms of speed performance.  The message
+               authenticity security level is of 64 bits or
+               more, and the certificate verification profile
+               is set to GNUTLS_PROFILE_LOW (80-bits).
+               
+NORMAL         Means all the known to be secure ciphersuites.
+               The ciphers are sorted by security margin,
+               although the 256-bit ciphers are included as a
+               fallback only.  The message authenticity
+               security level is of 64 bits or more, and the
+               certificate verification profile is set to
+               GNUTLS_PROFILE_LOW (80-bits).
+               
+               This priority string implicitly enables ECDHE
+               and DHE. The ECDHE ciphersuites are placed first
+               in the priority order, but due to compatibility
+               issues with the DHE ciphersuites they are placed
+               last in the priority order, after the plain RSA
+               ciphersuites.
+               
+LEGACY         This sets the NORMAL settings that were used for
+               GnuTLS 3.2.x or earlier.  There is no
+               verification profile set, and the allowed DH
+               primes are considered weak today (but are often
+               used by misconfigured servers).
+               
+PFS            Means all the known to be secure ciphersuites
+               that support perfect forward secrecy (ECDHE and
+               DHE). The ciphers are sorted by security margin,
+               although the 256-bit ciphers are included as a
+               fallback only.  The message authenticity
+               security level is of 80 bits or more, and the
+               certificate verification profile is set to
+               GNUTLS_PROFILE_LOW (80-bits).  This option is
+               available since 3.2.4 or later.
+               
+SECURE128      Means all known to be secure ciphersuites that
+               offer a security level 128-bit or more.  The
+               message authenticity security level is of 80
+               bits or more, and the certificate verification
+               profile is set to GNUTLS_PROFILE_LOW (80-bits).
+               
+SECURE192      Means all the known to be secure ciphersuites
+               that offer a security level 192-bit or more.
+               The message authenticity security level is of
+               128 bits or more, and the certificate
+               verification profile is set to
+               GNUTLS_PROFILE_HIGH (128-bits).
+               
+SECURE256      Currently alias for SECURE192.  This option,
+               will enable ciphers which use a 256-bit key but,
+               due to limitations of the TLS protocol, the
+               overall security level will be 192-bits (the
+               security level depends on more factors than
+               cipher key size).
+               
+SUITEB128      Means all the NSA Suite B cryptography (RFC5430)
+               ciphersuites with an 128 bit security level, as
+               well as the enabling of the corresponding
+               verification profile.
+               
+SUITEB192      Means all the NSA Suite B cryptography (RFC5430)
+               ciphersuites with an 192 bit security level, as
+               well as the enabling of the corresponding
+               verification profile.
+               
+NONE           Means nothing is enabled.  This disables even
+               protocol versions.  It should be followed by the
+               algorithms to be enabled.  Note that using this
+               option to build a priority string gives detailed
+               control into the resulting settings, however
+               with new revisions of the TLS protocol new
+               priority items are routinely added, and such
+               strings are not forward compatible with new
+               protocols.  As such, we advice against using
+               that option for applications targeting multiple
+               versions of the GnuTLS library, and recommend
+               using the defaults (see above) or adjusting the
+               defaults via
+               *note gnutls_set_default_priority_append::.
+               
+
+
+Table 6.3: Supported initial keywords.
+
+Unless the initial keyword is "NONE" the defaults (in preference order)
+are for TLS protocols TLS 1.2, TLS1.1, TLS1.0; for certificate types
+X.509.  In key exchange algorithms when in NORMAL or SECURE levels the
+perfect forward secrecy algorithms take precedence of the other
+protocols.  In all cases all the supported key exchange algorithms are
+enabled.
+
+Note that the SECURE levels distinguish between overall security level
+and message authenticity security level.  That is because the message
+authenticity security level requires the adversary to break the
+algorithms at real-time during the protocol run, whilst the overall
+security level refers to off-line adversaries (e.g.  adversaries
+breaking the ciphertext years after it was captured).
+
+The NONE keyword, if used, must followed by keywords specifying the
+algorithms and protocols to be enabled.  The other initial keywords do
+not require, but may be followed by such keywords.  All level keywords
+can be combined, and for example a level of "SECURE256:+SECURE128" is
+allowed.
+
+The order with which every algorithm or protocol is specified is
+significant.  Algorithms specified before others will take precedence.
+The supported in the GnuTLS version corresponding to this document
+algorithms and protocols are shown in *note Table 6.4:
+tab:prio-algorithms.; to list the supported algorithms in your currently
+using version use 'gnutls-cli -l'.
+
+To avoid collisions in order to specify a protocol version with "VERS-",
+signature algorithms with "SIGN-" and certificate types with "CTYPE-".
+All other algorithms don't need a prefix.  Each specified keyword
+(except for _special keywords_) can be prefixed with any of the
+following characters.
+
+'!' or '-'
+     appended with an algorithm will remove this algorithm.
+"+"
+     appended with an algorithm will add this algorithm.
+
+Type           Keywords
+------------------------------------------------------------------
+Ciphers        Examples are AES-128-GCM, AES-256-GCM,
+               AES-256-CBC, GOST28147-TC26Z-CNT; see also
+               *note Table 3.1: tab:ciphers. for more options.
+               Catch all name is CIPHER-ALL which will add all
+               the algorithms from NORMAL priority.  The
+               shortcut for secure GOST algorithms is
+               CIPHER-GOST-ALL.
+               
+Key exchange   RSA, RSA-PSK, RSA-EXPORT, DHE-RSA, DHE-DSS, SRP,
+               SRP-RSA, SRP-DSS, PSK, DHE-PSK, ECDHE-PSK,
+               ECDHE-RSA, ECDHE-ECDSA, VKO-GOST-12, ANON-ECDH,
+               ANON-DH. Catch all name is KX-ALL which will add
+               all the algorithms from NORMAL priority.  Under
+               TLS1.3, the DHE-PSK and ECDHE-PSK strings are
+               equivalent and instruct for a Diffie-Hellman key
+               exchange using the enabled groups.  The shortcut
+               for secure GOST algorithms is KX-GOST-ALL.
+               
+MAC            MD5, SHA1, SHA256, SHA384, GOST28147-TC26Z-IMIT,
+               AEAD (used with GCM ciphers only).  All
+               algorithms from NORMAL priority can be accessed
+               with MAC-ALL. The shortcut for secure GOST
+               algorithms is MAC-GOST-ALL.
+               
+Compression    COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
+algorithms     
+TLS versions   VERS-TLS1.0, VERS-TLS1.1, VERS-TLS1.2,
+               VERS-TLS1.3, VERS-DTLS0.9, VERS-DTLS1.0,
+               VERS-DTLS1.2.  Catch all are VERS-ALL, and will
+               enable all protocols from NORMAL priority.  To
+               distinguish between TLS and DTLS versions you
+               can use VERS-TLS-ALL and VERS-DTLS-ALL.
+               
+Signature      SIGN-RSA-SHA1, SIGN-RSA-SHA224, SIGN-RSA-SHA256,
+algorithms     SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1,
+               SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5,
+               SIGN-ECDSA-SHA1, SIGN-ECDSA-SHA224,
+               SIGN-ECDSA-SHA256, SIGN-ECDSA-SHA384,
+               SIGN-ECDSA-SHA512, SIGN-EdDSA-Ed25519,
+               SIGN-EdDSA-Ed448, SIGN-RSA-PSS-SHA256,
+               SIGN-RSA-PSS-SHA384, SIGN-RSA-PSS-SHA512,
+               SIGN-GOSTR341001, SIGN-GOSTR341012-256,
+               SIGN-GOSTR341012-512.  Catch all which enables
+               all algorithms from NORMAL priority is SIGN-ALL.
+               Shortcut which enables secure GOST algorithms is
+               SIGN-GOST-ALL. This option is only considered
+               for TLS 1.2 and later.
+               
+Groups         GROUP-SECP192R1, GROUP-SECP224R1,
+               GROUP-SECP256R1, GROUP-SECP384R1,
+               GROUP-SECP521R1, GROUP-X25519, GROUP-X448,
+               GROUP-GC256B, GROUP-GC512A, GROUP-FFDHE2048,
+               GROUP-FFDHE3072, GROUP-FFDHE4096,
+               GROUP-FFDHE6144, and GROUP-FFDHE8192.  Groups
+               include both elliptic curve groups, e.g.,
+               SECP256R1, as well as finite field groups such
+               as FFDHE2048.  Catch all which enables all
+               groups from NORMAL priority is GROUP-ALL. The
+               helper keywords GROUP-DH-ALL, GROUP-GOST-ALL and
+               GROUP-EC-ALL are also available, restricting the
+               groups to finite fields (DH), GOST curves and
+               generic elliptic curves.
+               
+Elliptic       CURVE-SECP192R1, CURVE-SECP224R1,
+curves         CURVE-SECP256R1, CURVE-SECP384R1,
+(legacy)       CURVE-SECP521R1, CURVE-X25519, and CURVE-X448.
+               Catch all which enables all curves from NORMAL
+               priority is CURVE-ALL. Note that the CURVE
+               keyword is kept for backwards compatibility
+               only, for new applications see the GROUP keyword
+               above.
+               
+Certificate    Certificate types can be given in a symmetric
+types          fashion (i.e.  the same for both client and
+               server) or, as of GnuTLS 3.6.4, in an asymmetric
+               fashion (i.e.  different for the client than for
+               the server).  Alternative certificate types must
+               be explicitly enabled via flags in
+               *note gnutls_init::.
+               
+               The currently supported types are CTYPE-X509,
+               CTYPE-RAWPK which apply both to client and
+               server; catch all is CTYPE-ALL. The types
+               CTYPE-CLI-X509, CTYPE-SRV-X509, CTYPE-CLI-RAWPK,
+               CTYPE-SRV-RAWPK can be used to specialize on
+               client or server; catch all is CTYPE-CLI-ALL and
+               CTYPE-SRV-ALL. The type 'X509' is aliased to
+               'X.509' for legacy reasons.
+               
+Generic        The keyword GOST is a shortcut for secure GOST
+               algorithms (MACs, ciphers, KXes, groups and
+               signatures).  For example the following string
+               will enable all TLS 1.2 GOST ciphersuites:
+               'NONE:+VERS-TLS1.2:+GOST'.
+               
+
+
+Table 6.4: The supported algorithm keywords in priority strings.
+
+Note that the finite field groups (indicated by the FFDHE prefix) and
+DHE key exchange methods are generally slower(1) than their elliptic
+curves counterpart (ECDHE).
+
+The available special keywords are shown in *note Table 6.5:
+tab:prio-special1. and *note Table 6.6: tab:prio-special2.
+
+Keyword                          Description
+                                 
+------------------------------------------------------------------
+%COMPAT                          will enable compatibility
+                                 mode.  It might mean that
+                                 violations of the protocols
+                                 are allowed as long as maximum
+                                 compatibility with problematic
+                                 clients and servers is
+                                 achieved.  More specifically
+                                 this string will tolerate
+                                 packets over the maximum
+                                 allowed TLS record, and add a
+                                 padding to TLS Client Hello
+                                 packet to prevent it being in
+                                 the 256-512 range which is
+                                 known to be causing issues
+                                 with a commonly used firewall
+                                 (see the %DUMBFW option).
+                                 
+%DUMBFW                          will add a private extension
+                                 with bogus data that make the
+                                 client hello exceed 512 bytes.
+                                 This avoids a black hole
+                                 behavior in some firewalls.
+                                 This is the [*note RFC7685::]
+                                 client hello padding
+                                 extension, also enabled with
+                                 %COMPAT.
+                                 
+%NO_EXTENSIONS                   will prevent the sending of
+                                 any TLS extensions in client
+                                 side.  Note that TLS 1.2
+                                 requires extensions to be
+                                 used, as well as safe
+                                 renegotiation thus this option
+                                 must be used with care.  When
+                                 this option is set no versions
+                                 later than TLS1.2 can be
+                                 negotiated.
+                                 
+%NO_TICKETS                      will prevent the advertizing
+                                 of the TLS session ticket
+                                 extension.
+                                 
+%NO_TICKETS_TLS12                will prevent the advertizing
+                                 of the TLS session ticket
+                                 extension in TLS 1.2.  This is
+                                 implied by the PFS keyword.
+                                 
+%NO_SESSION_HASH                 will prevent the advertizing
+                                 the TLS extended master secret
+                                 (session hash) extension.
+                                 
+%SERVER_PRECEDENCE               The ciphersuite will be
+                                 selected according to server
+                                 priorities and not the
+                                 client's.
+                                 
+%SSL3_RECORD_VERSION             will use SSL3.0 record version
+                                 in client hello.  By default
+                                 GnuTLS will set the minimum
+                                 supported version as the
+                                 client hello record version
+                                 (do not confuse that version
+                                 with the proposed handshake
+                                 version at the client hello).
+                                 
+%LATEST_RECORD_VERSION           will use the latest TLS
+                                 version record version in
+                                 client hello.
+                                 
+
+
+Table 6.5: Special priority string keywords.
+
+Keyword                          Description
+                                 
+------------------------------------------------------------------
+%STATELESS_COMPRESSION           ignored; no longer used.
+                                 
+%DISABLE_WILDCARDS               will disable matching
+                                 wildcards when comparing
+                                 hostnames in certificates.
+                                 
+%NO_ETM                          will disable the
+                                 encrypt-then-mac TLS extension
+                                 (RFC7366).  This is implied by
+                                 the %COMPAT keyword.
+                                 
+%FORCE_ETM                       negotiate CBC ciphersuites
+                                 only when both sides of the
+                                 connection support
+                                 encrypt-then-mac TLS extension
+                                 (RFC7366).
+                                 
+%DISABLE_SAFE_RENEGOTIATION      will completely disable safe
+                                 renegotiation completely.  Do
+                                 not use unless you know what
+                                 you are doing.
+                                 
+%UNSAFE_RENEGOTIATION            will allow handshakes and
+                                 re-handshakes without the safe
+                                 renegotiation extension.  Note
+                                 that for clients this mode is
+                                 insecure (you may be under
+                                 attack), and for servers it
+                                 will allow insecure clients to
+                                 connect (which could be fooled
+                                 by an attacker).  Do not use
+                                 unless you know what you are
+                                 doing and want maximum
+                                 compatibility.
+                                 
+%PARTIAL_RENEGOTIATION           will allow initial handshakes
+                                 to proceed, but not
+                                 re-handshakes.  This leaves
+                                 the client vulnerable to
+                                 attack, and servers will be
+                                 compatible with non-upgraded
+                                 clients for initial
+                                 handshakes.  This is currently
+                                 the default for clients and
+                                 servers, for compatibility
+                                 reasons.
+                                 
+%SAFE_RENEGOTIATION              will enforce safe
+                                 renegotiation.  Clients and
+                                 servers will refuse to talk to
+                                 an insecure peer.  Currently
+                                 this causes interoperability
+                                 problems, but is required for
+                                 full protection.
+                                 
+%FALLBACK_SCSV                   will enable the use of the
+                                 fallback signaling cipher
+                                 suite value in the client
+                                 hello.  Note that this should
+                                 be set only by applications
+                                 that try to reconnect with a
+                                 downgraded protocol version.
+                                 See RFC7507 for details.
+                                 
+%DISABLE_TLS13_COMPAT_MODE       will disable TLS 1.3 middlebox
+                                 compatibility mode (RFC8446,
+                                 Appendix D.4) for
+                                 non-compliant middleboxes.
+                                 
+%VERIFY_ALLOW_BROKEN             will allow signatures with
+                                 known to be broken algorithms
+                                 (such as MD5 or SHA1) in
+                                 certificate chains.
+                                 
+%VERIFY_ALLOW_SIGN_RSA_MD5       will allow RSA-MD5 signatures
+                                 in certificate chains.
+                                 
+%VERIFY_ALLOW_SIGN_WITH_SHA1     will allow signatures with
+                                 SHA1 hash algorithm in
+                                 certificate chains.
+                                 
+%VERIFY_DISABLE_CRL_CHECKS       will disable CRL or OCSP
+                                 checks in the verification of
+                                 the certificate chain.
+                                 
+%VERIFY_ALLOW_X509_V1_CA_CRT     will allow V1 CAs in chains.
+                                 
+%PROFILE_(LOW|LEGACY|MEDIUM|HIGH|ULTRA|FUTURE)require a certificate
+                                 verification profile the
+                                 corresponds to the specified
+                                 security level, see
+                                 *note Table 6.7: tab:key-sizes.
+                                 for the mappings to values.
+                                 
+%PROFILE_(SUITEB128|SUITEB192)   require a certificate
+                                 verification profile the
+                                 corresponds to SUITEB. Note
+                                 that an initial keyword that
+                                 enables SUITEB automatically
+                                 sets the profile.
+                                 
+
+
+Table 6.6: More priority string keywords.
+
+Finally the ciphersuites enabled by any priority string can be listed
+using the 'gnutls-cli' application (see *note gnutls-cli Invocation::),
+or by using the priority functions as in *note Listing the ciphersuites
+in a priority string::.
+
+Example priority strings are:
+     The system imposed security level:
+         "SYSTEM"
+
+     The default priority without the HMAC-MD5:
+         "NORMAL:-MD5"
+
+     Specifying RSA with AES-128-CBC:
+         "NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"
+
+     Specifying the defaults plus ARCFOUR-128:
+         "NORMAL:+ARCFOUR-128"
+
+     Enabling the 128-bit secure ciphers, while disabling TLS 1.0:
+         "SECURE128:-VERS-TLS1.0"
+
+     Enabling the 128-bit and 192-bit secure ciphers, while disabling all TLS versions
+     except TLS 1.2:
+         "SECURE128:+SECURE192:-VERS-ALL:+VERS-TLS1.2"
+
+   ---------- Footnotes ----------
+
+   (1) It depends on the group in use.  Groups with less bits are always
+faster, but the number of bits ties with the security parameter.  See
+*note Selecting cryptographic key sizes:: for the acceptable security
+levels.
+
+
+File: gnutls.info,  Node: Selecting cryptographic key sizes,  Next: Advanced topics,  Prev: Priority Strings,  Up: How to use GnuTLS in applications
+
+6.11 Selecting cryptographic key sizes
+======================================
+
+Because many algorithms are involved in TLS, it is not easy to set a
+consistent security level.  For this reason in *note Table 6.7:
+tab:key-sizes. we present some correspondence between key sizes of
+symmetric algorithms and public key algorithms based on [*note
+ECRYPT::].  Those can be used to generate certificates with appropriate
+key sizes as well as select parameters for Diffie-Hellman and SRP
+authentication.
+
+SecurityRSA, DH   ECC     Security       Description
+bits    and SRP   key     parameter      
+        parameter size    (profile)
+        size
+-----------------------------------------------------------------
+<64     <768      <128    'INSECURE'     Considered to be
+                                         insecure
+                                         
+64      768       128     'VERY WEAK'    Short term protection
+                                         against individuals
+                                         
+72      1008      160     'WEAK'         Short term protection
+                                         against small
+                                         organizations
+                                         
+80      1024      160     'LOW'          Very short term
+                                         protection against
+                                         agencies (corresponds
+                                         to ENISA legacy
+                                         level)
+                                         
+96      1776      192     'LEGACY'       Legacy standard level
+                                         
+112     2048      224     'MEDIUM'       Medium-term
+                                         protection
+                                         
+128     3072      256     'HIGH'         Long term protection
+                                         (corresponds to ENISA
+                                         future level)
+                                         
+192     8192      384     'ULTRA'        Even longer term
+                                         protection
+                                         
+256     15424     512     'FUTURE'       Foreseeable future
+                                         
+
+
+Table 6.7: Key sizes and security parameters.
+
+The first column provides a security parameter in a number of bits.
+This gives an indication of the number of combinations to be tried by an
+adversary to brute force a key.  For example to test all possible keys
+in a 112 bit security parameter 2^{112} combinations have to be tried.
+For today's technology this is infeasible.  The next two columns
+correlate the security parameter with actual bit sizes of parameters for
+DH, RSA, SRP and ECC algorithms.  A mapping to 'gnutls_sec_param_t'
+value is given for each security parameter, on the next column, and
+finally a brief description of the level.
+
+Note, however, that the values suggested here are nothing more than an
+educated guess that is valid today.  There are no guarantees that an
+algorithm will remain unbreakable or that these values will remain
+constant in time.  There could be scientific breakthroughs that cannot
+be predicted or total failure of the current public key systems by
+quantum computers.  On the other hand though the cryptosystems used in
+TLS are selected in a conservative way and such catastrophic
+breakthroughs or failures are believed to be unlikely.  The NIST
+publication SP 800-57 [*note NISTSP80057::] contains a similar table.
+
+When using GnuTLS and a decision on bit sizes for a public key algorithm
+is required, use of the following functions is recommended:
+
+ -- Function: unsigned int gnutls_sec_param_to_pk_bits
+          (gnutls_pk_algorithm_t ALGO, gnutls_sec_param_t PARAM)
+     ALGO: is a public key algorithm
+
+     PARAM: is a security parameter
+
+     When generating private and public key pairs a difficult question
+     is which size of "bits" the modulus will be in RSA and the group
+     size in DSA. The easy answer is 1024, which is also wrong.  This
+     function will convert a human understandable security parameter to
+     an appropriate size for the specific algorithm.
+
+     *Returns:* The number of bits, or (0).
+
+     *Since:* 2.12.0
+
+ -- Function: gnutls_sec_param_t gnutls_pk_bits_to_sec_param
+          (gnutls_pk_algorithm_t ALGO, unsigned int BITS)
+     ALGO: is a public key algorithm
+
+     BITS: is the number of bits
+
+     This is the inverse of 'gnutls_sec_param_to_pk_bits()' .  Given an
+     algorithm and the number of bits, it will return the security
+     parameter.  This is a rough indication.
+
+     *Returns:* The security parameter.
+
+     *Since:* 2.12.0
+
+Those functions will convert a human understandable security parameter
+of 'gnutls_sec_param_t' type, to a number of bits suitable for a public
+key algorithm.
+
+'CONST CHAR * *note gnutls_sec_param_get_name:: (gnutls_sec_param_t PARAM)'
+
+The following functions will set the minimum acceptable group size for
+Diffie-Hellman and SRP authentication.
+'VOID *note gnutls_dh_set_prime_bits:: (gnutls_session_t SESSION, unsigned int BITS)'
+'VOID *note gnutls_srp_set_prime_bits:: (gnutls_session_t SESSION, unsigned int BITS)'
+
+
+File: gnutls.info,  Node: Advanced topics,  Prev: Selecting cryptographic key sizes,  Up: How to use GnuTLS in applications
+
+6.12 Advanced topics
+====================
+
+* Menu:
+
+* Virtual hosts and credentials::
+* Session resumption::
+* Certificate verification::
+* TLS 1.2 re-authentication::
+* TLS 1.3 re-authentication and re-key::
+* Parameter generation::
+* Deriving keys for other applications/protocols::
+* Channel Bindings::
+* Interoperability::
+* Compatibility with the OpenSSL library::
+
+
+File: gnutls.info,  Node: Virtual hosts and credentials,  Next: Session resumption,  Up: Advanced topics
+
+6.12.1 Virtual hosts and credentials
+------------------------------------
+
+Often when operating with virtual hosts, one may not want to associate a
+particular certificate set to the credentials function early, before the
+virtual host is known.  That can be achieved by calling *note
+gnutls_credentials_set:: within a handshake pre-hook for client hello.
+That message contains the peer's intended hostname, and if read, and the
+appropriate credentials are set, gnutls will be able to continue in the
+handshake process.  A brief usage example is shown below.
+
+     static int ext_hook_func(void *ctx, unsigned tls_id,
+                              const unsigned char *data, unsigned size)
+     {
+     	if (tls_id == 0) { /* server name */
+     		/* figure the advertized name - the following hack
+                      * relies on the fact that this extension only supports
+                      * DNS names, and due to a protocol bug cannot be extended
+                      * to support anything else. */
+     		if (name < 5) return 0;
+     		name = data+5;
+     		name_size = size-5;
+     	}
+     	return 0;
+     }
+
+     static int
+     handshake_hook_func(gnutls_session_t session, unsigned int htype,
+                         unsigned when, unsigned int incoming, const gnutls_datum_t *msg)
+     {
+         int ret;
+
+         assert(htype == GNUTLS_HANDSHAKE_CLIENT_HELLO);
+         assert(when == GNUTLS_HOOK_PRE);
+
+         ret = gnutls_ext_raw_parse(NULL, ext_hook_func, msg,
+                                    GNUTLS_EXT_RAW_FLAG_TLS_CLIENT_HELLO);
+         assert(ret >= 0);
+
+         gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, cred);
+
+         return ret;
+     }
+
+     int main()
+     {
+       ...
+
+       gnutls_handshake_set_hook_function(server, GNUTLS_HANDSHAKE_CLIENT_HELLO,
+                                          GNUTLS_HOOK_PRE, handshake_hook_func);
+       ...
+     }
+
+ -- Function: void gnutls_handshake_set_hook_function (gnutls_session_t
+          SESSION, unsigned int HTYPE, int WHEN,
+          gnutls_handshake_hook_func FUNC)
+     SESSION: is a 'gnutls_session_t' type
+
+     HTYPE: the 'gnutls_handshake_description_t' of the message to hook
+     at
+
+     WHEN: 'GNUTLS_HOOK_' * depending on when the hook function should
+     be called
+
+     FUNC: is the function to be called
+
+     This function will set a callback to be called after or before the
+     specified handshake message has been received or generated.  This
+     is a generalization of
+     'gnutls_handshake_set_post_client_hello_function()' .
+
+     To call the hook function prior to the message being generated or
+     processed use 'GNUTLS_HOOK_PRE' as 'when' parameter,
+     'GNUTLS_HOOK_POST' to call after, and 'GNUTLS_HOOK_BOTH' for both
+     cases.
+
+     This callback must return 0 on success or a gnutls error code to
+     terminate the handshake.
+
+     To hook at all handshake messages use an 'htype' of
+     'GNUTLS_HANDSHAKE_ANY' .
+
+     *Warning:* You should not use this function to terminate the
+     handshake based on client input unless you know what you are doing.
+     Before the handshake is finished there is no way to know if there
+     is a man-in-the-middle attack being performed.
+
+
+File: gnutls.info,  Node: Session resumption,  Next: Certificate verification,  Prev: Virtual hosts and credentials,  Up: Advanced topics
+
+6.12.2 Session resumption
+-------------------------
+
+To reduce time and network traffic spent in a handshake the client can
+request session resumption from a server that previously shared a
+session with the client.
+
+Under TLS 1.2, in order to support resumption a server can either store
+the session security parameters in a local database or use session
+tickets (see *note Session tickets::) to delegate storage to the client.
+
+Under TLS 1.3, session resumption is only available through session
+tickets, and multiple tickets could be sent from server to client.  That
+provides the following advantages:
+   * When tickets are not re-used the subsequent client sessions cannot
+     be associated with each other by an eavesdropper
+   * On post-handshake authentication the server may send different
+     tickets asynchronously for each identity used by client.
+
+Client side
+...........
+
+The client has to retrieve and store the session parameters.  Before
+establishing a new session to the same server the parameters must be
+re-associated with the GnuTLS session using *note
+gnutls_session_set_data::.
+
+'INT *note gnutls_session_get_data2:: (gnutls_session_t SESSION, gnutls_datum_t * DATA)'
+'INT *note gnutls_session_set_data:: (gnutls_session_t SESSION, const void * SESSION_DATA, size_t SESSION_DATA_SIZE)'
+
+Keep in mind that sessions will be expired after some time, depending on
+the server, and a server may choose not to resume a session even when
+requested to.  The expiration is to prevent temporal session keys from
+becoming long-term keys.  Also note that as a client you must enable,
+using the priority functions, at least the algorithms used in the last
+session.
+
+ -- Function: int gnutls_session_is_resumed (gnutls_session_t SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     Checks whether session is resumed or not.  This is functional for
+     both server and client side.
+
+     *Returns:* non zero if this session is resumed, or a zero if this
+     is a new session.
+
+ -- Function: int gnutls_session_get_id2 (gnutls_session_t SESSION,
+          gnutls_datum_t * SESSION_ID)
+     SESSION: is a 'gnutls_session_t' type.
+
+     SESSION_ID: will point to the session ID.
+
+     Returns the TLS session identifier.  The session ID is selected by
+     the server, and in older versions of TLS was a unique identifier
+     shared between client and server which was persistent across
+     resumption.  In the latest version of TLS (1.3) or TLS 1.2 with
+     session tickets, the notion of session identifiers is undefined and
+     cannot be relied for uniquely identifying sessions across client
+     and server.
+
+     In client side this function returns the identifier returned by the
+     server, and cannot be assumed to have any relation to session
+     resumption.  In server side this function is guaranteed to return a
+     persistent identifier of the session since GnuTLS 3.6.4, which may
+     not necessarily map into the TLS session ID value.  Prior to that
+     version the value could only be considered a persistent identifier,
+     under TLS1.2 or earlier and when no session tickets were in use.
+
+     The session identifier value returned is always less than
+     'GNUTLS_MAX_SESSION_ID_SIZE' and should be treated as constant.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise an error code is returned.
+
+     *Since:* 3.1.4
+
+Server side
+...........
+
+A server enabling both session tickets and a storage for session data
+would use session tickets when clients support it and the storage
+otherwise.
+
+A storing server needs to specify callback functions to store, retrieve
+and delete session data.  These can be registered with the functions
+below.  The stored sessions in the database can be checked using *note
+gnutls_db_check_entry:: for expiration.
+
+'VOID *note gnutls_db_set_retrieve_function:: (gnutls_session_t SESSION, gnutls_db_retr_func RETR_FUNC)'
+'VOID *note gnutls_db_set_store_function:: (gnutls_session_t SESSION, gnutls_db_store_func STORE_FUNC)'
+'VOID *note gnutls_db_set_ptr:: (gnutls_session_t SESSION, void * PTR)'
+'VOID *note gnutls_db_set_remove_function:: (gnutls_session_t SESSION, gnutls_db_remove_func REM_FUNC)'
+'INT *note gnutls_db_check_entry:: (gnutls_session_t SESSION, gnutls_datum_t SESSION_ENTRY)'
+
+A server supporting session tickets must generate ticket encryption and
+authentication keys using *note gnutls_session_ticket_key_generate::.
+Those keys should be associated with the GnuTLS session using *note
+gnutls_session_ticket_enable_server::.
+
+Those will be the initial keys, but GnuTLS will rotate them regularly.
+The key rotation interval can be changed with *note
+gnutls_db_set_cache_expiration:: and will be set to three times the
+ticket expiration time (ie.  three times the value given in that
+function).  Every such interval, new keys will be generated from those
+initial keys.  This is a necessary mechanism to prevent the keys from
+becoming long-term keys and as such preserve forward-secrecy in the
+issued session tickets.  If no explicit key rotation interval is
+provided, GnuTLS will rotate them every 18 hours by default.
+
+The master key can be shared between processes or between systems.
+Processes which share the same master key will generate the same rotated
+subkeys, assuming they share the same time (irrespective of timezone
+differences).
+
+ -- Function: int gnutls_session_ticket_enable_server (gnutls_session_t
+          SESSION, const gnutls_datum_t * KEY)
+     SESSION: is a 'gnutls_session_t' type.
+
+     KEY: key to encrypt session parameters.
+
+     Request that the server should attempt session resumption using
+     session tickets, i.e., by delegating storage to the client.  'key'
+     must be initialized using 'gnutls_session_ticket_key_generate()' .
+     To avoid leaking that key, use 'gnutls_memset()' prior to releasing
+     it.
+
+     The default ticket expiration time can be overridden using
+     'gnutls_db_set_cache_expiration()' .
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
+     error code.
+
+     *Since:* 2.10.0
+
+ -- Function: int gnutls_session_ticket_key_generate (gnutls_datum_t *
+          KEY)
+     KEY: is a pointer to a 'gnutls_datum_t' which will contain a newly
+     created key.
+
+     Generate a random key to encrypt security parameters within
+     SessionTicket.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
+     error code.
+
+     *Since:* 2.10.0
+
+ -- Function: int gnutls_session_resumption_requested (gnutls_session_t
+          SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     Check whether the client has asked for session resumption.  This
+     function is valid only on server side.
+
+     *Returns:* non zero if session resumption was asked, or a zero if
+     not.
+
+The expiration time for session resumption, either in tickets or stored
+data is set using *note gnutls_db_set_cache_expiration::.  This function
+also controls the ticket key rotation period.  Currently, the session
+key rotation interval is set to 3 times the expiration time set by this
+function.
+
+Under TLS 1.3, the server sends by default 2 tickets, and can send
+additional session tickets at any time using *note
+gnutls_session_ticket_send::.
+
+ -- Function: int gnutls_session_ticket_send (gnutls_session_t SESSION,
+          unsigned NR, unsigned FLAGS)
+     SESSION: is a 'gnutls_session_t' type.
+
+     NR: the number of tickets to send
+
+     FLAGS: must be zero
+
+     Sends a fresh session ticket to the peer.  This is relevant only in
+     server side under TLS1.3.  This function may also return
+     'GNUTLS_E_AGAIN' or 'GNUTLS_E_INTERRUPTED' and in that case it must
+     be called again.
+
+     *Returns:* 'GNUTLS_E_SUCCESS' on success, or a negative error code.
+
+
+File: gnutls.info,  Node: Certificate verification,  Next: TLS 1.2 re-authentication,  Prev: Session resumption,  Up: Advanced topics
+
+6.12.3 Certificate verification
+-------------------------------
+
+In this section the functionality for additional certificate
+verification methods is listed.  These methods are intended to be used
+in addition to normal PKI verification, in order to reduce the risk of a
+compromised CA being undetected.
+
+6.12.3.1 Trust on first use
+...........................
+
+The GnuTLS library includes functionality to use an SSH-like trust on
+first use authentication.  The available functions to store and verify
+public keys are listed below.
+
+ -- Function: int gnutls_verify_stored_pubkey (const char * DB_NAME,
+          gnutls_tdb_t TDB, const char * HOST, const char * SERVICE,
+          gnutls_certificate_type_t CERT_TYPE, const gnutls_datum_t *
+          CERT, unsigned int FLAGS)
+     DB_NAME: A file specifying the stored keys (use NULL for the
+     default)
+
+     TDB: A storage structure or NULL to use the default
+
+     HOST: The peer's name
+
+     SERVICE: non-NULL if this key is specific to a service (e.g.  http)
+
+     CERT_TYPE: The type of the certificate
+
+     CERT: The raw (der) data of the certificate
+
+     FLAGS: should be 0.
+
+     This function will try to verify a raw public-key or a public-key
+     provided via a raw (DER-encoded) certificate using a list of stored
+     public keys.  The 'service' field if non-NULL should be a port
+     number.
+
+     The 'db_name' variable if non-null specifies a custom backend for
+     the retrieval of entries.  If it is NULL then the default file
+     backend will be used.  In POSIX-like systems the file backend uses
+     the $HOME/.gnutls/known_hosts file.
+
+     Note that if the custom storage backend is provided the retrieval
+     function should return 'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' if the
+     host/service pair is found but key doesn't match,
+     'GNUTLS_E_NO_CERTIFICATE_FOUND' if no such host/service with the
+     given key is found, and 0 if it was found.  The storage function
+     should return 0 on success.
+
+     As of GnuTLS 3.6.6 this function also verifies raw public keys.
+
+     *Returns:* If no associated public key is found then
+     'GNUTLS_E_NO_CERTIFICATE_FOUND' will be returned.  If a key is
+     found but does not match 'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' is
+     returned.  On success, 'GNUTLS_E_SUCCESS' (0) is returned, or a
+     negative error value on other errors.
+
+     *Since:* 3.0.13
+
+ -- Function: int gnutls_store_pubkey (const char * DB_NAME,
+          gnutls_tdb_t TDB, const char * HOST, const char * SERVICE,
+          gnutls_certificate_type_t CERT_TYPE, const gnutls_datum_t *
+          CERT, time_t EXPIRATION, unsigned int FLAGS)
+     DB_NAME: A file specifying the stored keys (use NULL for the
+     default)
+
+     TDB: A storage structure or NULL to use the default
+
+     HOST: The peer's name
+
+     SERVICE: non-NULL if this key is specific to a service (e.g.  http)
+
+     CERT_TYPE: The type of the certificate
+
+     CERT: The data of the certificate
+
+     EXPIRATION: The expiration time (use 0 to disable expiration)
+
+     FLAGS: should be 0.
+
+     This function will store a raw public-key or a public-key provided
+     via a raw (DER-encoded) certificate to the list of stored public
+     keys.  The key will be considered valid until the provided
+     expiration time.
+
+     The 'tdb' variable if non-null specifies a custom backend for the
+     storage of entries.  If it is NULL then the default file backend
+     will be used.
+
+     Unless an alternative 'tdb' is provided, the storage format is a
+     textual format consisting of a line for each host with fields
+     separated by '|'.  The contents of the fields are a
+     format-identifier which is set to 'g0', the hostname that the rest
+     of the data applies to, the numeric port or host name, the
+     expiration time in seconds since the epoch (0 for no expiration),
+     and a base64 encoding of the raw (DER) public key information
+     (SPKI) of the peer.
+
+     As of GnuTLS 3.6.6 this function also accepts raw public keys.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise a negative error value.
+
+     *Since:* 3.0.13
+
+In addition to the above the *note gnutls_store_commitment:: can be used
+to implement a key-pinning architecture as in [*note KEYPIN::].  This
+provides a way for web server to commit on a public key that is not yet
+active.
+
+ -- Function: int gnutls_store_commitment (const char * DB_NAME,
+          gnutls_tdb_t TDB, const char * HOST, const char * SERVICE,
+          gnutls_digest_algorithm_t HASH_ALGO, const gnutls_datum_t *
+          HASH, time_t EXPIRATION, unsigned int FLAGS)
+     DB_NAME: A file specifying the stored keys (use NULL for the
+     default)
+
+     TDB: A storage structure or NULL to use the default
+
+     HOST: The peer's name
+
+     SERVICE: non-NULL if this key is specific to a service (e.g.  http)
+
+     HASH_ALGO: The hash algorithm type
+
+     HASH: The raw hash
+
+     EXPIRATION: The expiration time (use 0 to disable expiration)
+
+     FLAGS: should be 0 or 'GNUTLS_SCOMMIT_FLAG_ALLOW_BROKEN' .
+
+     This function will store the provided hash commitment to the list
+     of stored public keys.  The key with the given hash will be
+     considered valid until the provided expiration time.
+
+     The 'tdb' variable if non-null specifies a custom backend for the
+     storage of entries.  If it is NULL then the default file backend
+     will be used.
+
+     Note that this function is not thread safe with the default
+     backend.
+
+     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
+     otherwise a negative error value.
+
+     *Since:* 3.0
+
+The storage and verification functions may be used with the default text
+file based back-end, or another back-end may be specified.  That should
+contain storage and retrieval functions and specified as below.
+
+'INT *note gnutls_tdb_init:: (gnutls_tdb_t * TDB)'
+'VOID *note gnutls_tdb_deinit:: (gnutls_tdb_t TDB)'
+'VOID *note gnutls_tdb_set_verify_func:: (gnutls_tdb_t TDB, gnutls_tdb_verify_func VERIFY)'
+'VOID *note gnutls_tdb_set_store_func:: (gnutls_tdb_t TDB, gnutls_tdb_store_func STORE)'
+'VOID *note gnutls_tdb_set_store_commitment_func:: (gnutls_tdb_t TDB, gnutls_tdb_store_commitment_func CSTORE)'
+
+6.12.3.2 DANE verification
+..........................
+
+Since the DANE library is not included in GnuTLS it requires programs to
+be linked against it.  This can be achieved with the following commands.
+
+     gcc -o foo foo.c `pkg-config gnutls-dane --cflags --libs`
+
+When a program uses the GNU autoconf system, then the following line or
+similar can be used to detect the presence of the library.
+
+     PKG_CHECK_MODULES([LIBDANE], [gnutls-dane >= 3.0.0])
+
+     AC_SUBST([LIBDANE_CFLAGS])
+     AC_SUBST([LIBDANE_LIBS])
+
+The high level functionality provided by the DANE library is shown
+below.
+
+ -- Function: int dane_verify_crt (dane_state_t S, const gnutls_datum_t
+          * CHAIN, unsigned CHAIN_SIZE, gnutls_certificate_type_t
+          CHAIN_TYPE, const char * HOSTNAME, const char * PROTO,
+          unsigned int PORT, unsigned int SFLAGS, unsigned int VFLAGS,
+          unsigned int * VERIFY)
+     S: A DANE state structure (may be NULL)
+
+     CHAIN: A certificate chain
+
+     CHAIN_SIZE: The size of the chain
+
+     CHAIN_TYPE: The type of the certificate chain
+
+     HOSTNAME: The hostname associated with the chain
+
+     PROTO: The protocol of the service connecting (e.g.  tcp)
+
+     PORT: The port of the service connecting (e.g.  443)
+
+     SFLAGS: Flags for the initialization of 's' (if NULL)
+
+     VFLAGS: Verification flags; an OR'ed list of 'dane_verify_flags_t'
+     .
+
+     VERIFY: An OR'ed list of 'dane_verify_status_t' .
+
+     This function will verify the given certificate chain against the
+     CA constrains and/or the certificate available via DANE. If no
+     information via DANE can be obtained the flag
+     'DANE_VERIFY_NO_DANE_INFO' is set.  If a DNSSEC signature is not
+     available for the DANE record then the verify flag
+     'DANE_VERIFY_NO_DNSSEC_DATA' is set.
+
+     Due to the many possible options of DANE, there is no single threat
+     model countered.  When notifying the user about DANE verification
+     results it may be better to mention: DANE verification did not
+     reject the certificate, rather than mentioning a successful DANE
+     verication.
+
+     Note that this function is designed to be run in addition to PKIX -
+     certificate chain - verification.  To be run independently the
+     'DANE_VFLAG_ONLY_CHECK_EE_USAGE' flag should be specified; then the
+     function will check whether the key of the peer matches the key
+     advertized in the DANE entry.
+
+     *Returns:* a negative error code on error and 'DANE_E_SUCCESS' (0)
+     when the DANE entries were successfully parsed, irrespective of
+     whether they were verified (see 'verify' for that information).  If
+     no usable entries were encountered
+     'DANE_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.
+
+'INT *note dane_verify_session_crt:: (dane_state_t S, gnutls_session_t SESSION, const char * HOSTNAME, const char * PROTO, unsigned int PORT, unsigned int SFLAGS, unsigned int VFLAGS, unsigned int * VERIFY)'
+'CONST CHAR * *note dane_strerror:: (int ERROR)'
+
+Note that the 'dane_state_t' structure that is accepted by both
+verification functions is optional.  It is required when many queries
+are performed to optimize against multiple re-initializations of the
+resolving back-end and loading of DNSSEC keys.
+
+The following flags are returned by the verify functions to indicate the
+status of the verification.
+
+'DANE_VERIFY_CA_CONSTRAINTS_VIOLATED'
+     The CA constraints were violated.
+'DANE_VERIFY_CERT_DIFFERS'
+     The certificate obtained via DNS differs.
+'DANE_VERIFY_UNKNOWN_DANE_INFO'
+     No known DANE data was found in the DNS record.
+
+
+Figure 6.3: The DANE verification status flags.
+
+In order to generate a DANE TLSA entry to use in a DNS server you may
+use danetool (see *note danetool Invocation::).
+
+
+File: gnutls.info,  Node: TLS 1.2 re-authentication,  Next: TLS 1.3 re-authentication and re-key,  Prev: Certificate verification,  Up: Advanced topics
+
+6.12.4 TLS 1.2 re-authentication
+--------------------------------
+
+In TLS 1.2 or earlier there is no distinction between re-key,
+re-authentication, and re-negotiation.  All of these use cases are
+handled by the TLS' rehandshake process.  For that reason in GnuTLS
+rehandshake is not transparent to the application, and the application
+must explicitly take control of that process.  In addition GnuTLS since
+version 3.5.0 will not allow the peer to switch identities during a
+rehandshake.  The threat addressed by that behavior depends on the
+application protocol, but primarily it protects applications from being
+misled by a rehandshake which switches the peer's identity.
+Applications can disable this protection by using the
+'GNUTLS_ALLOW_ID_CHANGE' flag in *note gnutls_init::.
+
+The following paragraphs explain how to safely use the rehandshake
+process.
+
+6.12.4.1 Client side
+....................
+
+According to the TLS specification a client may initiate a rehandshake
+at any time.  That can be achieved by calling *note gnutls_handshake::
+and rely on its return value for the outcome of the handshake (the
+server may deny a rehandshake).  If a server requests a re-handshake,
+then a call to *note gnutls_record_recv:: will return
+GNUTLS_E_REHANDSHAKE in the client, instructing it to call *note
+gnutls_handshake::.  To deny a rehandshake request by the server it is
+recommended to send a warning alert of type GNUTLS_A_NO_RENEGOTIATION.
+
+Due to limitations of early protocol versions, it is required to check
+whether safe renegotiation is in place, i.e., using *note
+gnutls_safe_renegotiation_status::, which ensures that the server
+remains the same as the initial.
+
+To make re-authentication transparent to the application when requested
+by the server, use the 'GNUTLS_AUTO_REAUTH' flag on the *note
+gnutls_init:: call.  In that case the re-authentication will happen in
+the call of *note gnutls_record_recv:: that received the
+reauthentication request.
+
+ -- Function: unsigned gnutls_safe_renegotiation_status
+          (gnutls_session_t SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     Can be used to check whether safe renegotiation is being used in
+     the current session.
+
+     *Returns:* 0 when safe renegotiation is not used and non (0) when
+     safe renegotiation is used.
+
+     *Since:* 2.10.0
+
+6.12.4.2 Server side
+....................
+
+A server which wants to instruct the client to re-authenticate, should
+call *note gnutls_rehandshake:: and wait for the client to
+re-authenticate.  It is recommended to only request re-handshake when
+safe renegotiation is enabled for that session (see *note
+gnutls_safe_renegotiation_status:: and the discussion in *note Safe
+renegotiation::).  A server could also encounter the
+GNUTLS_E_REHANDSHAKE error code while receiving data.  That indicates a
+client-initiated re-handshake request.  In that case the server could
+ignore that request, perform handshake (unsafe when done generally), or
+even drop the connection.
+
+ -- Function: int gnutls_rehandshake (gnutls_session_t SESSION)
+     SESSION: is a 'gnutls_session_t' type.
+
+     This function can only be called in server side, and instructs a
+     TLS 1.2 or earlier client to renegotiate parameters (perform a
+     handshake), by sending a hello request message.
+
+     If this function succeeds, the calling application should call
+     'gnutls_record_recv()' until 'GNUTLS_E_REHANDSHAKE' is returned to
+     clear any pending data.  If the 'GNUTLS_E_REHANDSHAKE' error code
+     is not seen, then the handshake request was not followed by the
+     peer (the TLS protocol does not require the client to do, and such
+     compliance should be handled by the application protocol).
+
+     Once the 'GNUTLS_E_REHANDSHAKE' error code is seen, the calling
+     application should proceed to calling 'gnutls_handshake()' to
+     negotiate the new parameters.
+
+     If the client does not wish to renegotiate parameters he may reply
+     with an alert message, and in that case the return code seen by
+     subsequent 'gnutls_record_recv()' will be
+     'GNUTLS_E_WARNING_ALERT_RECEIVED' with the specific alert being
+     'GNUTLS_A_NO_RENEGOTIATION' .  A client may also choose to ignore
+     this request.
+
+     Under TLS 1.3 this function is equivalent to
+     'gnutls_session_key_update()' with the 'GNUTLS_KU_PEER' flag.  In
+     that case subsequent calls to 'gnutls_record_recv()' will not
+     return 'GNUTLS_E_REHANDSHAKE' , and calls to 'gnutls_handshake()'
+     in server side are a no-op.
+
+     This function always fails with 'GNUTLS_E_INVALID_REQUEST' when
+     called in client side.
+
+     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
+     error code.
+
+
+File: gnutls.info,  Node: TLS 1.3 re-authentication and re-key,  Next: Parameter generation,  Prev: TLS 1.2 re-authentication,  Up: Advanced topics
+
+6.12.5 TLS 1.3 re-authentication and re-key
+-------------------------------------------
+
+The TLS 1.3 protocol distinguishes between re-key and re-authentication.
+The re-key process ensures that fresh keys are supplied to the already
+negotiated parameters, and on GnuTLS can be initiated using *note
+gnutls_session_key_update::.  The re-key process can be one-way (i.e.,
+the calling party only changes its keys), or two-way where the peer is
+requested to change keys as well.
+
+The re-authentication process, allows the connected client to switch
+identity by presenting a new certificate.  Unlike TLS 1.2, the server is
+not allowed to change identities.  That client re-authentication, or
+post-handshake authentication can be initiated only by the server using
+*note gnutls_reauth::, and only if a client has advertized support for
+it.  Both server and client have to explicitly enable support for post
+handshake authentication using the 'GNUTLS_POST_HANDSHAKE_AUTH' flag at
+*note gnutls_init::.
+
+A client receiving a re-authentication request will "see" the error code
+'GNUTLS_E_REAUTH_REQUEST' at *note gnutls_record_recv::.  At this point,
+it should also call *note gnutls_reauth::.
+
+To make re-authentication transparent to the application when requested
+by the server, use the 'GNUTLS_AUTO_REAUTH' and
+'GNUTLS_POST_HANDSHAKE_AUTH' flags on the *note gnutls_init:: call.  In
+that case the re-authentication will happen in the call of *note
+gnutls_record_recv:: that received the reauthentication request.
+
+
+File: gnutls.info,  Node: Parameter generation,  Next: Deriving keys for other applications/protocols,  Prev: TLS 1.3 re-authentication and re-key,  Up: Advanced topics
+
+6.12.6 Parameter generation
+---------------------------
+
+Prior to GnuTLS 3.6.0 for the ephemeral or anonymous Diffie-Hellman (DH)
+TLS ciphersuites the application was required to generate or provide DH
+parameters.  That is no longer necessary as GnuTLS utilizes DH
+parameters and negotiation from [*note RFC7919::].
+
+Applications can tune the used parameters by explicitly specifying them
+in the priority string.  In server side applications can set the minimum
+acceptable level of DH parameters by calling *note
+gnutls_certificate_set_known_dh_params::, *note
+gnutls_anon_set_server_known_dh_params::, or *note
+gnutls_psk_set_server_known_dh_params::, depending on the type of the
+credentials, to set the lower acceptable parameter limits.  Typical
+applications should rely on the default settings.
+
+'INT *note gnutls_certificate_set_known_dh_params:: (gnutls_certificate_credentials_t RES, gnutls_sec_param_t SEC_PARAM)'
+'INT *note gnutls_anon_set_server_known_dh_params:: (gnutls_anon_server_credentials_t RES, gnutls_sec_param_t SEC_PARAM)'
+'INT *note gnutls_psk_set_server_known_dh_params:: (gnutls_psk_server_credentials_t RES, gnutls_sec_param_t SEC_PARAM)'
+
+6.12.6.1 Legacy parameter generation
+....................................
+
+Note that older than 3.5.6 versions of GnuTLS provided functions to
+generate or import arbitrary DH parameters from a file.  This practice
+is still supported but discouraged in current versions.  There is no
+known advantage from using random parameters, while there have been
+several occasions where applications were utilizing incorrect, weak or
+insecure parameters.  This is the main reason GnuTLS includes the
+well-known parameters of [*note RFC7919::] and recommends applications
+utilizing them.
+
+In older applications which require to specify explicit DH parameters,
+we recommend using 'certtool' (of GnuTLS 3.5.6 or later) with the
+'--get-dh-params' option to obtain the FFDHE parameters discussed above.
+The output parameters of the tool are in PKCS#3 format and can be
+imported by most existing applications.
+
+The following functions are still supported but considered obsolete.
+
+'INT *note gnutls_dh_params_generate2:: (gnutls_dh_params_t DPARAMS, unsigned int BITS)'
+'INT *note gnutls_dh_params_import_pkcs3:: (gnutls_dh_params_t PARAMS, const gnutls_datum_t * PKCS3_PARAMS, gnutls_x509_crt_fmt_t FORMAT)'
+'VOID *note gnutls_certificate_set_dh_params:: (gnutls_certificate_credentials_t RES, gnutls_dh_params_t DH_PARAMS)'
+
+
+File: gnutls.info,  Node: Deriving keys for other applications/protocols,  Next: Channel Bindings,  Prev: Parameter generation,  Up: Advanced topics
+
+6.12.7 Deriving keys for other applications/protocols
+-----------------------------------------------------
+
+In several cases, after a TLS connection is established, it is desirable
+to derive keys to be used in another application or protocol (e.g., in
+an other TLS session using pre-shared keys).  The following describe
+GnuTLS' implementation of RFC5705 to extract keys based on a session's
+master secret.
+
+The API to use is *note gnutls_prf_rfc5705::.  The function needs to be
+provided with a label, and additional context data to mix in the
+'context' parameter.
+
+ -- Function: int gnutls_prf_rfc5705 (gnutls_session_t SESSION, size_t
+          LABEL_SIZE, const char * LABEL, size_t CONTEXT_SIZE, const
+          char * CONTEXT, size_t OUTSIZE, char * OUT)
+     SESSION: is a 'gnutls_session_t' type.
+
+     LABEL_SIZE: length of the 'label' variable.
+
+     LABEL: label used in PRF computation, typically a short string.
+
+     CONTEXT_SIZE: length of the 'extra' variable.
+
+     CONTEXT: optional extra data to seed the PRF with.
+
+     OUTSIZE: size of pre-allocated output buffer to hold the output.
+
+     OUT: pre-allocated buffer to hold the generated data.
+
+     Exports keying material from TLS/DTLS session to an application, as
+     specified in RFC5705.
+
+     In the TLS versions prior to 1.3, it applies the TLS
+     Pseudo-Random-Function (PRF) on the master secret and the provided
+     data, seeded with the client and server random fields.
+
+     In TLS 1.3, it applies HKDF on the exporter master secret derived
+     from the master secret.
+
+     The 'label' variable usually contains a string denoting the purpose
+     for the generated data.
+
+     The 'context' variable can be used to add more data to the seed,
+     after the random variables.  It can be used to make sure the
+     generated output is strongly connected to some additional data
+     (e.g., a string used in user authentication).
+
+     The output is placed in 'out' , which must be pre-allocated.
+
+     Note that, to provide the RFC5705 context, the 'context' variable
+     must be non-null.
+
+     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
+
+     *Since:* 3.4.4
+
+For example, after establishing a TLS session using *note
+gnutls_handshake::, you can obtain 32-bytes to be used as key, using
+this call:
+
+     #define MYLABEL "EXPORTER-My-protocol-name"
+     #define MYCONTEXT "my-protocol's-1st-session"
+
+     char out[32];
+     rc = gnutls_prf_rfc5705 (session, sizeof(MYLABEL)-1, MYLABEL,
+                              sizeof(MYCONTEXT)-1, MYCONTEXT, 32, out);
+
+The output key depends on TLS' master secret, and is the same on both
+client and server.
+
+For legacy applications which need to use a more flexible API, there is
+*note gnutls_prf::, which in addition, allows to switch the mix of the
+client and server random nonces, using the 'server_random_first'
+parameter.  For additional flexibility and low-level access to the
+TLS1.2 PRF, there is a low-level TLS PRF interface called *note
+gnutls_prf_raw::.  That however is not functional under newer protocol
+versions.
+
+
+File: gnutls.info,  Node: Channel Bindings,  Next: Interoperability,  Prev: Deriving keys for other applications/protocols,  Up: Advanced topics
+
+6.12.8 Channel bindings
+-----------------------
+
+In user authentication protocols (e.g., EAP or SASL mechanisms) it is
+useful to have a unique string that identifies the secure channel that
+is used, to bind together the user authentication with the secure
+channel.  This can protect against man-in-the-middle attacks in some
+situations.  That unique string is called a "channel binding".  For
+background and discussion see [*note RFC5056::].
+
+In GnuTLS you can extract a channel binding using the *note
+gnutls_session_channel_binding:: function.  Currently only the following
+types are supported:
+
+   * 'GNUTLS_CB_TLS_UNIQUE': corresponds to the 'tls-unique' channel
+     binding for TLS defined in [*note RFC5929::]
+   * 'GNUTLS_CB_TLS_EXPORTER': corresponds to the 'tls-exporter' channel
+     binding for TLS defined in [*note RFC9266::]
+
+The following example describes how to print the channel binding data.
+Note that it must be run after a successful TLS handshake.
+
+     {
+       gnutls_datum_t cb;
+       int rc;
+
+       rc = gnutls_session_channel_binding (session,
+                                            GNUTLS_CB_TLS_UNIQUE,
+                                            &cb);
+       if (rc)
+         fprintf (stderr, "Channel binding error: %s\n",
+                  gnutls_strerror (rc));
+       else
+         {
+           size_t i;
+           printf ("- Channel binding 'tls-unique': ");
+           for (i = 0; i < cb.size; i++)
+             printf ("%02x", cb.data[i]);
+           printf ("\n");
+         }
+     }
+
+
+File: gnutls.info,  Node: Interoperability,  Next: Compatibility with the OpenSSL library,  Prev: Channel Bindings,  Up: Advanced topics
+
+6.12.9 Interoperability
+-----------------------
+
+The TLS protocols support many ciphersuites, extensions and version
+numbers.  As a result, few implementations are not able to properly
+interoperate once faced with extensions or version protocols they do not
+support and understand.  The TLS protocol allows for a graceful
+downgrade to the commonly supported options, but practice shows it is
+not always implemented correctly.
+
+Because there is no way to achieve maximum interoperability with broken
+peers without sacrificing security, GnuTLS ignores such peers by
+default.  This might not be acceptable in cases where maximum
+compatibility is required.  Thus we allow enabling compatibility with
+broken peers using priority strings (see *note Priority Strings::).  A
+conservative priority string that would disable certain TLS protocol
+options that are known to cause compatibility problems, is shown below.
+NORMAL:%COMPAT
+
+For very old broken peers that do not tolerate TLS version numbers over
+TLS 1.0 another priority string is:
+NORMAL:-VERS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
+This priority string will in addition to above, only enable SSL 3.0 and
+TLS 1.0 as protocols.
+
+
+File: gnutls.info,  Node: Compatibility with the OpenSSL library,  Prev: Interoperability,  Up: Advanced topics
+
+6.12.10 Compatibility with the OpenSSL library
+----------------------------------------------
+
+To ease GnuTLS' integration with existing applications, a compatibility
+layer with the OpenSSL library is included in the 'gnutls-openssl'
+library.  This compatibility layer is not complete and it is not
+intended to completely re-implement the OpenSSL API with GnuTLS.  It
+only provides limited source-level compatibility.
+
+The prototypes for the compatibility functions are in the
+'gnutls/openssl.h' header file.  The limitations imposed by the
+compatibility layer include:
+
+   * Error handling is not thread safe.
+
+
+File: gnutls.info,  Node: GnuTLS application examples,  Next: System-wide configuration of the library,  Prev: How to use GnuTLS in applications,  Up: Top
+
+7 GnuTLS application examples
+*****************************
+
+In this chapter several examples of real-world use cases are listed.
+The examples are simplified to promote readability and contain little or
+no error checking.
+
+* Menu:
+
+* Client examples::
+* Server examples::
+* More advanced client and servers::
+* OCSP example::
+* Miscellaneous examples::
+
+
+File: gnutls.info,  Node: Client examples,  Next: Server examples,  Up: GnuTLS application examples
+
+7.1 Client examples
+===================
+
+This section contains examples of TLS and SSL clients, using GnuTLS.
+Note that some of the examples require functions implemented by another
+example.
+
+* Menu:
+
+* Client example with X.509 certificate support::
+* Datagram TLS client example::
+* Client using a smart card with TLS::
+* Client with Resume capability example::
+* Client example with SSH-style certificate verification::
+
+
+File: gnutls.info,  Node: Client example with X.509 certificate support,  Next: Datagram TLS client example,  Up: Client examples
+
+7.1.1 Client example with X.509 certificate support
+---------------------------------------------------
+
+Let's assume now that we want to create a TCP client which communicates
+with servers that use X.509 certificate authentication.  The following
+client is a very simple TLS client, which uses the high level
+verification functions for certificates, but does not support session
+resumption.
+
+Note that this client utilizes functionality present in the latest
+GnuTLS version.  For a reasonably portable version see *note Legacy
+client example with X.509 certificate support::.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+#include "examples.h"
+
+/* A very basic TLS client, with X.509 authentication and server certificate
+ * verification. Note that error recovery is minimal for simplicity.
+ */
+
+#define CHECK(x) assert((x)>=0)
+#define LOOP_CHECK(rval, cmd) \
+        do { \
+                rval = cmd; \
+        } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED); \
+        assert(rval >= 0)
+
+#define MAX_BUF 1024
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+extern int tcp_connect(void);
+extern void tcp_close(int sd);
+
+int main(void)
+{
+        int ret, sd, ii;
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1], *desc;
+        gnutls_datum_t out;
+        int type;
+        unsigned status;
+        gnutls_certificate_credentials_t xcred;
+
+        if (gnutls_check_version("3.4.6") == NULL) {
+                fprintf(stderr, "GnuTLS 3.4.6 or later is required for this example\n");
+                exit(1);
+        }
+
+        /* for backwards compatibility with gnutls < 3.3.0 */
+        CHECK(gnutls_global_init());
+
+        /* X509 stuff */
+        CHECK(gnutls_certificate_allocate_credentials(&xcred));
+
+        /* sets the system trusted CAs for Internet PKI */
+        CHECK(gnutls_certificate_set_x509_system_trust(xcred));
+
+        /* If client holds a certificate it can be set using the following:
+         *
+         gnutls_certificate_set_x509_key_file (xcred, "cert.pem", "key.pem", 
+         GNUTLS_X509_FMT_PEM); 
+         */
+
+        /* Initialize TLS session */
+        CHECK(gnutls_init(&session, GNUTLS_CLIENT));
+
+        CHECK(gnutls_server_name_set(session, GNUTLS_NAME_DNS, "www.example.com",
+                                     strlen("www.example.com")));
+
+        /* It is recommended to use the default priorities */
+        CHECK(gnutls_set_default_priority(session));
+
+        /* put the x509 credentials to the current session
+         */
+        CHECK(gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, xcred));
+        gnutls_session_set_verify_cert(session, "www.example.com", 0);
+
+        /* connect to the peer
+         */
+        sd = tcp_connect();
+
+        gnutls_transport_set_int(session, sd);
+        gnutls_handshake_set_timeout(session,
+                                     GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
+
+        /* Perform the TLS handshake
+         */
+        do {
+                ret = gnutls_handshake(session);
+        }
+        while (ret < 0 && gnutls_error_is_fatal(ret) == 0);
+        if (ret < 0) {
+                if (ret == GNUTLS_E_CERTIFICATE_VERIFICATION_ERROR) {
+                        /* check certificate verification status */
+                        type = gnutls_certificate_type_get(session);
+                        status = gnutls_session_get_verify_cert_status(session);
+                        CHECK(gnutls_certificate_verification_status_print(status,
+                              type, &out, 0));
+                        printf("cert verify output: %s\n", out.data);
+                        gnutls_free(out.data);
+                }
+                fprintf(stderr, "*** Handshake failed: %s\n", gnutls_strerror(ret));
+                goto end;
+        } else {
+                desc = gnutls_session_get_desc(session);
+                printf("- Session info: %s\n", desc);
+                gnutls_free(desc);
+        }
+
+	/* send data */
+        LOOP_CHECK(ret, gnutls_record_send(session, MSG, strlen(MSG)));
+
+        LOOP_CHECK(ret, gnutls_record_recv(session, buffer, MAX_BUF));
+        if (ret == 0) {
+                printf("- Peer has closed the TLS connection\n");
+                goto end;
+        } else if (ret < 0 && gnutls_error_is_fatal(ret) == 0) {
+                fprintf(stderr, "*** Warning: %s\n", gnutls_strerror(ret));
+        } else if (ret < 0) {
+                fprintf(stderr, "*** Error: %s\n", gnutls_strerror(ret));
+                goto end;
+        }
+
+        if (ret > 0) {
+                printf("- Received %d bytes: ", ret);
+                for (ii = 0; ii < ret; ii++) {
+                        fputc(buffer[ii], stdout);
+                }
+                fputs("\n", stdout);
+        }
+
+        CHECK(gnutls_bye(session, GNUTLS_SHUT_RDWR));
+
+      end:
+
+        tcp_close(sd);
+
+        gnutls_deinit(session);
+
+        gnutls_certificate_free_credentials(xcred);
+
+        gnutls_global_deinit();
+
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Datagram TLS client example,  Next: Client using a smart card with TLS,  Prev: Client example with X.509 certificate support,  Up: Client examples
+
+7.1.2 Datagram TLS client example
+---------------------------------
+
+This is a client that uses UDP to connect to a server.  This is the DTLS
+equivalent to the TLS example with X.509 certificates.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <arpa/inet.h>
+#include <assert.h>
+#include <unistd.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/dtls.h>
+
+/* A very basic Datagram TLS client, over UDP with X.509 authentication.
+ */
+
+#define CHECK(x) assert((x)>=0)
+#define LOOP_CHECK(rval, cmd) \
+        do { \
+                rval = cmd; \
+        } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED); \
+        assert(rval >= 0)
+
+#define MAX_BUF 1024
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+extern int udp_connect(void);
+extern void udp_close(int sd);
+extern int verify_certificate_callback(gnutls_session_t session);
+
+int main(void)
+{
+        int ret, sd, ii;
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1];
+        gnutls_certificate_credentials_t xcred;
+
+        if (gnutls_check_version("3.1.4") == NULL) {
+                fprintf(stderr, "GnuTLS 3.1.4 or later is required for this example\n");
+                exit(1);
+        }
+
+        /* for backwards compatibility with gnutls < 3.3.0 */
+        CHECK(gnutls_global_init());
+
+        /* X509 stuff */
+        CHECK(gnutls_certificate_allocate_credentials(&xcred));
+
+        /* sets the system trusted CAs for Internet PKI */
+        CHECK(gnutls_certificate_set_x509_system_trust(xcred));
+
+        /* Initialize TLS session */
+        CHECK(gnutls_init(&session, GNUTLS_CLIENT | GNUTLS_DATAGRAM));
+
+        /* Use default priorities */
+        CHECK(gnutls_set_default_priority(session));
+
+        /* put the x509 credentials to the current session */
+        CHECK(gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, xcred));
+        CHECK(gnutls_server_name_set(session, GNUTLS_NAME_DNS, "www.example.com",
+                                     strlen("www.example.com")));
+
+        gnutls_session_set_verify_cert(session, "www.example.com", 0);
+
+        /* connect to the peer */
+        sd = udp_connect();
+
+        gnutls_transport_set_int(session, sd);
+
+        /* set the connection MTU */
+        gnutls_dtls_set_mtu(session, 1000);
+        /* gnutls_dtls_set_timeouts(session, 1000, 60000); */
+
+        /* Perform the TLS handshake */
+        do {
+                ret = gnutls_handshake(session);
+        }
+        while (ret == GNUTLS_E_INTERRUPTED || ret == GNUTLS_E_AGAIN);
+        /* Note that DTLS may also receive GNUTLS_E_LARGE_PACKET */
+
+        if (ret < 0) {
+                fprintf(stderr, "*** Handshake failed\n");
+                gnutls_perror(ret);
+                goto end;
+        } else {
+                char *desc;
+
+                desc = gnutls_session_get_desc(session);
+                printf("- Session info: %s\n", desc);
+                gnutls_free(desc);
+        }
+
+        LOOP_CHECK(ret, gnutls_record_send(session, MSG, strlen(MSG)));
+
+        LOOP_CHECK(ret, gnutls_record_recv(session, buffer, MAX_BUF));
+        if (ret == 0) {
+                printf("- Peer has closed the TLS connection\n");
+                goto end;
+        } else if (ret < 0 && gnutls_error_is_fatal(ret) == 0) {
+                fprintf(stderr, "*** Warning: %s\n", gnutls_strerror(ret));
+        } else if (ret < 0) {
+                fprintf(stderr, "*** Error: %s\n", gnutls_strerror(ret));
+                goto end;
+        }
+
+        if (ret > 0) {
+                printf("- Received %d bytes: ", ret);
+                for (ii = 0; ii < ret; ii++) {
+                        fputc(buffer[ii], stdout);
+                }
+                fputs("\n", stdout);
+        }
+
+        /* It is suggested not to use GNUTLS_SHUT_RDWR in DTLS
+         * connections because the peer's closure message might
+         * be lost */
+        CHECK(gnutls_bye(session, GNUTLS_SHUT_WR));
+
+      end:
+
+        udp_close(sd);
+
+        gnutls_deinit(session);
+
+        gnutls_certificate_free_credentials(xcred);
+
+        gnutls_global_deinit();
+
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Client using a smart card with TLS,  Next: Client with Resume capability example,  Prev: Datagram TLS client example,  Up: Client examples
+
+7.1.3 Using a smart card with TLS
+---------------------------------
+
+This example will demonstrate how to load keys and certificates from a
+smart-card or any other PKCS #11 token, and use it in a TLS connection.
+The difference between this and the *note Client example with X.509
+certificate support:: is that the client keys are provided as PKCS #11
+URIs instead of files.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <arpa/inet.h>
+#include <unistd.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+#include <gnutls/pkcs11.h>
+#include <assert.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+#include <getpass.h>            /* for getpass() */
+
+/* A TLS client that loads the certificate and key.
+ */
+
+#define CHECK(x) assert((x)>=0)
+
+#define MAX_BUF 1024
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+#define MIN(x,y) (((x)<(y))?(x):(y))
+
+#define CAFILE "/etc/ssl/certs/ca-certificates.crt"
+
+/* The URLs of the objects can be obtained
+ * using p11tool --list-all --login
+ */
+#define KEY_URL "pkcs11:manufacturer=SomeManufacturer;object=Private%20Key" \
+  ";objecttype=private;id=%db%5b%3e%b5%72%33"
+#define CERT_URL "pkcs11:manufacturer=SomeManufacturer;object=Certificate;" \
+  "objecttype=cert;id=db%5b%3e%b5%72%33"
+
+extern int tcp_connect(void);
+extern void tcp_close(int sd);
+
+static int
+pin_callback(void *user, int attempt, const char *token_url,
+             const char *token_label, unsigned int flags, char *pin,
+             size_t pin_max)
+{
+        const char *password;
+        int len;
+
+        printf("PIN required for token '%s' with URL '%s'\n", token_label,
+               token_url);
+        if (flags & GNUTLS_PIN_FINAL_TRY)
+                printf("*** This is the final try before locking!\n");
+        if (flags & GNUTLS_PIN_COUNT_LOW)
+                printf("*** Only few tries left before locking!\n");
+        if (flags & GNUTLS_PIN_WRONG)
+                printf("*** Wrong PIN\n");
+
+        password = getpass("Enter pin: ");
+        /* FIXME: ensure that we are in UTF-8 locale */
+        if (password == NULL || password[0] == 0) {
+                fprintf(stderr, "No password given\n");
+                exit(1);
+        }
+
+        len = MIN(pin_max - 1, strlen(password));
+        memcpy(pin, password, len);
+        pin[len] = 0;
+
+        return 0;
+}
+
+int main(void)
+{
+        int ret, sd, ii;
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1];
+        gnutls_certificate_credentials_t xcred;
+        /* Allow connections to servers that have OpenPGP keys as well.
+         */
+
+        if (gnutls_check_version("3.1.4") == NULL) {
+                fprintf(stderr, "GnuTLS 3.1.4 or later is required for this example\n");
+                exit(1);
+        }
+
+        /* for backwards compatibility with gnutls < 3.3.0 */
+        CHECK(gnutls_global_init());
+
+        /* The PKCS11 private key operations may require PIN.
+         * Register a callback. */
+        gnutls_pkcs11_set_pin_function(pin_callback, NULL);
+
+        /* X509 stuff */
+        CHECK(gnutls_certificate_allocate_credentials(&xcred));
+
+        /* sets the trusted cas file
+         */
+        CHECK(gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
+                                                     GNUTLS_X509_FMT_PEM));
+
+        CHECK(gnutls_certificate_set_x509_key_file(xcred, CERT_URL, KEY_URL,
+                                                   GNUTLS_X509_FMT_DER));
+
+        /* Note that there is no server certificate verification in this example
+         */
+
+
+        /* Initialize TLS session
+         */
+        CHECK(gnutls_init(&session, GNUTLS_CLIENT));
+
+        /* Use default priorities */
+        CHECK(gnutls_set_default_priority(session));
+
+        /* put the x509 credentials to the current session
+         */
+        CHECK(gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, xcred));
+
+        /* connect to the peer
+         */
+        sd = tcp_connect();
+
+        gnutls_transport_set_int(session, sd);
+
+        /* Perform the TLS handshake
+         */
+        ret = gnutls_handshake(session);
+
+        if (ret < 0) {
+                fprintf(stderr, "*** Handshake failed\n");
+                gnutls_perror(ret);
+                goto end;
+        } else {
+                char *desc;
+
+                desc = gnutls_session_get_desc(session);
+                printf("- Session info: %s\n", desc);
+                gnutls_free(desc);
+        }
+
+        CHECK(gnutls_record_send(session, MSG, strlen(MSG)));
+
+        ret = gnutls_record_recv(session, buffer, MAX_BUF);
+        if (ret == 0) {
+                printf("- Peer has closed the TLS connection\n");
+                goto end;
+        } else if (ret < 0) {
+                fprintf(stderr, "*** Error: %s\n", gnutls_strerror(ret));
+                goto end;
+        }
+
+        printf("- Received %d bytes: ", ret);
+        for (ii = 0; ii < ret; ii++) {
+                fputc(buffer[ii], stdout);
+        }
+        fputs("\n", stdout);
+
+        CHECK(gnutls_bye(session, GNUTLS_SHUT_RDWR));
+
+      end:
+
+        tcp_close(sd);
+
+        gnutls_deinit(session);
+
+        gnutls_certificate_free_credentials(xcred);
+
+        gnutls_global_deinit();
+
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Client with Resume capability example,  Next: Client example with SSH-style certificate verification,  Prev: Client using a smart card with TLS,  Up: Client examples
+
+7.1.4 Client with resume capability example
+-------------------------------------------
+
+This is a modification of the simple client example.  Here we
+demonstrate the use of session resumption.  The client tries to connect
+once using TLS, close the connection and then try to establish a new
+connection using the previously negotiated data.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <assert.h>
+#include <gnutls/gnutls.h>
+
+extern void check_alert(gnutls_session_t session, int ret);
+extern int tcp_connect(void);
+extern void tcp_close(int sd);
+
+/* A very basic TLS client, with X.509 authentication and server certificate
+ * verification as well as session resumption.
+ *
+ * Note that error recovery is minimal for simplicity.
+ */
+
+#define CHECK(x) assert((x)>=0)
+#define LOOP_CHECK(rval, cmd) \
+        do { \
+                rval = cmd; \
+        } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED); \
+        assert(rval >= 0)
+
+#define MAX_BUF 1024
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+int main(void)
+{
+        int ret;
+        int sd, ii;
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1];
+        gnutls_certificate_credentials_t xcred;
+
+        /* variables used in session resuming 
+         */
+        int t;
+        gnutls_datum_t sdata;
+
+        /* for backwards compatibility with gnutls < 3.3.0 */
+        CHECK(gnutls_global_init());
+
+        CHECK(gnutls_certificate_allocate_credentials(&xcred));
+        CHECK(gnutls_certificate_set_x509_system_trust(xcred));
+
+        for (t = 0; t < 2; t++) {       /* connect 2 times to the server */
+
+                sd = tcp_connect();
+
+                CHECK(gnutls_init(&session, GNUTLS_CLIENT));
+
+                CHECK(gnutls_server_name_set(session, GNUTLS_NAME_DNS,
+                                             "www.example.com",
+                                             strlen("www.example.com")));
+                gnutls_session_set_verify_cert(session, "www.example.com", 0);
+
+                CHECK(gnutls_set_default_priority(session));
+
+                gnutls_transport_set_int(session, sd);
+                gnutls_handshake_set_timeout(session,
+                                             GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
+
+                gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
+                                       xcred);
+
+                if (t > 0) {
+                        /* if this is not the first time we connect */
+                        CHECK(gnutls_session_set_data(session, sdata.data,
+                                                      sdata.size));
+                        gnutls_free(sdata.data);
+                }
+
+                /* Perform the TLS handshake
+                 */
+                do {
+                        ret = gnutls_handshake(session);
+                }
+                while (ret < 0 && gnutls_error_is_fatal(ret) == 0);
+
+                if (ret < 0) {
+                        fprintf(stderr, "*** Handshake failed\n");
+                        gnutls_perror(ret);
+                        goto end;
+                } else {
+                        printf("- Handshake was completed\n");
+                }
+
+                if (t == 0) {   /* the first time we connect */
+                        /* get the session data */
+                        CHECK(gnutls_session_get_data2(session, &sdata));
+                } else { /* the second time we connect */
+
+                        /* check if we actually resumed the previous session */
+                        if (gnutls_session_is_resumed(session) != 0) {
+                                printf("- Previous session was resumed\n");
+                        } else {
+                                fprintf(stderr,
+                                        "*** Previous session was NOT resumed\n");
+                        }
+                }
+
+                LOOP_CHECK(ret, gnutls_record_send(session, MSG, strlen(MSG)));
+
+                LOOP_CHECK(ret, gnutls_record_recv(session, buffer, MAX_BUF));
+                if (ret == 0) {
+                        printf("- Peer has closed the TLS connection\n");
+                        goto end;
+                } else if (ret < 0 && gnutls_error_is_fatal(ret) == 0) {
+                        fprintf(stderr, "*** Warning: %s\n",
+                                gnutls_strerror(ret));
+                } else if (ret < 0) {
+                        fprintf(stderr, "*** Error: %s\n",
+                                gnutls_strerror(ret));
+                        goto end;
+                }
+
+                if (ret > 0) {
+                        printf("- Received %d bytes: ", ret);
+                        for (ii = 0; ii < ret; ii++) {
+                                fputc(buffer[ii], stdout);
+                        }
+                        fputs("\n", stdout);
+                }
+
+                gnutls_bye(session, GNUTLS_SHUT_RDWR);
+
+              end:
+
+                tcp_close(sd);
+
+                gnutls_deinit(session);
+
+        }                       /* for() */
+
+        gnutls_certificate_free_credentials(xcred);
+
+        gnutls_global_deinit();
+
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Client example with SSH-style certificate verification,  Prev: Client with Resume capability example,  Up: Client examples
+
+7.1.5 Client example with SSH-style certificate verification
+------------------------------------------------------------
+
+This is an alternative verification function that will use the X.509
+certificate authorities for verification, but also assume an trust on
+first use (SSH-like) authentication system.  That is the user is
+prompted on unknown public keys and known public keys are considered
+trusted.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+#include <assert.h>
+#include "examples.h"
+
+#define CHECK(x) assert((x)>=0)
+
+/* This function will verify the peer's certificate, check
+ * if the hostname matches. In addition it will perform an
+ * SSH-style authentication, where ultimately trusted keys
+ * are only the keys that have been seen before.
+ */
+int _ssh_verify_certificate_callback(gnutls_session_t session)
+{
+        unsigned int status;
+        const gnutls_datum_t *cert_list;
+        unsigned int cert_list_size;
+        int ret, type;
+        gnutls_datum_t out;
+        const char *hostname;
+
+        /* read hostname */
+        hostname = gnutls_session_get_ptr(session);
+
+        /* This verification function uses the trusted CAs in the credentials
+         * structure. So you must have installed one or more CA certificates.
+         */
+        CHECK(gnutls_certificate_verify_peers3(session, hostname, &status));
+
+        type = gnutls_certificate_type_get(session);
+
+        CHECK(gnutls_certificate_verification_status_print(status,
+                                                           type, &out, 0));
+        printf("%s", out.data);
+
+        gnutls_free(out.data);
+
+        if (status != 0)        /* Certificate is not trusted */
+                return GNUTLS_E_CERTIFICATE_ERROR;
+
+        /* Do SSH verification */
+        cert_list = gnutls_certificate_get_peers(session, &cert_list_size);
+        if (cert_list == NULL) {
+                printf("No certificate was found!\n");
+                return GNUTLS_E_CERTIFICATE_ERROR;
+        }
+
+        /* service may be obtained alternatively using getservbyport() */
+        ret = gnutls_verify_stored_pubkey(NULL, NULL, hostname, "https",
+                                          type, &cert_list[0], 0);
+        if (ret == GNUTLS_E_NO_CERTIFICATE_FOUND) {
+                printf("Host %s is not known.", hostname);
+                if (status == 0)
+                        printf("Its certificate is valid for %s.\n",
+                               hostname);
+
+                /* the certificate must be printed and user must be asked on
+                 * whether it is trustworthy. --see gnutls_x509_crt_print() */
+
+                /* if not trusted */
+                return GNUTLS_E_CERTIFICATE_ERROR;
+        } else if (ret == GNUTLS_E_CERTIFICATE_KEY_MISMATCH) {
+                printf
+                    ("Warning: host %s is known but has another key associated.",
+                     hostname);
+                printf
+                    ("It might be that the server has multiple keys, or you are under attack\n");
+                if (status == 0)
+                        printf("Its certificate is valid for %s.\n",
+                               hostname);
+
+                /* the certificate must be printed and user must be asked on
+                 * whether it is trustworthy. --see gnutls_x509_crt_print() */
+
+                /* if not trusted */
+                return GNUTLS_E_CERTIFICATE_ERROR;
+        } else if (ret < 0) {
+                printf("gnutls_verify_stored_pubkey: %s\n",
+                       gnutls_strerror(ret));
+                return ret;
+        }
+
+        /* user trusts the key -> store it */
+        if (ret != 0) {
+                CHECK(gnutls_store_pubkey(NULL, NULL, hostname, "https",
+                                          type, &cert_list[0], 0, 0));
+        }
+
+        /* notify gnutls to continue handshake normally */
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Server examples,  Next: More advanced client and servers,  Prev: Client examples,  Up: GnuTLS application examples
+
+7.2 Server examples
+===================
+
+This section contains examples of TLS and SSL servers, using GnuTLS.
+
+* Menu:
+
+* Echo server with X.509 authentication::
+* DTLS echo server with X.509 authentication::
+
+
+File: gnutls.info,  Node: Echo server with X.509 authentication,  Next: DTLS echo server with X.509 authentication,  Up: Server examples
+
+7.2.1 Echo server with X.509 authentication
+-------------------------------------------
+
+This example is a very simple echo server which supports X.509
+authentication.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <errno.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <string.h>
+#include <unistd.h>
+#include <gnutls/gnutls.h>
+#include <assert.h>
+
+#define KEYFILE "key.pem"
+#define CERTFILE "cert.pem"
+#define CAFILE "/etc/ssl/certs/ca-certificates.crt"
+#define CRLFILE "crl.pem"
+
+#define CHECK(x) assert((x)>=0)
+#define LOOP_CHECK(rval, cmd) \
+        do { \
+                rval = cmd; \
+        } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED)
+
+/* The OCSP status file contains up to date information about revocation
+ * of the server's certificate. That can be periodically be updated
+ * using:
+ * $ ocsptool --ask --load-cert your_cert.pem --load-issuer your_issuer.pem
+ *            --load-signer your_issuer.pem --outfile ocsp-status.der
+ */
+#define OCSP_STATUS_FILE "ocsp-status.der"
+
+/* This is a sample TLS 1.0 echo server, using X.509 authentication and
+ * OCSP stapling support.
+ */
+
+#define MAX_BUF 1024
+#define PORT 5556               /* listen to 5556 port */
+
+int main(void)
+{
+        int listen_sd;
+        int sd, ret;
+        gnutls_certificate_credentials_t x509_cred;
+        gnutls_priority_t priority_cache;
+        struct sockaddr_in sa_serv;
+        struct sockaddr_in sa_cli;
+        socklen_t client_len;
+        char topbuf[512];
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1];
+        int optval = 1;
+
+        /* for backwards compatibility with gnutls < 3.3.0 */
+        CHECK(gnutls_global_init());
+
+        CHECK(gnutls_certificate_allocate_credentials(&x509_cred));
+
+        CHECK(gnutls_certificate_set_x509_trust_file(x509_cred, CAFILE,
+                                                     GNUTLS_X509_FMT_PEM));
+
+        CHECK(gnutls_certificate_set_x509_crl_file(x509_cred, CRLFILE,
+                                                   GNUTLS_X509_FMT_PEM));
+
+        /* The following code sets the certificate key pair as well as, 
+         * an OCSP response which corresponds to it. It is possible
+         * to set multiple key-pairs and multiple OCSP status responses
+         * (the latter since 3.5.6). See the manual pages of the individual
+         * functions for more information.
+         */
+        CHECK(gnutls_certificate_set_x509_key_file(x509_cred, CERTFILE,
+                                                   KEYFILE,
+                                                   GNUTLS_X509_FMT_PEM));
+
+        CHECK(gnutls_certificate_set_ocsp_status_request_file(x509_cred,
+                                                              OCSP_STATUS_FILE,
+                                                              0));
+
+        CHECK(gnutls_priority_init(&priority_cache, NULL, NULL));
+
+        /* Instead of the default options as shown above one could specify
+         * additional options such as server precedence in ciphersuite selection
+         * as follows:
+         * gnutls_priority_init2(&priority_cache,
+         *                       "%SERVER_PRECEDENCE",
+         *                       NULL, GNUTLS_PRIORITY_INIT_DEF_APPEND);
+	 */
+
+#if GNUTLS_VERSION_NUMBER >= 0x030506
+        /* only available since GnuTLS 3.5.6, on previous versions see
+         * gnutls_certificate_set_dh_params(). */
+        gnutls_certificate_set_known_dh_params(x509_cred, GNUTLS_SEC_PARAM_MEDIUM);
+#endif
+
+        /* Socket operations
+         */
+        listen_sd = socket(AF_INET, SOCK_STREAM, 0);
+
+        memset(&sa_serv, '\0', sizeof(sa_serv));
+        sa_serv.sin_family = AF_INET;
+        sa_serv.sin_addr.s_addr = INADDR_ANY;
+        sa_serv.sin_port = htons(PORT); /* Server Port number */
+
+        setsockopt(listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &optval,
+                   sizeof(int));
+
+        bind(listen_sd, (struct sockaddr *) &sa_serv, sizeof(sa_serv));
+
+        listen(listen_sd, 1024);
+
+        printf("Server ready. Listening to port '%d'.\n\n", PORT);
+
+        client_len = sizeof(sa_cli);
+        for (;;) {
+                CHECK(gnutls_init(&session, GNUTLS_SERVER));
+                CHECK(gnutls_priority_set(session, priority_cache));
+                CHECK(gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
+                                             x509_cred));
+
+                /* We don't request any certificate from the client.
+                 * If we did we would need to verify it. One way of
+                 * doing that is shown in the "Verifying a certificate"
+                 * example.
+                 */
+                gnutls_certificate_server_set_request(session,
+                                                      GNUTLS_CERT_IGNORE);
+                gnutls_handshake_set_timeout(session,
+                                             GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
+
+                sd = accept(listen_sd, (struct sockaddr *) &sa_cli,
+                            &client_len);
+
+                printf("- connection from %s, port %d\n",
+                       inet_ntop(AF_INET, &sa_cli.sin_addr, topbuf,
+                                 sizeof(topbuf)), ntohs(sa_cli.sin_port));
+
+                gnutls_transport_set_int(session, sd);
+
+                LOOP_CHECK(ret, gnutls_handshake(session));
+                if (ret < 0) {
+                        close(sd);
+                        gnutls_deinit(session);
+                        fprintf(stderr,
+                                "*** Handshake has failed (%s)\n\n",
+                                gnutls_strerror(ret));
+                        continue;
+                }
+                printf("- Handshake was completed\n");
+
+                /* see the Getting peer's information example */
+                /* print_info(session); */
+
+                for (;;) {
+                        LOOP_CHECK(ret, gnutls_record_recv(session, buffer, MAX_BUF));
+
+                        if (ret == 0) {
+                                printf
+                                    ("\n- Peer has closed the GnuTLS connection\n");
+                                break;
+                        } else if (ret < 0
+                                   && gnutls_error_is_fatal(ret) == 0) {
+                                fprintf(stderr, "*** Warning: %s\n",
+                                        gnutls_strerror(ret));
+                        } else if (ret < 0) {
+                                fprintf(stderr, "\n*** Received corrupted "
+                                        "data(%d). Closing the connection.\n\n",
+                                        ret);
+                                break;
+                        } else if (ret > 0) {
+                                /* echo data back to the client
+                                 */
+                                CHECK(gnutls_record_send(session, buffer, ret));
+                        }
+                }
+                printf("\n");
+                /* do not wait for the peer to close the connection.
+                 */
+                LOOP_CHECK(ret, gnutls_bye(session, GNUTLS_SHUT_WR));
+
+                close(sd);
+                gnutls_deinit(session);
+
+        }
+        close(listen_sd);
+
+        gnutls_certificate_free_credentials(x509_cred);
+        gnutls_priority_deinit(priority_cache);
+
+        gnutls_global_deinit();
+
+        return 0;
+
+}
+
+
+File: gnutls.info,  Node: DTLS echo server with X.509 authentication,  Prev: Echo server with X.509 authentication,  Up: Server examples
+
+7.2.2 DTLS echo server with X.509 authentication
+------------------------------------------------
+
+This example is a very simple echo server using Datagram TLS and X.509
+authentication.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <errno.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <sys/select.h>
+#include <netdb.h>
+#include <string.h>
+#include <unistd.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/dtls.h>
+
+#define KEYFILE "key.pem"
+#define CERTFILE "cert.pem"
+#define CAFILE "/etc/ssl/certs/ca-certificates.crt"
+#define CRLFILE "crl.pem"
+
+/* This is a sample DTLS echo server, using X.509 authentication.
+ * Note that error checking is minimal to simplify the example.
+ */
+
+#define LOOP_CHECK(rval, cmd) \
+        do { \
+                rval = cmd; \
+        } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED)
+
+#define MAX_BUFFER 1024
+#define PORT 5557
+
+typedef struct {
+        gnutls_session_t session;
+        int fd;
+        struct sockaddr *cli_addr;
+        socklen_t cli_addr_size;
+} priv_data_st;
+
+static int pull_timeout_func(gnutls_transport_ptr_t ptr, unsigned int ms);
+static ssize_t push_func(gnutls_transport_ptr_t p, const void *data,
+                         size_t size);
+static ssize_t pull_func(gnutls_transport_ptr_t p, void *data,
+                         size_t size);
+static const char *human_addr(const struct sockaddr *sa, socklen_t salen,
+                              char *buf, size_t buflen);
+static int wait_for_connection(int fd);
+
+/* Use global credentials and parameters to simplify
+ * the example. */
+static gnutls_certificate_credentials_t x509_cred;
+static gnutls_priority_t priority_cache;
+
+int main(void)
+{
+        int listen_sd;
+        int sock, ret;
+        struct sockaddr_in sa_serv;
+        struct sockaddr_in cli_addr;
+        socklen_t cli_addr_size;
+        gnutls_session_t session;
+        char buffer[MAX_BUFFER];
+        priv_data_st priv;
+        gnutls_datum_t cookie_key;
+        gnutls_dtls_prestate_st prestate;
+        int mtu = 1400;
+        unsigned char sequence[8];
+
+        /* this must be called once in the program
+         */
+        gnutls_global_init();
+
+        gnutls_certificate_allocate_credentials(&x509_cred);
+        gnutls_certificate_set_x509_trust_file(x509_cred, CAFILE,
+                                               GNUTLS_X509_FMT_PEM);
+
+        gnutls_certificate_set_x509_crl_file(x509_cred, CRLFILE,
+                                             GNUTLS_X509_FMT_PEM);
+
+        ret =
+            gnutls_certificate_set_x509_key_file(x509_cred, CERTFILE,
+                                                 KEYFILE,
+                                                 GNUTLS_X509_FMT_PEM);
+        if (ret < 0) {
+                printf("No certificate or key were found\n");
+                exit(1);
+        }
+
+        gnutls_certificate_set_known_dh_params(x509_cred, GNUTLS_SEC_PARAM_MEDIUM);
+
+        /* pre-3.6.3 equivalent:
+         * gnutls_priority_init(&priority_cache,
+         *                      "NORMAL:-VERS-TLS-ALL:+VERS-DTLS1.0:%SERVER_PRECEDENCE",
+         *                      NULL);
+         */
+        gnutls_priority_init2(&priority_cache,
+                              "%SERVER_PRECEDENCE",
+                              NULL, GNUTLS_PRIORITY_INIT_DEF_APPEND);
+
+        gnutls_key_generate(&cookie_key, GNUTLS_COOKIE_KEY_SIZE);
+
+        /* Socket operations
+         */
+        listen_sd = socket(AF_INET, SOCK_DGRAM, 0);
+
+        memset(&sa_serv, '\0', sizeof(sa_serv));
+        sa_serv.sin_family = AF_INET;
+        sa_serv.sin_addr.s_addr = INADDR_ANY;
+        sa_serv.sin_port = htons(PORT);
+
+        {                       /* DTLS requires the IP don't fragment (DF) bit to be set */
+#if defined(IP_DONTFRAG)
+                int optval = 1;
+                setsockopt(listen_sd, IPPROTO_IP, IP_DONTFRAG,
+                           (const void *) &optval, sizeof(optval));
+#elif defined(IP_MTU_DISCOVER)
+                int optval = IP_PMTUDISC_DO;
+                setsockopt(listen_sd, IPPROTO_IP, IP_MTU_DISCOVER,
+                           (const void *) &optval, sizeof(optval));
+#endif
+        }
+
+        bind(listen_sd, (struct sockaddr *) &sa_serv, sizeof(sa_serv));
+
+        printf("UDP server ready. Listening to port '%d'.\n\n", PORT);
+
+        for (;;) {
+                printf("Waiting for connection...\n");
+                sock = wait_for_connection(listen_sd);
+                if (sock < 0)
+                        continue;
+
+                cli_addr_size = sizeof(cli_addr);
+                ret = recvfrom(sock, buffer, sizeof(buffer), MSG_PEEK,
+                               (struct sockaddr *) &cli_addr,
+                               &cli_addr_size);
+                if (ret > 0) {
+                        memset(&prestate, 0, sizeof(prestate));
+                        ret =
+                            gnutls_dtls_cookie_verify(&cookie_key,
+                                                      &cli_addr,
+                                                      sizeof(cli_addr),
+                                                      buffer, ret,
+                                                      &prestate);
+                        if (ret < 0) {  /* cookie not valid */
+                                priv_data_st s;
+
+                                memset(&s, 0, sizeof(s));
+                                s.fd = sock;
+                                s.cli_addr = (void *) &cli_addr;
+                                s.cli_addr_size = sizeof(cli_addr);
+
+                                printf
+                                    ("Sending hello verify request to %s\n",
+                                     human_addr((struct sockaddr *)
+                                                &cli_addr,
+                                                sizeof(cli_addr), buffer,
+                                                sizeof(buffer)));
+
+                                gnutls_dtls_cookie_send(&cookie_key,
+                                                        &cli_addr,
+                                                        sizeof(cli_addr),
+                                                        &prestate,
+                                                        (gnutls_transport_ptr_t)
+                                                        & s, push_func);
+
+                                /* discard peeked data */
+                                recvfrom(sock, buffer, sizeof(buffer), 0,
+                                         (struct sockaddr *) &cli_addr,
+                                         &cli_addr_size);
+                                usleep(100);
+                                continue;
+                        }
+                        printf("Accepted connection from %s\n",
+                               human_addr((struct sockaddr *)
+                                          &cli_addr, sizeof(cli_addr),
+                                          buffer, sizeof(buffer)));
+                } else
+                        continue;
+
+                gnutls_init(&session, GNUTLS_SERVER | GNUTLS_DATAGRAM);
+                gnutls_priority_set(session, priority_cache);
+                gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
+                                       x509_cred);
+
+                gnutls_dtls_prestate_set(session, &prestate);
+                gnutls_dtls_set_mtu(session, mtu);
+
+                priv.session = session;
+                priv.fd = sock;
+                priv.cli_addr = (struct sockaddr *) &cli_addr;
+                priv.cli_addr_size = sizeof(cli_addr);
+
+                gnutls_transport_set_ptr(session, &priv);
+                gnutls_transport_set_push_function(session, push_func);
+                gnutls_transport_set_pull_function(session, pull_func);
+                gnutls_transport_set_pull_timeout_function(session,
+                                                           pull_timeout_func);
+
+                LOOP_CHECK(ret, gnutls_handshake(session));
+                /* Note that DTLS may also receive GNUTLS_E_LARGE_PACKET.
+                 * In that case the MTU should be adjusted.
+                 */
+
+                if (ret < 0) {
+                        fprintf(stderr, "Error in handshake(): %s\n",
+                                gnutls_strerror(ret));
+                        gnutls_deinit(session);
+                        continue;
+                }
+
+                printf("- Handshake was completed\n");
+
+                for (;;) {
+                        LOOP_CHECK(ret,
+                                    gnutls_record_recv_seq(session, buffer,
+                                                           MAX_BUFFER,
+                                                           sequence));
+
+                        if (ret < 0 && gnutls_error_is_fatal(ret) == 0) {
+                                fprintf(stderr, "*** Warning: %s\n",
+                                        gnutls_strerror(ret));
+                                continue;
+                        } else if (ret < 0) {
+                                fprintf(stderr, "Error in recv(): %s\n",
+                                        gnutls_strerror(ret));
+                                break;
+                        }
+
+                        if (ret == 0) {
+                                printf("EOF\n\n");
+                                break;
+                        }
+
+                        buffer[ret] = 0;
+                        printf
+                            ("received[%.2x%.2x%.2x%.2x%.2x%.2x%.2x%.2x]: %s\n",
+                             sequence[0], sequence[1], sequence[2],
+                             sequence[3], sequence[4], sequence[5],
+                             sequence[6], sequence[7], buffer);
+
+                        /* reply back */
+                        LOOP_CHECK(ret, gnutls_record_send(session, buffer, ret));
+                        if (ret < 0) {
+                                fprintf(stderr, "Error in send(): %s\n",
+                                        gnutls_strerror(ret));
+                                break;
+                        }
+                }
+
+                LOOP_CHECK(ret, gnutls_bye(session, GNUTLS_SHUT_WR));
+                gnutls_deinit(session);
+
+        }
+        close(listen_sd);
+
+        gnutls_certificate_free_credentials(x509_cred);
+        gnutls_priority_deinit(priority_cache);
+
+        gnutls_global_deinit();
+
+        return 0;
+
+}
+
+static int wait_for_connection(int fd)
+{
+        fd_set rd, wr;
+        int n;
+
+        FD_ZERO(&rd);
+        FD_ZERO(&wr);
+
+        FD_SET(fd, &rd);
+
+        /* waiting part */
+        n = select(fd + 1, &rd, &wr, NULL, NULL);
+        if (n == -1 && errno == EINTR)
+                return -1;
+        if (n < 0) {
+                perror("select()");
+                exit(1);
+        }
+
+        return fd;
+}
+
+/* Wait for data to be received within a timeout period in milliseconds
+ */
+static int pull_timeout_func(gnutls_transport_ptr_t ptr, unsigned int ms)
+{
+        fd_set rfds;
+        struct timeval tv;
+        priv_data_st *priv = ptr;
+        struct sockaddr_in cli_addr;
+        socklen_t cli_addr_size;
+        int ret;
+        char c;
+
+        FD_ZERO(&rfds);
+        FD_SET(priv->fd, &rfds);
+
+        tv.tv_sec = ms / 1000;
+        tv.tv_usec = (ms % 1000) * 1000;
+
+        ret = select(priv->fd + 1, &rfds, NULL, NULL, &tv);
+
+        if (ret <= 0)
+                return ret;
+
+        /* only report ok if the next message is from the peer we expect
+         * from 
+         */
+        cli_addr_size = sizeof(cli_addr);
+        ret =
+            recvfrom(priv->fd, &c, 1, MSG_PEEK,
+                     (struct sockaddr *) &cli_addr, &cli_addr_size);
+        if (ret > 0) {
+                if (cli_addr_size == priv->cli_addr_size
+                    && memcmp(&cli_addr, priv->cli_addr,
+                              sizeof(cli_addr)) == 0)
+                        return 1;
+        }
+
+        return 0;
+}
+
+static ssize_t
+push_func(gnutls_transport_ptr_t p, const void *data, size_t size)
+{
+        priv_data_st *priv = p;
+
+        return sendto(priv->fd, data, size, 0, priv->cli_addr,
+                      priv->cli_addr_size);
+}
+
+static ssize_t pull_func(gnutls_transport_ptr_t p, void *data, size_t size)
+{
+        priv_data_st *priv = p;
+        struct sockaddr_in cli_addr;
+        socklen_t cli_addr_size;
+        char buffer[64];
+        int ret;
+
+        cli_addr_size = sizeof(cli_addr);
+        ret =
+            recvfrom(priv->fd, data, size, 0,
+                     (struct sockaddr *) &cli_addr, &cli_addr_size);
+        if (ret == -1)
+                return ret;
+
+        if (cli_addr_size == priv->cli_addr_size
+            && memcmp(&cli_addr, priv->cli_addr, sizeof(cli_addr)) == 0)
+                return ret;
+
+        printf("Denied connection from %s\n",
+               human_addr((struct sockaddr *)
+                          &cli_addr, sizeof(cli_addr), buffer,
+                          sizeof(buffer)));
+
+        gnutls_transport_set_errno(priv->session, EAGAIN);
+        return -1;
+}
+
+static const char *human_addr(const struct sockaddr *sa, socklen_t salen,
+                              char *buf, size_t buflen)
+{
+        const char *save_buf = buf;
+        size_t l;
+
+        if (!buf || !buflen)
+                return NULL;
+
+        *buf = '\0';
+
+        switch (sa->sa_family) {
+#if HAVE_IPV6
+        case AF_INET6:
+                snprintf(buf, buflen, "IPv6 ");
+                break;
+#endif
+
+        case AF_INET:
+                snprintf(buf, buflen, "IPv4 ");
+                break;
+        }
+
+        l = strlen(buf);
+        buf += l;
+        buflen -= l;
+
+        if (getnameinfo(sa, salen, buf, buflen, NULL, 0, NI_NUMERICHOST) !=
+            0)
+                return NULL;
+
+        l = strlen(buf);
+        buf += l;
+        buflen -= l;
+
+        strncat(buf, " port ", buflen);
+
+        l = strlen(buf);
+        buf += l;
+        buflen -= l;
+
+        if (getnameinfo(sa, salen, NULL, 0, buf, buflen, NI_NUMERICSERV) !=
+            0)
+                return NULL;
+
+        return save_buf;
+}
+
+
+
+File: gnutls.info,  Node: More advanced client and servers,  Next: OCSP example,  Prev: Server examples,  Up: GnuTLS application examples
+
+7.3 More advanced client and servers
+====================================
+
+This section has various, more advanced topics in client and servers.
+
+* Menu:
+
+* Client example with anonymous authentication::
+* Using a callback to select the certificate to use::
+* Obtaining session information::
+* Advanced certificate verification example::
+* Client example with PSK authentication::
+* Client example with SRP authentication::
+* Legacy client example with X.509 certificate support::
+* Client example in C++::
+* Echo server with PSK authentication::
+* Echo server with SRP authentication::
+* Echo server with anonymous authentication::
+* Helper functions for TCP connections::
+* Helper functions for UDP connections::
+
+
+File: gnutls.info,  Node: Client example with anonymous authentication,  Next: Using a callback to select the certificate to use,  Up: More advanced client and servers
+
+7.3.1 Client example with anonymous authentication
+--------------------------------------------------
+
+The simplest client using TLS is the one that doesn't do any
+authentication.  This means no external certificates or passwords are
+needed to set up the connection.  As could be expected, the connection
+is vulnerable to man-in-the-middle (active or redirection) attacks.
+However, the data are integrity protected and encrypted from passive
+eavesdroppers.
+
+Note that due to the vulnerable nature of this method very few public
+servers support it.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <arpa/inet.h>
+#include <unistd.h>
+#include <assert.h>
+#include <gnutls/gnutls.h>
+
+/* A very basic TLS client, with anonymous authentication.
+ */
+
+#define LOOP_CHECK(rval, cmd) \
+        do { \
+                rval = cmd; \
+        } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED); \
+        assert(rval >= 0)
+
+#define MAX_BUF 1024
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+extern int tcp_connect(void);
+extern void tcp_close(int sd);
+
+int main(void)
+{
+        int ret, sd, ii;
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1];
+        gnutls_anon_client_credentials_t anoncred;
+        /* Need to enable anonymous KX specifically. */
+
+        gnutls_global_init();
+
+        gnutls_anon_allocate_client_credentials(&anoncred);
+
+        /* Initialize TLS session 
+         */
+        gnutls_init(&session, GNUTLS_CLIENT);
+
+        /* Use default priorities */
+        gnutls_priority_set_direct(session,
+                                   "PERFORMANCE:+ANON-ECDH:+ANON-DH",
+                                   NULL);
+
+        /* put the anonymous credentials to the current session
+         */
+        gnutls_credentials_set(session, GNUTLS_CRD_ANON, anoncred);
+
+        /* connect to the peer
+         */
+        sd = tcp_connect();
+
+        gnutls_transport_set_int(session, sd);
+        gnutls_handshake_set_timeout(session,
+                                     GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
+
+        /* Perform the TLS handshake
+         */
+        do {
+                ret = gnutls_handshake(session);
+        }
+        while (ret < 0 && gnutls_error_is_fatal(ret) == 0);
+
+        if (ret < 0) {
+                fprintf(stderr, "*** Handshake failed\n");
+                gnutls_perror(ret);
+                goto end;
+        } else {
+                char *desc;
+
+                desc = gnutls_session_get_desc(session);
+                printf("- Session info: %s\n", desc);
+                gnutls_free(desc);
+        }
+
+        LOOP_CHECK(ret, gnutls_record_send(session, MSG, strlen(MSG)));
+
+        LOOP_CHECK(ret, gnutls_record_recv(session, buffer, MAX_BUF));
+        if (ret == 0) {
+                printf("- Peer has closed the TLS connection\n");
+                goto end;
+        } else if (ret < 0 && gnutls_error_is_fatal(ret) == 0) {
+                fprintf(stderr, "*** Warning: %s\n", gnutls_strerror(ret));
+        } else if (ret < 0) {
+                fprintf(stderr, "*** Error: %s\n", gnutls_strerror(ret));
+                goto end;
+        }
+
+        if (ret > 0) {
+                printf("- Received %d bytes: ", ret);
+                for (ii = 0; ii < ret; ii++) {
+                        fputc(buffer[ii], stdout);
+                }
+                fputs("\n", stdout);
+        }
+
+        LOOP_CHECK(ret, gnutls_bye(session, GNUTLS_SHUT_RDWR));
+
+      end:
+
+        tcp_close(sd);
+
+        gnutls_deinit(session);
+
+        gnutls_anon_free_client_credentials(anoncred);
+
+        gnutls_global_deinit();
+
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Using a callback to select the certificate to use,  Next: Obtaining session information,  Prev: Client example with anonymous authentication,  Up: More advanced client and servers
+
+7.3.2 Using a callback to select the certificate to use
+-------------------------------------------------------
+
+There are cases where a client holds several certificate and key pairs,
+and may not want to load all of them in the credentials structure.  The
+following example demonstrates the use of the certificate selection
+callback.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <arpa/inet.h>
+#include <unistd.h>
+#include <assert.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+#include <gnutls/abstract.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+
+/* A TLS client that loads the certificate and key.
+ */
+
+#define CHECK(x) assert((x)>=0)
+
+#define MAX_BUF 1024
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+#define CERT_FILE "cert.pem"
+#define KEY_FILE "key.pem"
+#define CAFILE "/etc/ssl/certs/ca-certificates.crt"
+
+extern int tcp_connect(void);
+extern void tcp_close(int sd);
+
+static int
+cert_callback(gnutls_session_t session,
+              const gnutls_datum_t * req_ca_rdn, int nreqs,
+              const gnutls_pk_algorithm_t * sign_algos,
+              int sign_algos_length, gnutls_pcert_st ** pcert,
+              unsigned int *pcert_length, gnutls_privkey_t * pkey);
+
+gnutls_pcert_st pcrt;
+gnutls_privkey_t key;
+
+/* Load the certificate and the private key.
+ */
+static void load_keys(void)
+{
+        gnutls_datum_t data;
+
+        CHECK(gnutls_load_file(CERT_FILE, &data));
+
+        CHECK(gnutls_pcert_import_x509_raw(&pcrt, &data,
+                                           GNUTLS_X509_FMT_PEM, 0));
+
+        gnutls_free(data.data);
+
+        CHECK(gnutls_load_file(KEY_FILE, &data));
+
+        CHECK(gnutls_privkey_init(&key));
+
+        CHECK(gnutls_privkey_import_x509_raw(key, &data,
+                                             GNUTLS_X509_FMT_PEM,
+                                             NULL, 0));
+        gnutls_free(data.data);
+}
+
+int main(void)
+{
+        int ret, sd, ii;
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1];
+        gnutls_certificate_credentials_t xcred;
+        
+        if (gnutls_check_version("3.1.4") == NULL) {
+                fprintf(stderr, "GnuTLS 3.1.4 or later is required for this example\n");
+                exit(1);
+        }
+
+        /* for backwards compatibility with gnutls < 3.3.0 */
+        CHECK(gnutls_global_init());
+
+        load_keys();
+
+        /* X509 stuff */
+        CHECK(gnutls_certificate_allocate_credentials(&xcred));
+
+        /* sets the trusted cas file
+         */
+        CHECK(gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
+                                                     GNUTLS_X509_FMT_PEM));
+
+        gnutls_certificate_set_retrieve_function2(xcred, cert_callback);
+
+        /* Initialize TLS session 
+         */
+        CHECK(gnutls_init(&session, GNUTLS_CLIENT));
+
+        /* Use default priorities */
+        CHECK(gnutls_set_default_priority(session));
+
+        /* put the x509 credentials to the current session
+         */
+        CHECK(gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, xcred));
+
+        /* connect to the peer
+         */
+        sd = tcp_connect();
+
+        gnutls_transport_set_int(session, sd);
+
+        /* Perform the TLS handshake
+         */
+        ret = gnutls_handshake(session);
+
+        if (ret < 0) {
+                fprintf(stderr, "*** Handshake failed\n");
+                gnutls_perror(ret);
+                goto end;
+        } else {
+                char *desc;
+
+                desc = gnutls_session_get_desc(session);
+                printf("- Session info: %s\n", desc);
+                gnutls_free(desc);
+        }
+
+        CHECK(gnutls_record_send(session, MSG, strlen(MSG)));
+
+        ret = gnutls_record_recv(session, buffer, MAX_BUF);
+        if (ret == 0) {
+                printf("- Peer has closed the TLS connection\n");
+                goto end;
+        } else if (ret < 0) {
+                fprintf(stderr, "*** Error: %s\n", gnutls_strerror(ret));
+                goto end;
+        }
+
+        printf("- Received %d bytes: ", ret);
+        for (ii = 0; ii < ret; ii++) {
+                fputc(buffer[ii], stdout);
+        }
+        fputs("\n", stdout);
+
+        CHECK(gnutls_bye(session, GNUTLS_SHUT_RDWR));
+
+      end:
+
+        tcp_close(sd);
+
+        gnutls_deinit(session);
+
+        gnutls_certificate_free_credentials(xcred);
+
+        gnutls_global_deinit();
+
+        return 0;
+}
+
+
+
+/* This callback should be associated with a session by calling
+ * gnutls_certificate_client_set_retrieve_function( session, cert_callback),
+ * before a handshake.
+ */
+
+static int
+cert_callback(gnutls_session_t session,
+              const gnutls_datum_t * req_ca_rdn, int nreqs,
+              const gnutls_pk_algorithm_t * sign_algos,
+              int sign_algos_length, gnutls_pcert_st ** pcert,
+              unsigned int *pcert_length, gnutls_privkey_t * pkey)
+{
+        char issuer_dn[256];
+        int i, ret;
+        size_t len;
+        gnutls_certificate_type_t type;
+
+        /* Print the server's trusted CAs
+         */
+        if (nreqs > 0)
+                printf("- Server's trusted authorities:\n");
+        else
+                printf
+                    ("- Server did not send us any trusted authorities names.\n");
+
+        /* print the names (if any) */
+        for (i = 0; i < nreqs; i++) {
+                len = sizeof(issuer_dn);
+                ret = gnutls_x509_rdn_get(&req_ca_rdn[i], issuer_dn, &len);
+                if (ret >= 0) {
+                        printf("   [%d]: ", i);
+                        printf("%s\n", issuer_dn);
+                }
+        }
+
+        /* Select a certificate and return it.
+         * The certificate must be of any of the "sign algorithms"
+         * supported by the server.
+         */
+        type = gnutls_certificate_type_get(session);
+        if (type == GNUTLS_CRT_X509) {
+                *pcert_length = 1;
+                *pcert = &pcrt;
+                *pkey = key;
+        } else {
+                return -1;
+        }
+
+        return 0;
+
+}
+
+
+File: gnutls.info,  Node: Obtaining session information,  Next: Advanced certificate verification example,  Prev: Using a callback to select the certificate to use,  Up: More advanced client and servers
+
+7.3.3 Obtaining session information
+-----------------------------------
+
+Most of the times it is desirable to know the security properties of the
+current established session.  This includes the underlying ciphers and
+the protocols involved.  That is the purpose of the following function.
+Note that this function will print meaningful values only if called
+after a successful *note gnutls_handshake::.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+
+#include "examples.h"
+
+/* This function will print some details of the
+ * given session.
+ */
+int print_info(gnutls_session_t session)
+{
+        gnutls_credentials_type_t cred;
+        gnutls_kx_algorithm_t kx;
+        int dhe, ecdh, group;
+        char *desc;
+
+        /* get a description of the session connection, protocol,
+         * cipher/key exchange */
+        desc = gnutls_session_get_desc(session);
+        if (desc != NULL) {
+                printf("- Session: %s\n", desc);
+        }
+
+        dhe = ecdh = 0;
+
+        kx = gnutls_kx_get(session);
+
+        /* Check the authentication type used and switch
+         * to the appropriate.
+         */
+        cred = gnutls_auth_get_type(session);
+        switch (cred) {
+#ifdef ENABLE_SRP
+        case GNUTLS_CRD_SRP:
+                printf("- SRP session with username %s\n",
+                       gnutls_srp_server_get_username(session));
+                break;
+#endif
+
+        case GNUTLS_CRD_PSK:
+                /* This returns NULL in server side.
+                 */
+                if (gnutls_psk_client_get_hint(session) != NULL)
+                        printf("- PSK authentication. PSK hint '%s'\n",
+                               gnutls_psk_client_get_hint(session));
+                /* This returns NULL in client side.
+                 */
+                if (gnutls_psk_server_get_username(session) != NULL)
+                        printf("- PSK authentication. Connected as '%s'\n",
+                               gnutls_psk_server_get_username(session));
+
+                if (kx == GNUTLS_KX_ECDHE_PSK)
+                        ecdh = 1;
+                else if (kx == GNUTLS_KX_DHE_PSK)
+                        dhe = 1;
+                break;
+
+        case GNUTLS_CRD_ANON:  /* anonymous authentication */
+
+                printf("- Anonymous authentication.\n");
+                if (kx == GNUTLS_KX_ANON_ECDH)
+                        ecdh = 1;
+                else if (kx == GNUTLS_KX_ANON_DH)
+                        dhe = 1;
+                break;
+
+        case GNUTLS_CRD_CERTIFICATE:   /* certificate authentication */
+
+                /* Check if we have been using ephemeral Diffie-Hellman.
+                 */
+                if (kx == GNUTLS_KX_DHE_RSA || kx == GNUTLS_KX_DHE_DSS)
+                        dhe = 1;
+                else if (kx == GNUTLS_KX_ECDHE_RSA
+                         || kx == GNUTLS_KX_ECDHE_ECDSA)
+                        ecdh = 1;
+
+                /* if the certificate list is available, then
+                 * print some information about it.
+                 */
+                print_x509_certificate_info(session);
+                break;
+	default:
+		break;
+        }                       /* switch */
+
+        /* read the negotiated group - if any */
+        group = gnutls_group_get(session);
+        if (group != 0) {
+                printf("- Negotiated group %s\n",
+                       gnutls_group_get_name(group));
+        } else {
+                if (ecdh != 0)
+                        printf("- Ephemeral ECDH using curve %s\n",
+	                       gnutls_ecc_curve_get_name(gnutls_ecc_curve_get
+                                                         (session)));
+                else if (dhe != 0)
+                        printf("- Ephemeral DH using prime of %d bits\n",
+                               gnutls_dh_get_prime_bits(session));
+        }
+
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Advanced certificate verification example,  Next: Client example with PSK authentication,  Prev: Obtaining session information,  Up: More advanced client and servers
+
+7.3.4 Advanced certificate verification
+---------------------------------------
+
+An example is listed below which uses the high level verification
+functions to verify a given certificate chain against a set of CAs and
+CRLs.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+
+#include "examples.h"
+
+#define CHECK(x) assert((x)>=0)
+
+/* All the available CRLs
+ */
+gnutls_x509_crl_t *crl_list;
+int crl_list_size;
+
+/* All the available trusted CAs
+ */
+gnutls_x509_crt_t *ca_list;
+int ca_list_size;
+
+static int print_details_func(gnutls_x509_crt_t cert,
+                              gnutls_x509_crt_t issuer,
+                              gnutls_x509_crl_t crl,
+                              unsigned int verification_output);
+
+/* This function will try to verify the peer's certificate chain, and
+ * also check if the hostname matches.
+ */
+void
+verify_certificate_chain(const char *hostname,
+                         const gnutls_datum_t * cert_chain,
+                         int cert_chain_length)
+{
+        int i;
+        gnutls_x509_trust_list_t tlist;
+        gnutls_x509_crt_t *cert;
+        gnutls_datum_t txt;
+        unsigned int output;
+
+        /* Initialize the trusted certificate list. This should be done
+         * once on initialization. gnutls_x509_crt_list_import2() and
+         * gnutls_x509_crl_list_import2() can be used to load them.
+         */
+        CHECK(gnutls_x509_trust_list_init(&tlist, 0));
+
+        CHECK(gnutls_x509_trust_list_add_cas(tlist, ca_list, ca_list_size, 0));
+        CHECK(gnutls_x509_trust_list_add_crls(tlist, crl_list, crl_list_size,
+                                              GNUTLS_TL_VERIFY_CRL, 0));
+
+        cert = gnutls_calloc(cert_chain_length, sizeof(*cert));
+        assert(cert != NULL);
+
+        /* Import all the certificates in the chain to
+         * native certificate format.
+         */
+        for (i = 0; i < cert_chain_length; i++) {
+                CHECK(gnutls_x509_crt_init(&cert[i]));
+                CHECK(gnutls_x509_crt_import(cert[i], &cert_chain[i],
+                                             GNUTLS_X509_FMT_DER));
+        }
+
+        CHECK(gnutls_x509_trust_list_verify_named_crt(tlist, cert[0],
+                                                hostname,
+                                                strlen(hostname),
+                                                GNUTLS_VERIFY_DISABLE_CRL_CHECKS,
+                                                &output,
+                                                print_details_func));
+
+        /* if this certificate is not explicitly trusted verify against CAs 
+         */
+        if (output != 0) {
+                CHECK(gnutls_x509_trust_list_verify_crt(tlist, cert,
+                                                  cert_chain_length, 0,
+                                                  &output,
+                                                  print_details_func));
+        }
+
+
+
+        if (output & GNUTLS_CERT_INVALID) {
+                fprintf(stderr, "Not trusted\n");
+                CHECK(gnutls_certificate_verification_status_print(
+                                                     output,
+                                                     GNUTLS_CRT_X509,
+                                                     &txt, 0));
+
+                fprintf(stderr, "Error: %s\n", txt.data);
+                gnutls_free(txt.data);
+        } else
+                fprintf(stderr, "Trusted\n");
+
+        /* Check if the name in the first certificate matches our destination!
+         */
+        if (!gnutls_x509_crt_check_hostname(cert[0], hostname)) {
+                printf
+                    ("The certificate's owner does not match hostname '%s'\n",
+                     hostname);
+        }
+
+        for (i = 0; i < cert_chain_length; i++) {
+                gnutls_x509_crt_deinit(cert[i]);
+        }
+	gnutls_free(cert);
+
+        gnutls_x509_trust_list_deinit(tlist, 1);
+
+        return;
+}
+
+static int
+print_details_func(gnutls_x509_crt_t cert,
+                   gnutls_x509_crt_t issuer, gnutls_x509_crl_t crl,
+                   unsigned int verification_output)
+{
+        char name[512];
+        char issuer_name[512];
+        size_t name_size;
+        size_t issuer_name_size;
+
+        issuer_name_size = sizeof(issuer_name);
+        gnutls_x509_crt_get_issuer_dn(cert, issuer_name,
+                                      &issuer_name_size);
+
+        name_size = sizeof(name);
+        gnutls_x509_crt_get_dn(cert, name, &name_size);
+
+        fprintf(stdout, "\tSubject: %s\n", name);
+        fprintf(stdout, "\tIssuer: %s\n", issuer_name);
+
+        if (issuer != NULL) {
+                issuer_name_size = sizeof(issuer_name);
+                gnutls_x509_crt_get_dn(issuer, issuer_name,
+                                       &issuer_name_size);
+
+                fprintf(stdout, "\tVerified against: %s\n", issuer_name);
+        }
+
+        if (crl != NULL) {
+                issuer_name_size = sizeof(issuer_name);
+                gnutls_x509_crl_get_issuer_dn(crl, issuer_name,
+                                              &issuer_name_size);
+
+                fprintf(stdout, "\tVerified against CRL of: %s\n",
+                        issuer_name);
+        }
+
+        fprintf(stdout, "\tVerification output: %x\n\n",
+                verification_output);
+
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Client example with PSK authentication,  Next: Client example with SRP authentication,  Prev: Advanced certificate verification example,  Up: More advanced client and servers
+
+7.3.5 Client example with PSK authentication
+--------------------------------------------
+
+The following client is a very simple PSK TLS client which connects to a
+server and authenticates using a _username_ and a _key_.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <arpa/inet.h>
+#include <unistd.h>
+#include <assert.h>
+#include <gnutls/gnutls.h>
+
+/* A very basic TLS client, with PSK authentication.
+ */
+
+#define CHECK(x) assert((x)>=0)
+#define LOOP_CHECK(rval, cmd) \
+        do { \
+                rval = cmd; \
+        } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED); \
+        assert(rval >= 0)
+
+#define MAX_BUF 1024
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+extern int tcp_connect(void);
+extern void tcp_close(int sd);
+
+int main(void)
+{
+        int ret, sd, ii;
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1];
+        const char *err;
+        gnutls_psk_client_credentials_t pskcred;
+        const gnutls_datum_t key = { (void *) "DEADBEEF", 8 };
+
+        if (gnutls_check_version("3.6.3") == NULL) {
+                fprintf(stderr, "GnuTLS 3.6.3 or later is required for this example\n");
+                exit(1);
+        }
+
+        CHECK(gnutls_global_init());
+
+        CHECK(gnutls_psk_allocate_client_credentials(&pskcred));
+        CHECK(gnutls_psk_set_client_credentials(pskcred, "test", &key,
+                                                GNUTLS_PSK_KEY_HEX));
+
+        /* Initialize TLS session
+         */
+        CHECK(gnutls_init(&session, GNUTLS_CLIENT));
+
+        ret =
+            gnutls_set_default_priority_append(session,
+                                         "-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK",
+                                         &err, 0);
+
+        /* Alternative for pre-3.6.3 versions:
+         * gnutls_priority_set_direct(session, "NORMAL:+ECDHE-PSK:+DHE-PSK:+PSK", &err)
+         */
+        if (ret < 0) {
+                if (ret == GNUTLS_E_INVALID_REQUEST) {
+                        fprintf(stderr, "Syntax error at: %s\n", err);
+                }
+                exit(1);
+        }
+
+        /* put the x509 credentials to the current session
+         */
+        CHECK(gnutls_credentials_set(session, GNUTLS_CRD_PSK, pskcred));
+
+        /* connect to the peer
+         */
+        sd = tcp_connect();
+
+        gnutls_transport_set_int(session, sd);
+        gnutls_handshake_set_timeout(session,
+                                     GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
+
+        /* Perform the TLS handshake
+         */
+        do {
+                ret = gnutls_handshake(session);
+        }
+        while (ret < 0 && gnutls_error_is_fatal(ret) == 0);
+
+        if (ret < 0) {
+                fprintf(stderr, "*** Handshake failed\n");
+                gnutls_perror(ret);
+                goto end;
+        } else {
+                char *desc;
+
+                desc = gnutls_session_get_desc(session);
+                printf("- Session info: %s\n", desc);
+                gnutls_free(desc);
+        }
+
+        LOOP_CHECK(ret, gnutls_record_send(session, MSG, strlen(MSG)));
+
+        LOOP_CHECK(ret, gnutls_record_recv(session, buffer, MAX_BUF));
+        if (ret == 0) {
+                printf("- Peer has closed the TLS connection\n");
+                goto end;
+        } else if (ret < 0 && gnutls_error_is_fatal(ret) == 0) {
+                fprintf(stderr, "*** Warning: %s\n", gnutls_strerror(ret));
+        } else if (ret < 0) {
+                fprintf(stderr, "*** Error: %s\n", gnutls_strerror(ret));
+                goto end;
+        }
+
+        if (ret > 0) {
+                printf("- Received %d bytes: ", ret);
+                for (ii = 0; ii < ret; ii++) {
+                        fputc(buffer[ii], stdout);
+                }
+                fputs("\n", stdout);
+        }
+
+        CHECK(gnutls_bye(session, GNUTLS_SHUT_RDWR));
+
+      end:
+
+        tcp_close(sd);
+
+        gnutls_deinit(session);
+
+        gnutls_psk_free_client_credentials(pskcred);
+
+        gnutls_global_deinit();
+
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Client example with SRP authentication,  Next: Legacy client example with X.509 certificate support,  Prev: Client example with PSK authentication,  Up: More advanced client and servers
+
+7.3.6 Client example with SRP authentication
+--------------------------------------------
+
+The following client is a very simple SRP TLS client which connects to a
+server and authenticates using a _username_ and a _password_.  The
+server may authenticate itself using a certificate, and in that case it
+has to be verified.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <gnutls/gnutls.h>
+
+/* Those functions are defined in other examples.
+ */
+extern void check_alert(gnutls_session_t session, int ret);
+extern int tcp_connect(void);
+extern void tcp_close(int sd);
+
+#define MAX_BUF 1024
+#define USERNAME "user"
+#define PASSWORD "pass"
+#define CAFILE "/etc/ssl/certs/ca-certificates.crt"
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+int main(void)
+{
+        int ret;
+        int sd, ii;
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1];
+        gnutls_srp_client_credentials_t srp_cred;
+        gnutls_certificate_credentials_t cert_cred;
+
+        if (gnutls_check_version("3.1.4") == NULL) {
+                fprintf(stderr, "GnuTLS 3.1.4 or later is required for this example\n");
+                exit(1);
+        }
+
+        /* for backwards compatibility with gnutls < 3.3.0 */
+        gnutls_global_init();
+
+        gnutls_srp_allocate_client_credentials(&srp_cred);
+        gnutls_certificate_allocate_credentials(&cert_cred);
+
+        gnutls_certificate_set_x509_trust_file(cert_cred, CAFILE,
+                                               GNUTLS_X509_FMT_PEM);
+        gnutls_srp_set_client_credentials(srp_cred, USERNAME, PASSWORD);
+
+        /* connects to server
+         */
+        sd = tcp_connect();
+
+        /* Initialize TLS session
+         */
+        gnutls_init(&session, GNUTLS_CLIENT);
+
+
+        /* Set the priorities.
+         */
+        gnutls_priority_set_direct(session,
+                                   "NORMAL:+SRP:+SRP-RSA:+SRP-DSS",
+                                   NULL);
+
+        /* put the SRP credentials to the current session
+         */
+        gnutls_credentials_set(session, GNUTLS_CRD_SRP, srp_cred);
+        gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, cert_cred);
+
+        gnutls_transport_set_int(session, sd);
+        gnutls_handshake_set_timeout(session,
+                                     GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
+
+        /* Perform the TLS handshake
+         */
+        do {
+                ret = gnutls_handshake(session);
+        }
+        while (ret < 0 && gnutls_error_is_fatal(ret) == 0);
+
+        if (ret < 0) {
+                fprintf(stderr, "*** Handshake failed\n");
+                gnutls_perror(ret);
+                goto end;
+        } else {
+                char *desc;
+
+                desc = gnutls_session_get_desc(session);
+                printf("- Session info: %s\n", desc);
+                gnutls_free(desc);
+        }
+
+        gnutls_record_send(session, MSG, strlen(MSG));
+
+        ret = gnutls_record_recv(session, buffer, MAX_BUF);
+        if (gnutls_error_is_fatal(ret) != 0 || ret == 0) {
+                if (ret == 0) {
+                        printf
+                            ("- Peer has closed the GnuTLS connection\n");
+                        goto end;
+                } else {
+                        fprintf(stderr, "*** Error: %s\n",
+                                gnutls_strerror(ret));
+                        goto end;
+                }
+        } else
+                check_alert(session, ret);
+
+        if (ret > 0) {
+                printf("- Received %d bytes: ", ret);
+                for (ii = 0; ii < ret; ii++) {
+                        fputc(buffer[ii], stdout);
+                }
+                fputs("\n", stdout);
+        }
+        gnutls_bye(session, GNUTLS_SHUT_RDWR);
+
+      end:
+
+        tcp_close(sd);
+
+        gnutls_deinit(session);
+
+        gnutls_srp_free_client_credentials(srp_cred);
+        gnutls_certificate_free_credentials(cert_cred);
+
+        gnutls_global_deinit();
+
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Legacy client example with X.509 certificate support,  Next: Client example in C++,  Prev: Client example with SRP authentication,  Up: More advanced client and servers
+
+7.3.7 Legacy client example with X.509 certificate support
+----------------------------------------------------------
+
+For applications that need to maintain compatibility with the GnuTLS
+3.1.x library, this client example is identical to *note Client example
+with X.509 certificate support:: but utilizes APIs that were available
+in GnuTLS 3.1.4.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+#include "examples.h"
+
+/* A very basic TLS client, with X.509 authentication and server certificate
+ * verification utilizing the GnuTLS 3.1.x API. 
+ * Note that error recovery is minimal for simplicity.
+ */
+
+#define CHECK(x) assert((x)>=0)
+#define LOOP_CHECK(rval, cmd) \
+        do { \
+                rval = cmd; \
+        } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED); \
+        assert(rval >= 0)
+
+#define MAX_BUF 1024
+#define CAFILE "/etc/ssl/certs/ca-certificates.crt"
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+extern int tcp_connect(void);
+extern void tcp_close(int sd);
+static int _verify_certificate_callback(gnutls_session_t session);
+
+int main(void)
+{
+        int ret, sd, ii;
+        gnutls_session_t session;
+        char buffer[MAX_BUF + 1];
+        gnutls_certificate_credentials_t xcred;
+
+        if (gnutls_check_version("3.1.4") == NULL) {
+                fprintf(stderr, "GnuTLS 3.1.4 or later is required for this example\n");
+                exit(1);
+        }
+
+        CHECK(gnutls_global_init());
+
+        /* X509 stuff */
+        CHECK(gnutls_certificate_allocate_credentials(&xcred));
+
+        /* sets the trusted cas file
+         */
+        CHECK(gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
+                                                     GNUTLS_X509_FMT_PEM));
+        gnutls_certificate_set_verify_function(xcred,
+                                               _verify_certificate_callback);
+
+        /* If client holds a certificate it can be set using the following:
+         *
+         gnutls_certificate_set_x509_key_file (xcred, 
+         "cert.pem", "key.pem", 
+         GNUTLS_X509_FMT_PEM); 
+         */
+
+        /* Initialize TLS session 
+         */
+        CHECK(gnutls_init(&session, GNUTLS_CLIENT));
+
+        gnutls_session_set_ptr(session, (void *) "www.example.com");
+
+        gnutls_server_name_set(session, GNUTLS_NAME_DNS, "www.example.com",
+                               strlen("www.example.com"));
+
+        /* use default priorities */
+        CHECK(gnutls_set_default_priority(session));
+#if 0
+	/* if more fine-graned control is required */
+        ret = gnutls_priority_set_direct(session, 
+                                         "NORMAL", &err);
+        if (ret < 0) {
+                if (ret == GNUTLS_E_INVALID_REQUEST) {
+                        fprintf(stderr, "Syntax error at: %s\n", err);
+                }
+                exit(1);
+        }
+#endif
+
+        /* put the x509 credentials to the current session
+         */
+        CHECK(gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, xcred));
+
+        /* connect to the peer
+         */
+        sd = tcp_connect();
+
+        gnutls_transport_set_int(session, sd);
+        gnutls_handshake_set_timeout(session,
+                                     GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
+
+        /* Perform the TLS handshake
+         */
+        do {
+                ret = gnutls_handshake(session);
+        }
+        while (ret < 0 && gnutls_error_is_fatal(ret) == 0);
+
+        if (ret < 0) {
+                fprintf(stderr, "*** Handshake failed\n");
+                gnutls_perror(ret);
+                goto end;
+        } else {
+                char *desc;
+
+                desc = gnutls_session_get_desc(session);
+                printf("- Session info: %s\n", desc);
+                gnutls_free(desc);
+        }
+
+        LOOP_CHECK(ret, gnutls_record_send(session, MSG, strlen(MSG)));
+
+        LOOP_CHECK(ret, gnutls_record_recv(session, buffer, MAX_BUF));
+        if (ret == 0) {
+                printf("- Peer has closed the TLS connection\n");
+                goto end;
+        } else if (ret < 0 && gnutls_error_is_fatal(ret) == 0) {
+                fprintf(stderr, "*** Warning: %s\n", gnutls_strerror(ret));
+        } else if (ret < 0) {
+                fprintf(stderr, "*** Error: %s\n", gnutls_strerror(ret));
+                goto end;
+        }
+
+        if (ret > 0) {
+                printf("- Received %d bytes: ", ret);
+                for (ii = 0; ii < ret; ii++) {
+                        fputc(buffer[ii], stdout);
+                }
+                fputs("\n", stdout);
+        }
+
+        CHECK(gnutls_bye(session, GNUTLS_SHUT_RDWR));
+
+      end:
+
+        tcp_close(sd);
+
+        gnutls_deinit(session);
+
+        gnutls_certificate_free_credentials(xcred);
+
+        gnutls_global_deinit();
+
+        return 0;
+}
+
+/* This function will verify the peer's certificate, and check
+ * if the hostname matches, as well as the activation, expiration dates.
+ */
+static int _verify_certificate_callback(gnutls_session_t session)
+{
+        unsigned int status;
+        int type;
+        const char *hostname;
+        gnutls_datum_t out;
+
+        /* read hostname */
+        hostname = gnutls_session_get_ptr(session);
+
+        /* This verification function uses the trusted CAs in the credentials
+         * structure. So you must have installed one or more CA certificates.
+         */
+
+        CHECK(gnutls_certificate_verify_peers3(session, hostname,
+					       &status));
+
+        type = gnutls_certificate_type_get(session);
+
+        CHECK(gnutls_certificate_verification_status_print(status, type,
+                                                           &out, 0));
+
+        printf("%s", out.data);
+
+        gnutls_free(out.data);
+
+        if (status != 0)        /* Certificate is not trusted */
+                return GNUTLS_E_CERTIFICATE_ERROR;
+
+        /* notify gnutls to continue handshake normally */
+        return 0;
+}
+
+
+File: gnutls.info,  Node: Client example in C++,  Next: Echo server with PSK authentication,  Prev: Legacy client example with X.509 certificate support,  Up: More advanced client and servers
+
+7.3.8 Client example using the C++ API
+--------------------------------------
+
+The following client is a simple example of a client client utilizing
+the GnuTLS C++ API.
+
+#include <config.h>
+#include <iostream>
+#include <stdexcept>
+#include <gnutls/gnutls.h>
+#include <gnutls/gnutlsxx.h>
+#include <cstring> /* for strlen */
+
+/* A very basic TLS client, with anonymous authentication.
+ * written by Eduardo Villanueva Che.
+ */
+
+#define MAX_BUF 1024
+#define SA struct sockaddr
+
+#define CAFILE "ca.pem"
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+extern "C"
+{
+    int tcp_connect(void);
+    void tcp_close(int sd);
+}
+
+
+int main(void)
+{
+    int sd = -1;
+    gnutls_global_init();
+
+    try
+    {
+
+        /* Allow connections to servers that have OpenPGP keys as well.
+         */
+        gnutls::client_session session;
+
+        /* X509 stuff */
+        gnutls::certificate_credentials credentials;
+
+
+        /* sets the trusted cas file
+         */
+        credentials.set_x509_trust_file(CAFILE, GNUTLS_X509_FMT_PEM);
+        /* put the x509 credentials to the current session
+         */
+        session.set_credentials(credentials);
+
+        /* Use default priorities */
+        session.set_priority ("NORMAL", NULL);
+
+        /* connect to the peer
+         */
+        sd = tcp_connect();
+        session.set_transport_ptr((gnutls_transport_ptr_t) (ptrdiff_t)sd);
+
+        /* Perform the TLS handshake
+         */
+        int ret = session.handshake();
+        if (ret < 0)
+        {
+            throw std::runtime_error("Handshake failed");
+        }
+        else
+        {
+            std::cout << "- Handshake was completed" << std::endl;
+        }
+
+        session.send(MSG, strlen(MSG));
+        char buffer[MAX_BUF + 1];
+        ret = session.recv(buffer, MAX_BUF);
+        if (ret == 0)
+        {
+            throw std::runtime_error("Peer has closed the TLS connection");
+        }
+        else if (ret < 0)
+        {
+            throw std::runtime_error(gnutls_strerror(ret));
+        }
+
+        std::cout << "- Received " << ret << " bytes:" << std::endl;
+        std::cout.write(buffer, ret);
+        std::cout << std::endl;
+
+        session.bye(GNUTLS_SHUT_RDWR);
+    }
+    catch (std::exception &ex)
+    {
+        std::cerr << "Exception caught: " << ex.what() << std::endl;
+    }
+
+    if (sd != -1)
+        tcp_close(sd);
+
+    gnutls_global_deinit();
+
+    return 0;
+}
+
+
+File: gnutls.info,  Node: Echo server with PSK authentication,  Next: Echo server with SRP authentication,  Prev: Client example in C++,  Up: More advanced client and servers
+
+7.3.9 Echo server with PSK authentication
+-----------------------------------------
+
+This is a server which supports PSK authentication.
+
+/* This example code is placed in the public domain. */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <errno.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <string.h>
+#include <unistd.h>
+#include <gnutls/gnutls.h>
+
+#define KEYFILE "key.pem"
+#define CERTFILE "cert.pem"
+#define CAFILE "/etc/ssl/certs/ca-certificates.crt"
+#define CRLFILE "crl.pem"
+
+#define LOOP_CHECK(rval, cmd) \
+        do { \
+                rval = cmd; \
+        } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED)
+
+/* This is a sample TLS echo server, supporting X.509 and PSK
+   authentication.
+ */
+
+#define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
+#define MAX_BUF 1024
+#define PORT 5556               /* listen to 5556 port */
+
+static int
+pskfunc(gnutls_session_t session, const char *username,
+        gnutls_datum_t * key)
+{
+        printf("psk: username %s\n", username);
+        key->data = gnutls_malloc(4);
+        key->data[0] = 0xDE;
+        key->data[1] = 0xAD;
+        key->data[2] = 0xBE;
+        key->data[3] = 0xEF;
+        key->size = 4;
+        return 0;
+}
+
+int main(void)
+{
+        int err, listen_sd;
+        int sd, ret;
+        struct sockaddr_in sa_serv;
+        struct sockaddr_in sa_cli;
+        socklen_t client_len;
+        char topbuf[512];
+        gnutls_session_t session;
+        gnutls_certificate_credentials_t x509_cred;
+        gnutls_psk_server_credentials_t psk_cred;
+        gnutls_priority_t priority_cache;
+        char buffer[MAX_BUF + 1];
+        int optval = 1;
+        int kx;
+
+        if (gnutls_check_version("3.1.4") == NULL) {
+                fprintf(stderr, "GnuTLS 3.1.4 or later is required for this example\n");
+                exit(1);
+        }
+
+        /* for backwards compatibility with gnutls < 3.3.0 */
+        gnutls_global_init();
+
+        gnutls_certificate_allocate_credentials(&x509_cred);
+        gnutls_certificate_set_x509_trust_file(x509_cred, CAFILE,
+                                               GNUTLS_X509_FMT_PEM);
+
+        gnutls_certificate_set_x509_crl_file(x509_cred, CRLFILE,
+                                             GNUTLS_X509_FMT_PEM);
+
+        gnutls_certificate_set_x509_key_file(x509_cred, CERTFILE, KEYFILE,
+                                             GNUTLS_X509_FMT_PEM);
+
+        gnutls_psk_allocate_server_credentials(&psk_cred);
+        gnutls_psk_set_server_credentials_function(psk_cred, pskfunc);
+
+        /* pre-3.6.3 equivalent:
+         * gnutls_priority_init(&priority_cache,
+         *                      "NORMAL:+PSK:+ECDHE-PSK:+DHE-PSK",
+         *                      NULL);
+         */
+        gnutls_priority_init2(&priority_cache,
+                              "+ECDHE-PSK:+DHE-PSK:+PSK",
+                              NULL, GNUTLS_PRIORITY_INIT_DEF_APPEND);
+
+        gnutls_certificate_set_known_dh_params(x509_cred, GNUTLS_SEC_PARAM_MEDIUM);
+
+        /* Socket operations
+         */
+        listen_sd = socket(AF_INET, SOCK_STREAM, 0);
+        SOCKET_ERR(listen_sd, "socket");
+
+        memset(&sa_serv, '\0', sizeof(sa_serv));
+        sa_serv.sin_family = AF_INET;
+        sa_serv.sin_addr.s_addr = INADDR_ANY;
+        sa_serv.sin_port = htons(PORT); /* Server Port number */
+
+        setsockopt(listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &optval,
+                   sizeof(int));
+
+        err =
+            bind(listen_sd, (struct sockaddr *) &sa_serv, sizeof(sa_serv));
+        SOCKET_ERR(err, "bind");
+        err = listen(listen_sd, 1024);
+        SOCKET_ERR(err, "listen");
+
+        printf("Server ready. Listening to port '%d'.\n\n", PORT);
+
+        client_len = sizeof(sa_cli);
+        for (;;) {
+                gnutls_init(&session, GNUTLS_SERVER);
+                gnutls_priority_set(session, priority_cache);
+                gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
+                                       x509_cred);
+                gnutls_credentials_set(session, GNUTLS_CRD_PSK, psk_cred);
+
+                /* request client certificate if any.
+                 */
+                gnutls_certificate_server_set_request(session,
+                                                      GNUTLS_CERT_REQUEST);
+
+                sd = accept(listen_sd, (struct sockaddr *) &sa_cli,
+                            &client_len);
+
+                printf("- connection from %s, port %d\n",
+                       inet_ntop(AF_INET, &sa_cli.sin_addr, topbuf,
+                                 sizeof(topbuf)), ntohs(sa_cli.sin_port));
+
+                gnutls_transport_set_int(session, sd);
+                LOOP_CHECK(ret, gnutls_handshake(session));
+                if (ret < 0) {
+                        close(sd);
+                        gnutls_deinit(session);
+                        fprintf(stderr,
+                                "*** Handshake has failed (%s)\n\n",
+                                gnutls_strerror(ret));
+                        continue;
+                }
+                printf("- Handshake was completed\n");
+
+                kx = gnutls_kx_get(session);
+                if (kx == GNUTLS_KX_PSK || kx == GNUTLS_KX_DHE_PSK ||
+                    kx == GNUTLS_KX_ECDHE_PSK) {
+                        printf("- User %s was connected\n",
+                               gnutls_psk_server_get_username(session));
+                }
+
+                /* see the Getting peer's information example */
+                /* print_info(session); */
+
+                for (;;) {
+                        LOOP_CHECK(ret, gnutls_record_recv(session, buffer, MAX_BUF));
+
+                        if (ret == 0) {
+                                printf
+                                    ("\n- Peer has closed the GnuTLS connection\n");
+                                break;
+                        } else if (ret < 0
+                                   && gnutls_error_is_fatal(ret) == 0) {
+                                fprintf(stderr, "*** Warning: %s\n",
+                                        gnutls_strerror(ret));
+                        } else if (ret < 0) {
+                                fprintf(stderr, "\n*** Received corrupted "
+                                        "data(%d). Closing the connection.\n\n",
+                                        ret);
+                                break;
+                        } else if (ret > 0) {
+                                /* echo data back to the client
+                                 */
+                                gnutls_record_send(session, buffer, ret);
+                        }
+                }
+                printf("\n");
+                /* do not wait for the peer to close the connection.
+                 */
+                LOOP_CHECK(ret, gnutls_bye(session, GNUTLS_SHUT_WR));
+
+                close(sd);
+                gnutls_deinit(session);
+
+        }
+        close(listen_sd);
+
+        gnutls_certificate_free_credentials(x509_cred);
+        gnutls_psk_free_server_credentials(psk_cred);
+
+        gnutls_priority_deinit(priority_cache);
+
+        gnutls_global_deinit();
+
+        return 0;
+
+}
+