This manual is last updated 3 January 2019 for version 3.6.7 of GnuTLS.

Copyright (C) 2001-2019 Free Software Foundation, Inc.\\ Copyright (C)
2001-2019 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".

7.3.11 Echo server with anonymous authentication
------------------------------------------------

This example server supports anonymous authentication, and could be used
to serve the example client for anonymous 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>

/* This is a sample TLS 1.0 echo server, for anonymous authentication only.
 */

#define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
#define MAX_BUF 1024
#define PORT 5556               /* listen to 5556 port */

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_anon_server_credentials_t anoncred;
        char buffer[MAX_BUF + 1];
        int optval = 1;

        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_anon_allocate_server_credentials(&anoncred);

        gnutls_anon_set_server_known_dh_params(anoncred, 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_direct(session,
                                           "NORMAL:+ANON-ECDH:+ANON-DH",
                                           NULL);
                gnutls_credentials_set(session, GNUTLS_CRD_ANON, anoncred);

                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);

                do {
                        ret = gnutls_handshake(session);
                }
                while (ret < 0 && gnutls_error_is_fatal(ret) == 0);

                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 (;;) {
                        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.
                 */
                gnutls_bye(session, GNUTLS_SHUT_WR);

                close(sd);
                gnutls_deinit(session);

        }
        close(listen_sd);

        gnutls_anon_free_server_credentials(anoncred);

        gnutls_global_deinit();

        return 0;

}

7.3.12 Helper functions for TCP connections
-------------------------------------------

Those helper function abstract away TCP connection handling from the
other examples.  It is required to build some examples.

/* 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 <netinet/in.h>
#include <unistd.h>

/* tcp.c */
int tcp_connect(void);
void tcp_close(int sd);

/* Connects to the peer and returns a socket
 * descriptor.
 */
extern int tcp_connect(void)
{
        const char *PORT = "5556";
        const char *SERVER = "127.0.0.1";
        int err, sd;
        struct sockaddr_in sa;

        /* connects to server
         */
        sd = socket(AF_INET, SOCK_STREAM, 0);

        memset(&sa, '\0', sizeof(sa));
        sa.sin_family = AF_INET;
        sa.sin_port = htons(atoi(PORT));
        inet_pton(AF_INET, SERVER, &sa.sin_addr);

        err = connect(sd, (struct sockaddr *) &sa, sizeof(sa));
        if (err < 0) {
                fprintf(stderr, "Connect error\n");
                exit(1);
        }

        return sd;
}

/* closes the given socket descriptor.
 */
extern void tcp_close(int sd)
{
        shutdown(sd, SHUT_RDWR);        /* no more receptions */
        close(sd);
}

7.3.13 Helper functions for UDP connections
-------------------------------------------

The UDP helper functions abstract away UDP connection handling from the
other examples.  It is required to build the examples using UDP.

/* 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 <netinet/in.h>
#include <unistd.h>

/* udp.c */
int udp_connect(void);
void udp_close(int sd);

/* Connects to the peer and returns a socket
 * descriptor.
 */
extern int udp_connect(void)
{
        const char *PORT = "5557";
        const char *SERVER = "127.0.0.1";
        int err, sd;
#if defined(IP_DONTFRAG) || defined(IP_MTU_DISCOVER)
        int optval;
#endif
        struct sockaddr_in sa;

        /* connects to server
         */
        sd = socket(AF_INET, SOCK_DGRAM, 0);

        memset(&sa, '\0', sizeof(sa));
        sa.sin_family = AF_INET;
        sa.sin_port = htons(atoi(PORT));
        inet_pton(AF_INET, SERVER, &sa.sin_addr);

#if defined(IP_DONTFRAG)
        optval = 1;
        setsockopt(sd, IPPROTO_IP, IP_DONTFRAG,
                   (const void *) &optval, sizeof(optval));
#elif defined(IP_MTU_DISCOVER)
        optval = IP_PMTUDISC_DO;
        setsockopt(sd, IPPROTO_IP, IP_MTU_DISCOVER,
                   (const void *) &optval, sizeof(optval));
#endif

        err = connect(sd, (struct sockaddr *) &sa, sizeof(sa));
        if (err < 0) {
                fprintf(stderr, "Connect error\n");
                exit(1);
        }

        return sd;
}

/* closes the given socket descriptor.
 */
extern void udp_close(int sd)
{
        close(sd);
}

7.4 OCSP example
================

Generate OCSP request
---------------------

A small tool to generate OCSP requests.

/* 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/crypto.h>
#include <gnutls/ocsp.h>
#ifndef NO_LIBCURL
#include <curl/curl.h>
#endif
#include "read-file.h"

size_t get_data(void *buffer, size_t size, size_t nmemb, void *userp);
static gnutls_x509_crt_t load_cert(const char *cert_file);
static void _response_info(const gnutls_datum_t * data);
static void
_generate_request(gnutls_datum_t * rdata, gnutls_x509_crt_t cert,
                  gnutls_x509_crt_t issuer, gnutls_datum_t *nonce);
static int
_verify_response(gnutls_datum_t * data, gnutls_x509_crt_t cert,
                 gnutls_x509_crt_t signer, gnutls_datum_t *nonce);

/* This program queries an OCSP server.
   It expects three files. argv[1] containing the certificate to
   be checked, argv[2] holding the issuer for this certificate,
   and argv[3] holding a trusted certificate to verify OCSP's response.
   argv[4] is optional and should hold the server host name.

   For simplicity the libcurl library is used.
 */

int main(int argc, char *argv[])
{
        gnutls_datum_t ud, tmp;
        int ret;
        gnutls_datum_t req;
        gnutls_x509_crt_t cert, issuer, signer;
#ifndef NO_LIBCURL
        CURL *handle;
        struct curl_slist *headers = NULL;
#endif
        int v, seq;
        const char *cert_file = argv[1];
        const char *issuer_file = argv[2];
        const char *signer_file = argv[3];
        char *hostname = NULL;
        unsigned char noncebuf[23];
        gnutls_datum_t nonce = { noncebuf, sizeof(noncebuf) };

        gnutls_global_init();

        if (argc > 4)
                hostname = argv[4];

        ret = gnutls_rnd(GNUTLS_RND_NONCE, nonce.data, nonce.size);
        if (ret < 0)
                exit(1);

        cert = load_cert(cert_file);
        issuer = load_cert(issuer_file);
        signer = load_cert(signer_file);

        if (hostname == NULL) {

                for (seq = 0;; seq++) {
                        ret =
                            gnutls_x509_crt_get_authority_info_access(cert,
                                                                      seq,
                                                                      GNUTLS_IA_OCSP_URI,
                                                                      &tmp,
                                                                      NULL);
                        if (ret == GNUTLS_E_UNKNOWN_ALGORITHM)
                                continue;
                        if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE) {
                                fprintf(stderr,
                                        "No URI was found in the certificate.\n");
                                exit(1);
                        }
                        if (ret < 0) {
                                fprintf(stderr, "error: %s\n",
                                        gnutls_strerror(ret));
                                exit(1);
                        }

                        printf("CA issuers URI: %.*s\n", tmp.size,
                               tmp.data);

                        hostname = malloc(tmp.size + 1);
                        memcpy(hostname, tmp.data, tmp.size);
                        hostname[tmp.size] = 0;

                        gnutls_free(tmp.data);
                        break;
                }

        }

        /* Note that the OCSP servers hostname might be available
         * using gnutls_x509_crt_get_authority_info_access() in the issuer's
         * certificate */

        memset(&ud, 0, sizeof(ud));
        fprintf(stderr, "Connecting to %s\n", hostname);

        _generate_request(&req, cert, issuer, &nonce);

#ifndef NO_LIBCURL
        curl_global_init(CURL_GLOBAL_ALL);

        handle = curl_easy_init();
        if (handle == NULL)
                exit(1);

        headers =
            curl_slist_append(headers,
                              "Content-Type: application/ocsp-request");

        curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(handle, CURLOPT_POSTFIELDS, (void *) req.data);
        curl_easy_setopt(handle, CURLOPT_POSTFIELDSIZE, req.size);
        curl_easy_setopt(handle, CURLOPT_URL, hostname);
        curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, get_data);
        curl_easy_setopt(handle, CURLOPT_WRITEDATA, &ud);

        ret = curl_easy_perform(handle);
        if (ret != 0) {
                fprintf(stderr, "curl[%d] error %d\n", __LINE__, ret);
                exit(1);
        }

        curl_easy_cleanup(handle);
#endif

        _response_info(&ud);

        v = _verify_response(&ud, cert, signer, &nonce);

        gnutls_x509_crt_deinit(cert);
        gnutls_x509_crt_deinit(issuer);
        gnutls_x509_crt_deinit(signer);
        gnutls_global_deinit();

        return v;
}

static void _response_info(const gnutls_datum_t * data)
{
        gnutls_ocsp_resp_t resp;
        int ret;
        gnutls_datum buf;

        ret = gnutls_ocsp_resp_init(&resp);
        if (ret < 0)
                exit(1);

        ret = gnutls_ocsp_resp_import(resp, data);
        if (ret < 0)
                exit(1);

        ret = gnutls_ocsp_resp_print(resp, GNUTLS_OCSP_PRINT_FULL, &buf);
        if (ret != 0)
                exit(1);

        printf("%.*s", buf.size, buf.data);
        gnutls_free(buf.data);

        gnutls_ocsp_resp_deinit(resp);
}

static gnutls_x509_crt_t load_cert(const char *cert_file)
{
        gnutls_x509_crt_t crt;
        int ret;
        gnutls_datum_t data;
        size_t size;

        ret = gnutls_x509_crt_init(&crt);
        if (ret < 0)
                exit(1);

        data.data = (void *) read_binary_file(cert_file, &size);
        data.size = size;

        if (!data.data) {
                fprintf(stderr, "Cannot open file: %s\n", cert_file);
                exit(1);
        }

        ret = gnutls_x509_crt_import(crt, &data, GNUTLS_X509_FMT_PEM);
        free(data.data);
        if (ret < 0) {
                fprintf(stderr, "Cannot import certificate in %s: %s\n",
                        cert_file, gnutls_strerror(ret));
                exit(1);
        }

        return crt;
}

static void
_generate_request(gnutls_datum_t * rdata, gnutls_x509_crt_t cert,
                  gnutls_x509_crt_t issuer, gnutls_datum_t *nonce)
{
        gnutls_ocsp_req_t req;
        int ret;

        ret = gnutls_ocsp_req_init(&req);
        if (ret < 0)
                exit(1);

        ret = gnutls_ocsp_req_add_cert(req, GNUTLS_DIG_SHA1, issuer, cert);
        if (ret < 0)
                exit(1);

        ret = gnutls_ocsp_req_set_nonce(req, 0, nonce);
        if (ret < 0)
                exit(1);

        ret = gnutls_ocsp_req_export(req, rdata);
        if (ret != 0)
                exit(1);

        gnutls_ocsp_req_deinit(req);

        return;
}

static int
_verify_response(gnutls_datum_t * data, gnutls_x509_crt_t cert,
                 gnutls_x509_crt_t signer, gnutls_datum_t *nonce)
{
        gnutls_ocsp_resp_t resp;
        int ret;
        unsigned verify;
        gnutls_datum_t rnonce;

        ret = gnutls_ocsp_resp_init(&resp);
        if (ret < 0)
                exit(1);

        ret = gnutls_ocsp_resp_import(resp, data);
        if (ret < 0)
                exit(1);

        ret = gnutls_ocsp_resp_check_crt(resp, 0, cert);
        if (ret < 0)
                exit(1);

	ret = gnutls_ocsp_resp_get_nonce(resp, NULL, &rnonce);
	if (ret < 0)
		exit(1);

	if (rnonce.size != nonce->size || memcmp(nonce->data, rnonce.data,
		nonce->size) != 0) {
		exit(1);
	}

        ret = gnutls_ocsp_resp_verify_direct(resp, signer, &verify, 0);
        if (ret < 0)
                exit(1);

        printf("Verifying OCSP Response: ");
        if (verify == 0)
                printf("Verification success!\n");
        else
                printf("Verification error!\n");

        if (verify & GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND)
                printf("Signer cert not found\n");

        if (verify & GNUTLS_OCSP_VERIFY_SIGNER_KEYUSAGE_ERROR)
                printf("Signer cert keyusage error\n");

        if (verify & GNUTLS_OCSP_VERIFY_UNTRUSTED_SIGNER)
                printf("Signer cert is not trusted\n");

        if (verify & GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM)
                printf("Insecure algorithm\n");

        if (verify & GNUTLS_OCSP_VERIFY_SIGNATURE_FAILURE)
                printf("Signature failure\n");

        if (verify & GNUTLS_OCSP_VERIFY_CERT_NOT_ACTIVATED)
                printf("Signer cert not yet activated\n");

        if (verify & GNUTLS_OCSP_VERIFY_CERT_EXPIRED)
                printf("Signer cert expired\n");

        gnutls_free(rnonce.data);
        gnutls_ocsp_resp_deinit(resp);

        return verify;
}

size_t get_data(void *buffer, size_t size, size_t nmemb, void *userp)
{
        gnutls_datum_t *ud = userp;

        size *= nmemb;

        ud->data = realloc(ud->data, size + ud->size);
        if (ud->data == NULL) {
                fprintf(stderr, "Not enough memory for the request\n");
                exit(1);
        }

        memcpy(&ud->data[ud->size], buffer, size);
        ud->size += size;

        return size;
}

7.5 Miscellaneous examples
==========================

7.5.1 Checking for an alert
---------------------------

This is a function that checks if an alert has been received in the
current session.

/* 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 "examples.h"

/* This function will check whether the given return code from
 * a gnutls function (recv/send), is an alert, and will print
 * that alert.
 */
void check_alert(gnutls_session_t session, int ret)
{
        int last_alert;

        if (ret == GNUTLS_E_WARNING_ALERT_RECEIVED
            || ret == GNUTLS_E_FATAL_ALERT_RECEIVED) {
                last_alert = gnutls_alert_get(session);

                /* The check for renegotiation is only useful if we are
                 * a server, and we had requested a rehandshake.
                 */
                if (last_alert == GNUTLS_A_NO_RENEGOTIATION &&
                    ret == GNUTLS_E_WARNING_ALERT_RECEIVED)
                        printf("* Received NO_RENEGOTIATION alert. "
                               "Client Does not support renegotiation.\n");
                else
                        printf("* Received alert '%d': %s.\n", last_alert,
                               gnutls_alert_get_name(last_alert));
        }
}

7.5.2 X.509 certificate parsing example
---------------------------------------

To demonstrate the X.509 parsing capabilities an example program is
listed below.  That program reads the peer's certificate, and prints
information about 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 <gnutls/gnutls.h>
#include <gnutls/x509.h>

#include "examples.h"

static const char *bin2hex(const void *bin, size_t bin_size)
{
        static char printable[110];
        const unsigned char *_bin = bin;
        char *print;
        size_t i;

        if (bin_size > 50)
                bin_size = 50;

        print = printable;
        for (i = 0; i < bin_size; i++) {
                sprintf(print, "%.2x ", _bin[i]);
                print += 2;
        }

        return printable;
}

/* This function will print information about this session's peer
 * certificate.
 */
void print_x509_certificate_info(gnutls_session_t session)
{
        char serial[40];
        char dn[256];
        size_t size;
        unsigned int algo, bits;
        time_t expiration_time, activation_time;
        const gnutls_datum_t *cert_list;
        unsigned int cert_list_size = 0;
        gnutls_x509_crt_t cert;
        gnutls_datum_t cinfo;

        /* This function only works for X.509 certificates.
         */
        if (gnutls_certificate_type_get(session) != GNUTLS_CRT_X509)
                return;

        cert_list = gnutls_certificate_get_peers(session, &cert_list_size);

        printf("Peer provided %d certificates.\n", cert_list_size);

        if (cert_list_size > 0) {
                int ret;

                /* we only print information about the first certificate.
                 */
                gnutls_x509_crt_init(&cert);

                gnutls_x509_crt_import(cert, &cert_list[0],
                                       GNUTLS_X509_FMT_DER);

                printf("Certificate info:\n");

                /* This is the preferred way of printing short information about
                   a certificate. */

                ret =
                    gnutls_x509_crt_print(cert, GNUTLS_CRT_PRINT_ONELINE,
                                          &cinfo);
                if (ret == 0) {
                        printf("\t%s\n", cinfo.data);
                        gnutls_free(cinfo.data);
                }

                /* If you want to extract fields manually for some other reason,
                   below are popular example calls. */

                expiration_time =
                    gnutls_x509_crt_get_expiration_time(cert);
                activation_time =
                    gnutls_x509_crt_get_activation_time(cert);

                printf("\tCertificate is valid since: %s",
                       ctime(&activation_time));
                printf("\tCertificate expires: %s",
                       ctime(&expiration_time));

                /* Print the serial number of the certificate.
                 */
                size = sizeof(serial);
                gnutls_x509_crt_get_serial(cert, serial, &size);

                printf("\tCertificate serial number: %s\n",
                       bin2hex(serial, size));

                /* Extract some of the public key algorithm's parameters
                 */
                algo = gnutls_x509_crt_get_pk_algorithm(cert, &bits);

                printf("Certificate public key: %s",
                       gnutls_pk_algorithm_get_name(algo));

                /* Print the version of the X.509
                 * certificate.
                 */
                printf("\tCertificate version: #%d\n",
                       gnutls_x509_crt_get_version(cert));

                size = sizeof(dn);
                gnutls_x509_crt_get_dn(cert, dn, &size);
                printf("\tDN: %s\n", dn);

                size = sizeof(dn);
                gnutls_x509_crt_get_issuer_dn(cert, dn, &size);
                printf("\tIssuer's DN: %s\n", dn);

                gnutls_x509_crt_deinit(cert);

        }
}

7.5.3 Listing the ciphersuites in a priority string
---------------------------------------------------

This is a small program to list the enabled ciphersuites by a priority
string.

/* This example code is placed in the public domain. */

#include <config.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <gnutls/gnutls.h>

static void print_cipher_suite_list(const char *priorities)
{
        size_t i;
        int ret;
        unsigned int idx;
        const char *name;
        const char *err;
        unsigned char id[2];
        gnutls_protocol_t version;
        gnutls_priority_t pcache;

        if (priorities != NULL) {
                printf("Cipher suites for %s\n", priorities);

                ret = gnutls_priority_init(&pcache, priorities, &err);
                if (ret < 0) {
                        fprintf(stderr, "Syntax error at: %s\n", err);
                        exit(1);
                }

                for (i = 0;; i++) {
                        ret =
                            gnutls_priority_get_cipher_suite_index(pcache,
                                                                   i,
                                                                   &idx);
                        if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
                                break;
                        if (ret == GNUTLS_E_UNKNOWN_CIPHER_SUITE)
                                continue;

                        name =
                            gnutls_cipher_suite_info(idx, id, NULL, NULL,
                                                     NULL, &version);

                        if (name != NULL)
                                printf("%-50s\t0x%02x, 0x%02x\t%s\n",
                                       name, (unsigned char) id[0],
                                       (unsigned char) id[1],
                                       gnutls_protocol_get_name(version));
                }

                return;
        }
}

int main(int argc, char **argv)
{
        if (argc > 1)
                print_cipher_suite_list(argv[1]);
        return 0;
}

7.5.4 PKCS #12 structure generation example
-------------------------------------------

This small program demonstrates the usage of the PKCS #12 API, by
generating such a structure.

/* 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/pkcs12.h>

#include "examples.h"

#define OUTFILE "out.p12"

/* This function will write a pkcs12 structure into a file.
 * cert: is a DER encoded certificate
 * pkcs8_key: is a PKCS #8 encrypted key (note that this must be
 *  encrypted using a PKCS #12 cipher, or some browsers will crash)
 * password: is the password used to encrypt the PKCS #12 packet.
 */
int
write_pkcs12(const gnutls_datum_t * cert,
             const gnutls_datum_t * pkcs8_key, const char *password)
{
        gnutls_pkcs12_t pkcs12;
        int ret, bag_index;
        gnutls_pkcs12_bag_t bag, key_bag;
        char pkcs12_struct[10 * 1024];
        size_t pkcs12_struct_size;
        FILE *fd;

        /* A good idea might be to use gnutls_x509_privkey_get_key_id()
         * to obtain a unique ID.
         */
        gnutls_datum_t key_id = { (void *) "\x00\x00\x07", 3 };

        gnutls_global_init();

        /* Firstly we create two helper bags, which hold the certificate,
         * and the (encrypted) key.
         */

        gnutls_pkcs12_bag_init(&bag);
        gnutls_pkcs12_bag_init(&key_bag);

        ret =
            gnutls_pkcs12_bag_set_data(bag, GNUTLS_BAG_CERTIFICATE, cert);
        if (ret < 0) {
                fprintf(stderr, "ret: %s\n", gnutls_strerror(ret));
                return 1;
        }

        /* ret now holds the bag's index.
         */
        bag_index = ret;

        /* Associate a friendly name with the given certificate. Used
         * by browsers.
         */
        gnutls_pkcs12_bag_set_friendly_name(bag, bag_index, "My name");

        /* Associate the certificate with the key using a unique key
         * ID.
         */
        gnutls_pkcs12_bag_set_key_id(bag, bag_index, &key_id);

        /* use weak encryption for the certificate.
         */
        gnutls_pkcs12_bag_encrypt(bag, password,
                                  GNUTLS_PKCS_USE_PKCS12_RC2_40);

        /* Now the key.
         */

        ret = gnutls_pkcs12_bag_set_data(key_bag,
                                         GNUTLS_BAG_PKCS8_ENCRYPTED_KEY,
                                         pkcs8_key);
        if (ret < 0) {
                fprintf(stderr, "ret: %s\n", gnutls_strerror(ret));
                return 1;
        }

        /* Note that since the PKCS #8 key is already encrypted we don't
         * bother encrypting that bag.
         */
        bag_index = ret;

        gnutls_pkcs12_bag_set_friendly_name(key_bag, bag_index, "My name");

        gnutls_pkcs12_bag_set_key_id(key_bag, bag_index, &key_id);

        /* The bags were filled. Now create the PKCS #12 structure.
         */
        gnutls_pkcs12_init(&pkcs12);

        /* Insert the two bags in the PKCS #12 structure.
         */

        gnutls_pkcs12_set_bag(pkcs12, bag);
        gnutls_pkcs12_set_bag(pkcs12, key_bag);

        /* Generate a message authentication code for the PKCS #12
         * structure.
         */
        gnutls_pkcs12_generate_mac(pkcs12, password);

        pkcs12_struct_size = sizeof(pkcs12_struct);
        ret =
            gnutls_pkcs12_export(pkcs12, GNUTLS_X509_FMT_DER,
                                 pkcs12_struct, &pkcs12_struct_size);
        if (ret < 0) {
                fprintf(stderr, "ret: %s\n", gnutls_strerror(ret));
                return 1;
        }

        fd = fopen(OUTFILE, "w");
        if (fd == NULL) {
                fprintf(stderr, "cannot open file\n");
                return 1;
        }
        fwrite(pkcs12_struct, 1, pkcs12_struct_size, fd);
        fclose(fd);

        gnutls_pkcs12_bag_deinit(bag);
        gnutls_pkcs12_bag_deinit(key_bag);
        gnutls_pkcs12_deinit(pkcs12);

        return 0;
}

8 Using GnuTLS as a cryptographic library
*****************************************

GnuTLS is not a low-level cryptographic library, i.e., it does not
provide access to basic cryptographic primitives.  However it abstracts
the internal cryptographic back-end (see Cryptographic Backend),
providing symmetric crypto, hash and HMAC algorithms, as well access to
the random number generation.  For a low-level crypto API the usage of
nettle (1) library is recommended.

   ---------- Footnotes ----------

   (1) See <https://www.lysator.liu.se/~nisse/nettle/>.

8.1 Symmetric algorithms
========================

The available functions to access symmetric crypto algorithms operations
are listed in the sections below.  The supported algorithms are the
algorithms required by the TLS protocol.  They are listed in
Figure 8.1.  Note that there two types of
ciphers, the ones providing an authenticated-encryption with associated
data (AEAD), and the legacy ciphers which provide raw access to the
ciphers.  We recommend the use of the AEAD APIs for new applications as
it is designed to minimize misuse of cryptography.

'GNUTLS_CIPHER_UNKNOWN'
     Value to identify an unknown/unsupported algorithm.
'GNUTLS_CIPHER_NULL'
     The NULL (identity) encryption algorithm.
'GNUTLS_CIPHER_ARCFOUR_128'
     ARCFOUR stream cipher with 128-bit keys.
'GNUTLS_CIPHER_3DES_CBC'
     3DES in CBC mode.
'GNUTLS_CIPHER_AES_128_CBC'
     AES in CBC mode with 128-bit keys.
'GNUTLS_CIPHER_AES_256_CBC'
     AES in CBC mode with 256-bit keys.
'GNUTLS_CIPHER_ARCFOUR_40'
     ARCFOUR stream cipher with 40-bit keys.
'GNUTLS_CIPHER_CAMELLIA_128_CBC'
     Camellia in CBC mode with 128-bit keys.
'GNUTLS_CIPHER_CAMELLIA_256_CBC'
     Camellia in CBC mode with 256-bit keys.
'GNUTLS_CIPHER_AES_192_CBC'
     AES in CBC mode with 192-bit keys.
'GNUTLS_CIPHER_AES_128_GCM'
     AES in GCM mode with 128-bit keys.
'GNUTLS_CIPHER_AES_256_GCM'
     AES in GCM mode with 256-bit keys.
'GNUTLS_CIPHER_CAMELLIA_192_CBC'
     Camellia in CBC mode with 192-bit keys.
'GNUTLS_CIPHER_SALSA20_256'
     Salsa20 with 256-bit keys.
'GNUTLS_CIPHER_ESTREAM_SALSA20_256'
     Estream's Salsa20 variant with 256-bit keys.
'GNUTLS_CIPHER_CAMELLIA_128_GCM'
     CAMELLIA in GCM mode with 128-bit keys.
'GNUTLS_CIPHER_CAMELLIA_256_GCM'
     CAMELLIA in GCM mode with 256-bit keys.
'GNUTLS_CIPHER_RC2_40_CBC'
     RC2 in CBC mode with 40-bit keys.
'GNUTLS_CIPHER_DES_CBC'
     DES in CBC mode (56-bit keys).
'GNUTLS_CIPHER_AES_128_CCM'
     AES in CCM mode with 128-bit keys.
'GNUTLS_CIPHER_AES_256_CCM'
     AES in CCM mode with 256-bit keys.
'GNUTLS_CIPHER_AES_128_CCM_8'
     AES in CCM mode with 64-bit tag and 128-bit keys.
'GNUTLS_CIPHER_AES_256_CCM_8'
     AES in CCM mode with 64-bit tag and 256-bit keys.
'GNUTLS_CIPHER_CHACHA20_POLY1305'
     The Chacha20 cipher with the Poly1305 authenticator (AEAD).
'GNUTLS_CIPHER_GOST28147_TC26Z_CFB'
     GOST 28147-89 (Magma) cipher in CFB mode with TC26 Z S-box.
'GNUTLS_CIPHER_GOST28147_CPA_CFB'
     GOST 28147-89 (Magma) cipher in CFB mode with CryptoPro A S-box.
'GNUTLS_CIPHER_GOST28147_CPB_CFB'
     GOST 28147-89 (Magma) cipher in CFB mode with CryptoPro B S-box.
'GNUTLS_CIPHER_GOST28147_CPC_CFB'
     GOST 28147-89 (Magma) cipher in CFB mode with CryptoPro C S-box.
'GNUTLS_CIPHER_GOST28147_CPD_CFB'
     GOST 28147-89 (Magma) cipher in CFB mode with CryptoPro D S-box.
'GNUTLS_CIPHER_AES_128_CFB8'
     AES in CFB8 mode with 128-bit keys.
'GNUTLS_CIPHER_AES_192_CFB8'
     AES in CFB8 mode with 192-bit keys.
'GNUTLS_CIPHER_AES_256_CFB8'
     AES in CFB8 mode with 256-bit keys.
'GNUTLS_CIPHER_IDEA_PGP_CFB'
     IDEA in CFB mode (placeholder - unsupported).
'GNUTLS_CIPHER_3DES_PGP_CFB'
     3DES in CFB mode (placeholder - unsupported).
'GNUTLS_CIPHER_CAST5_PGP_CFB'
     CAST5 in CFB mode (placeholder - unsupported).
'GNUTLS_CIPHER_BLOWFISH_PGP_CFB'
     Blowfish in CFB mode (placeholder - unsupported).
'GNUTLS_CIPHER_SAFER_SK128_PGP_CFB'
     Safer-SK in CFB mode with 128-bit keys (placeholder - unsupported).
'GNUTLS_CIPHER_AES128_PGP_CFB'
     AES in CFB mode with 128-bit keys (placeholder - unsupported).
'GNUTLS_CIPHER_AES192_PGP_CFB'
     AES in CFB mode with 192-bit keys (placeholder - unsupported).
'GNUTLS_CIPHER_AES256_PGP_CFB'
     AES in CFB mode with 256-bit keys (placeholder - unsupported).
'GNUTLS_CIPHER_TWOFISH_PGP_CFB'
     Twofish in CFB mode (placeholder - unsupported).

Figure 8.1: The supported ciphers.

Authenticated-encryption API
----------------------------

The AEAD API provides access to all ciphers supported by GnuTLS which
support authenticated encryption with associated data.  That is
particularly suitable for message or packet-encryption as it provides
authentication and encryption on the same API. See 'RFC5116' for more
information on authenticated encryption.

'INT gnutls_aead_cipher_init (gnutls_aead_cipher_hd_t * HANDLE, gnutls_cipher_algorithm_t CIPHER, const gnutls_datum_t * KEY)'
'INT gnutls_aead_cipher_encrypt (gnutls_aead_cipher_hd_t HANDLE, const void * NONCE, size_t NONCE_LEN, const void * AUTH, size_t AUTH_LEN, size_t TAG_SIZE, const void * PTEXT, size_t PTEXT_LEN, void * CTEXT, size_t * CTEXT_LEN)'
'INT gnutls_aead_cipher_decrypt (gnutls_aead_cipher_hd_t HANDLE, const void * NONCE, size_t NONCE_LEN, const void * AUTH, size_t AUTH_LEN, size_t TAG_SIZE, const void * CTEXT, size_t CTEXT_LEN, void * PTEXT, size_t * PTEXT_LEN)'
'VOID gnutls_aead_cipher_deinit (gnutls_aead_cipher_hd_t HANDLE)'

Because the encryption function above may be difficult to use with
scattered data, we provide the following API.

 -- Function: int gnutls_aead_cipher_encryptv (gnutls_aead_cipher_hd_t
          HANDLE, const void * NONCE, size_t NONCE_LEN, const giovec_t *
          AUTH_IOV, int AUTH_IOVCNT, size_t TAG_SIZE, const giovec_t *
          IOV, int IOVCNT, void * CTEXT, size_t * CTEXT_LEN)
     HANDLE: is a 'gnutls_aead_cipher_hd_t' type.

     NONCE: the nonce to set

     NONCE_LEN: The length of the nonce

     AUTH_IOV: additional data to be authenticated

     AUTH_IOVCNT: The number of buffers in 'auth_iov'

     TAG_SIZE: The size of the tag to use (use zero for the default)

     IOV: the data to be encrypted

     IOVCNT: The number of buffers in 'iov'

     CTEXT: the encrypted data including authentication tag

     CTEXT_LEN: the length of encrypted data (initially must hold the
     maximum available size, including space for tag)

     This function will encrypt the provided data buffers using the
     algorithm specified by the context.  The output data will contain
     the authentication tag.

     *Returns:* Zero or a negative error code on error.

     *Since:* 3.6.3

Legacy API
----------

The legacy API provides low-level access to all legacy ciphers supported
by GnuTLS, and some of the AEAD ciphers (e.g., AES-GCM and CHACHA20).
The restrictions of the nettle library implementation of the ciphers
apply verbatim to this API(1).

'INT gnutls_cipher_init (gnutls_cipher_hd_t * HANDLE, gnutls_cipher_algorithm_t CIPHER, const gnutls_datum_t * KEY, const gnutls_datum_t * IV)'
'INT gnutls_cipher_encrypt2 (gnutls_cipher_hd_t HANDLE, const void * PTEXT, size_t PTEXT_LEN, void * CTEXT, size_t CTEXT_LEN)'
'INT gnutls_cipher_decrypt2 (gnutls_cipher_hd_t HANDLE, const void * CTEXT, size_t CTEXT_LEN, void * PTEXT, size_t PTEXT_LEN)'
'VOID gnutls_cipher_set_iv (gnutls_cipher_hd_t HANDLE, void * IV, size_t IVLEN)'
'VOID gnutls_cipher_deinit (gnutls_cipher_hd_t HANDLE)'

'INT gnutls_cipher_add_auth (gnutls_cipher_hd_t HANDLE, const void * PTEXT, size_t PTEXT_SIZE)'
'INT gnutls_cipher_tag (gnutls_cipher_hd_t HANDLE, void * TAG, size_t TAG_SIZE)'
While the latter two functions allow the same API can be used with
authenticated encryption ciphers, it is recommended to use the following
functions which are solely for AEAD ciphers.  The latter API is designed
to be simple to use and also hard to misuse, by handling the tag
verification and addition in transparent way.

   ---------- Footnotes ----------

   (1) See the nettle manual
<https://www.lysator.liu.se/~nisse/nettle/nettle.html>

8.2 Public key algorithms
=========================

Public key cryptography algorithms such as RSA, DSA and ECDSA, are
accessed using the abstract key API in Abstract key types.  This
is a high level API with the advantage of transparently handling keys
stored in memory and keys present in smart cards.

'INT gnutls_privkey_init (gnutls_privkey_t * KEY)'
'INT gnutls_privkey_import_url (gnutls_privkey_t KEY, const char * URL, unsigned int FLAGS)'
'INT gnutls_privkey_import_x509_raw (gnutls_privkey_t PKEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS)'
'INT gnutls_privkey_sign_data (gnutls_privkey_t SIGNER, gnutls_digest_algorithm_t HASH, unsigned int FLAGS, const gnutls_datum_t * DATA, gnutls_datum_t * SIGNATURE)'
'INT gnutls_privkey_sign_hash (gnutls_privkey_t SIGNER, gnutls_digest_algorithm_t HASH_ALGO, unsigned int FLAGS, const gnutls_datum_t * HASH_DATA, gnutls_datum_t * SIGNATURE)'
'VOID gnutls_privkey_deinit (gnutls_privkey_t KEY)'

'INT gnutls_pubkey_init (gnutls_pubkey_t * KEY)'
'INT gnutls_pubkey_import_url (gnutls_pubkey_t KEY, const char * URL, unsigned int FLAGS)'
'INT gnutls_pubkey_import_x509 (gnutls_pubkey_t KEY, gnutls_x509_crt_t CRT, unsigned int FLAGS)'
'INT gnutls_pubkey_verify_data2 (gnutls_pubkey_t PUBKEY, gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const gnutls_datum_t * DATA, const gnutls_datum_t * SIGNATURE)'
'INT gnutls_pubkey_verify_hash2 (gnutls_pubkey_t KEY, gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const gnutls_datum_t * HASH, const gnutls_datum_t * SIGNATURE)'
'VOID gnutls_pubkey_deinit (gnutls_pubkey_t KEY)'

Keys stored in memory can be imported using functions like
gnutls_privkey_import_x509_raw, while keys on smart cards or HSMs
should be imported using their PKCS#11 URL with
gnutls_privkey_import_url.

If any of the smart card operations require PIN, that should be provided
either by setting the global PIN function (see
gnutls_pkcs11_set_pin_function), or better with the targeted to
structures functions such as gnutls_privkey_set_pin_function.

8.2.1 Key generation
--------------------

All supported key types (including RSA, DSA, ECDSA, Ed25519) can be
generated with GnuTLS. They can be generated with the simpler
gnutls_privkey_generate or with the more advanced
gnutls_privkey_generate2.

 -- Function: int gnutls_privkey_generate2 (gnutls_privkey_t PKEY,
          gnutls_pk_algorithm_t ALGO, unsigned int BITS, unsigned int
          FLAGS, const gnutls_keygen_data_st * DATA, unsigned DATA_SIZE)
     PKEY: The private key

     ALGO: is one of the algorithms in 'gnutls_pk_algorithm_t' .

     BITS: the size of the modulus

     FLAGS: Must be zero or flags from 'gnutls_privkey_flags_t' .

     DATA: Allow specifying 'gnutls_keygen_data_st' types such as the
     seed to be used.

     DATA_SIZE: The number of 'data' available.

     This function will generate a random private key.  Note that this
     function must be called on an initialized private key.

     The flag 'GNUTLS_PRIVKEY_FLAG_PROVABLE' instructs the key
     generation process to use algorithms like Shawe-Taylor (from FIPS
     PUB186-4) which generate provable parameters out of a seed for RSA
     and DSA keys.  On DSA keys the PQG parameters are generated using
     the seed, while on RSA the two primes.  To specify an explicit seed
     (by default a random seed is used), use the 'data' with a
     'GNUTLS_KEYGEN_SEED' type.

     Note that when generating an elliptic curve key, the curve can be
     substituted in the place of the bits parameter using the
     'GNUTLS_CURVE_TO_BITS()' macro.

     To export the generated keys in memory or in files it is
     recommended to use the PKCS'8' form as it can handle all key types,
     and can store additional parameters such as the seed, in case of
     provable RSA or DSA keys.  Generated keys can be exported in memory
     using 'gnutls_privkey_export_x509()' , and then with
     'gnutls_x509_privkey_export2_pkcs8()' .

     If key generation is part of your application, avoid setting the
     number of bits directly, and instead use
     'gnutls_sec_param_to_pk_bits()' .  That way the generated keys will
     adapt to the security levels of the underlying GnuTLS library.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

     *Since:* 3.5.0

8.3 Cryptographic Message Syntax / PKCS#7
=========================================

The CMS or PKCS #7 format is a commonly used format for digital
signatures.  PKCS #7 is the name of the original standard when published
by RSA, though today the standard is adopted by IETF under the name CMS.

The standards include multiple ways of signing a digital document, e.g.,
by embedding the data into the signature, or creating detached
signatures of the data, including a timestamp, additional certificates
etc.  In certain cases the same format is also used to transport lists
of certificates and CRLs.

It is a relatively popular standard to sign structures, and is being
used to sign in PDF files, as well as for signing kernel modules and
other structures.

In GnuTLS, the basic functions to initialize, deinitialize, import,
export or print information about a PKCS #7 structure are listed below.
'INT gnutls_pkcs7_init (gnutls_pkcs7_t * PKCS7)'
'VOID gnutls_pkcs7_deinit (gnutls_pkcs7_t PKCS7)'
'INT gnutls_pkcs7_export2 (gnutls_pkcs7_t PKCS7, gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)'
'INT gnutls_pkcs7_import (gnutls_pkcs7_t PKCS7, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)'
'INT gnutls_pkcs7_print (gnutls_pkcs7_t PKCS7, gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t * OUT)'

The following functions allow the verification of a structure using
either a trust list, or individual certificates.  The
gnutls_pkcs7_sign function is the data signing function.

'INT gnutls_pkcs7_verify_direct (gnutls_pkcs7_t PKCS7, gnutls_x509_crt_t SIGNER, unsigned IDX, const gnutls_datum_t * DATA, unsigned FLAGS)'
'INT gnutls_pkcs7_verify (gnutls_pkcs7_t PKCS7, gnutls_x509_trust_list_t TL, gnutls_typed_vdata_st * VDATA, unsigned int VDATA_SIZE, unsigned IDX, const gnutls_datum_t * DATA, unsigned FLAGS)'

 -- Function: int gnutls_pkcs7_sign (gnutls_pkcs7_t PKCS7,
          gnutls_x509_crt_t SIGNER, gnutls_privkey_t SIGNER_KEY, const
          gnutls_datum_t * DATA, gnutls_pkcs7_attrs_t SIGNED_ATTRS,
          gnutls_pkcs7_attrs_t UNSIGNED_ATTRS, gnutls_digest_algorithm_t
          DIG, unsigned FLAGS)
     PKCS7: should contain a 'gnutls_pkcs7_t' type

     SIGNER: the certificate to sign the structure

     SIGNER_KEY: the key to sign the structure

     DATA: The data to be signed or 'NULL' if the data are already
     embedded

     SIGNED_ATTRS: Any additional attributes to be included in the
     signed ones (or 'NULL' )

     UNSIGNED_ATTRS: Any additional attributes to be included in the
     unsigned ones (or 'NULL' )

     DIG: The digest algorithm to use for signing

     FLAGS: Should be zero or one of 'GNUTLS_PKCS7' flags

     This function will add a signature in the provided PKCS '7'
     structure for the provided data.  Multiple signatures can be made
     with different signers.

     The available flags are: 'GNUTLS_PKCS7_EMBED_DATA' ,
     'GNUTLS_PKCS7_INCLUDE_TIME' , 'GNUTLS_PKCS7_INCLUDE_CERT' , and
     'GNUTLS_PKCS7_WRITE_SPKI' .  They are explained in the
     'gnutls_pkcs7_sign_flags' definition.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

     *Since:* 3.4.2

'GNUTLS_PKCS7_EMBED_DATA'
     The signed data will be embedded in the structure.
'GNUTLS_PKCS7_INCLUDE_TIME'
     The signing time will be included in the structure.
'GNUTLS_PKCS7_INCLUDE_CERT'
     The signer's certificate will be included in the cert list.
'GNUTLS_PKCS7_WRITE_SPKI'
     Use the signer's key identifier instead of name.

Figure 8.2: Flags applicable to gnutls_pkcs7_sign()

Other helper functions which allow to access the signatures, or
certificates attached in the structure are listed below.

'INT gnutls_pkcs7_get_signature_count (gnutls_pkcs7_t PKCS7)'
'INT gnutls_pkcs7_get_signature_info (gnutls_pkcs7_t PKCS7, unsigned IDX, gnutls_pkcs7_signature_info_st * INFO)'
'INT gnutls_pkcs7_get_crt_count (gnutls_pkcs7_t PKCS7)'
'INT gnutls_pkcs7_get_crt_raw2 (gnutls_pkcs7_t PKCS7, unsigned INDX, gnutls_datum_t * CERT)'
'INT gnutls_pkcs7_get_crl_count (gnutls_pkcs7_t PKCS7)'
'INT gnutls_pkcs7_get_crl_raw2 (gnutls_pkcs7_t PKCS7, unsigned INDX, gnutls_datum_t * CRL)'

To append certificates, or CRLs in the structure the following functions
are provided.
'INT gnutls_pkcs7_set_crt_raw (gnutls_pkcs7_t PKCS7, const gnutls_datum_t * CRT)'
'INT gnutls_pkcs7_set_crt (gnutls_pkcs7_t PKCS7, gnutls_x509_crt_t CRT)'
'INT gnutls_pkcs7_set_crl_raw (gnutls_pkcs7_t PKCS7, const gnutls_datum_t * CRL)'
'INT gnutls_pkcs7_set_crl (gnutls_pkcs7_t PKCS7, gnutls_x509_crl_t CRL)'

8.4 Hash and MAC functions
==========================

The available operations to access hash functions and hash-MAC (HMAC)
algorithms are shown below.  HMAC algorithms provided keyed hash
functionality.  The supported MAC and HMAC algorithms are listed in
Figure 8.3.  Note that, despite the 'hmac'
part in the name of the MAC functions listed below, they can be used
either for HMAC or MAC operations.

'GNUTLS_MAC_UNKNOWN'
     Unknown MAC algorithm.
'GNUTLS_MAC_NULL'
     NULL MAC algorithm (empty output).
'GNUTLS_MAC_MD5'
     HMAC-MD5 algorithm.
'GNUTLS_MAC_SHA1'
     HMAC-SHA-1 algorithm.
'GNUTLS_MAC_RMD160'
     HMAC-RMD160 algorithm.
'GNUTLS_MAC_MD2'
     HMAC-MD2 algorithm.
'GNUTLS_MAC_SHA256'
     HMAC-SHA-256 algorithm.
'GNUTLS_MAC_SHA384'
     HMAC-SHA-384 algorithm.
'GNUTLS_MAC_SHA512'
     HMAC-SHA-512 algorithm.
'GNUTLS_MAC_SHA224'
     HMAC-SHA-224 algorithm.
'GNUTLS_MAC_SHA3_224'
     Reserved; unimplemented.
'GNUTLS_MAC_SHA3_256'
     Reserved; unimplemented.
'GNUTLS_MAC_SHA3_384'
     Reserved; unimplemented.
'GNUTLS_MAC_SHA3_512'
     Reserved; unimplemented.
'GNUTLS_MAC_MD5_SHA1'
     Combined MD5+SHA1 MAC placeholder.
'GNUTLS_MAC_GOSTR_94'
     HMAC GOST R 34.11-94 algorithm.
'GNUTLS_MAC_STREEBOG_256'
     HMAC GOST R 34.11-2001 (Streebog) algorithm, 256 bit.
'GNUTLS_MAC_STREEBOG_512'
     HMAC GOST R 34.11-2001 (Streebog) algorithm, 512 bit.
'GNUTLS_MAC_AEAD'
     MAC implicit through AEAD cipher.
'GNUTLS_MAC_UMAC_96'
     The UMAC-96 MAC algorithm.
'GNUTLS_MAC_UMAC_128'
     The UMAC-128 MAC algorithm.
'GNUTLS_MAC_AES_CMAC_128'
     The AES-CMAC-128 MAC algorithm.
'GNUTLS_MAC_AES_CMAC_256'
     The AES-CMAC-256 MAC algorithm.

Figure 8.3: The supported MAC and HMAC algorithms.

'INT gnutls_hmac_init (gnutls_hmac_hd_t * DIG, gnutls_mac_algorithm_t ALGORITHM, const void * KEY, size_t KEYLEN)'
'INT gnutls_hmac (gnutls_hmac_hd_t HANDLE, const void * PTEXT, size_t PTEXT_LEN)'
'VOID gnutls_hmac_output (gnutls_hmac_hd_t HANDLE, void * DIGEST)'
'VOID gnutls_hmac_deinit (gnutls_hmac_hd_t HANDLE, void * DIGEST)'
'UNSIGNED gnutls_hmac_get_len (gnutls_mac_algorithm_t ALGORITHM)'
'INT gnutls_hmac_fast (gnutls_mac_algorithm_t ALGORITHM, const void * KEY, size_t KEYLEN, const void * PTEXT, size_t PTEXT_LEN, void * DIGEST)'

The available functions to access hash functions are shown below.  The
supported hash functions are shown in Figure 8.4.

'INT gnutls_hash_init (gnutls_hash_hd_t * DIG, gnutls_digest_algorithm_t ALGORITHM)'
'INT gnutls_hash (gnutls_hash_hd_t HANDLE, const void * PTEXT, size_t PTEXT_LEN)'
'VOID gnutls_hash_output (gnutls_hash_hd_t HANDLE, void * DIGEST)'
'VOID gnutls_hash_deinit (gnutls_hash_hd_t HANDLE, void * DIGEST)'
'UNSIGNED gnutls_hash_get_len (gnutls_digest_algorithm_t ALGORITHM)'
'INT gnutls_hash_fast (gnutls_digest_algorithm_t ALGORITHM, const void * PTEXT, size_t PTEXT_LEN, void * DIGEST)'
'INT gnutls_fingerprint (gnutls_digest_algorithm_t ALGO, const gnutls_datum_t * DATA, void * RESULT, size_t * RESULT_SIZE)'

'GNUTLS_DIG_UNKNOWN'
     Unknown hash algorithm.
'GNUTLS_DIG_NULL'
     NULL hash algorithm (empty output).
'GNUTLS_DIG_MD5'
     MD5 algorithm.
'GNUTLS_DIG_SHA1'
     SHA-1 algorithm.
'GNUTLS_DIG_RMD160'
     RMD160 algorithm.
'GNUTLS_DIG_MD2'
     MD2 algorithm.
'GNUTLS_DIG_SHA256'
     SHA-256 algorithm.
'GNUTLS_DIG_SHA384'
     SHA-384 algorithm.
'GNUTLS_DIG_SHA512'
     SHA-512 algorithm.
'GNUTLS_DIG_SHA224'
     SHA-224 algorithm.
'GNUTLS_DIG_SHA3_224'
     SHA3-224 algorithm.
'GNUTLS_DIG_SHA3_256'
     SHA3-256 algorithm.
'GNUTLS_DIG_SHA3_384'
     SHA3-384 algorithm.
'GNUTLS_DIG_SHA3_512'
     SHA3-512 algorithm.
'GNUTLS_DIG_MD5_SHA1'
     Combined MD5+SHA1 algorithm.
'GNUTLS_DIG_GOSTR_94'
     GOST R 34.11-94 algorithm.
'GNUTLS_DIG_STREEBOG_256'
     GOST R 34.11-2001 (Streebog) algorithm, 256 bit.
'GNUTLS_DIG_STREEBOG_512'
     GOST R 34.11-2001 (Streebog) algorithm, 512 bit.

Figure 8.4: The supported hash algorithms.

8.5 Random number generation
============================

Access to the random number generator is provided using the
gnutls_rnd function.  It allows obtaining random data of various
levels.

'GNUTLS_RND_NONCE'
     Non-predictable random number.  Fatal in parts of session if
     broken, i.e., vulnerable to statistical analysis.
'GNUTLS_RND_RANDOM'
     Pseudo-random cryptographic random number.  Fatal in session if
     broken.  Example use: temporal keys.
'GNUTLS_RND_KEY'
     Fatal in many sessions if broken.  Example use: Long-term keys.

Figure 8.5: The random number levels.

 -- Function: int gnutls_rnd (gnutls_rnd_level_t LEVEL, void * DATA,
          size_t LEN)
     LEVEL: a security level

     DATA: place to store random bytes

     LEN: The requested size

     This function will generate random data and store it to output
     buffer.  The value of 'level' should be one of 'GNUTLS_RND_NONCE' ,
     'GNUTLS_RND_RANDOM' and 'GNUTLS_RND_KEY' .  See the manual and
     'gnutls_rnd_level_t' for detailed information.

     This function is thread-safe and also fork-safe.

     *Returns:* Zero on success, or a negative error code on error.

     *Since:* 2.12.0

See Random Number Generators-internals for more information on
the random number generator operation.

8.6 Overriding algorithms
=========================

In systems which provide a hardware accelerated cipher implementation
that is not directly supported by GnuTLS, it is possible to utilize it.
There are functions which allow overriding the default cipher, digest
and MAC implementations.  Those are described below.

To override public key operations see Abstract private keys.

 -- Function: int gnutls_crypto_register_cipher
          (gnutls_cipher_algorithm_t ALGORITHM, int PRIORITY,
          gnutls_cipher_init_func INIT, gnutls_cipher_setkey_func
          SETKEY, gnutls_cipher_setiv_func SETIV,
          gnutls_cipher_encrypt_func ENCRYPT, gnutls_cipher_decrypt_func
          DECRYPT, gnutls_cipher_deinit_func DEINIT)
     ALGORITHM: is the gnutls algorithm identifier

     PRIORITY: is the priority of the algorithm

     INIT: A function which initializes the cipher

     SETKEY: A function which sets the key of the cipher

     SETIV: A function which sets the nonce/IV of the cipher (non-AEAD)

     ENCRYPT: A function which performs encryption (non-AEAD)

     DECRYPT: A function which performs decryption (non-AEAD)

     DEINIT: A function which deinitializes the cipher

     This function will register a cipher algorithm to be used by
     gnutls.  Any algorithm registered will override the included
     algorithms and by convention kernel implemented algorithms have
     priority of 90 and CPU-assisted of 80.  The algorithm with the
     lowest priority will be used by gnutls.

     In the case the registered init or setkey functions return
     'GNUTLS_E_NEED_FALLBACK' , GnuTLS will attempt to use the next in
     priority registered cipher.

     The functions which are marked as non-AEAD they are not required
     when registering a cipher to be used with the new AEAD API
     introduced in GnuTLS 3.4.0.  Internally GnuTLS uses the new AEAD
     API.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.4.0

 -- Function: int gnutls_crypto_register_aead_cipher
          (gnutls_cipher_algorithm_t ALGORITHM, int PRIORITY,
          gnutls_cipher_init_func INIT, gnutls_cipher_setkey_func
          SETKEY, gnutls_cipher_aead_encrypt_func AEAD_ENCRYPT,
          gnutls_cipher_aead_decrypt_func AEAD_DECRYPT,
          gnutls_cipher_deinit_func DEINIT)
     ALGORITHM: is the gnutls AEAD cipher identifier

     PRIORITY: is the priority of the algorithm

     INIT: A function which initializes the cipher

     SETKEY: A function which sets the key of the cipher

     AEAD_ENCRYPT: Perform the AEAD encryption

     AEAD_DECRYPT: Perform the AEAD decryption

     DEINIT: A function which deinitializes the cipher

     This function will register a cipher algorithm to be used by
     gnutls.  Any algorithm registered will override the included
     algorithms and by convention kernel implemented algorithms have
     priority of 90 and CPU-assisted of 80.  The algorithm with the
     lowest priority will be used by gnutls.

     In the case the registered init or setkey functions return
     'GNUTLS_E_NEED_FALLBACK' , GnuTLS will attempt to use the next in
     priority registered cipher.

     The functions registered will be used with the new AEAD API
     introduced in GnuTLS 3.4.0.  Internally GnuTLS uses the new AEAD
     API.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.4.0

 -- Function: int gnutls_crypto_register_mac (gnutls_mac_algorithm_t
          ALGORITHM, int PRIORITY, gnutls_mac_init_func INIT,
          gnutls_mac_setkey_func SETKEY, gnutls_mac_setnonce_func
          SETNONCE, gnutls_mac_hash_func HASH, gnutls_mac_output_func
          OUTPUT, gnutls_mac_deinit_func DEINIT, gnutls_mac_fast_func
          HASH_FAST)
     ALGORITHM: is the gnutls MAC identifier

     PRIORITY: is the priority of the algorithm

     INIT: A function which initializes the MAC

     SETKEY: A function which sets the key of the MAC

     SETNONCE: A function which sets the nonce for the mac (may be
     'NULL' for common MAC algorithms)

     HASH: Perform the hash operation

     OUTPUT: Provide the output of the MAC

     DEINIT: A function which deinitializes the MAC

     HASH_FAST: Perform the MAC operation in one go

     This function will register a MAC algorithm to be used by gnutls.
     Any algorithm registered will override the included algorithms and
     by convention kernel implemented algorithms have priority of 90 and
     CPU-assisted of 80.  The algorithm with the lowest priority will be
     used by gnutls.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.4.0

 -- Function: int gnutls_crypto_register_digest
          (gnutls_digest_algorithm_t ALGORITHM, int PRIORITY,
          gnutls_digest_init_func INIT, gnutls_digest_hash_func HASH,
          gnutls_digest_output_func OUTPUT, gnutls_digest_deinit_func
          DEINIT, gnutls_digest_fast_func HASH_FAST)
     ALGORITHM: is the gnutls digest identifier

     PRIORITY: is the priority of the algorithm

     INIT: A function which initializes the digest

     HASH: Perform the hash operation

     OUTPUT: Provide the output of the digest

     DEINIT: A function which deinitializes the digest

     HASH_FAST: Perform the digest operation in one go

     This function will register a digest algorithm to be used by
     gnutls.  Any algorithm registered will override the included
     algorithms and by convention kernel implemented algorithms have
     priority of 90 and CPU-assisted of 80.  The algorithm with the
     lowest priority will be used by gnutls.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.4.0

9 Other included programs
*************************

Included with GnuTLS are also a few command line tools that let you use
the library for common tasks without writing an application.  The
applications are discussed in this chapter.

9.1 Invoking gnutls-cli
=======================

Simple client program to set up a TLS connection to some other computer.
It sets up a TLS connection and forwards data from the standard input to
the secured socket and vice versa.

This section was generated by *AutoGen*, using the 'agtexi-cmd' template
and the option descriptions for the 'gnutls-cli' program.  This software
is released under the GNU General Public License, version 3 or later.

gnutls-cli help/usage ('--help')
--------------------------------

This is the automatically generated usage text for gnutls-cli.

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.

     gnutls-cli - GnuTLS client
     Usage:  gnutls-cli [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [hostname]

        -d, --debug=num            Enable debugging
                                     - it must be in the range:
                                       0 to 9999
        -V, --verbose              More verbose output
                                     - may appear multiple times
            --tofu                 Enable trust on first use authentication
                                     - disabled as '--no-tofu'
            --strict-tofu          Fail to connect if a certificate is unknown or a known certificate has
     changed
                                     - disabled as '--no-strict-tofu'
            --dane                 Enable DANE certificate verification (DNSSEC)
                                     - disabled as '--no-dane'
            --local-dns            Use the local DNS server for DNSSEC resolving
                                     - disabled as '--no-local-dns'
            --ca-verification      Enable CA certificate verification
                                     - disabled as '--no-ca-verification'
                                     - enabled by default
            --ocsp                 Enable OCSP certificate verification
                                     - disabled as '--no-ocsp'
        -r, --resume               Establish a session and resume
            --earlydata=str        Send early data on resumption from the specified file
        -e, --rehandshake          Establish a session and rehandshake
            --sni-hostname=str     Server's hostname for server name indication extension
            --verify-hostname=str  Server's hostname to use for validation
        -s, --starttls             Connect, establish a plain session and start TLS
            --app-proto=str        an alias for the 'starttls-proto' option
            --starttls-proto=str   The application protocol to be used to obtain the server's certificate
     (https, ftp, smtp, imap, ldap, xmpp, lmtp, pop3, nntp, sieve, postgres)
                                     - prohibits the option 'starttls'
        -u, --udp                  Use DTLS (datagram TLS) over UDP
            --mtu=num              Set MTU for datagram TLS
                                     - it must be in the range:
                                       0 to 17000
            --crlf                 Send CR LF instead of LF
            --fastopen             Enable TCP Fast Open
            --x509fmtder           Use DER format for certificates to read from
            --print-cert           Print peer's certificate in PEM format
            --save-cert=str        Save the peer's certificate chain in the specified file in PEM format
            --save-ocsp=str        Save the peer's OCSP status response in the provided file
            --save-server-trace=str Save the server-side TLS message trace in the provided file
            --save-client-trace=str Save the client-side TLS message trace in the provided file
            --dh-bits=num          The minimum number of bits allowed for DH
            --priority=str         Priorities string
            --x509cafile=str       Certificate file or PKCS #11 URL to use
            --x509crlfile=file     CRL file to use
                                     - file must pre-exist
            --x509keyfile=str      X.509 key file or PKCS #11 URL to use
            --x509certfile=str     X.509 Certificate file or PKCS #11 URL to use
                                     - requires the option 'x509keyfile'
            --srpusername=str      SRP username to use
            --srppasswd=str        SRP password to use
            --pskusername=str      PSK username to use
            --pskkey=str           PSK key (in hex) to use
        -p, --port=str             The port or service to connect to
            --insecure             Don't abort program if server certificate can't be validated
            --verify-allow-broken  Allow broken algorithms, such as MD5 for certificate verification
            --benchmark-ciphers    Benchmark individual ciphers
            --benchmark-tls-kx     Benchmark TLS key exchange methods
            --benchmark-tls-ciphers  Benchmark TLS ciphers
        -l, --list                 Print a list of the supported algorithms and modes
                                     - prohibits the option 'port'
            --priority-list        Print a list of the supported priority strings
            --noticket             Don't allow session tickets
            --srtp-profiles=str    Offer SRTP profiles
            --alpn=str             Application layer protocol
                                     - may appear multiple times
        -b, --heartbeat            Activate heartbeat support
            --recordsize=num       The maximum record size to advertize
                                     - it must be in the range:
                                       0 to 4096
            --disable-sni          Do not send a Server Name Indication (SNI)
            --single-key-share     Send a single key share under TLS1.3
            --post-handshake-auth  Enable post-handshake authentication under TLS1.3
            --inline-commands      Inline commands of the form ^<cmd>^
            --inline-commands-prefix=str Change the default delimiter for inline commands.
            --provider=file        Specify the PKCS #11 provider library
                                     - file must pre-exist
            --fips140-mode         Reports the status of the FIPS140-2 mode in gnutls library
            --logfile=str          Redirect informational messages to a specific file.
        -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.
     Operands and options may be intermixed.  They will be reordered.

     Simple client program to set up a TLS connection to some other computer.  It
     sets up a TLS connection and forwards data from the standard input to the
     secured socket and vice versa.

debug option (-d)
-----------------

This is the "enable debugging" option.  This option takes a number
argument.  Specifies the debug level.

tofu option
-----------

This is the "enable trust on first use authentication" option.

This option has some usage constraints.  It:
   * can be disabled with -no-tofu.

This option will, in addition to certificate authentication, perform
authentication based on previously seen public keys, a model similar to
SSH authentication.  Note that when tofu is specified (PKI) and DANE
authentication will become advisory to assist the public key acceptance
process.

strict-tofu option
------------------

This is the "fail to connect if a certificate is unknown or a known
certificate has changed" option.

This option has some usage constraints.  It:
   * can be disabled with -no-strict-tofu.

This option will perform authentication as with option -tofu; however,
no questions shall be asked whatsoever, neither to accept an unknown
certificate nor a changed one.

dane option
-----------

This is the "enable dane certificate verification (dnssec)" option.

This option has some usage constraints.  It:
   * can be disabled with -no-dane.

This option will, in addition to certificate authentication using the
trusted CAs, verify the server certificates using on the DANE
information available via DNSSEC.

local-dns option
----------------

This is the "use the local dns server for dnssec resolving" option.

This option has some usage constraints.  It:
   * can be disabled with -no-local-dns.

This option will use the local DNS server for DNSSEC. This is disabled
by default due to many servers not allowing DNSSEC.

ca-verification option
----------------------

This is the "enable ca certificate verification" option.

This option has some usage constraints.  It:
   * can be disabled with -no-ca-verification.
   * It is enabled by default.

This option can be used to enable or disable CA certificate
verification.  It is to be used with the -dane or -tofu options.

ocsp option
-----------

This is the "enable ocsp certificate verification" option.

This option has some usage constraints.  It:
   * can be disabled with -no-ocsp.

This option will enable verification of the peer's certificate using
ocsp

resume option (-r)
------------------

This is the "establish a session and resume" option.  Connect, establish
a session, reconnect and resume.

rehandshake option (-e)
-----------------------

This is the "establish a session and rehandshake" option.  Connect,
establish a session and rehandshake immediately.

sni-hostname option
-------------------

This is the "server's hostname for server name indication extension"
option.  This option takes a string argument.  Set explicitly the server
name used in the TLS server name indication extension.  That is useful
when testing with servers setup on different DNS name than the intended.
If not specified, the provided hostname is used.  Even with this option
server certificate verification still uses the hostname passed on the
main commandline.  Use -verify-hostname to change this.

verify-hostname option
----------------------

This is the "server's hostname to use for validation" option.  This
option takes a string argument.  Set explicitly the server name to be
used when validating the server's certificate.

starttls option (-s)
--------------------

This is the "connect, establish a plain session and start tls" option.
The TLS session will be initiated when EOF or a SIGALRM is received.

app-proto option
----------------

This is an alias for the 'starttls-proto' option, see the starttls-proto option documentation.

starttls-proto option
---------------------

This is the "the application protocol to be used to obtain the server's
certificate (https, ftp, smtp, imap, ldap, xmpp, lmtp, pop3, nntp,
sieve, postgres)" option.  This option takes a string argument.

This option has some usage constraints.  It:
   * must not appear in combination with any of the following options:
     starttls.

Specify the application layer protocol for STARTTLS. If the protocol is
supported, gnutls-cli will proceed to the TLS negotiation.

dh-bits option
--------------

This is the "the minimum number of bits allowed for dh" option.  This
option takes a number argument.  This option sets the minimum number of
bits allowed for a Diffie-Hellman key exchange.  You may want to lower
the default value if the peer sends a weak prime and you get an
connection error with unacceptable prime.

priority option
---------------

This is the "priorities string" option.  This option takes a string
argument.  TLS algorithms and protocols to enable.  You can use
predefined sets of ciphersuites such as PERFORMANCE, NORMAL, PFS,
SECURE128, SECURE256.  The default is NORMAL.

Check the GnuTLS manual on section "Priority strings" for more
information on the allowed keywords

ranges option
-------------

This is the "use length-hiding padding to prevent traffic analysis"
option.  When possible (e.g., when using CBC ciphersuites), use
length-hiding padding to prevent traffic analysis.

*NOTE**: THIS OPTION IS DEPRECATED*

benchmark-ciphers option
------------------------

This is the "benchmark individual ciphers" option.  By default the
benchmarked ciphers will utilize any capabilities of the local CPU to
improve performance.  To test against the raw software implementation
set the environment variable GNUTLS_CPUID_OVERRIDE to 0x1.

benchmark-tls-ciphers option
----------------------------

This is the "benchmark tls ciphers" option.  By default the benchmarked
ciphers will utilize any capabilities of the local CPU to improve
performance.  To test against the raw software implementation set the
environment variable GNUTLS_CPUID_OVERRIDE to 0x1.

list option (-l)
----------------

This is the "print a list of the supported algorithms and modes" option.

This option has some usage constraints.  It:
   * must not appear in combination with any of the following options:
     port.

Print a list of the supported algorithms and modes.  If a priority
string is given then only the enabled ciphersuites are shown.

priority-list option
--------------------

This is the "print a list of the supported priority strings" option.
Print a list of the supported priority strings.  The ciphersuites
corresponding to each priority string can be examined using -l -p.

noticket option
---------------

This is the "don't allow session tickets" option.  Disable the request
of receiving of session tickets under TLS1.2 or earlier

alpn option
-----------

This is the "application layer protocol" option.  This option takes a
string argument.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

This option will set and enable the Application Layer Protocol
Negotiation (ALPN) in the TLS protocol.

disable-extensions option
-------------------------

This is the "disable all the tls extensions" option.  This option
disables all TLS extensions.  Deprecated option.  Use the priority
string.

*NOTE**: THIS OPTION IS DEPRECATED*

single-key-share option
-----------------------

This is the "send a single key share under tls1.3" option.  This option
switches the default mode of sending multiple key shares, to send a
single one (the top one).

post-handshake-auth option
--------------------------

This is the "enable post-handshake authentication under tls1.3" option.
This option enables post-handshake authentication when under TLS1.3.

inline-commands option
----------------------

This is the "inline commands of the form ^<cmd>^" option.  Enable inline
commands of the form ^<cmd>^.  The inline commands are expected to be in
a line by themselves.  The available commands are: resume, rekey1 (local
rekey), rekey (rekey on both peers) and renegotiate.

inline-commands-prefix option
-----------------------------

This is the "change the default delimiter for inline commands."  option.
This option takes a string argument.  Change the default delimiter (^)
used for inline commands.  The delimiter is expected to be a single
US-ASCII character (octets 0 - 127).  This option is only relevant if
inline commands are enabled via the inline-commands option

provider option
---------------

This is the "specify the pkcs #11 provider library" option.  This option
takes a file argument.  This will override the default options in
/etc/gnutls/pkcs11.conf

gnutls-cli 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.

gnutls-cli See Also
-------------------

gnutls-cli-debug(1), gnutls-serv(1)

gnutls-cli Examples
-------------------

Connecting using PSK authentication
-----------------------------------

To connect to a server using PSK authentication, you need to enable the
choice of PSK by using a cipher priority parameter such as in the
example below.
     $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
         --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
         --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
     Resolving 'localhost'...
     Connecting to '127.0.0.1:5556'...
     - PSK authentication.
     - Version: TLS1.1
     - Key Exchange: PSK
     - Cipher: AES-128-CBC
     - MAC: SHA1
     - Compression: NULL
     - Handshake was completed

     - Simple Client Mode:
By keeping the -pskusername parameter and removing the -pskkey
parameter, it will query only for the password during the handshake.

Connecting to STARTTLS services
-------------------------------

You could also use the client to connect to services with starttls
capability.
     $ gnutls-cli --starttls-proto smtp --port 25 localhost

Listing ciphersuites in a priority string
-----------------------------------------

To list the ciphersuites in a priority string:
     $ ./gnutls-cli --priority SECURE192 -l
     Cipher suites for SECURE192
     TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24	TLS1.2
     TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e	TLS1.2
     TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30	TLS1.2
     TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b	TLS1.2
     TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a	TLS1.2
     TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d	TLS1.2

     Certificate types: CTYPE-X.509
     Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
     Compression: COMP-NULL
     Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
     PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512

Connecting using a PKCS #11 token
---------------------------------

To connect to a server using a certificate and a private key present in
a PKCS #11 token you need to substitute the PKCS 11 URLs in the
x509certfile and x509keyfile parameters.

Those can be found using "p11tool -list-tokens" and then listing all the
objects in the needed token, and using the appropriate.
     $ p11tool --list-tokens

     Token 0:
     URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
     Label: Test
     Manufacturer: EnterSafe
     Model: PKCS15
     Serial: 1234

     $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"

     Object 0:
     URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
     Type: X.509 Certificate
     Label: client
     ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a

     $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
     $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
     $ export MYCERT MYKEY

     $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
Notice that the private key only differs from the certificate in the
type.

9.2 Invoking gnutls-serv
========================

Server program that listens to incoming TLS connections.

This section was generated by *AutoGen*, using the 'agtexi-cmd' template
and the option descriptions for the 'gnutls-serv' program.  This
software is released under the GNU General Public License, version 3 or
later.

gnutls-serv help/usage ('--help')
---------------------------------

This is the automatically generated usage text for gnutls-serv.

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.

     gnutls-serv - GnuTLS server
     Usage:  gnutls-serv [ -<flag> [<val>] | --<name>[{=| }<val>] ]...

        -d, --debug=num            Enable debugging
                                     - it must be in the range:
                                       0 to 9999
            --sni-hostname=str     Server's hostname for server name extension
            --sni-hostname-fatal   Send fatal alert on sni-hostname mismatch
            --alpn=str             Specify ALPN protocol to be enabled by the server
                                     - may appear multiple times
            --alpn-fatal           Send fatal alert on non-matching ALPN name
            --noticket             Don't accept session tickets
            --earlydata            Accept early data
            --maxearlydata=num     The maximum early data size to accept
                                     - it must be in the range:
                                       1 to 4294967295
            --nocookie             Don't require cookie on DTLS sessions
        -g, --generate             Generate Diffie-Hellman parameters
        -q, --quiet                Suppress some messages
            --nodb                 Do not use a resumption database
            --http                 Act as an HTTP server
            --echo                 Act as an Echo server
        -u, --udp                  Use DTLS (datagram TLS) over UDP
            --mtu=num              Set MTU for datagram TLS
                                     - it must be in the range:
                                       0 to 17000
            --srtp-profiles=str    Offer SRTP profiles
        -a, --disable-client-cert  Do not request a client certificate
                                     - prohibits the option 'require-client-cert'
        -r, --require-client-cert  Require a client certificate
            --verify-client-cert   If a client certificate is sent then verify it.
        -b, --heartbeat            Activate heartbeat support
            --x509fmtder           Use DER format for certificates to read from
            --priority=str         Priorities string
            --dhparams=file        DH params file to use
                                     - file must pre-exist
            --x509cafile=str       Certificate file or PKCS #11 URL to use
            --x509crlfile=file     CRL file to use
                                     - file must pre-exist
            --x509keyfile=str      X.509 key file or PKCS #11 URL to use
                                     - may appear multiple times
            --x509certfile=str     X.509 Certificate file or PKCS #11 URL to use
                                     - may appear multiple times
            --srppasswd=file       SRP password file to use
                                     - file must pre-exist
            --srppasswdconf=file   SRP password configuration file to use
                                     - file must pre-exist
            --pskpasswd=file       PSK password file to use
                                     - file must pre-exist
            --pskhint=str          PSK identity hint to use
            --ocsp-response=str    The OCSP response to send to client
                                     - may appear multiple times
            --ignore-ocsp-response-errors  Ignore any errors when setting the OCSP response
        -p, --port=num             The port to connect to
        -l, --list                 Print a list of the supported algorithms and modes
            --provider=file        Specify the PKCS #11 provider library
                                     - file must pre-exist
        -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.

     Server program that listens to incoming TLS connections.

debug option (-d)
-----------------

This is the "enable debugging" option.  This option takes a number
argument.  Specifies the debug level.

sni-hostname option
-------------------

This is the "server's hostname for server name extension" option.  This
option takes a string argument.  Server name of type host_name that the
server will recognise as its own.  If the server receives client hello
with different name, it will send a warning-level unrecognized_name
alert.

alpn option
-----------

This is the "specify alpn protocol to be enabled by the server" option.
This option takes a string argument.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

Specify the (textual) ALPN protocol for the server to use.

require-client-cert option (-r)
-------------------------------

This is the "require a client certificate" option.  This option before
3.6.0 used to imply -verify-client-cert.  Since 3.6.0 it will no longer
verify the certificate by default.

verify-client-cert option
-------------------------

This is the "if a client certificate is sent then verify it."  option.
Do not require, but if a client certificate is sent then verify it and
close the connection if invalid.

heartbeat option (-b)
---------------------

This is the "activate heartbeat support" option.  Regularly ping client
via heartbeat extension messages

priority option
---------------

This is the "priorities string" option.  This option takes a string
argument.  TLS algorithms and protocols to enable.  You can use
predefined sets of ciphersuites such as PERFORMANCE, NORMAL, SECURE128,
SECURE256.  The default is NORMAL.

Check the GnuTLS manual on section "Priority strings" for more
information on allowed keywords

x509keyfile option
------------------

This is the "x.509 key file or pkcs #11 url to use" option.  This option
takes a string argument.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

Specify the private key file or URI to use; it must correspond to the
certificate specified in -x509certfile.  Multiple keys and certificates
can be specified with this option and in that case each occurrence of
keyfile must be followed by the corresponding x509certfile or
vice-versa.

x509certfile option
-------------------

This is the "x.509 certificate file or pkcs #11 url to use" option.
This option takes a string argument.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

Specify the certificate file or URI to use; it must correspond to the
key specified in -x509keyfile.  Multiple keys and certificates can be
specified with this option and in that case each occurrence of keyfile
must be followed by the corresponding x509certfile or vice-versa.

x509dsakeyfile option
---------------------

This is an alias for the 'x509keyfile' option, see the x509keyfile option documentation.

x509dsacertfile option
----------------------

This is an alias for the 'x509certfile' option, see the x509certfile option documentation.

x509ecckeyfile option
---------------------

This is an alias for the 'x509keyfile' option, see the x509keyfile option documentation.

x509ecccertfile option
----------------------

This is an alias for the 'x509certfile' option, see the x509certfile option documentation.

ocsp-response option
--------------------

This is the "the ocsp response to send to client" option.  This option
takes a string argument.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

If the client requested an OCSP response, return data from this file to
the client.

ignore-ocsp-response-errors option
----------------------------------

This is the "ignore any errors when setting the ocsp response" option.
That option instructs gnutls to not attempt to match the provided OCSP
responses with the certificates.

list option (-l)
----------------

This is the "print a list of the supported algorithms and modes" option.
Print a list of the supported algorithms and modes.  If a priority
string is given then only the enabled ciphersuites are shown.

provider option
---------------

This is the "specify the pkcs #11 provider library" option.  This option
takes a file argument.  This will override the default options in
/etc/gnutls/pkcs11.conf

gnutls-serv 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.

gnutls-serv See Also
--------------------

gnutls-cli-debug(1), gnutls-cli(1)

gnutls-serv Examples
--------------------

Running your own TLS server based on GnuTLS can be useful when debugging
clients and/or GnuTLS itself.  This section describes how to use
'gnutls-serv' as a simple HTTPS server.

The most basic server can be started as:

     gnutls-serv --http --priority "NORMAL:+ANON-ECDH:+ANON-DH"

It will only support anonymous ciphersuites, which many TLS clients
refuse to use.

The next step is to add support for X.509.  First we generate a CA:

     $ certtool --generate-privkey > x509-ca-key.pem
     $ echo 'cn = GnuTLS test CA' > ca.tmpl
     $ echo 'ca' >> ca.tmpl
     $ echo 'cert_signing_key' >> ca.tmpl
     $ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
       --template ca.tmpl --outfile x509-ca.pem

Then generate a server certificate.  Remember to change the dns_name
value to the name of your server host, or skip that command to avoid the
field.

     $ certtool --generate-privkey > x509-server-key.pem
     $ echo 'organization = GnuTLS test server' > server.tmpl
     $ echo 'cn = test.gnutls.org' >> server.tmpl
     $ echo 'tls_www_server' >> server.tmpl
     $ echo 'encryption_key' >> server.tmpl
     $ echo 'signing_key' >> server.tmpl
     $ echo 'dns_name = test.gnutls.org' >> server.tmpl
     $ certtool --generate-certificate --load-privkey x509-server-key.pem \
       --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
       --template server.tmpl --outfile x509-server.pem

For use in the client, you may want to generate a client certificate as
well.

     $ certtool --generate-privkey > x509-client-key.pem
     $ echo 'cn = GnuTLS test client' > client.tmpl
     $ echo 'tls_www_client' >> client.tmpl
     $ echo 'encryption_key' >> client.tmpl
     $ echo 'signing_key' >> client.tmpl
     $ certtool --generate-certificate --load-privkey x509-client-key.pem \
       --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
       --template client.tmpl --outfile x509-client.pem

To be able to import the client key/certificate into some applications,
you will need to convert them into a PKCS#12 structure.  This also
encrypts the security sensitive key with a password.

     $ certtool --to-p12 --load-ca-certificate x509-ca.pem \
       --load-privkey x509-client-key.pem --load-certificate x509-client.pem \
       --outder --outfile x509-client.p12

For icing, we'll create a proxy certificate for the client too.

     $ certtool --generate-privkey > x509-proxy-key.pem
     $ echo 'cn = GnuTLS test client proxy' > proxy.tmpl
     $ certtool --generate-proxy --load-privkey x509-proxy-key.pem \
       --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
       --load-certificate x509-client.pem --template proxy.tmpl \
       --outfile x509-proxy.pem

Then start the server again:

     $ gnutls-serv --http \
                 --x509cafile x509-ca.pem \
                 --x509keyfile x509-server-key.pem \
                 --x509certfile x509-server.pem

Try connecting to the server using your web browser.  Note that the
server listens to port 5556 by default.

While you are at it, to allow connections using ECDSA, you can also
create a ECDSA key and certificate for the server.  These credentials
will be used in the final example below.

     $ certtool --generate-privkey --ecdsa > x509-server-key-ecc.pem
     $ certtool --generate-certificate --load-privkey x509-server-key-ecc.pem \
       --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
       --template server.tmpl --outfile x509-server-ecc.pem

The next step is to add support for SRP authentication.  This requires
an SRP password file created with 'srptool'.  To start the server with
SRP support:

     gnutls-serv --http --priority NORMAL:+SRP-RSA:+SRP \
                 --srppasswdconf srp-tpasswd.conf \
                 --srppasswd srp-passwd.txt

Let's also start a server with support for PSK. This would require a
password file created with 'psktool'.

     gnutls-serv --http --priority NORMAL:+ECDHE-PSK:+PSK \
                 --pskpasswd psk-passwd.txt

Finally, we start the server with all the earlier parameters and you get
this command:

     gnutls-serv --http --priority NORMAL:+PSK:+SRP \
                 --x509cafile x509-ca.pem \
                 --x509keyfile x509-server-key.pem \
                 --x509certfile x509-server.pem \
                 --x509keyfile x509-server-key-ecc.pem \
                 --x509certfile x509-server-ecc.pem \
                 --srppasswdconf srp-tpasswd.conf \
                 --srppasswd srp-passwd.txt \
                 --pskpasswd psk-passwd.txt

9.3 Invoking gnutls-cli-debug
=============================

TLS debug client.  It sets up multiple TLS connections to a server and
queries its capabilities.  It was created to assist in debugging GnuTLS,
but it might be useful to extract a TLS server's capabilities.  It
connects to a TLS server, performs tests and print the server's
capabilities.  If called with the '-V' parameter more checks will be
performed.  Can be used to check for servers with special needs or bugs.

This section was generated by *AutoGen*, using the 'agtexi-cmd' template
and the option descriptions for the 'gnutls-cli-debug' program.  This
software is released under the GNU General Public License, version 3 or
later.

gnutls-cli-debug help/usage ('--help')
--------------------------------------

This is the automatically generated usage text for gnutls-cli-debug.

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.

     gnutls-cli-debug - GnuTLS debug client
     Usage:  gnutls-cli-debug [ -<flag> [<val>] | --<name>[{=| }<val>] ]...

        -d, --debug=num            Enable debugging
                                     - it must be in the range:
                                       0 to 9999
        -V, --verbose              More verbose output
                                     - may appear multiple times
        -p, --port=num             The port to connect to
                                     - it must be in the range:
                                       0 to 65536
            --app-proto=str        an alias for the 'starttls-proto' option
            --starttls-proto=str   The application protocol to be used to obtain the server's certificate
     (https, ftp, smtp, imap, ldap, xmpp, lmtp, pop3, nntp, sieve, postgres)
        -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.
     Operands and options may be intermixed.  They will be reordered.

     TLS debug client.  It sets up multiple TLS connections to a server and
     queries its capabilities.  It was created to assist in debugging GnuTLS,
     but it might be useful to extract a TLS server's capabilities.  It connects
     to a TLS server, performs tests and print the server's capabilities.  If
     called with the `-V' parameter more checks will be performed.  Can be used
     to check for servers with special needs or bugs.

debug option (-d)
-----------------

This is the "enable debugging" option.  This option takes a number
argument.  Specifies the debug level.

app-proto option
----------------

This is an alias for the 'starttls-proto' option, see the starttls-proto option documentation.

starttls-proto option
---------------------

This is the "the application protocol to be used to obtain the server's
certificate (https, ftp, smtp, imap, ldap, xmpp, lmtp, pop3, nntp,
sieve, postgres)" option.  This option takes a string argument.  Specify
the application layer protocol for STARTTLS. If the protocol is
supported, gnutls-cli will proceed to the TLS negotiation.

gnutls-cli-debug 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.

gnutls-cli-debug See Also
-------------------------

gnutls-cli(1), gnutls-serv(1)

gnutls-cli-debug Examples
-------------------------

     $ gnutls-cli-debug localhost
     GnuTLS debug client 3.5.0
     Checking localhost:443
                                  for SSL 3.0 (RFC6101) support... yes
                             whether we need to disable TLS 1.2... no
                             whether we need to disable TLS 1.1... no
                             whether we need to disable TLS 1.0... no
                             whether %NO_EXTENSIONS is required... no
                                    whether %COMPAT is required... no
                                  for TLS 1.0 (RFC2246) support... yes
                                  for TLS 1.1 (RFC4346) support... yes
                                  for TLS 1.2 (RFC5246) support... yes
                                       fallback from TLS 1.6 to... TLS1.2
                             for RFC7507 inappropriate fallback... yes
                                          for HTTPS server name... Local
                                    for certificate chain order... sorted
                       for safe renegotiation (RFC5746) support... yes
                          for Safe renegotiation support (SCSV)... no
                         for encrypt-then-MAC (RFC7366) support... no
                        for ext master secret (RFC7627) support... no
                                for heartbeat (RFC6520) support... no
                            for version rollback bug in RSA PMS... dunno
                       for version rollback bug in Client Hello... no
                 whether the server ignores the RSA PMS version... yes
     whether small records (512 bytes) are tolerated on handshake... yes
         whether cipher suites not in SSL 3.0 spec are accepted... yes
     whether a bogus TLS record version in the client hello is accepted... yes
              whether the server understands TLS closure alerts... partially
                 whether the server supports session resumption... yes
                           for anonymous authentication support... no
                           for ephemeral Diffie-Hellman support... no
                        for ephemeral EC Diffie-Hellman support... yes
                         ephemeral EC Diffie-Hellman group info... SECP256R1
                       for AES-128-GCM cipher (RFC5288) support... yes
                       for AES-128-CCM cipher (RFC6655) support... no
                     for AES-128-CCM-8 cipher (RFC6655) support... no
                       for AES-128-CBC cipher (RFC3268) support... yes
                  for CAMELLIA-128-GCM cipher (RFC6367) support... no
                  for CAMELLIA-128-CBC cipher (RFC5932) support... no
                          for 3DES-CBC cipher (RFC2246) support... yes
                       for ARCFOUR 128 cipher (RFC2246) support... yes
                                            for MD5 MAC support... yes
                                           for SHA1 MAC support... yes
                                         for SHA256 MAC support... yes
                                   for ZLIB compression support... no
                          for max record size (RFC6066) support... no
                     for OCSP status response (RFC6066) support... no
                   for OpenPGP authentication (RFC6091) support... no

You could also use the client to debug services with starttls
capability.
     $ gnutls-cli-debug --starttls-proto smtp --port 25 localhost

10 Internal Architecture of GnuTLS
**********************************

This chapter is to give a brief description of the way GnuTLS works.
The focus is to give an idea to potential developers and those who want
to know what happens inside the black box.

10.1 The TLS Protocol
=====================

The main use case for the TLS protocol is shown in Figure 10.1.
A user of a library implementing the protocol
expects no less than this functionality, i.e., to be able to set
parameters such as the accepted security level, perform a negotiation
with the peer and be able to exchange data.

Figure 10.1: TLS protocol use case.

10.2 TLS Handshake Protocol
===========================

The GnuTLS handshake protocol is implemented as a state machine that
waits for input or returns immediately when the non-blocking transport
layer functions are used.  The main idea is shown in Figure 10.2.

Figure 10.2: GnuTLS handshake state machine.

Also the way the input is processed varies per ciphersuite.  Several
implementations of the internal handlers are available and
gnutls_handshake only multiplexes the input to the appropriate
handler.  For example a PSK ciphersuite has a different implementation
of the 'process_client_key_exchange' than a certificate ciphersuite.  We
illustrate the idea in Figure 10.3.

Figure 10.3: GnuTLS handshake process sequence.

10.3 TLS Authentication Methods
===============================

In GnuTLS authentication methods can be implemented quite easily.  Since
the required changes to add a new authentication method affect only the
handshake protocol, a simple interface is used.  An authentication
method needs to implement the functions shown below.

typedef struct
{
  const char *name;
  int (*gnutls_generate_server_certificate) (gnutls_session_t, gnutls_buffer_st*);
  int (*gnutls_generate_client_certificate) (gnutls_session_t, gnutls_buffer_st*);
  int (*gnutls_generate_server_kx) (gnutls_session_t, gnutls_buffer_st*);
  int (*gnutls_generate_client_kx) (gnutls_session_t, gnutls_buffer_st*);
  int (*gnutls_generate_client_cert_vrfy) (gnutls_session_t, gnutls_buffer_st *);
  int (*gnutls_generate_server_certificate_request) (gnutls_session_t,
                                                     gnutls_buffer_st *);

  int (*gnutls_process_server_certificate) (gnutls_session_t, opaque *,
                                            size_t);
  int (*gnutls_process_client_certificate) (gnutls_session_t, opaque *,
                                            size_t);
  int (*gnutls_process_server_kx) (gnutls_session_t, opaque *, size_t);
  int (*gnutls_process_client_kx) (gnutls_session_t, opaque *, size_t);
  int (*gnutls_process_client_cert_vrfy) (gnutls_session_t, opaque *, size_t);
  int (*gnutls_process_server_certificate_request) (gnutls_session_t,
                                                    opaque *, size_t);
} mod_auth_st;

Those functions are responsible for the interpretation of the handshake
protocol messages.  It is common for such functions to read data from
one or more 'credentials_t' structures(1) and write data, such as
certificates, usernames etc.  to 'auth_info_t' structures.

Simple examples of existing authentication methods can be seen in
'auth/psk.c' for PSK ciphersuites and 'auth/srp.c' for SRP ciphersuites.
After implementing these functions the structure holding its pointers
has to be registered in 'gnutls_algorithms.c' in the
'_gnutls_kx_algorithms' structure.

   ---------- Footnotes ----------

   (1) such as the 'gnutls_certificate_credentials_t' structures

10.4 TLS Extension Handling
===========================

As with authentication methods, adding TLS hello extensions can be done
quite easily by implementing the interface shown below.

typedef int (*gnutls_ext_recv_func) (gnutls_session_t session,
                                     const unsigned char *data, size_t len);
typedef int (*gnutls_ext_send_func) (gnutls_session_t session,
                                     gnutls_buffer_st *extdata);

Here there are two main functions, one for parsing the received
extension data and one for formatting the extension data that must be
send.  These functions have to check internally whether they operate
within a client or a server session.

A simple example of an extension handler can be seen in 'lib/ext/srp.c'
in GnuTLS' source code.  After implementing these functions, the
extension has to be registered.  Registering an extension can be done in
two ways.  You can create a GnuTLS internal extension and register it in
'hello_ext.c' or write an external extension (not inside GnuTLS but
inside an application using GnuTLS) and register it via the exported
functions gnutls_session_ext_register or
gnutls_ext_register.

Adding a new TLS hello extension
--------------------------------

Adding support for a new TLS hello extension is done from time to time,
and the process to do so is not difficult.  Here are the steps you need
to follow if you wish to do this yourself.  For the sake of discussion,
let's consider adding support for the hypothetical TLS extension
'foobar'.  The following section is about adding an hello extension to
GnuTLS itself.  For custom application extensions you should check the
exported functions gnutls_session_ext_register or
gnutls_ext_register.

Add 'configure' option like '--enable-foobar' or '--disable-foobar'.
....................................................................

This step is useful when the extension code is large and it might be
desirable under some circumstances to be able to leave out the extension
during compilation of GnuTLS. If you don't need this kind of feature
this step can be safely skipped.

Whether to choose enable or disable depends on whether you intend to
make the extension be enabled by default.  Look at existing checks
(i.e., SRP, authz) for how to model the code.  For example:

     AC_MSG_CHECKING([whether to disable foobar support])
     AC_ARG_ENABLE(foobar,
     	AS_HELP_STRING([--disable-foobar],
     		[disable foobar support]),
     	ac_enable_foobar=no)
     if test x$ac_enable_foobar != xno; then
      AC_MSG_RESULT(no)
      AC_DEFINE(ENABLE_FOOBAR, 1, [enable foobar])
     else
      ac_full=0
      AC_MSG_RESULT(yes)
     fi
     AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no")

These lines should go in 'lib/m4/hooks.m4'.

Add an extension identifier to 'extensions_t' in 'gnutls_int.h'.
................................................................

A good name for the identifier would be GNUTLS_EXTENSION_FOOBAR. If the
extension that you are implementing is an extension that is officially
registered by IANA then it is recommended to use its official name such
that the extension can be correctly identified by other developers.
Check with <https://www.iana.org/assignments/tls-extensiontype-values>
for registered extensions.

Register the extension in 'lib/hello_ext.c'.
............................................

In order for the extension to be executed you need to register it in the
'static hello_ext_entry_st const *extfunc[]' list in 'lib/hello_ext.c'.

A typical entry would be:

     #ifdef ENABLE_FOOBAR
     	[GNUTLS_EXTENSION_FOOBAR] = &ext_mod_foobar,
     #endif

Also for every extension you need to create an 'hello_ext_entry_st' that
describes the extension.  This structure is placed in the designated c
file for your extension and its name is used in the registration entry
as depicted above.

The structure of 'hello_ext_entry_st' is as follows:
       const hello_ext_entry_st ext_mod_foobar = {
         .name = "FOOBAR",
         .tls_id = 255,
         .gid = GNUTLS_EXTENSION_FOOBAR,
         .parse_type = GNUTLS_EXT_TLS,
         .validity = GNUTLS_EXT_FLAG_CLIENT_HELLO |
     	GNUTLS_EXT_FLAG_TLS12_SERVER_HELLO |
     	GNUTLS_EXT_FLAG_TLS13_SERVER_HELLO |
     	GNUTLS_EXT_FLAG_TLS,
         .recv_func = _gnutls_foobar_recv_params,
         .send_func = _gnutls_foobar_send_params,
         .pack_func = _gnutls_foobar_pack,
         .unpack_func = _gnutls_foobar_unpack,
         .deinit_func = _gnutls_foobar_deinit,
         .cannot_be_overriden = 1
       };

The GNUTLS_EXTENSION_FOOBAR is the identifier that you've added to
'gnutls_int.h' earlier.  The '.tls_id' should contain the number that
IANA has assigned to this extension, or an unassigned number of your
choice if this is an unregistered extension.  In the rest of this
structure you specify the functions to handle the extension data.  The
'receive' function will be called upon reception of the data and will be
used to parse or interpret the extension data.  The 'send' function will
be called prior to sending the extension data on the wire and will be
used to format the data such that it can be send over the wire.  The
'pack' and 'unpack' functions will be used to prepare the data for
storage in case of session resumption (and vice versa).  The 'deinit'
function will be called to deinitialize the extension's private
parameters, if any.

Look at 'gnutls_ext_parse_type_t' and 'gnutls_ext_flags_t' for a
complete list of available flags.

Note that the conditional 'ENABLE_FOOBAR' definition should only be used
if step 1 with the 'configure' options has taken place.

Add new files that implement the hello extension.
.................................................

To keep things structured every extension should have its own files.
The functions that you should (at least) add are those referenced in the
struct from the previous step.  Use descriptive file names such as
'lib/ext/foobar.c' and for the corresponding header 'lib/ext/foobar.h'.
As a starter, you could add this:

     int
     _gnutls_foobar_recv_params (gnutls_session_t session, const uint8_t * data,
                          size_t data_size)
     {
       return 0;
     }

     int
     _gnutls_foobar_send_params (gnutls_session_t session, gnutls_buffer_st* data)
     {
       return 0;
     }

     int
     _gnutls_foobar_pack (extension_priv_data_t epriv, gnutls_buffer_st * ps)
     {
        /* Append the extension's internal state to buffer */
        return 0;
     }

     int
     _gnutls_foobar_unpack (gnutls_buffer_st * ps, extension_priv_data_t * epriv)
     {
        /* Read the internal state from buffer */
        return 0;
     }

The '_gnutls_foobar_recv_params' function is responsible for parsing
incoming extension data (both in the client and server).

The '_gnutls_foobar_send_params' function is responsible for formatting
extension data such that it can be send over the wire (both in the
client and server).  It should append data to provided buffer and return
a positive (or zero) number on success or a negative error code.
Previous to 3.6.0 versions of GnuTLS required that function to return
the number of bytes that were written.  If zero is returned and no bytes
are appended the extension will not be sent.  If a zero byte extension
is to be sent this function must return 'GNUTLS_E_INT_RET_0'.

If you receive length fields that don't match, return
'GNUTLS_E_UNEXPECTED_PACKET_LENGTH'.  If you receive invalid data,
return 'GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER'.  You can use other error
codes from the list in Error codes.  Return 0 on success.

An extension typically stores private information in the 'session' data
for later usage.  That can be done using the functions
'_gnutls_hello_ext_set_datum' and '_gnutls_hello_ext_get_datum'.  You
can check simple examples at 'lib/ext/max_record.c' and
'lib/ext/server_name.c' extensions.  That private information can be
saved and restored across session resumption if the following functions
are set:

The '_gnutls_foobar_pack' function is responsible for packing internal
extension data to save them in the session resumption storage.

The '_gnutls_foobar_unpack' function is responsible for restoring
session data from the session resumption storage.

When the internal data is stored using the
'_gnutls_hello_ext_set_datum', then you can rely on the default pack and
unpack functions: '_gnutls_hello_ext_default_pack' and
'_gnutls_hello_ext_default_unpack'.

Recall that both for the client and server, the send and receive
functions most likely will need to do different things depending on
which mode they are in.  It may be useful to make this distinction
explicit in the code.  Thus, for example, a better template than above
would be:

     int
     _gnutls_foobar_recv_params (gnutls_session_t session,
                                 const uint8_t * data,
                                 size_t data_size)
     {
       if (session->security_parameters.entity == GNUTLS_CLIENT)
         return foobar_recv_client (session, data, data_size);
       else
         return foobar_recv_server (session, data, data_size);
     }

     int
     _gnutls_foobar_send_params (gnutls_session_t session,
                                 gnutls_buffer_st * data)
     {
       if (session->security_parameters.entity == GNUTLS_CLIENT)
         return foobar_send_client (session, data);
       else
         return foobar_send_server (session, data);
     }

The functions used would be declared as 'static' functions, of the
appropriate prototype, in the same file.

When adding the new extension files, you'll need to add them to
'lib/ext/Makefile.am' as well, for example:

     if ENABLE_FOOBAR
     libgnutls_ext_la_SOURCES += ext/foobar.c ext/foobar.h
     endif

Add API functions to use the extension.
.......................................

It might be desirable to allow users of the extension to request the use
of the extension, or set extension specific data.  This can be
implemented by adding extension specific function calls that can be
added to 'includes/gnutls/gnutls.h', as long as the LGPLv2.1+ applies.
The implementation of these functions should lie in the
'lib/ext/foobar.c' file.

To make the API available in the shared library you need to add the
added symbols in 'lib/libgnutls.map', so that the symbols are exported
properly.

When writing GTK-DOC style documentation for your new APIs, don't forget
to add 'Since:' tags to indicate the GnuTLS version the API was
introduced in.

Adding a new Supplemental Data Handshake Message
------------------------------------------------

TLS handshake extensions allow to send so called supplemental data
handshake messages [see RFC4680].  This short section explains how
to implement a supplemental data handshake message for a given TLS
extension.

First of all, modify your extension 'foobar' in the way, to instruct the
handshake process to send and receive supplemental data, as shown below.

     int
     _gnutls_foobar_recv_params (gnutls_session_t session, const opaque * data,
                                      size_t _data_size)
     {
        ...
        gnutls_supplemental_recv(session, 1);
        ...
     }

     int
     _gnutls_foobar_send_params (gnutls_session_t session, gnutls_buffer_st *extdata)
     {
        ...
        gnutls_supplemental_send(session, 1);
        ...
     }

Furthermore you'll need two new functions '_foobar_supp_recv_params' and
'_foobar_supp_send_params', which must conform to the following
prototypes.

     typedef int (*gnutls_supp_recv_func)(gnutls_session_t session,
                                          const unsigned char *data,
                                          size_t data_size);
     typedef int (*gnutls_supp_send_func)(gnutls_session_t session,
                                          gnutls_buffer_t buf);

The following example code shows how to send a "Hello World" string in
the supplemental data handshake message.

     int
     _foobar_supp_recv_params(gnutls_session_t session, const opaque *data, size_t _data_size)
     {
        uint8_t len = _data_size;
        unsigned char *msg;

        msg = gnutls_malloc(len);
        if (msg == NULL) return GNUTLS_E_MEMORY_ERROR;

        memcpy(msg, data, len);
        msg[len]='\0';

        /* do something with msg */
        gnutls_free(msg);

        return len;
     }

     int
     _foobar_supp_send_params(gnutls_session_t session, gnutls_buffer_t buf)
     {
        unsigned char *msg = "hello world";
        int len = strlen(msg);

        if (gnutls_buffer_append_data(buf, msg, len) < 0)
            abort();

        return len;
     }

Afterwards, register the new supplemental data using
gnutls_session_supplemental_register, or
gnutls_supplemental_register at some point in your program.

10.5 Cryptographic Backend
==========================

Today most new processors, either for embedded or desktop systems
include either instructions intended to speed up cryptographic
operations, or a co-processor with cryptographic capabilities.  Taking
advantage of those is a challenging task for every cryptographic
application or library.  GnuTLS handles the cryptographic provider in a
modular way, following a layered approach to access cryptographic
operations as in Figure 10.4.

Figure 10.4: GnuTLS cryptographic back-end design.

The TLS layer uses a cryptographic provider layer, that will in turn
either use the default crypto provider - a software crypto library, or
use an external crypto provider, if available in the local system.  The
reason of handling the external cryptographic provider in GnuTLS and not
delegating it to the cryptographic libraries, is that none of the
supported cryptographic libraries support '/dev/crypto' or CPU-optimized
cryptography in an efficient way.

Cryptographic library layer
---------------------------

The Cryptographic library layer, currently supports only libnettle.
Older versions of GnuTLS used to support libgcrypt, but it was switched
with nettle mainly for performance reasons(1) and secondary because it
is a simpler library to use.  In the future other cryptographic
libraries might be supported as well.

External cryptography provider
------------------------------

Systems that include a cryptographic co-processor, typically come with
kernel drivers to utilize the operations from software.  For this reason
GnuTLS provides a layer where each individual algorithm used can be
replaced by another implementation, i.e., the one provided by the
driver.  The FreeBSD, OpenBSD and Linux kernels(2) include already a
number of hardware assisted implementations, and also provide an
interface to access them, called '/dev/crypto'.  GnuTLS will take
advantage of this interface if compiled with special options.  That is
because in most systems where hardware-assisted cryptographic operations
are not available, using this interface might actually harm performance.

In systems that include cryptographic instructions with the CPU's
instructions set, using the kernel interface will introduce an unneeded
layer.  For this reason GnuTLS includes such optimizations found in
popular processors such as the AES-NI or VIA PADLOCK instruction sets.
This is achieved using a mechanism that detects CPU capabilities and
overrides parts of crypto back-end at runtime.  The next section
discusses the registration of a detected algorithm optimization.  For
more information please consult the GnuTLS source code in
'lib/accelerated/'.

Overriding specific algorithms
..............................

When an optimized implementation of a single algorithm is available, say
a hardware assisted version of AES-CBC then the following functions,
from 'crypto.h', can be used to register those algorithms.

   * gnutls_crypto_register_cipher: To register a cipher
     algorithm.

   * gnutls_crypto_register_aead_cipher: To register an AEAD
     cipher algorithm.

   * gnutls_crypto_register_mac: To register a MAC algorithm.

   * gnutls_crypto_register_digest: To register a hash
     algorithm.

Those registration functions will only replace the specified algorithm
and leave the rest of subsystem intact.

Protecting keys through isolation
---------------------------------

For asymmetric or public keys, GnuTLS supports PKCS #11 which allows
operation without access to long term keys, in addition to CPU
offloading.  For more information see Hardware security modules and abstract key types.

   ---------- Footnotes ----------

   (1) See
<https://lists.gnu.org/archive/html/gnutls-devel/2011-02/msg00079.html>.

   (2) Check <https://home.gna.org/cryptodev-linux/> for the Linux
kernel implementation of '/dev/crypto'.

10.6 Random Number Generators
=============================

About the generators
--------------------

GnuTLS provides two random generators.  The default, and the AES-DRBG
random generator which is only used when the library is compiled with
support for FIPS140-2 and the system is in FIPS140-2 mode.

The default generator - inner workings
--------------------------------------

The random number generator levels in 'gnutls_rnd_level_t' map to two
CHACHA-based random generators which are initially seeded using the OS
random device, e.g., '/dev/urandom' or 'getrandom()'.  These random
generators are unique per thread, and are automatically re-seeded when a
fork is detected.

The reason the CHACHA cipher was selected for the GnuTLS' PRNG is the
fact that CHACHA is considered a secure and fast stream cipher, and is
already defined for use in TLS protocol.  As such, the utilization of it
would not stress the CPU caches, and would allow for better performance
on busy servers, irrespective of their architecture (e.g., even if AES
is not available with an optimized instruction set).

The generators are unique per thread to allow lock-free operation.  That
induces a cost of around 140-bytes for the state of the generators per
thread, on threads that would utilize gnutls_rnd.  At the same
time it allows fast and lock-free access to the generators.  The
lock-free access benefits servers which utilize more than 4 threads,
while imposes no cost on single threaded processes.

On the first call to gnutls_rnd the generators are seeded with
two independent keys obtained from the OS random device.  Their seed is
used to output a fixed amount of bytes before re-seeding; the number of
bytes output varies per generator.

One generator is dedicated for the 'GNUTLS_RND_NONCE' level, and the
second is shared for the 'GNUTLS_RND_KEY' and 'GNUTLS_RND_RANDOM'
levels.  For the rest of this section we refer to the first as the nonce
generator and the second as the key generator.

The nonce generator will reseed after outputting a fixed amount of bytes
(typically few megabytes), or after few hours of operation without
reaching the limit has passed.  It is being re-seed using the key
generator to obtain a new key for the CHACHA cipher, which is mixed with
its old one.

Similarly, the key generator, will also re-seed after a fixed amount of
bytes is generated (typically less than the nonce), and will also
re-seed based on time, i.e., after few hours of operation without
reaching the limit for a re-seed.  For its re-seed it mixes mixes data
obtained from the OS random device with the previous key.

Although the key generator used to provide data for the
'GNUTLS_RND_RANDOM' and 'GNUTLS_RND_KEY' levels is identical, when used
with the 'GNUTLS_RND_KEY' level a re-key of the PRNG using its own
output, is additionally performed.  That ensures that the recovery of
the PRNG state will not be sufficient to recover previously generated
values.

The AES-DRBG generator - inner workings
---------------------------------------

Similar with the default generator, the random number generator levels
in 'gnutls_rnd_level_t' map to two AES-DRBG random generators which are
initially seeded using the OS random device, e.g., '/dev/urandom' or
'getrandom()'.  These random generators are unique per thread, and are
automatically re-seeded when a fork is detected.

The AES-DRBG generator is based on the AES cipher in counter mode and is
re-seeded after a fixed amount of bytes are generated.

Defense against PRNG attacks
----------------------------

This section describes the counter-measures available in the
Pseudo-random number generator (PRNG) of GnuTLS for known attacks as
described in [see PRNGATTACKS].  Note that, the attacks on a PRNG
such as state-compromise, assume a quite powerful adversary which has in
practice access to the PRNG state.

Cryptanalytic
.............

To defend against cryptanalytic attacks GnuTLS' PRNG is a stream cipher
designed to defend against the same attacks.  As such, GnuTLS' PRNG
strength with regards to this attack relies on the underlying crypto
block, which at the time of writing is CHACHA. That is easily
replaceable in the future if attacks are found to be possible in that
cipher.

Input-based attacks
...................

These attacks assume that the attacker can influence the input that is
used to form the state of the PRNG. To counter these attacks GnuTLS does
not gather input from the system environment but rather relies on the OS
provided random generator.  That is the '/dev/urandom' or
'getentropy'/'getrandom' system calls.  As such, GnuTLS' PRNG is as
strong as the system random generator can assure with regards to
input-based attacks.

State-compromise: Backtracking
..............................

A backtracking attack, assumes that an adversary obtains at some point
of time access to the generator state, and wants to recover past bytes.
As the GnuTLS generator is fine-tuned to provide multiple levels, such
an attack mainly concerns levels 'GNUTLS_RND_RANDOM' and
'GNUTLS_RND_KEY', since 'GNUTLS_RND_NONCE' is intended to output
non-secret data.  The 'GNUTLS_RND_RANDOM' generator at the time of
writing can output 2MB prior to being re-seeded thus this is its upper
bound for previously generated data recovered using this attack.  That
assumes that the state of the operating system random generator is
unknown to the attacker, and we carry that assumption on the next
paragraphs.  The usage of 'GNUTLS_RND_KEY' level ensures that no
backtracking is possible for all output data, by re-keying the PRNG
using its own output.

Such an attack reflects the real world scenario where application's
memory is temporarily compromised, while the kernel's memory is
inaccessible.

State-compromise: Permanent Compromise Attack
.............................................

A permanent compromise attack implies that once an attacker compromises
the state of GnuTLS' random generator at a specific time, future and
past outputs from the generator are compromised.  For past outputs the
previous paragraph applies.  For future outputs, both the
'GNUTLS_RND_RANDOM' and the 'GNUTLS_RND_KEY' will recover after 2MB of
data have been generated or few hours have passed (two at the time of
writing).  Similarly the 'GNUTLS_RND_NONCE' level generator will recover
after several megabytes of output is generated, or its re-key time is
reached.

State-compromise: Iterative guessing
....................................

This attack assumes that after an attacker obtained the PRNG state at
some point, is able to recover the state at a later time by observing
outputs of the PRNG. That is countered by switching the key to
generators using a combination of a fresh key and the old one (using
XOR), at re-seed time.  All levels are immune to such attack after a
re-seed.

State-compromise: Meet-in-the-Middle
....................................

This attack assumes that the attacker obtained the PRNG state at two
distinct times, and being able to recover the state at the third time
after observing the output of the PRNG. Given the approach described on
the above paragraph, all levels are immune to such attack.

10.7 FIPS140-2 mode
===================

GnuTLS can operate in a special mode for FIPS140-2.  That mode of
operation is for the conformance to NIST's FIPS140-2 publication, which
consists of policies for cryptographic modules (such as software
libraries).  Its implementation in GnuTLS is designed for Red Hat
Enterprise Linux, and can only be enabled when the library is explicitly
compiled with the '-enable-fips140-mode' configure option.  The
operation of the library is then modified, as follows.

   * FIPS140-2 mode is enabled when '/proc/sys/crypto/fips_enabled'
     contains '1' and '/etc/system-fips' is present.
   * Only approved by FIPS140-2 algorithms are enabled
   * Only approved by FIPS140-2 key lengths are allowed for key
     generation
   * The random generator used switches to DRBG-AES
   * The integrity of the GnuTLS and dependent libraries is checked on
     startup
   * Algorithm self-tests are run on library load
   * Any cryptographic operation will be refused if any of the
     self-tests failed

There are also few environment variables which modify that operation.
The environment variable 'GNUTLS_SKIP_FIPS_INTEGRITY_CHECKS' will
disable the library integrity tests on startup, and the variable
'GNUTLS_FORCE_FIPS_MODE' can be set to force a value from Figure 10.5,
i.e., '1' will enable the FIPS140-2 mode,
while '0' will disable it.

The integrity checks for the dependent libraries and GnuTLS are
performed using '.hmac' files which are present at the same path as the
library.  The key for the operations can be provided on compile-time
with the configure option '-with-fips140-key'.  The MAC algorithm used
is HMAC-SHA256.

On runtime an application can verify whether the library is in FIPS140-2
mode using the gnutls_fips140_mode_enabled function.

Relaxing FIPS140-2 requirements
-------------------------------

The library by default operates in a strict enforcing mode, ensuring
that all constraints imposed by the FIPS140-2 specification are
enforced.  However the application can relax these requirements via
gnutls_fips140_set_mode which can switch to alternative modes as
in Figure 10.5.

'GNUTLS_FIPS140_DISABLED'
     The FIPS140-2 mode is disabled.
'GNUTLS_FIPS140_STRICT'
     The default mode; all forbidden operations will cause an operation
     failure via error code.
'GNUTLS_FIPS140_SELFTESTS'
     A transient state during library initialization.  That state cannot
     be set or seen by applications.
'GNUTLS_FIPS140_LAX'
     The library still uses the FIPS140-2 relevant algorithms but all
     forbidden by FIPS140-2 operations are allowed; this is useful when
     the application is aware of the followed security policy, and needs
     to utilize disallowed operations for other reasons (e.g.,
     compatibility).
'GNUTLS_FIPS140_LOG'
     Similarly to 'GNUTLS_FIPS140_LAX' , it allows forbidden operations;
     any use of them results to a message to the audit callback
     functions.

Figure 10.5: The 'gnutls_fips_mode_t' enumeration.

The intention of this API is to be used by applications which may run in
FIPS140-2 mode, while they utilize few algorithms not in the allowed
set, e.g., for non-security related purposes.  In these cases
applications should wrap the non-compliant code within blocks like the
following.

     GNUTLS_FIPS140_SET_LAX_MODE();

     _gnutls_hash_fast(GNUTLS_DIG_MD5, buffer, sizeof(buffer), output);

     GNUTLS_FIPS140_SET_STRICT_MODE();

The 'GNUTLS_FIPS140_SET_LAX_MODE' and 'GNUTLS_FIPS140_SET_STRICT_MODE'
are macros to simplify the following sequence of calls.

     if (gnutls_fips140_mode_enabled())
       gnutls_fips140_set_mode(GNUTLS_FIPS140_LAX, GNUTLS_FIPS140_SET_MODE_THREAD);

     _gnutls_hash_fast(GNUTLS_DIG_MD5, buffer, sizeof(buffer), output);

     if (gnutls_fips140_mode_enabled())
       gnutls_fips140_set_mode(GNUTLS_FIPS140_STRICT, GNUTLS_FIPS140_SET_MODE_THREAD);

The reason of the 'GNUTLS_FIPS140_SET_MODE_THREAD' flag in the previous
calls is to localize the change in the mode.  Note also, that such a
block has no effect when the library is not operating under FIPS140-2
mode, and thus it can be considered a no-op.

Applications could also switch FIPS140-2 mode explicitly off, by calling
     gnutls_fips140_set_mode(GNUTLS_FIPS140_LAX, 0);

Appendix A Upgrading from previous versions
*******************************************

The GnuTLS library typically maintains binary and source code
compatibility across versions.  The releases that have the major version
increased break binary compatibility but source compatibility is
provided.  This section lists exceptional cases where changes to
existing code are required due to library changes.

Upgrading to 2.12.x from previous versions
==========================================

GnuTLS 2.12.x is binary compatible with previous versions but changes
the semantics of 'gnutls_transport_set_lowat', which might cause
breakage in applications that relied on its default value be 1.  Two
fixes are proposed:
   * Quick fix.  Explicitly call 'gnutls_transport_set_lowat (session,
     1);' after gnutls_init.
   * Long term fix.  Because later versions of gnutls abolish the
     functionality of using the system call 'select' to check for gnutls
     pending data, the function gnutls_record_check_pending has
     to be used to achieve the same functionality as described in
     Asynchronous operation.

Upgrading to 3.0.x from 2.12.x
==============================

GnuTLS 3.0.x is source compatible with previous versions except for the
functions listed below.

Old function           Replacement

-------------------------------------------------------------------
'gnutls_transport_set_lowat'To replace its functionality the function
                       gnutls_record_check_pending has
                       to be used, as described in
                       Asynchronous operation

'gnutls_session_get_server_random',They are replaced by the safer function
'gnutls_session_get_client_random'gnutls_session_get_random

'gnutls_session_get_master_secret'Replaced by the keying material exporters
                       discussed in
                       Deriving keys for other applications/protocols

'gnutls_transport_set_global_errno'Replaced by using the system's errno
                       facility or
                       gnutls_transport_set_errno.

'gnutls_x509_privkey_verify_data'Replaced by
                       See gnutls_pubkey_verify_data2.

'gnutls_certificate_verify_peers'Replaced by
                       See gnutls_certificate_verify_peers2.

'gnutls_psk_netconf_derive_key'Removed.  The key derivation function was
                       never standardized.

'gnutls_session_set_finished_function'Removed.

'gnutls_ext_register'  Removed.  Extension registration API is
                       now internal to allow easier changes in
                       the API.

'gnutls_certificate_get_x509_crls',Removed to allow updating the internal
'gnutls_certificate_get_x509_cas'structures.  Replaced by
                       See gnutls_certificate_get_issuer.

'gnutls_certificate_get_openpgp_keyring'Removed.

'gnutls_ia_'           Removed.  The inner application
                       extensions were completely removed (they
                       failed to be standardized).

Upgrading to 3.1.x from 3.0.x
=============================

GnuTLS 3.1.x is source and binary compatible with GnuTLS 3.0.x releases.
Few functions have been deprecated and are listed below.

Old function           Replacement

-------------------------------------------------------------------
'gnutls_pubkey_verify_hash'The function
                       gnutls_pubkey_verify_hash2 is
                       provided and is functionally equivalent
                       and safer to use.

'gnutls_pubkey_verify_data'The function
                       gnutls_pubkey_verify_data2 is
                       provided and is functionally equivalent
                       and safer to use.

Upgrading to 3.2.x from 3.1.x
=============================

GnuTLS 3.2.x is source and binary compatible with GnuTLS 3.1.x releases.
Few functions have been deprecated and are listed below.

Old function           Replacement

-------------------------------------------------------------------
'gnutls_privkey_sign_raw_data'The function
                       gnutls_privkey_sign_hash is
                       equivalent when the flag
                       'GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA' is
                       specified.

Upgrading to 3.3.x from 3.2.x
=============================

GnuTLS 3.3.x is source and binary compatible with GnuTLS 3.2.x releases;
however there few changes in semantics which are listed below.

Old function           Replacement

-------------------------------------------------------------------
'gnutls_global_init'   No longer required.  The library is
                       initialized using a constructor.

'gnutls_global_deinit' No longer required.  The library is
                       deinitialized using a destructor.

Upgrading to 3.4.x from 3.3.x
=============================

GnuTLS 3.4.x is source compatible with GnuTLS 3.3.x releases; however,
several deprecated functions were removed, and are listed below.

Old function           Replacement

-------------------------------------------------------------------
Priority string        The following string emulates the 3.3.x
"NORMAL" has been      behavior
modified               "NORMAL:+VERS-SSL3.0:+ARCFOUR-128:+DHE-DSS:+SIGN-DSA-SHA512:+SIGN-DSA-SHA256:+SIGN-DSA-SHA1"

'gnutls_certificate_client_set_retrieve_function',see gnutls_certificate_set_retrieve_function
'gnutls_certificate_server_set_retrieve_function'
'gnutls_certificate_set_rsa_export_params',No replacement; the library does not
'gnutls_rsa_export_get_modulus_bits',support the RSA-EXPORT ciphersuites.
'gnutls_rsa_export_get_pubkey',
'gnutls_rsa_params_cpy',
'gnutls_rsa_params_deinit',
'gnutls_rsa_params_export_pkcs1',
'gnutls_rsa_params_export_raw',
'gnutls_rsa_params_generate2',
'gnutls_rsa_params_import_pkcs1',
'gnutls_rsa_params_import_raw',
'gnutls_rsa_params_init'
'gnutls_pubkey_verify_hash',see gnutls_pubkey_verify_hash2.

'gnutls_pubkey_verify_data',see gnutls_pubkey_verify_data2.

'gnutls_x509_crt_get_verify_algorithm',No replacement; a similar function is
                       See gnutls_x509_crt_get_signature_algorithm.

'gnutls_pubkey_get_verify_algorithm',No replacement; a similar function is
                       See gnutls_pubkey_get_preferred_hash_algorithm.

'gnutls_certificate_type_set_priority',see gnutls_priority_set_direct.
'gnutls_cipher_set_priority',
'gnutls_compression_set_priority',
'gnutls_kx_set_priority',
'gnutls_mac_set_priority',
'gnutls_protocol_set_priority'
'gnutls_sign_callback_get',see gnutls_privkey_import_ext3
'gnutls_sign_callback_set'
'gnutls_x509_crt_verify_hash'gnutls_pubkey_verify_hash2

'gnutls_x509_crt_verify_data'gnutls_pubkey_verify_data2

'gnutls_privkey_sign_raw_data'gnutls_privkey_sign_hash with the
                       flag GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA

Upgrading to 3.6.x from 3.5.x
=============================

GnuTLS 3.6.x is source and binary compatible with GnuTLS 3.5.x releases;
however, there are minor differences, listed below.

Old functionality      Replacement

-------------------------------------------------------------------
The priority strings   TLS compression is no longer available.
"+COMP" are a no-op
The SSL 3.0 protocol   SSL 3.0 is no longer compiled in by
is a no-op             default.  It is a legacy protocol which
                       is completely eliminated from public
                       internet.  As such it was removed to
                       reduce the attack vector for applications
                       using the library.

The hash function      TLS 1.3 no longer uses SHA2-224, and it
SHA2-224 is a no-op    was never a widespread hash algorithm.
for TLS1.2             As such it was removed for simplicity.

The SRP key exchange   The SRP key exchange is restricted to
accepted parameters    [see TLSSRP] spec parameters to
outside the            protect clients from MitM attacks.
[see TLSSRP]
spec
The                    No longer use 'gnutls_compression_get',
compression-related    'gnutls_compression_get_name',
functions are          'gnutls_compression_list', and
deprecated             'gnutls_compression_get_id'.

See gnutls_x509_crt_sign,These signing functions will no longer
gnutls_x509_crl_sign,sign using SHA1, but with a secure hash
gnutls_x509_crq_signalgorithm.

gnutls_certificate_set_ocsp_status_request_fileThis function will return an error if the
                       loaded response doesn't match any of the
                       present certificates.  To revert to
                       previous semantics set the
                       'GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK'
                       flag using
                       gnutls_certificate_set_flags.

The callback           It is replaced with
gnutls_privkey_import_ext3gnutls_privkey_import_ext4
is not flexible
enough for new
signature algorithms
such as RSA-PSS
Re-handshake           It is replaced by separate key update and
functionality is not   re-authentication functionality which can
applicable under TLS   be accessed directly via
1.3.                   gnutls_session_key_update and
                       gnutls_reauth.

TLS session            The TLS session identifiers are
identifiers are not    persistent across resumption only on
shared with the        server side and can be obtained as before
server under TLS       via gnutls_session_get_id2.
1.3.
See gnutls_pkcs11_privkey_generate3,These functions no longer create an
gnutls_pkcs11_copy_secret_key,exportable key by default; they require
gnutls_pkcs11_copy_x509_privkey2the flag
                       'GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE'
                       to do so.

See gnutls_db_set_retrieve_function,These functions are no longer relevant
gnutls_db_set_store_function,under TLS 1.3; resumption under TLS 1.3
gnutls_db_set_remove_functionis done via session tickets, c.f.
                       see gnutls_session_ticket_enable_server.

See gnutls_session_get_data2,These functions may introduce a slight
gnutls_session_get_datadelay under TLS 1.3 for few milliseconds.
                       Check output of
                       gnutls_session_get_flags for
                       GNUTLS_SFLAGS_SESSION_TICKET before
                       calling this function to avoid delays.

SRP and RSA-PSK key    SRP and RSA-PSK key exchanges are not
exchanges are not      supported in TLS 1.3, so when these key
supported under TLS    exchanges are present in a priority
1.3                    string, TLS 1.3 is disabled.

Anonymous key          There is no anonymous key exchange
exchange is not        supported under TLS 1.3, so if an
supported under TLS    anonymous key exchange method is set in a
1.3                    priority string, and no certificate
                       credentials are set in the client or
                       server, TLS 1.3 will not be negotiated.

ECDHE-PSK and          In the priority strings, both 'ECDHEPSK'
DHE-PSK keywords       and 'DHEPSK' indicate the intent to
have the same          support an ephemeral key exchange with
meaning under TLS      the pre-shared key.  The parameters of
1.3                    the key exchange are negotiated with the
                       supported groups specified in the
                       priority string.

Authentication-only    Ciphersuites with the 'NULL' cipher
ciphersuites are not   (i.e., authentication-only) are not
supported under TLS    supported in TLS 1.3, so when they are
1.3                    specified in a priority string, TLS 1.3
                       is disabled.

Supplemental data is   The TLS supplemental data handshake
not supported under    message (RFC 4680) is not supported under
TLS 1.3                TLS 1.3, so if the application calls
                       gnutls_supplemental_register or
                       gnutls_session_supplemental_register,
                       TLS 1.3 is disabled.

The                    The macro was non-functional and because
GNUTLS_X509_NO_WELL_DEFINED_EXPIRATIONof the nature of the definition of the
macro is a no-op       no-well-defined date for certificates (a
                       real date), it will not be fixed or
                       re-introduced.

Appendix B Support
******************

B.1 Getting Help
================

A mailing list where users may help each other exists, and you can reach
it by sending e-mail to <gnutls-help@gnutls.org>.  Archives of the
mailing list discussions, and an interface to manage subscriptions, is
available through the World Wide Web at
<https://lists.gnutls.org/pipermail/gnutls-help/>.

A mailing list for developers are also available, see
<https://www.gnutls.org/lists.html>.  Bug reports should be sent to
<bugs@gnutls.org>, see Bug Reports.

B.2 Commercial Support
======================

Commercial support is available for users of GnuTLS. See
<https://www.gnutls.org/commercial.html> for more information.

B.3 Bug Reports
===============

If you think you have found a bug in GnuTLS, please investigate it and
report it.

   * Please make sure that the bug is really in GnuTLS, and preferably
     also check that it hasn't already been fixed in the latest version.

   * You have to send us a test case that makes it possible for us to
     reproduce the bug.

   * You also have to explain what is wrong; if you get a crash, or if
     the results printed are not good and in that case, in what way.
     Make sure that the bug report includes all information you would
     need to fix this kind of bug for someone else.

Please make an effort to produce a self-contained report, with something
definite that can be tested or debugged.  Vague queries or piecemeal
messages are difficult to act on and don't help the development effort.

If your bug report is good, we will do our best to help you to get a
corrected version of the software; if the bug report is poor, we won't
do anything about it (apart from asking you to send better bug reports).

If you think something in this manual is unclear, or downright
incorrect, or if the language needs to be improved, please also send a
note.

Send your bug report to:

                           'bugs@gnutls.org'

B.4 Contributing
================

If you want to submit a patch for inclusion - from solving a typo you
discovered, up to adding support for a new feature - you should submit
it as a bug report, using the process in Bug Reports.  There are
some things that you can do to increase the chances for it to be
included in the official package.

Unless your patch is very small (say, under 10 lines) we require that
you assign the copyright of your work to the Free Software Foundation.
This is to protect the freedom of the project.  If you have not already
signed papers, we will send you the necessary information when you
submit your contribution.

For contributions that doesn't consist of actual programming code, the
only guidelines are common sense.  For code contributions, a number of
style guides will help you:

   * Coding Style.  Follow the GNU Standards document.

     If you normally code using another coding standard, there is no
     problem, but you should use 'indent' to reformat the code before
     submitting your work.

   * Use the unified diff format 'diff -u'.

   * Return errors.  No reason whatsoever should abort the execution of
     the library.  Even memory allocation errors, e.g.  when malloc
     return NULL, should work although result in an error code.

   * Design with thread safety in mind.  Don't use global variables.
     Don't even write to per-handle global variables unless the
     documented behaviour of the function you write is to write to the
     per-handle global variable.

   * Avoid using the C math library.  It causes problems for embedded
     implementations, and in most situations it is very easy to avoid
     using it.

   * Document your functions.  Use comments before each function
     headers, that, if properly formatted, are extracted into Texinfo
     manuals and GTK-DOC web pages.

   * Supply a ChangeLog and NEWS entries, where appropriate.

B.5 Certification
=================

There are certifications from national or international bodies which
"prove" to an auditor that the crypto component follows some best
practices, such as unit testing and reliance on well known crypto
primitives.

GnuTLS has support for the FIPS 140-2 certification under Red Hat
Enterprise Linux.  See FIPS140-2 mode for more information.

Appendix C Error Codes and Descriptions
***************************************

The error codes used throughout the library are described below.  The
return code 'GNUTLS_E_SUCCESS' indicates a successful operation, and is
guaranteed to have the value 0, so you can use it in logical
expressions.

0           GNUTLS_E_SUCCESS              Success.
-3          GNUTLS_E_UNKNOWN_COMPRESSION_ALGORITHMCould not negotiate a
                                          supported compression
                                          method.
-6          GNUTLS_E_UNKNOWN_CIPHER_TYPE  The cipher type is
                                          unsupported.
-7          GNUTLS_E_LARGE_PACKET         The transmitted packet is
                                          too large (EMSGSIZE).
-8          GNUTLS_E_UNSUPPORTED_VERSION_PACKETA packet with illegal or
                                          unsupported version was
                                          received.
-9          GNUTLS_E_UNEXPECTED_PACKET_LENGTHError decoding the
                                          received TLS packet.
-10         GNUTLS_E_INVALID_SESSION      The specified session has
                                          been invalidated for some
                                          reason.
-12         GNUTLS_E_FATAL_ALERT_RECEIVED A TLS fatal alert has
                                          been received.
-15         GNUTLS_E_UNEXPECTED_PACKET    An unexpected TLS packet
                                          was received.
-16         GNUTLS_E_WARNING_ALERT_RECEIVEDA TLS warning alert has
                                          been received.
-18         GNUTLS_E_ERROR_IN_FINISHED_PACKETAn error was encountered
                                          at the TLS Finished
                                          packet calculation.
-19         GNUTLS_E_UNEXPECTED_HANDSHAKE_PACKETAn unexpected TLS
                                          handshake packet was
                                          received.
-21         GNUTLS_E_UNKNOWN_CIPHER_SUITE Could not negotiate a
                                          supported cipher suite.
-22         GNUTLS_E_UNWANTED_ALGORITHM   An algorithm that is not
                                          enabled was negotiated.
-23         GNUTLS_E_MPI_SCAN_FAILED      The scanning of a large
                                          integer has failed.
-24         GNUTLS_E_DECRYPTION_FAILED    Decryption has failed.
-25         GNUTLS_E_MEMORY_ERROR         Internal error in memory
                                          allocation.
-26         GNUTLS_E_DECOMPRESSION_FAILED Decompression of the TLS
                                          record packet has failed.
-27         GNUTLS_E_COMPRESSION_FAILED   Compression of the TLS
                                          record packet has failed.
-28         GNUTLS_E_AGAIN                Resource temporarily
                                          unavailable, try again.
-29         GNUTLS_E_EXPIRED              The session or
                                          certificate has expired.
-30         GNUTLS_E_DB_ERROR             Error in Database
                                          backend.
-31         GNUTLS_E_SRP_PWD_ERROR        Error in password/key
                                          file.
-32         GNUTLS_E_INSUFFICIENT_CREDENTIALSInsufficient credentials
                                          for that request.
-33         GNUTLS_E_HASH_FAILED          Hashing has failed.
-34         GNUTLS_E_BASE64_DECODING_ERRORBase64 decoding error.
-35         GNUTLS_E_MPI_PRINT_FAILED     Could not export a large
                                          integer.
-37         GNUTLS_E_REHANDSHAKE          Rehandshake was requested
                                          by the peer.
-38         GNUTLS_E_GOT_APPLICATION_DATA TLS Application data were
                                          received, while expecting
                                          handshake data.
-39         GNUTLS_E_RECORD_LIMIT_REACHED The upper limit of record
                                          packet sequence numbers
                                          has been reached.  Wow!
-40         GNUTLS_E_ENCRYPTION_FAILED    Encryption has failed.
-43         GNUTLS_E_CERTIFICATE_ERROR    Error in the certificate.
-44         GNUTLS_E_PK_ENCRYPTION_FAILED Public key encryption has
                                          failed.
-45         GNUTLS_E_PK_DECRYPTION_FAILED Public key decryption has
                                          failed.
-46         GNUTLS_E_PK_SIGN_FAILED       Public key signing has
                                          failed.
-47         GNUTLS_E_X509_UNSUPPORTED_CRITICAL_EXTENSIONUnsupported critical
                                          extension in X.509
                                          certificate.
-48         GNUTLS_E_KEY_USAGE_VIOLATION  Key usage violation in
                                          certificate has been
                                          detected.
-49         GNUTLS_E_NO_CERTIFICATE_FOUND No certificate was found.
-50         GNUTLS_E_INVALID_REQUEST      The request is invalid.
-51         GNUTLS_E_SHORT_MEMORY_BUFFER  The given memory buffer
                                          is too short to hold
                                          parameters.
-52         GNUTLS_E_INTERRUPTED          Function was interrupted.
-53         GNUTLS_E_PUSH_ERROR           Error in the push
                                          function.
-54         GNUTLS_E_PULL_ERROR           Error in the pull
                                          function.
-55         GNUTLS_E_RECEIVED_ILLEGAL_PARAMETERAn illegal parameter has
                                          been received.
-56         GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLEThe requested data were
                                          not available.
-57         GNUTLS_E_PKCS1_WRONG_PAD      Wrong padding in PKCS1
                                          packet.
-58         GNUTLS_E_RECEIVED_ILLEGAL_EXTENSIONAn illegal TLS extension
                                          was received.
-59         GNUTLS_E_INTERNAL_ERROR       GnuTLS internal error.
-60         GNUTLS_E_CERTIFICATE_KEY_MISMATCHThe certificate and the
                                          given key do not match.
-61         GNUTLS_E_UNSUPPORTED_CERTIFICATE_TYPEThe certificate type is
                                          not supported.
-62         GNUTLS_E_X509_UNKNOWN_SAN     Unknown Subject
                                          Alternative name in X.509
                                          certificate.
-63         GNUTLS_E_DH_PRIME_UNACCEPTABLEThe Diffie-Hellman prime
                                          sent by the server is not
                                          acceptable (not long
                                          enough).
-64         GNUTLS_E_FILE_ERROR           Error while reading file.
-67         GNUTLS_E_ASN1_ELEMENT_NOT_FOUNDASN1 parser: Element was
                                          not found.
-68         GNUTLS_E_ASN1_IDENTIFIER_NOT_FOUNDASN1 parser: Identifier
                                          was not found
-69         GNUTLS_E_ASN1_DER_ERROR       ASN1 parser: Error in DER
                                          parsing.
-70         GNUTLS_E_ASN1_VALUE_NOT_FOUND ASN1 parser: Value was
                                          not found.
-71         GNUTLS_E_ASN1_GENERIC_ERROR   ASN1 parser: Generic
                                          parsing error.
-72         GNUTLS_E_ASN1_VALUE_NOT_VALID ASN1 parser: Value is not
                                          valid.
-73         GNUTLS_E_ASN1_TAG_ERROR       ASN1 parser: Error in
                                          TAG.
-74         GNUTLS_E_ASN1_TAG_IMPLICIT    ASN1 parser: error in
                                          implicit tag
-75         GNUTLS_E_ASN1_TYPE_ANY_ERROR  ASN1 parser: Error in
                                          type 'ANY'.
-76         GNUTLS_E_ASN1_SYNTAX_ERROR    ASN1 parser: Syntax
                                          error.
-77         GNUTLS_E_ASN1_DER_OVERFLOW    ASN1 parser: Overflow in
                                          DER parsing.
-78         GNUTLS_E_TOO_MANY_EMPTY_PACKETSToo many empty record
                                          packets have been
                                          received.
-79         GNUTLS_E_OPENPGP_UID_REVOKED  The OpenPGP User ID is
                                          revoked.
-80         GNUTLS_E_UNKNOWN_PK_ALGORITHM An unknown public key
                                          algorithm was
                                          encountered.
-81         GNUTLS_E_TOO_MANY_HANDSHAKE_PACKETSToo many handshake
                                          packets have been
                                          received.
-82         GNUTLS_E_RECEIVED_DISALLOWED_NAMEA disallowed SNI server
                                          name has been received.
-84         GNUTLS_E_NO_TEMPORARY_RSA_PARAMSNo temporary RSA
                                          parameters were found.
-86         GNUTLS_E_NO_COMPRESSION_ALGORITHMSNo supported compression
                                          algorithms have been
                                          found.
-87         GNUTLS_E_NO_CIPHER_SUITES     No supported cipher
                                          suites have been found.
-88         GNUTLS_E_OPENPGP_GETKEY_FAILEDCould not get OpenPGP
                                          key.
-89         GNUTLS_E_PK_SIG_VERIFY_FAILED Public key signature
                                          verification has failed.
-90         GNUTLS_E_ILLEGAL_SRP_USERNAME The SRP username supplied
                                          is illegal.
-91         GNUTLS_E_SRP_PWD_PARSING_ERRORParsing error in
                                          password/key file.
-93         GNUTLS_E_NO_TEMPORARY_DH_PARAMSNo temporary DH
                                          parameters were found.
-94         GNUTLS_E_OPENPGP_FINGERPRINT_UNSUPPORTEDThe OpenPGP fingerprint
                                          is not supported.
-95         GNUTLS_E_X509_UNSUPPORTED_ATTRIBUTEThe certificate has
                                          unsupported attributes.
-96         GNUTLS_E_UNKNOWN_HASH_ALGORITHMThe hash algorithm is
                                          unknown.
-97         GNUTLS_E_UNKNOWN_PKCS_CONTENT_TYPEThe PKCS structure's
                                          content type is unknown.
-98         GNUTLS_E_UNKNOWN_PKCS_BAG_TYPEThe PKCS structure's bag
                                          type is unknown.
-99         GNUTLS_E_INVALID_PASSWORD     The given password
                                          contains invalid
                                          characters.
-100        GNUTLS_E_MAC_VERIFY_FAILED    The Message
                                          Authentication Code
                                          verification failed.
-101        GNUTLS_E_CONSTRAINT_ERROR     Some constraint limits
                                          were reached.
-104        GNUTLS_E_IA_VERIFY_FAILED     Verifying TLS/IA phase
                                          checksum failed
-105        GNUTLS_E_UNKNOWN_ALGORITHM    The specified algorithm
                                          or protocol is unknown.
-106        GNUTLS_E_UNSUPPORTED_SIGNATURE_ALGORITHMThe signature algorithm
                                          is not supported.
-107        GNUTLS_E_SAFE_RENEGOTIATION_FAILEDSafe renegotiation
                                          failed.
-108        GNUTLS_E_UNSAFE_RENEGOTIATION_DENIEDUnsafe renegotiation
                                          denied.
-109        GNUTLS_E_UNKNOWN_SRP_USERNAME The username supplied is
                                          unknown.
-110        GNUTLS_E_PREMATURE_TERMINATIONThe TLS connection was
                                          non-properly terminated.
-111        GNUTLS_E_MALFORMED_CIDR       CIDR name constraint is
                                          malformed in size or
                                          structure.
-112        GNUTLS_E_CERTIFICATE_REQUIRED Certificate is required.
-201        GNUTLS_E_BASE64_ENCODING_ERRORBase64 encoding error.
-202        GNUTLS_E_INCOMPATIBLE_GCRYPT_LIBRARYThe crypto library
                                          version is too old.
-203        GNUTLS_E_INCOMPATIBLE_LIBTASN1_LIBRARYThe tasn1 library version
                                          is too old.
-204        GNUTLS_E_OPENPGP_KEYRING_ERRORError loading the
                                          keyring.
-205        GNUTLS_E_X509_UNSUPPORTED_OID The OID is not supported.
-206        GNUTLS_E_RANDOM_FAILED        Failed to acquire random
                                          data.
-207        GNUTLS_E_BASE64_UNEXPECTED_HEADER_ERRORBase64 unexpected header
                                          error.
-208        GNUTLS_E_OPENPGP_SUBKEY_ERROR Could not find OpenPGP
                                          subkey.
-209        GNUTLS_E_CRYPTO_ALREADY_REGISTEREDThere is already a crypto
                                          algorithm with lower
                                          priority.
-210        GNUTLS_E_HANDSHAKE_TOO_LARGE  The handshake data size
                                          is too large.
-211        GNUTLS_E_CRYPTODEV_IOCTL_ERRORError interfacing with
                                          /dev/crypto
-212        GNUTLS_E_CRYPTODEV_DEVICE_ERRORError opening /dev/crypto
-213        GNUTLS_E_CHANNEL_BINDING_NOT_AVAILABLEChannel binding data not
                                          available
-214        GNUTLS_E_BAD_COOKIE           The cookie was bad.
-215        GNUTLS_E_OPENPGP_PREFERRED_KEY_ERRORThe OpenPGP key has not a
                                          preferred key set.
-216        GNUTLS_E_INCOMPAT_DSA_KEY_WITH_TLS_PROTOCOLThe given DSA key is
                                          incompatible with the
                                          selected TLS protocol.
-217        GNUTLS_E_INSUFFICIENT_SECURITYOne of the involved
                                          algorithms has
                                          insufficient security
                                          level.
-292        GNUTLS_E_HEARTBEAT_PONG_RECEIVEDA heartbeat pong message
                                          was received.
-293        GNUTLS_E_HEARTBEAT_PING_RECEIVEDA heartbeat ping message
                                          was received.
-294        GNUTLS_E_UNRECOGNIZED_NAME    The SNI host name not
                                          recognised.
-300        GNUTLS_E_PKCS11_ERROR         PKCS #11 error.
-301        GNUTLS_E_PKCS11_LOAD_ERROR    PKCS #11 initialization
                                          error.
-302        GNUTLS_E_PARSING_ERROR        Error in parsing.
-303        GNUTLS_E_PKCS11_PIN_ERROR     Error in provided PIN.
-305        GNUTLS_E_PKCS11_SLOT_ERROR    PKCS #11 error in slot
-306        GNUTLS_E_LOCKING_ERROR        Thread locking error
-307        GNUTLS_E_PKCS11_ATTRIBUTE_ERRORPKCS #11 error in
                                          attribute
-308        GNUTLS_E_PKCS11_DEVICE_ERROR  PKCS #11 error in device
-309        GNUTLS_E_PKCS11_DATA_ERROR    PKCS #11 error in data
-310        GNUTLS_E_PKCS11_UNSUPPORTED_FEATURE_ERRORPKCS #11 unsupported
                                          feature
-311        GNUTLS_E_PKCS11_KEY_ERROR     PKCS #11 error in key
-312        GNUTLS_E_PKCS11_PIN_EXPIRED   PKCS #11 PIN expired
-313        GNUTLS_E_PKCS11_PIN_LOCKED    PKCS #11 PIN locked
-314        GNUTLS_E_PKCS11_SESSION_ERROR PKCS #11 error in session
-315        GNUTLS_E_PKCS11_SIGNATURE_ERRORPKCS #11 error in
                                          signature
-316        GNUTLS_E_PKCS11_TOKEN_ERROR   PKCS #11 error in token
-317        GNUTLS_E_PKCS11_USER_ERROR    PKCS #11 user error
-318        GNUTLS_E_CRYPTO_INIT_FAILED   The initialization of
                                          crypto backend has
                                          failed.
-319        GNUTLS_E_TIMEDOUT             The operation timed out
-320        GNUTLS_E_USER_ERROR           The operation was
                                          cancelled due to user
                                          error
-321        GNUTLS_E_ECC_NO_SUPPORTED_CURVESNo supported ECC curves
                                          were found
-322        GNUTLS_E_ECC_UNSUPPORTED_CURVEThe curve is unsupported
-323        GNUTLS_E_PKCS11_REQUESTED_OBJECT_NOT_AVAILBLEThe requested PKCS #11
                                          object is not available
-324        GNUTLS_E_CERTIFICATE_LIST_UNSORTEDThe provided X.509
                                          certificate list is not
                                          sorted (in subject to
                                          issuer order)
-325        GNUTLS_E_ILLEGAL_PARAMETER    An illegal parameter was
                                          found.
-326        GNUTLS_E_NO_PRIORITIES_WERE_SETNo or insufficient
                                          priorities were set.
-327        GNUTLS_E_X509_UNSUPPORTED_EXTENSIONUnsupported extension in
                                          X.509 certificate.
-328        GNUTLS_E_SESSION_EOF          Peer has terminated the
                                          connection
-329        GNUTLS_E_TPM_ERROR            TPM error.
-330        GNUTLS_E_TPM_KEY_PASSWORD_ERRORError in provided
                                          password for key to be
                                          loaded in TPM.
-331        GNUTLS_E_TPM_SRK_PASSWORD_ERRORError in provided SRK
                                          password for TPM.
-332        GNUTLS_E_TPM_SESSION_ERROR    Cannot initialize a
                                          session with the TPM.
-333        GNUTLS_E_TPM_KEY_NOT_FOUND    TPM key was not found in
                                          persistent storage.
-334        GNUTLS_E_TPM_UNINITIALIZED    TPM is not initialized.
-335        GNUTLS_E_TPM_NO_LIB           The TPM library
                                          (trousers) cannot be
                                          found.
-340        GNUTLS_E_NO_CERTIFICATE_STATUSThere is no certificate
                                          status (OCSP).
-341        GNUTLS_E_OCSP_RESPONSE_ERROR  The OCSP response is
                                          invalid
-342        GNUTLS_E_RANDOM_DEVICE_ERROR  Error in the system's
                                          randomness device.
-343        GNUTLS_E_AUTH_ERROR           Could not authenticate
                                          peer.
-344        GNUTLS_E_NO_APPLICATION_PROTOCOLNo common application
                                          protocol could be
                                          negotiated.
-345        GNUTLS_E_SOCKETS_INIT_ERROR   Error in sockets
                                          initialization.
-346        GNUTLS_E_KEY_IMPORT_FAILED    Failed to import the key
                                          into store.
-347        GNUTLS_E_INAPPROPRIATE_FALLBACKA connection with
                                          inappropriate fallback
                                          was attempted.
-348        GNUTLS_E_CERTIFICATE_VERIFICATION_ERRORError in the certificate
                                          verification.
-349        GNUTLS_E_PRIVKEY_VERIFICATION_ERRORError in the private key
                                          verification; seed
                                          doesn't match.
-350        GNUTLS_E_UNEXPECTED_EXTENSIONS_LENGTHInvalid TLS extensions
                                          length field.
-351        GNUTLS_E_ASN1_EMBEDDED_NULL_IN_STRINGThe provided string has
                                          an embedded null.
-400        GNUTLS_E_SELF_TEST_ERROR      Error while performing
                                          self checks.
-401        GNUTLS_E_NO_SELF_TEST         There is no self test for
                                          this algorithm.
-402        GNUTLS_E_LIB_IN_ERROR_STATE   An error has been
                                          detected in the library
                                          and cannot continue
                                          operations.
-403        GNUTLS_E_PK_GENERATION_ERROR  Error in public key
                                          generation.
-404        GNUTLS_E_IDNA_ERROR           There was an issue
                                          converting to or from
                                          UTF8.
-406        GNUTLS_E_SESSION_USER_ID_CHANGEDPeer's certificate or
                                          username has changed
                                          during a rehandshake.
-407        GNUTLS_E_HANDSHAKE_DURING_FALSE_STARTAttempted handshake
                                          during false start.
-408        GNUTLS_E_UNAVAILABLE_DURING_HANDSHAKECannot perform this
                                          action while handshake is
                                          in progress.
-409        GNUTLS_E_PK_INVALID_PUBKEY    The public key is
                                          invalid.
-410        GNUTLS_E_PK_INVALID_PRIVKEY   The private key is
                                          invalid.
-411        GNUTLS_E_NOT_YET_ACTIVATED    The certificate is not
                                          yet activated.
-412        GNUTLS_E_INVALID_UTF8_STRING  The given string contains
                                          invalid UTF-8 characters.
-413        GNUTLS_E_NO_EMBEDDED_DATA     There are no embedded
                                          data in the structure.
-414        GNUTLS_E_INVALID_UTF8_EMAIL   The given email string
                                          contains non-ASCII
                                          characters before '.'
-415        GNUTLS_E_INVALID_PASSWORD_STRINGThe given password
                                          contains invalid
                                          characters.
-416        GNUTLS_E_CERTIFICATE_TIME_ERRORError in the time fields
                                          of certificate.
-417        GNUTLS_E_RECORD_OVERFLOW      A TLS record packet with
                                          invalid length was
                                          received.
-418        GNUTLS_E_ASN1_TIME_ERROR      The DER time encoding is
                                          invalid.
-419        GNUTLS_E_INCOMPATIBLE_SIG_WITH_KEYThe signature is
                                          incompatible with the
                                          public key.
-420        GNUTLS_E_PK_INVALID_PUBKEY_PARAMSThe public key parameters
                                          are invalid.
-421        GNUTLS_E_PK_NO_VALIDATION_PARAMSThere are no validation
                                          parameters present.
-422        GNUTLS_E_OCSP_MISMATCH_WITH_CERTSThe OCSP response
                                          provided doesn't match
                                          the available
                                          certificates
-423        GNUTLS_E_NO_COMMON_KEY_SHARE  No common key share with
                                          peer.
-424        GNUTLS_E_REAUTH_REQUEST       Re-authentication was
                                          requested by the peer.
-425        GNUTLS_E_TOO_MANY_MATCHES     More than a single object
                                          matches the criteria.
-426        GNUTLS_E_CRL_VERIFICATION_ERRORError in the CRL
                                          verification.
-427        GNUTLS_E_MISSING_EXTENSION    An required TLS extension
                                          was received.
-428        GNUTLS_E_DB_ENTRY_EXISTS      The Database entry
                                          already exists.
-429        GNUTLS_E_EARLY_DATA_REJECTED  The early data were
                                          rejected.

Appendix D Supported Ciphersuites
*********************************

Ciphersuites
============

Ciphersuite name                            TLS ID         Since
--------------------------------------------------------------------------
TLS_AES_128_GCM_SHA256                      0x13 0x01      TLS1.3
TLS_AES_256_GCM_SHA384                      0x13 0x02      TLS1.3
TLS_CHACHA20_POLY1305_SHA256                0x13 0x03      TLS1.3
TLS_AES_128_CCM_SHA256                      0x13 0x04      TLS1.3
TLS_AES_128_CCM_8_SHA256                    0x13 0x05      TLS1.3
TLS_RSA_NULL_MD5                            0x00 0x01      TLS1.0
TLS_RSA_NULL_SHA1                           0x00 0x02      TLS1.0
TLS_RSA_NULL_SHA256                         0x00 0x3B      TLS1.2
TLS_RSA_ARCFOUR_128_SHA1                    0x00 0x05      TLS1.0
TLS_RSA_ARCFOUR_128_MD5                     0x00 0x04      TLS1.0
TLS_RSA_3DES_EDE_CBC_SHA1                   0x00 0x0A      TLS1.0
TLS_RSA_AES_128_CBC_SHA1                    0x00 0x2F      TLS1.0
TLS_RSA_AES_256_CBC_SHA1                    0x00 0x35      TLS1.0
TLS_RSA_CAMELLIA_128_CBC_SHA256             0x00 0xBA      TLS1.2
TLS_RSA_CAMELLIA_256_CBC_SHA256             0x00 0xC0      TLS1.2
TLS_RSA_CAMELLIA_128_CBC_SHA1               0x00 0x41      TLS1.0
TLS_RSA_CAMELLIA_256_CBC_SHA1               0x00 0x84      TLS1.0
TLS_RSA_AES_128_CBC_SHA256                  0x00 0x3C      TLS1.2
TLS_RSA_AES_256_CBC_SHA256                  0x00 0x3D      TLS1.2
TLS_RSA_AES_128_GCM_SHA256                  0x00 0x9C      TLS1.2
TLS_RSA_AES_256_GCM_SHA384                  0x00 0x9D      TLS1.2
TLS_RSA_CAMELLIA_128_GCM_SHA256             0xC0 0x7A      TLS1.2
TLS_RSA_CAMELLIA_256_GCM_SHA384             0xC0 0x7B      TLS1.2
TLS_RSA_AES_128_CCM                         0xC0 0x9C      TLS1.2
TLS_RSA_AES_256_CCM                         0xC0 0x9D      TLS1.2
TLS_RSA_AES_128_CCM_8                       0xC0 0xA0      TLS1.2
TLS_RSA_AES_256_CCM_8                       0xC0 0xA1      TLS1.2
TLS_DHE_DSS_ARCFOUR_128_SHA1                0x00 0x66      TLS1.0
TLS_DHE_DSS_3DES_EDE_CBC_SHA1               0x00 0x13      TLS1.0
TLS_DHE_DSS_AES_128_CBC_SHA1                0x00 0x32      TLS1.0
TLS_DHE_DSS_AES_256_CBC_SHA1                0x00 0x38      TLS1.0
TLS_DHE_DSS_CAMELLIA_128_CBC_SHA256         0x00 0xBD      TLS1.2
TLS_DHE_DSS_CAMELLIA_256_CBC_SHA256         0x00 0xC3      TLS1.2
TLS_DHE_DSS_CAMELLIA_128_CBC_SHA1           0x00 0x44      TLS1.0
TLS_DHE_DSS_CAMELLIA_256_CBC_SHA1           0x00 0x87      TLS1.0
TLS_DHE_DSS_AES_128_CBC_SHA256              0x00 0x40      TLS1.2
TLS_DHE_DSS_AES_256_CBC_SHA256              0x00 0x6A      TLS1.2
TLS_DHE_DSS_AES_128_GCM_SHA256              0x00 0xA2      TLS1.2
TLS_DHE_DSS_AES_256_GCM_SHA384              0x00 0xA3      TLS1.2
TLS_DHE_DSS_CAMELLIA_128_GCM_SHA256         0xC0 0x80      TLS1.2
TLS_DHE_DSS_CAMELLIA_256_GCM_SHA384         0xC0 0x81      TLS1.2
TLS_DHE_RSA_3DES_EDE_CBC_SHA1               0x00 0x16      TLS1.0
TLS_DHE_RSA_AES_128_CBC_SHA1                0x00 0x33      TLS1.0
TLS_DHE_RSA_AES_256_CBC_SHA1                0x00 0x39      TLS1.0
TLS_DHE_RSA_CAMELLIA_128_CBC_SHA256         0x00 0xBE      TLS1.2
TLS_DHE_RSA_CAMELLIA_256_CBC_SHA256         0x00 0xC4      TLS1.2
TLS_DHE_RSA_CAMELLIA_128_CBC_SHA1           0x00 0x45      TLS1.0
TLS_DHE_RSA_CAMELLIA_256_CBC_SHA1           0x00 0x88      TLS1.0
TLS_DHE_RSA_AES_128_CBC_SHA256              0x00 0x67      TLS1.2
TLS_DHE_RSA_AES_256_CBC_SHA256              0x00 0x6B      TLS1.2
TLS_DHE_RSA_AES_128_GCM_SHA256              0x00 0x9E      TLS1.2
TLS_DHE_RSA_AES_256_GCM_SHA384              0x00 0x9F      TLS1.2
TLS_DHE_RSA_CAMELLIA_128_GCM_SHA256         0xC0 0x7C      TLS1.2
TLS_DHE_RSA_CAMELLIA_256_GCM_SHA384         0xC0 0x7D      TLS1.2
TLS_DHE_RSA_CHACHA20_POLY1305               0xCC 0xAA      TLS1.2
TLS_DHE_RSA_AES_128_CCM                     0xC0 0x9E      TLS1.2
TLS_DHE_RSA_AES_256_CCM                     0xC0 0x9F      TLS1.2
TLS_DHE_RSA_AES_128_CCM_8                   0xC0 0xA2      TLS1.2
TLS_DHE_RSA_AES_256_CCM_8                   0xC0 0xA3      TLS1.2
TLS_ECDHE_RSA_NULL_SHA1                     0xC0 0x10      TLS1.0
TLS_ECDHE_RSA_3DES_EDE_CBC_SHA1             0xC0 0x12      TLS1.0
TLS_ECDHE_RSA_AES_128_CBC_SHA1              0xC0 0x13      TLS1.0
TLS_ECDHE_RSA_AES_256_CBC_SHA1              0xC0 0x14      TLS1.0
TLS_ECDHE_RSA_AES_256_CBC_SHA384            0xC0 0x28      TLS1.2
TLS_ECDHE_RSA_ARCFOUR_128_SHA1              0xC0 0x11      TLS1.0
TLS_ECDHE_RSA_CAMELLIA_128_CBC_SHA256       0xC0 0x76      TLS1.2
TLS_ECDHE_RSA_CAMELLIA_256_CBC_SHA384       0xC0 0x77      TLS1.2
TLS_ECDHE_ECDSA_NULL_SHA1                   0xC0 0x06      TLS1.0
TLS_ECDHE_ECDSA_3DES_EDE_CBC_SHA1           0xC0 0x08      TLS1.0
TLS_ECDHE_ECDSA_AES_128_CBC_SHA1            0xC0 0x09      TLS1.0
TLS_ECDHE_ECDSA_AES_256_CBC_SHA1            0xC0 0x0A      TLS1.0
TLS_ECDHE_ECDSA_ARCFOUR_128_SHA1            0xC0 0x07      TLS1.0
TLS_ECDHE_ECDSA_CAMELLIA_128_CBC_SHA256     0xC0 0x72      TLS1.2
TLS_ECDHE_ECDSA_CAMELLIA_256_CBC_SHA384     0xC0 0x73      TLS1.2
TLS_ECDHE_ECDSA_AES_128_CBC_SHA256          0xC0 0x23      TLS1.2
TLS_ECDHE_RSA_AES_128_CBC_SHA256            0xC0 0x27      TLS1.2
TLS_ECDHE_ECDSA_CAMELLIA_128_GCM_SHA256     0xC0 0x86      TLS1.2
TLS_ECDHE_ECDSA_CAMELLIA_256_GCM_SHA384     0xC0 0x87      TLS1.2
TLS_ECDHE_ECDSA_AES_128_GCM_SHA256          0xC0 0x2B      TLS1.2
TLS_ECDHE_ECDSA_AES_256_GCM_SHA384          0xC0 0x2C      TLS1.2
TLS_ECDHE_RSA_AES_128_GCM_SHA256            0xC0 0x2F      TLS1.2
TLS_ECDHE_RSA_AES_256_GCM_SHA384            0xC0 0x30      TLS1.2
TLS_ECDHE_ECDSA_AES_256_CBC_SHA384          0xC0 0x24      TLS1.2
TLS_ECDHE_RSA_CAMELLIA_128_GCM_SHA256       0xC0 0x8A      TLS1.2
TLS_ECDHE_RSA_CAMELLIA_256_GCM_SHA384       0xC0 0x8B      TLS1.2
TLS_ECDHE_RSA_CHACHA20_POLY1305             0xCC 0xA8      TLS1.2
TLS_ECDHE_ECDSA_CHACHA20_POLY1305           0xCC 0xA9      TLS1.2
TLS_ECDHE_ECDSA_AES_128_CCM                 0xC0 0xAC      TLS1.2
TLS_ECDHE_ECDSA_AES_256_CCM                 0xC0 0xAD      TLS1.2
TLS_ECDHE_ECDSA_AES_128_CCM_8               0xC0 0xAE      TLS1.2
TLS_ECDHE_ECDSA_AES_256_CCM_8               0xC0 0xAF      TLS1.2
TLS_ECDHE_PSK_3DES_EDE_CBC_SHA1             0xC0 0x34      TLS1.0
TLS_ECDHE_PSK_AES_128_CBC_SHA1              0xC0 0x35      TLS1.0
TLS_ECDHE_PSK_AES_256_CBC_SHA1              0xC0 0x36      TLS1.0
TLS_ECDHE_PSK_AES_128_CBC_SHA256            0xC0 0x37      TLS1.2
TLS_ECDHE_PSK_AES_256_CBC_SHA384            0xC0 0x38      TLS1.2
TLS_ECDHE_PSK_ARCFOUR_128_SHA1              0xC0 0x33      TLS1.0
TLS_ECDHE_PSK_NULL_SHA1                     0xC0 0x39      TLS1.0
TLS_ECDHE_PSK_NULL_SHA256                   0xC0 0x3A      TLS1.2
TLS_ECDHE_PSK_NULL_SHA384                   0xC0 0x3B      TLS1.0
TLS_ECDHE_PSK_CAMELLIA_128_CBC_SHA256       0xC0 0x9A      TLS1.2
TLS_ECDHE_PSK_CAMELLIA_256_CBC_SHA384       0xC0 0x9B      TLS1.2
TLS_PSK_ARCFOUR_128_SHA1                    0x00 0x8A      TLS1.0
TLS_PSK_3DES_EDE_CBC_SHA1                   0x00 0x8B      TLS1.0
TLS_PSK_AES_128_CBC_SHA1                    0x00 0x8C      TLS1.0
TLS_PSK_AES_256_CBC_SHA1                    0x00 0x8D      TLS1.0
TLS_PSK_AES_128_CBC_SHA256                  0x00 0xAE      TLS1.2
TLS_PSK_AES_256_GCM_SHA384                  0x00 0xA9      TLS1.2
TLS_PSK_CAMELLIA_128_GCM_SHA256             0xC0 0x8E      TLS1.2
TLS_PSK_CAMELLIA_256_GCM_SHA384             0xC0 0x8F      TLS1.2
TLS_PSK_AES_128_GCM_SHA256                  0x00 0xA8      TLS1.2
TLS_PSK_NULL_SHA1                           0x00 0x2C      TLS1.0
TLS_PSK_NULL_SHA256                         0x00 0xB0      TLS1.2
TLS_PSK_CAMELLIA_128_CBC_SHA256             0xC0 0x94      TLS1.2
TLS_PSK_CAMELLIA_256_CBC_SHA384             0xC0 0x95      TLS1.2
TLS_PSK_AES_256_CBC_SHA384                  0x00 0xAF      TLS1.2
TLS_PSK_NULL_SHA384                         0x00 0xB1      TLS1.2
TLS_RSA_PSK_ARCFOUR_128_SHA1                0x00 0x92      TLS1.0
TLS_RSA_PSK_3DES_EDE_CBC_SHA1               0x00 0x93      TLS1.0
TLS_RSA_PSK_AES_128_CBC_SHA1                0x00 0x94      TLS1.0
TLS_RSA_PSK_AES_256_CBC_SHA1                0x00 0x95      TLS1.0
TLS_RSA_PSK_CAMELLIA_128_GCM_SHA256         0xC0 0x92      TLS1.2
TLS_RSA_PSK_CAMELLIA_256_GCM_SHA384         0xC0 0x93      TLS1.2
TLS_RSA_PSK_AES_128_GCM_SHA256              0x00 0xAC      TLS1.2
TLS_RSA_PSK_AES_128_CBC_SHA256              0x00 0xB6      TLS1.2
TLS_RSA_PSK_NULL_SHA1                       0x00 0x2E      TLS1.0
TLS_RSA_PSK_NULL_SHA256                     0x00 0xB8      TLS1.2
TLS_RSA_PSK_AES_256_GCM_SHA384              0x00 0xAD      TLS1.2
TLS_RSA_PSK_AES_256_CBC_SHA384              0x00 0xB7      TLS1.2
TLS_RSA_PSK_NULL_SHA384                     0x00 0xB9      TLS1.2
TLS_RSA_PSK_CAMELLIA_128_CBC_SHA256         0xC0 0x98      TLS1.2
TLS_RSA_PSK_CAMELLIA_256_CBC_SHA384         0xC0 0x99      TLS1.2
TLS_DHE_PSK_ARCFOUR_128_SHA1                0x00 0x8E      TLS1.0
TLS_DHE_PSK_3DES_EDE_CBC_SHA1               0x00 0x8F      TLS1.0
TLS_DHE_PSK_AES_128_CBC_SHA1                0x00 0x90      TLS1.0
TLS_DHE_PSK_AES_256_CBC_SHA1                0x00 0x91      TLS1.0
TLS_DHE_PSK_AES_128_CBC_SHA256              0x00 0xB2      TLS1.2
TLS_DHE_PSK_AES_128_GCM_SHA256              0x00 0xAA      TLS1.2
TLS_DHE_PSK_NULL_SHA1                       0x00 0x2D      TLS1.0
TLS_DHE_PSK_NULL_SHA256                     0x00 0xB4      TLS1.2
TLS_DHE_PSK_NULL_SHA384                     0x00 0xB5      TLS1.2
TLS_DHE_PSK_AES_256_CBC_SHA384              0x00 0xB3      TLS1.2
TLS_DHE_PSK_AES_256_GCM_SHA384              0x00 0xAB      TLS1.2
TLS_DHE_PSK_CAMELLIA_128_CBC_SHA256         0xC0 0x96      TLS1.2
TLS_DHE_PSK_CAMELLIA_256_CBC_SHA384         0xC0 0x97      TLS1.2
TLS_DHE_PSK_CAMELLIA_128_GCM_SHA256         0xC0 0x90      TLS1.2
TLS_DHE_PSK_CAMELLIA_256_GCM_SHA384         0xC0 0x91      TLS1.2
TLS_PSK_AES_128_CCM                         0xC0 0xA4      TLS1.2
TLS_PSK_AES_256_CCM                         0xC0 0xA5      TLS1.2
TLS_DHE_PSK_AES_128_CCM                     0xC0 0xA6      TLS1.2
TLS_DHE_PSK_AES_256_CCM                     0xC0 0xA7      TLS1.2
TLS_PSK_AES_128_CCM_8                       0xC0 0xA8      TLS1.2
TLS_PSK_AES_256_CCM_8                       0xC0 0xA9      TLS1.2
TLS_DHE_PSK_AES_128_CCM_8                   0xC0 0xAA      TLS1.2
TLS_DHE_PSK_AES_256_CCM_8                   0xC0 0xAB      TLS1.2
TLS_DHE_PSK_CHACHA20_POLY1305               0xCC 0xAD      TLS1.2
TLS_ECDHE_PSK_CHACHA20_POLY1305             0xCC 0xAC      TLS1.2
TLS_RSA_PSK_CHACHA20_POLY1305               0xCC 0xAE      TLS1.2
TLS_PSK_CHACHA20_POLY1305                   0xCC 0xAB      TLS1.2
TLS_DH_ANON_ARCFOUR_128_MD5                 0x00 0x18      TLS1.0
TLS_DH_ANON_3DES_EDE_CBC_SHA1               0x00 0x1B      TLS1.0
TLS_DH_ANON_AES_128_CBC_SHA1                0x00 0x34      TLS1.0
TLS_DH_ANON_AES_256_CBC_SHA1                0x00 0x3A      TLS1.0
TLS_DH_ANON_CAMELLIA_128_CBC_SHA256         0x00 0xBF      TLS1.2
TLS_DH_ANON_CAMELLIA_256_CBC_SHA256         0x00 0xC5      TLS1.2
TLS_DH_ANON_CAMELLIA_128_CBC_SHA1           0x00 0x46      TLS1.0
TLS_DH_ANON_CAMELLIA_256_CBC_SHA1           0x00 0x89      TLS1.0
TLS_DH_ANON_AES_128_CBC_SHA256              0x00 0x6C      TLS1.2
TLS_DH_ANON_AES_256_CBC_SHA256              0x00 0x6D      TLS1.2
TLS_DH_ANON_AES_128_GCM_SHA256              0x00 0xA6      TLS1.2
TLS_DH_ANON_AES_256_GCM_SHA384              0x00 0xA7      TLS1.2
TLS_DH_ANON_CAMELLIA_128_GCM_SHA256         0xC0 0x84      TLS1.2
TLS_DH_ANON_CAMELLIA_256_GCM_SHA384         0xC0 0x85      TLS1.2
TLS_ECDH_ANON_NULL_SHA1                     0xC0 0x15      TLS1.0
TLS_ECDH_ANON_3DES_EDE_CBC_SHA1             0xC0 0x17      TLS1.0
TLS_ECDH_ANON_AES_128_CBC_SHA1              0xC0 0x18      TLS1.0
TLS_ECDH_ANON_AES_256_CBC_SHA1              0xC0 0x19      TLS1.0
TLS_ECDH_ANON_ARCFOUR_128_SHA1              0xC0 0x16      TLS1.0
TLS_SRP_SHA_3DES_EDE_CBC_SHA1               0xC0 0x1A      TLS1.0
TLS_SRP_SHA_AES_128_CBC_SHA1                0xC0 0x1D      TLS1.0
TLS_SRP_SHA_AES_256_CBC_SHA1                0xC0 0x20      TLS1.0
TLS_SRP_SHA_DSS_3DES_EDE_CBC_SHA1           0xC0 0x1C      TLS1.0
TLS_SRP_SHA_RSA_3DES_EDE_CBC_SHA1           0xC0 0x1B      TLS1.0
TLS_SRP_SHA_DSS_AES_128_CBC_SHA1            0xC0 0x1F      TLS1.0
TLS_SRP_SHA_RSA_AES_128_CBC_SHA1            0xC0 0x1E      TLS1.0
TLS_SRP_SHA_DSS_AES_256_CBC_SHA1            0xC0 0x22      TLS1.0
TLS_SRP_SHA_RSA_AES_256_CBC_SHA1            0xC0 0x21      TLS1.0

Certificate types
=================

'X.509'
'Raw Public Key'

Protocols
=========

'SSL3.0'
'TLS1.0'
'TLS1.1'
'TLS1.2'
'TLS1.3'
'DTLS0.9'
'DTLS1.0'
'DTLS1.2'

Ciphers
=======

'AES-256-CBC'
'AES-192-CBC'
'AES-128-CBC'
'AES-128-GCM'
'AES-256-GCM'
'AES-128-CCM'
'AES-256-CCM'
'AES-128-CCM-8'
'AES-256-CCM-8'
'ARCFOUR-128'
'ESTREAM-SALSA20-256'
'SALSA20-256'
'CAMELLIA-256-CBC'
'CAMELLIA-192-CBC'
'CAMELLIA-128-CBC'
'CHACHA20-POLY1305'
'CAMELLIA-128-GCM'
'CAMELLIA-256-GCM'
'GOST28147-TC26Z-CFB'
'GOST28147-CPA-CFB'
'GOST28147-CPB-CFB'
'GOST28147-CPC-CFB'
'GOST28147-CPD-CFB'
'AES-128-CFB8'
'AES-192-CFB8'
'AES-256-CFB8'
'3DES-CBC'
'DES-CBC'
'RC2-40'
'NULL'

MAC algorithms
==============

'SHA1'
'SHA256'
'SHA384'
'SHA512'
'SHA224'
'UMAC-96'
'UMAC-128'
'AEAD'
'MD5'
'GOSTR341194'
'STREEBOG-256'
'STREEBOG-512'

Key exchange methods
====================

'ECDHE-RSA'
'ECDHE-ECDSA'
'RSA'
'DHE-RSA'
'DHE-DSS'
'PSK'
'RSA-PSK'
'DHE-PSK'
'ECDHE-PSK'
'SRP-DSS'
'SRP-RSA'
'SRP'
'ANON-DH'
'ANON-ECDH'
'RSA-EXPORT'

Public key algorithms
=====================

'RSA'
'RSA-PSS'
'RSA'
'DSA'
'GOST R 34.10-2012-512'
'GOST R 34.10-2012-256'
'GOST R 34.10-2001'
'EC/ECDSA'
'EdDSA (Ed25519)'
'DH'
'ECDH (X25519)'

Public key signature algorithms
===============================

'RSA-SHA256'
'RSA-SHA384'
'RSA-SHA512'
'RSA-PSS-SHA256'
'RSA-PSS-RSAE-SHA256'
'RSA-PSS-SHA384'
'RSA-PSS-RSAE-SHA384'
'RSA-PSS-SHA512'
'RSA-PSS-RSAE-SHA512'
'EdDSA-Ed25519'
'ECDSA-SHA256'
'ECDSA-SHA384'
'ECDSA-SHA512'
'ECDSA-SECP256R1-SHA256'
'ECDSA-SECP384R1-SHA384'
'ECDSA-SECP521R1-SHA512'
'ECDSA-SHA3-224'
'ECDSA-SHA3-256'
'ECDSA-SHA3-384'
'ECDSA-SHA3-512'
'RSA-SHA3-224'
'RSA-SHA3-256'
'RSA-SHA3-384'
'RSA-SHA3-512'
'DSA-SHA3-224'
'DSA-SHA3-256'
'DSA-SHA3-384'
'DSA-SHA3-512'
'RSA-RAW'
'RSA-SHA1'
'RSA-SHA1'
'RSA-SHA224'
'RSA-RMD160'
'DSA-SHA1'
'DSA-SHA1'
'DSA-SHA224'
'DSA-SHA256'
'RSA-MD5'
'RSA-MD5'
'RSA-MD2'
'ECDSA-SHA1'
'ECDSA-SHA224'
'GOSTR341012-512'
'GOSTR341012-256'
'GOSTR341001'
'DSA-SHA384'
'DSA-SHA512'

Groups
======

'SECP192R1'
'SECP224R1'
'SECP256R1'
'SECP384R1'
'SECP521R1'
'X25519'
'FFDHE2048'
'FFDHE3072'
'FFDHE4096'
'FFDHE6144'
'FFDHE8192'

Appendix E API reference
************************

E.1 Core TLS API
================

The prototypes for the following functions lie in 'gnutls/gnutls.h'.

gnutls_alert_get
----------------

 -- 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.

gnutls_alert_get_name
---------------------

 -- 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.

gnutls_alert_get_strname
------------------------

 -- Function: const char * gnutls_alert_get_strname
          (gnutls_alert_description_t ALERT)
     ALERT: is an alert number.

     This function will return a string of the name of the alert.

     *Returns:* string corresponding to 'gnutls_alert_description_t'
     value.

     *Since:* 3.0

gnutls_alert_send
-----------------

 -- 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.

gnutls_alert_send_appropriate
-----------------------------

 -- Function: int gnutls_alert_send_appropriate (gnutls_session_t
          SESSION, int ERR)
     SESSION: is a 'gnutls_session_t' type.

     ERR: is an error code returned by another GnuTLS function

     Sends an alert to the peer depending on the error code returned by
     a gnutls function.  This function will call
     'gnutls_error_to_alert()' to determine the appropriate alert to
     send.

     This function may also return 'GNUTLS_E_AGAIN' , or
     'GNUTLS_E_INTERRUPTED' .

     This function historically was always sending an alert to the peer,
     even if 'err' was inappropriate to respond with an alert (e.g.,
     'GNUTLS_E_SUCCESS' ).  Since 3.6.6 this function returns success
     without transmitting any data on error codes that should not result
     to an alert.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_alpn_get_selected_protocol
---------------------------------

 -- Function: int gnutls_alpn_get_selected_protocol (gnutls_session_t
          SESSION, gnutls_datum_t * PROTOCOL)
     SESSION: is a 'gnutls_session_t' type.

     PROTOCOL: will hold the protocol name

     This function allows you to get the negotiated protocol name.  The
     returned protocol should be treated as opaque, constant value and
     only valid during the session life.

     The selected protocol is the first supported by the list sent by
     the client.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     Since 3.2.0

gnutls_alpn_set_protocols
-------------------------

 -- Function: int gnutls_alpn_set_protocols (gnutls_session_t SESSION,
          const gnutls_datum_t * PROTOCOLS, unsigned PROTOCOLS_SIZE,
          unsigned int FLAGS)
     SESSION: is a 'gnutls_session_t' type.

     PROTOCOLS: is the protocol names to add.

     PROTOCOLS_SIZE: the number of protocols to add.

     FLAGS: zero or a sequence of 'gnutls_alpn_flags_t'

     This function is to be used by both clients and servers, to declare
     the supported ALPN protocols, which are used during negotiation
     with peer.

     See 'gnutls_alpn_flags_t' description for the documentation of
     available flags.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     Since 3.2.0

gnutls_anon_allocate_client_credentials
---------------------------------------

 -- Function: int gnutls_anon_allocate_client_credentials
          (gnutls_anon_client_credentials_t * SC)
     SC: is a pointer to a 'gnutls_anon_client_credentials_t' type.

     Allocate a gnutls_anon_client_credentials_t structure.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

gnutls_anon_allocate_server_credentials
---------------------------------------

 -- Function: int gnutls_anon_allocate_server_credentials
          (gnutls_anon_server_credentials_t * SC)
     SC: is a pointer to a 'gnutls_anon_server_credentials_t' type.

     Allocate a gnutls_anon_server_credentials_t structure.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

gnutls_anon_free_client_credentials
-----------------------------------

 -- Function: void gnutls_anon_free_client_credentials
          (gnutls_anon_client_credentials_t SC)
     SC: is a 'gnutls_anon_client_credentials_t' type.

     Free a gnutls_anon_client_credentials_t structure.

gnutls_anon_free_server_credentials
-----------------------------------

 -- Function: void gnutls_anon_free_server_credentials
          (gnutls_anon_server_credentials_t SC)
     SC: is a 'gnutls_anon_server_credentials_t' type.

     Free a gnutls_anon_server_credentials_t structure.

gnutls_anon_set_params_function
-------------------------------

 -- Function: void gnutls_anon_set_params_function
          (gnutls_anon_server_credentials_t RES, gnutls_params_function
          * FUNC)
     RES: is a gnutls_anon_server_credentials_t type

     FUNC: is the function to be called

     This function will set a callback in order for the server to get
     the Diffie-Hellman or RSA parameters for anonymous authentication.
     The callback should return 'GNUTLS_E_SUCCESS' (0) on success.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

gnutls_anon_set_server_dh_params
--------------------------------

 -- Function: void gnutls_anon_set_server_dh_params
          (gnutls_anon_server_credentials_t RES, gnutls_dh_params_t
          DH_PARAMS)
     RES: is a gnutls_anon_server_credentials_t type

     DH_PARAMS: The Diffie-Hellman parameters.

     This function will set the Diffie-Hellman parameters for an
     anonymous server to use.  These parameters will be used in
     Anonymous Diffie-Hellman cipher suites.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

gnutls_anon_set_server_known_dh_params
--------------------------------------

 -- Function: int gnutls_anon_set_server_known_dh_params
          (gnutls_anon_server_credentials_t RES, gnutls_sec_param_t
          SEC_PARAM)
     RES: is a gnutls_anon_server_credentials_t type

     SEC_PARAM: is an option of the 'gnutls_sec_param_t' enumeration

     This function will set the Diffie-Hellman parameters for an
     anonymous server to use.  These parameters will be used in
     Anonymous Diffie-Hellman cipher suites and will be selected from
     the FFDHE set of RFC7919 according to the security level provided.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

     *Since:* 3.5.6

gnutls_anon_set_server_params_function
--------------------------------------

 -- Function: void gnutls_anon_set_server_params_function
          (gnutls_anon_server_credentials_t RES, gnutls_params_function
          * FUNC)
     RES: is a gnutls_certificate_credentials_t type

     FUNC: is the function to be called

     This function will set a callback in order for the server to get
     the Diffie-Hellman parameters for anonymous authentication.  The
     callback should return 'GNUTLS_E_SUCCESS' (0) on success.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

gnutls_anti_replay_deinit
-------------------------

 -- Function: void gnutls_anti_replay_deinit (gnutls_anti_replay_t
          ANTI_REPLAY)
     ANTI_REPLAY: is a 'gnutls_anti_replay' type

     This function will deinitialize all resources occupied by the given
     anti-replay context.

     *Since:* 3.6.5

gnutls_anti_replay_enable
-------------------------

 -- Function: void gnutls_anti_replay_enable (gnutls_session_t SESSION,
          gnutls_anti_replay_t ANTI_REPLAY)
     SESSION: is a 'gnutls_session_t' type.

     ANTI_REPLAY: is a 'gnutls_anti_replay_t' type.

     Request that the server should use anti-replay mechanism.

     *Since:* 3.6.5

gnutls_anti_replay_init
-----------------------

 -- Function: int gnutls_anti_replay_init (gnutls_anti_replay_t *
          ANTI_REPLAY)
     ANTI_REPLAY: is a pointer to 'gnutls_anti_replay_t' type

     This function will allocate and initialize the 'anti_replay'
     context to be usable for detect replay attacks.  The context can
     then be attached to a 'gnutls_session_t' with
     'gnutls_anti_replay_enable()' .

     *Returns:* Zero or a negative error code on error.

     *Since:* 3.6.5

gnutls_anti_replay_set_add_function
-----------------------------------

 -- Function: void gnutls_anti_replay_set_add_function
          (gnutls_anti_replay_t ANTI_REPLAY, gnutls_db_add_func
          ADD_FUNC)
     ANTI_REPLAY: is a 'gnutls_anti_replay_t' type.

     ADD_FUNC: is the function.

     Sets the function that will be used to store an entry if it is not
     already present in the resumed sessions database.  This function
     returns 0 if the entry is successfully stored, and a negative error
     code otherwise.  In particular, if the entry is found in the
     database, it returns 'GNUTLS_E_DB_ENTRY_EXISTS' .

     The arguments to the 'add_func' are: - 'ptr' : the pointer set with
     'gnutls_anti_replay_set_ptr()' - 'exp_time' : the expiration time
     of the entry - 'key' : a pointer to the key - 'data' : a pointer to
     data to store

     The data set by this function can be examined using
     'gnutls_db_check_entry_expire_time()' and
     'gnutls_db_check_entry_time()' .

     *Since:* 3.6.5

gnutls_anti_replay_set_ptr
--------------------------

 -- Function: void gnutls_anti_replay_set_ptr (gnutls_anti_replay_t
          ANTI_REPLAY, void * PTR)
     ANTI_REPLAY: is a 'gnutls_anti_replay_t' type.

     PTR: is the pointer

     Sets the pointer that will be provided to db add function as the
     first argument.

gnutls_anti_replay_set_window
-----------------------------

 -- Function: void gnutls_anti_replay_set_window (gnutls_anti_replay_t
          ANTI_REPLAY, unsigned int WINDOW)
     ANTI_REPLAY: is a 'gnutls_anti_replay_t' type.

     WINDOW: is the time window recording ClientHello, in milliseconds

     Sets the time window used for ClientHello recording.  In order to
     protect against replay attacks, the server records ClientHello
     messages within this time period from the last update, and
     considers it a replay when a ClientHello outside of the period; if
     a ClientHello arrives within this period, the server checks the
     database and detects duplicates.

     For the details of the algorithm, see RFC 8446, section 8.2.

     *Since:* 3.6.5

gnutls_auth_client_get_type
---------------------------

 -- Function: gnutls_credentials_type_t gnutls_auth_client_get_type
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Returns the type of credentials that were used for client
     authentication.  The returned information is to be used to
     distinguish the function used to access authentication data.

     Note that on resumed sessions, this function returns the schema
     used in the original session authentication.

     *Returns:* The type of credentials for the client authentication
     schema, a 'gnutls_credentials_type_t' type.

gnutls_auth_get_type
--------------------

 -- Function: gnutls_credentials_type_t gnutls_auth_get_type
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Returns type of credentials for the current authentication schema.
     The returned information is to be used to distinguish the function
     used to access authentication data.

     Eg.  for CERTIFICATE ciphersuites (key exchange algorithms:
     'GNUTLS_KX_RSA' , 'GNUTLS_KX_DHE_RSA' ), the same function are to
     be used to access the authentication data.

     Note that on resumed sessions, this function returns the schema
     used in the original session authentication.

     *Returns:* The type of credentials for the current authentication
     schema, a 'gnutls_credentials_type_t' type.

gnutls_auth_server_get_type
---------------------------

 -- Function: gnutls_credentials_type_t gnutls_auth_server_get_type
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Returns the type of credentials that were used for server
     authentication.  The returned information is to be used to
     distinguish the function used to access authentication data.

     Note that on resumed sessions, this function returns the schema
     used in the original session authentication.

     *Returns:* The type of credentials for the server authentication
     schema, a 'gnutls_credentials_type_t' type.

gnutls_base64_decode2
---------------------

 -- Function: int gnutls_base64_decode2 (const gnutls_datum_t * BASE64,
          gnutls_datum_t * RESULT)
     BASE64: contains the encoded data

     RESULT: the location of decoded data

     This function will decode the given base64 encoded data.  The
     decoded data will be allocated, and stored into result.

     You should use 'gnutls_free()' to free the returned data.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

     *Since:* 3.6.0

gnutls_base64_encode2
---------------------

 -- Function: int gnutls_base64_encode2 (const gnutls_datum_t * DATA,
          gnutls_datum_t * RESULT)
     DATA: contains the raw data

     RESULT: will hold the newly allocated encoded data

     This function will convert the given data to printable data, using
     the base64 encoding.  This function will allocate the required
     memory to hold the encoded data.

     You should use 'gnutls_free()' to free the returned data.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

     *Since:* 3.6.0

gnutls_buffer_append_data
-------------------------

 -- Function: int gnutls_buffer_append_data (gnutls_buffer_t DEST, const
          void * DATA, size_t DATA_SIZE)
     DEST: the buffer to append to

     DATA: the data

     DATA_SIZE: the size of 'data'

     Appends the provided 'data' to the destination buffer.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.4.0

gnutls_bye
----------

 -- 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.

gnutls_certificate_activation_time_peers
----------------------------------------

 -- Function: time_t gnutls_certificate_activation_time_peers
          (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     This function will return the peer's certificate activation time.

     *Returns:* (time_t)-1 on error.

     *Deprecated:* 'gnutls_certificate_verify_peers2()' now verifies
     activation times.

gnutls_certificate_allocate_credentials
---------------------------------------

 -- Function: int gnutls_certificate_allocate_credentials
          (gnutls_certificate_credentials_t * RES)
     RES: is a pointer to a 'gnutls_certificate_credentials_t' type.

     Allocate a gnutls_certificate_credentials_t structure.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

gnutls_certificate_client_get_request_status
--------------------------------------------

 -- Function: unsigned gnutls_certificate_client_get_request_status
          (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     Get whether client certificate was requested on the last handshake
     or not.

     *Returns:* 0 if the peer (server) did not request client
     authentication or 1 otherwise.

gnutls_certificate_expiration_time_peers
----------------------------------------

 -- Function: time_t gnutls_certificate_expiration_time_peers
          (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     This function will return the peer's certificate expiration time.

     *Returns:* (time_t)-1 on error.

     *Deprecated:* 'gnutls_certificate_verify_peers2()' now verifies
     expiration times.

gnutls_certificate_free_ca_names
--------------------------------

 -- Function: void gnutls_certificate_free_ca_names
          (gnutls_certificate_credentials_t SC)
     SC: is a 'gnutls_certificate_credentials_t' type.

     This function will delete all the CA name in the given credentials.
     Clients may call this to save some memory since in client side the
     CA names are not used.  Servers might want to use this function if
     a large list of trusted CAs is present and sending the names of it
     would just consume bandwidth without providing information to
     client.

     CA names are used by servers to advertise the CAs they support to
     clients.

gnutls_certificate_free_cas
---------------------------

 -- Function: void gnutls_certificate_free_cas
          (gnutls_certificate_credentials_t SC)
     SC: is a 'gnutls_certificate_credentials_t' type.

     This function was operational on very early versions of gnutls.
     Due to internal refactorings and the fact that this was hardly ever
     used, it is currently a no-op.

gnutls_certificate_free_credentials
-----------------------------------

 -- Function: void gnutls_certificate_free_credentials
          (gnutls_certificate_credentials_t SC)
     SC: is a 'gnutls_certificate_credentials_t' type.

     Free a gnutls_certificate_credentials_t structure.

     This function does not free any temporary parameters associated
     with this structure (ie RSA and DH parameters are not freed by this
     function).

gnutls_certificate_free_crls
----------------------------

 -- Function: void gnutls_certificate_free_crls
          (gnutls_certificate_credentials_t SC)
     SC: is a 'gnutls_certificate_credentials_t' type.

     This function will delete all the CRLs associated with the given
     credentials.

gnutls_certificate_free_keys
----------------------------

 -- Function: void gnutls_certificate_free_keys
          (gnutls_certificate_credentials_t SC)
     SC: is a 'gnutls_certificate_credentials_t' type.

     This function will delete all the keys and the certificates
     associated with the given credentials.  This function must not be
     called when a TLS negotiation that uses the credentials is in
     progress.

gnutls_certificate_get_crt_raw
------------------------------

 -- Function: int gnutls_certificate_get_crt_raw
          (gnutls_certificate_credentials_t SC, unsigned IDX1, unsigned
          IDX2, gnutls_datum_t * CERT)
     SC: is a 'gnutls_certificate_credentials_t' type.

     IDX1: the index of the certificate chain if multiple are present

     IDX2: the index of the certificate in the chain.  Zero gives the
     server's certificate.

     CERT: Will hold the DER encoded certificate.

     This function will return the DER encoded certificate of the server
     or any other certificate on its certificate chain (based on 'idx2'
     ).  The returned data should be treated as constant and only
     accessible during the lifetime of 'sc' .  The 'idx1' matches the
     value 'gnutls_certificate_set_x509_key()' and friends functions.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.  In case the indexes are out of
     bounds 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.

     *Since:* 3.2.5

gnutls_certificate_get_issuer
-----------------------------

 -- Function: int gnutls_certificate_get_issuer
          (gnutls_certificate_credentials_t SC, gnutls_x509_crt_t CERT,
          gnutls_x509_crt_t * ISSUER, unsigned int FLAGS)
     SC: is a 'gnutls_certificate_credentials_t' type.

     CERT: is the certificate to find issuer for

     ISSUER: Will hold the issuer if any.  Should be treated as
     constant.

     FLAGS: Use zero or 'GNUTLS_TL_GET_COPY'

     This function will return the issuer of a given certificate.  If
     the flag 'GNUTLS_TL_GET_COPY' is specified a copy of the issuer
     will be returned which must be freed using
     'gnutls_x509_crt_deinit()' .  In that case the provided 'issuer'
     must not be initialized.

     As with 'gnutls_x509_trust_list_get_issuer()' this function
     requires the 'GNUTLS_TL_GET_COPY' flag in order to operate with
     PKCS'11' trust lists in a thread-safe way.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

     *Since:* 3.0

gnutls_certificate_get_ocsp_expiration
--------------------------------------

 -- Function: time_t gnutls_certificate_get_ocsp_expiration
          (gnutls_certificate_credentials_t SC, unsigned IDX, int OIDX,
          unsigned FLAGS)
     SC: is a credentials structure.

     IDX: is a certificate chain index as returned by
     'gnutls_certificate_set_key()' and friends

     OIDX: is an OCSP response index

     FLAGS: should be zero

     This function returns the validity of the loaded OCSP responses, to
     provide information on when to reload/refresh them.

     Note that the credentials structure should be read-only when in
     use, thus when reloading, either the credentials structure must not
     be in use by any sessions, or a new credentials structure should be
     allocated for new sessions.

     When 'oidx' is (-1) then the minimum refresh time for all responses
     is returned.  Otherwise the index specifies the response
     corresponding to the 'odix' certificate in the certificate chain.

     *Returns:* On success, the expiration time of the OCSP response.
     Otherwise (time_t)(-1) on error, or (time_t)-2 on out of bounds.

     *Since:* 3.6.3

gnutls_certificate_get_ours
---------------------------

 -- Function: const gnutls_datum_t * gnutls_certificate_get_ours
          (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     Gets the certificate as sent to the peer in the last handshake.
     The certificate is in raw (DER) format.  No certificate list is
     being returned.  Only the first certificate.

     This function returns the certificate that was sent in the current
     handshake.  In subsequent resumed sessions this function will
     return 'NULL' .  That differs from 'gnutls_certificate_get_peers()'
     which always returns the peer's certificate used in the original
     session.

     *Returns:* a pointer to a 'gnutls_datum_t' containing our
     certificate, or 'NULL' in case of an error or if no certificate was
     used.

gnutls_certificate_get_peers
----------------------------

 -- Function: const gnutls_datum_t * gnutls_certificate_get_peers
          (gnutls_session_t SESSION, unsigned int * LIST_SIZE)
     SESSION: is a gnutls session

     LIST_SIZE: is the length of the certificate list (may be 'NULL' )

     Get the peer's raw certificate (chain) as sent by the peer.  These
     certificates are in raw format (DER encoded for X.509).  In case of
     a X.509 then a certificate list may be present.  The list is
     provided as sent by the server; the server must send as first
     certificate in the list its own certificate, following the issuer's
     certificate, then the issuer's issuer etc.  However, there are
     servers which violate this principle and thus on certain occasions
     this may be an unsorted list.

     In resumed sessions, this function will return the peer's
     certificate list as used in the first/original session.

     *Returns:* a pointer to a 'gnutls_datum_t' containing the peer's
     certificates, or 'NULL' in case of an error or if no certificate
     was used.

gnutls_certificate_get_peers_subkey_id
--------------------------------------

 -- Function: int gnutls_certificate_get_peers_subkey_id
          (gnutls_session_t SESSION, gnutls_datum_t * ID)
     SESSION: is a gnutls session

     ID: will contain the ID

     This function is no-op.

     *Returns:* 'GNUTLS_E_UNIMPLEMENTED_FEATURE' .

     *Since:* 3.1.3

gnutls_certificate_get_verify_flags
-----------------------------------

 -- Function: unsigned int gnutls_certificate_get_verify_flags
          (gnutls_certificate_credentials_t RES)
     RES: is a gnutls_certificate_credentials_t type

     Returns the verification flags set with
     'gnutls_certificate_set_verify_flags()' .

     *Returns:* The certificate verification flags used by 'res' .

     *Since:* 3.4.0

gnutls_certificate_get_x509_crt
-------------------------------

 -- Function: int gnutls_certificate_get_x509_crt
          (gnutls_certificate_credentials_t RES, unsigned INDEX,
          gnutls_x509_crt_t ** CRT_LIST, unsigned * CRT_LIST_SIZE)
     RES: is a 'gnutls_certificate_credentials_t' type.

     INDEX: The index of the certificate list to obtain.

     CRT_LIST: Where to store the certificate list.

     CRT_LIST_SIZE: Will hold the number of certificates.

     Obtains a X.509 certificate list that has been stored in 'res' with
     one of 'gnutls_certificate_set_x509_key()' ,
     'gnutls_certificate_set_key()' ,
     'gnutls_certificate_set_x509_key_file()' ,
     'gnutls_certificate_set_x509_key_file2()' ,
     'gnutls_certificate_set_x509_key_mem()' , or
     'gnutls_certificate_set_x509_key_mem2()' .  Each certificate in the
     returned certificate list must be deallocated with
     'gnutls_x509_crt_deinit()' , and the list itself must be freed with
     'gnutls_free()' .

     The 'index' matches the return value of
     'gnutls_certificate_set_x509_key()' and friends functions, when the
     'GNUTLS_CERTIFICATE_API_V2' flag is set.

     If there is no certificate with the given index,
     'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.  If the
     certificate with the given index is not a X.509 certificate,
     'GNUTLS_E_INVALID_REQUEST' is returned.  The returned certificates
     must be deinitialized after use, and the 'crt_list' pointer must be
     freed using 'gnutls_free()' .

     *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
     code.

     *Since:* 3.4.0

gnutls_certificate_get_x509_key
-------------------------------

 -- Function: int gnutls_certificate_get_x509_key
          (gnutls_certificate_credentials_t RES, unsigned INDEX,
          gnutls_x509_privkey_t * KEY)
     RES: is a 'gnutls_certificate_credentials_t' type.

     INDEX: The index of the key to obtain.

     KEY: Location to store the key.

     Obtains a X.509 private key that has been stored in 'res' with one
     of 'gnutls_certificate_set_x509_key()' ,
     'gnutls_certificate_set_key()' ,
     'gnutls_certificate_set_x509_key_file()' ,
     'gnutls_certificate_set_x509_key_file2()' ,
     'gnutls_certificate_set_x509_key_mem()' , or
     'gnutls_certificate_set_x509_key_mem2()' .  The returned key must
     be deallocated with 'gnutls_x509_privkey_deinit()' when no longer
     needed.

     The 'index' matches the return value of
     'gnutls_certificate_set_x509_key()' and friends functions, when the
     'GNUTLS_CERTIFICATE_API_V2' flag is set.

     If there is no key with the given index,
     'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.  If the key
     with the given index is not a X.509 key, 'GNUTLS_E_INVALID_REQUEST'
     is returned.

     *Returns:* 'GNUTLS_E_SUCCESS' (0) on success, or a negative error
     code.

     *Since:* 3.4.0

gnutls_certificate_send_x509_rdn_sequence
-----------------------------------------

 -- 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.

gnutls_certificate_server_set_request
-------------------------------------

 -- 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

     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.

gnutls_certificate_set_dh_params
--------------------------------

 -- Function: void gnutls_certificate_set_dh_params
          (gnutls_certificate_credentials_t RES, gnutls_dh_params_t
          DH_PARAMS)
     RES: is a gnutls_certificate_credentials_t type

     DH_PARAMS: the Diffie-Hellman parameters.

     This function will set the Diffie-Hellman parameters for a
     certificate server to use.  These parameters will be used in
     Ephemeral Diffie-Hellman cipher suites.  Note that only a pointer
     to the parameters are stored in the certificate handle, so you must
     not deallocate the parameters before the certificate is
     deallocated.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

gnutls_certificate_set_flags
----------------------------

 -- Function: void gnutls_certificate_set_flags
          (gnutls_certificate_credentials_t RES, unsigned int FLAGS)
     RES: is a gnutls_certificate_credentials_t type

     FLAGS: are the flags of 'gnutls_certificate_flags' type

     This function will set flags to tweak the operation of the
     credentials structure.  See the 'gnutls_certificate_flags'
     enumerations for more information on the available flags.

     *Since:* 3.4.7

gnutls_certificate_set_known_dh_params
--------------------------------------

 -- Function: int gnutls_certificate_set_known_dh_params
          (gnutls_certificate_credentials_t RES, gnutls_sec_param_t
          SEC_PARAM)
     RES: is a gnutls_certificate_credentials_t type

     SEC_PARAM: is an option of the 'gnutls_sec_param_t' enumeration

     This function will set the Diffie-Hellman parameters for a
     certificate server to use.  These parameters will be used in
     Ephemeral Diffie-Hellman cipher suites and will be selected from
     the FFDHE set of RFC7919 according to the security level provided.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

     *Since:* 3.5.6

gnutls_certificate_set_ocsp_status_request_file
-----------------------------------------------

 -- Function: int gnutls_certificate_set_ocsp_status_request_file
          (gnutls_certificate_credentials_t SC, const char *
          RESPONSE_FILE, unsigned IDX)
     SC: is a credentials structure.

     RESPONSE_FILE: a filename of the OCSP response

     IDX: is a certificate index as returned by
     'gnutls_certificate_set_key()' and friends

     This function loads the provided OCSP response.  It will be sent to
     the client if requests an OCSP certificate status for the
     certificate chain specified by 'idx' .

     *Note:* the ability to set multiple OCSP responses per credential
     structure via the index 'idx' was added in version 3.5.6.  To keep
     backwards compatibility, it requires using
     'gnutls_certificate_set_flags()' with the
     'GNUTLS_CERTIFICATE_API_V2' flag to make the set certificate
     functions return an index usable by this function.

     This function can be called multiple times since GnuTLS 3.6.3 when
     multiple responses which apply to the chain are available.  If the
     response provided does not match any certificates present in the
     chain, the code 'GNUTLS_E_OCSP_MISMATCH_WITH_CERTS' is returned.
     To revert to the previous behavior set the flag
     'GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK' in the certificate
     credentials structure.  In that case, only the end-certificate's
     OCSP response can be set.  If the response is already expired at
     the time of loading the code 'GNUTLS_E_EXPIRED' is returned.

     To revert to the previous behavior of this function which does not
     return any errors, set the flag
     'GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK'

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     *Since:* 3.1.3

gnutls_certificate_set_ocsp_status_request_file2
------------------------------------------------

 -- Function: int gnutls_certificate_set_ocsp_status_request_file2
          (gnutls_certificate_credentials_t SC, const char *
          RESPONSE_FILE, unsigned IDX, gnutls_x509_crt_fmt_t FMT)
     SC: is a credentials structure.

     RESPONSE_FILE: a filename of the OCSP response

     IDX: is a certificate index as returned by
     'gnutls_certificate_set_key()' and friends

     FMT: is PEM or DER

     This function loads the OCSP responses to be sent to the peer for
     the certificate chain specified by 'idx' .  When 'fmt' is set to
     PEM, multiple responses can be loaded.

     This function must be called after setting any certificates, and
     cannot be used for certificates that are provided via a callback -
     that is when 'gnutls_certificate_set_retrieve_function()' is used.
     In that case consider using
     'gnutls_certificate_set_retrieve_function3()' .

     This function can be called multiple times when multiple responses
     applicable to the certificate chain are available.  If the response
     provided does not match any certificates present in the chain, the
     code 'GNUTLS_E_OCSP_MISMATCH_WITH_CERTS' is returned.  If the
     response is already expired at the time of loading the code
     'GNUTLS_E_EXPIRED' is returned.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     *Since:* 3.1.3

gnutls_certificate_set_ocsp_status_request_function
---------------------------------------------------

 -- Function: void gnutls_certificate_set_ocsp_status_request_function
          (gnutls_certificate_credentials_t SC,
          gnutls_status_request_ocsp_func OCSP_FUNC, void * PTR)
     SC: is a 'gnutls_certificate_credentials_t' type.

     OCSP_FUNC: function pointer to OCSP status request callback.

     PTR: opaque pointer passed to callback function

     This function is to be used by server to register a callback to
     handle OCSP status requests from the client.  The callback will be
     invoked if the client supplied a status-request OCSP extension.
     The callback function prototype is:

     typedef int (*gnutls_status_request_ocsp_func) (gnutls_session_t
     session, void *ptr, gnutls_datum_t *ocsp_response);

     The callback will be invoked if the client requests an OCSP
     certificate status.  The callback may return
     'GNUTLS_E_NO_CERTIFICATE_STATUS' , if there is no recent OCSP
     response.  If the callback returns 'GNUTLS_E_SUCCESS' , it is
     expected to have the 'ocsp_response' field set with a valid
     (DER-encoded) OCSP response.  The response must be a value
     allocated using 'gnutls_malloc()' , and will be deinitialized by
     the caller.

     It is possible to set a specific callback for each provided
     certificate using
     'gnutls_certificate_set_ocsp_status_request_function2()' .

     *Since:* 3.1.3

gnutls_certificate_set_ocsp_status_request_function2
----------------------------------------------------

 -- Function: int gnutls_certificate_set_ocsp_status_request_function2
          (gnutls_certificate_credentials_t SC, unsigned IDX,
          gnutls_status_request_ocsp_func OCSP_FUNC, void * PTR)
     SC: is a 'gnutls_certificate_credentials_t' type.

     IDX: is a certificate index as returned by
     'gnutls_certificate_set_key()' and friends

     OCSP_FUNC: function pointer to OCSP status request callback.

     PTR: opaque pointer passed to callback function

     This function is to be used by server to register a callback to
     provide OCSP status requests that correspond to the indexed
     certificate chain from the client.  The callback will be invoked if
     the client supplied a status-request OCSP extension.

     The callback function prototype is:

     typedef int (*gnutls_status_request_ocsp_func) (gnutls_session_t
     session, void *ptr, gnutls_datum_t *ocsp_response);

     The callback will be invoked if the client requests an OCSP
     certificate status.  The callback may return
     'GNUTLS_E_NO_CERTIFICATE_STATUS' , if there is no recent OCSP
     response.  If the callback returns 'GNUTLS_E_SUCCESS' , it is
     expected to have the 'ocsp_response' field set with a valid
     (DER-encoded) OCSP response.  The response must be a value
     allocated using 'gnutls_malloc()' , and will be deinitialized by
     the caller.

     *Note:* the ability to set multiple OCSP responses per credential
     structure via the index 'idx' was added in version 3.5.6.  To keep
     backwards compatibility, it requires using
     'gnutls_certificate_set_flags()' with the
     'GNUTLS_CERTIFICATE_API_V2' flag to make the set certificate
     functions return an index usable by this function.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     *Since:* 3.5.5

gnutls_certificate_set_ocsp_status_request_mem
----------------------------------------------

 -- Function: int gnutls_certificate_set_ocsp_status_request_mem
          (gnutls_certificate_credentials_t SC, const gnutls_datum_t *
          RESP_DATA, unsigned IDX, gnutls_x509_crt_fmt_t FMT)
     SC: is a credentials structure.

     RESP_DATA: a memory buffer holding an OCSP response

     IDX: is a certificate index as returned by
     'gnutls_certificate_set_key()' and friends

     FMT: is PEM or DER

     This function sets the OCSP responses to be sent to the peer for
     the certificate chain specified by 'idx' .  When 'fmt' is set to
     PEM, multiple responses can be loaded.

     *Note:* the ability to set multiple OCSP responses per credential
     structure via the index 'idx' was added in version 3.5.6.  To keep
     backwards compatibility, it requires using
     'gnutls_certificate_set_flags()' with the
     'GNUTLS_CERTIFICATE_API_V2' flag to make the set certificate
     functions return an index usable by this function.

     This function must be called after setting any certificates, and
     cannot be used for certificates that are provided via a callback -
     that is when 'gnutls_certificate_set_retrieve_function()' is used.

     This function can be called multiple times when multiple responses
     which apply to the certificate chain are available.  If the
     response provided does not match any certificates present in the
     chain, the code 'GNUTLS_E_OCSP_MISMATCH_WITH_CERTS' is returned.
     If the response is already expired at the time of loading the code
     'GNUTLS_E_EXPIRED' is returned.

     *Returns:* On success, the number of loaded responses is returned,
     otherwise a negative error code.

     *Since:* 3.6.3

gnutls_certificate_set_params_function
--------------------------------------

 -- Function: void gnutls_certificate_set_params_function
          (gnutls_certificate_credentials_t RES, gnutls_params_function
          * FUNC)
     RES: is a gnutls_certificate_credentials_t type

     FUNC: is the function to be called

     This function will set a callback in order for the server to get
     the Diffie-Hellman or RSA parameters for certificate
     authentication.  The callback should return 'GNUTLS_E_SUCCESS' (0)
     on success.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

gnutls_certificate_set_pin_function
-----------------------------------

 -- 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

gnutls_certificate_set_rawpk_key_file
-------------------------------------

 -- Function: int 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)
     CRED: is a 'gnutls_certificate_credentials_t' type.

     RAWPKFILE: contains a raw public key in PKIX.SubjectPublicKeyInfo
     format.

     PRIVKEYFILE: contains a file path to a private key.

     FORMAT: encoding of the keys.  DER or PEM.

     PASS: an optional password to unlock the private key privkeyfile.

     KEY_USAGE: an ORed sequence of 'GNUTLS_KEY_' * flags.

     NAMES: is an array of DNS names belonging to the public-key (NULL
     if none).

     NAMES_LENGTH: holds the length of the names list.

     PRIVKEY_FLAGS: an ORed sequence of 'gnutls_pkcs_encrypt_flags_t' .
     These apply to the private key pkey.

     PKCS11_FLAGS: one of gnutls_pkcs11_obj_flags.  These apply to URLs.

     This function sets a public/private keypair read from file in the
     'gnutls_certificate_credentials_t' type to be used for
     authentication and/or encryption.  'spki' and 'privkey' should
     match otherwise set signatures cannot be validated.  In case of no
     match this function returns 'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' .
     This function should be called once for the client because there is
     currently no mechanism to determine which raw public-key to select
     for the peer when there are multiple present.  Multiple raw public
     keys for the server can be distinghuished by setting the 'names' .

     Note here that 'spki' is a raw public-key as defined in RFC7250.
     It means that there is no surrounding certificate that holds the
     public key and that there is therefore no direct mechanism to prove
     the authenticity of this key.  The keypair can be used during a TLS
     handshake but its authenticity should be established via a
     different mechanism (e.g.  TOFU or known fingerprint).

     The supported formats are basic unencrypted key, PKCS8, PKCS12, and
     the openssl format and will be autodetected.

     If the raw public-key and the private key are given in PEM encoding
     then the strings that hold their values must be null terminated.

     Key usage (as defined by X.509 extension (2.5.29.15)) can be
     explicitly set because there is no certificate structure around the
     key to define this value.  See for more info
     'gnutls_x509_crt_get_key_usage()' .

     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 in other functions to refer
     to the added key-pair.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, in case
     the key pair does not match 'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' is
     returned, in other erroneous cases a different negative error code
     is returned.

     *Since:* 3.6.6

gnutls_certificate_set_rawpk_key_mem
------------------------------------

 -- Function: int 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)
     CRED: is a 'gnutls_certificate_credentials_t' type.

     SPKI: contains a raw public key in PKIX.SubjectPublicKeyInfo
     format.

     PKEY: contains a raw private key.

     FORMAT: encoding of the keys.  DER or PEM.

     PASS: an optional password to unlock the private key pkey.

     KEY_USAGE: An ORed sequence of 'GNUTLS_KEY_' * flags.

     NAMES: is an array of DNS names belonging to the public-key (NULL
     if none).

     NAMES_LENGTH: holds the length of the names list.

     FLAGS: an ORed sequence of 'gnutls_pkcs_encrypt_flags_t' .  These
     apply to the private key pkey.

     This function sets a public/private keypair in the
     'gnutls_certificate_credentials_t' type to be used for
     authentication and/or encryption.  'spki' and 'privkey' should
     match otherwise set signatures cannot be validated.  In case of no
     match this function returns 'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' .
     This function should be called once for the client because there is
     currently no mechanism to determine which raw public-key to select
     for the peer when there are multiple present.  Multiple raw public
     keys for the server can be distinghuished by setting the 'names' .

     Note here that 'spki' is a raw public-key as defined in RFC7250.
     It means that there is no surrounding certificate that holds the
     public key and that there is therefore no direct mechanism to prove
     the authenticity of this key.  The keypair can be used during a TLS
     handshake but its authenticity should be established via a
     different mechanism (e.g.  TOFU or known fingerprint).

     The supported formats are basic unencrypted key, PKCS8, PKCS12, and
     the openssl format and will be autodetected.

     If the raw public-key and the private key are given in PEM encoding
     then the strings that hold their values must be null terminated.

     Key usage (as defined by X.509 extension (2.5.29.15)) can be
     explicitly set because there is no certificate structure around the
     key to define this value.  See for more info
     'gnutls_x509_crt_get_key_usage()' .

     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 in other functions to refer
     to the added key-pair.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, in case
     the key pair does not match 'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' is
     returned, in other erroneous cases a different negative error code
     is returned.

     *Since:* 3.6.6

gnutls_certificate_set_retrieve_function
----------------------------------------

 -- Function: void gnutls_certificate_set_retrieve_function
          (gnutls_certificate_credentials_t CRED,
          gnutls_certificate_retrieve_function * FUNC)
     CRED: is a 'gnutls_certificate_credentials_t' type.

     FUNC: is the callback function

     This function sets a callback to be called in order to retrieve the
     certificate to be used in the handshake.  The callback will take
     control only if a certificate is requested by the peer.  You are
     advised to use 'gnutls_certificate_set_retrieve_function2()'
     because it is much more efficient in the processing it requires
     from gnutls.

     The callback's function prototype is: int
     (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int
     nreqs, const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length,
     gnutls_retr2_st* st);

     'req_ca_dn' is only used in X.509 certificates.  Contains a list
     with the CA names that the server considers trusted.  This is a
     hint and typically the client should send a certificate that is
     signed by one of these CAs.  These names, when available, are DER
     encoded.  To get a more meaningful value use the function
     'gnutls_x509_rdn_get()' .

     'pk_algos' contains a list with server's acceptable public key
     algorithms.  The certificate returned should support the server's
     given algorithms.

     'st' should contain the certificates and private keys.

     If the callback function is provided then gnutls will call it, in
     the handshake, after the certificate request message has been
     received.

     In server side pk_algos and req_ca_dn are NULL.

     The callback function should set the certificate list to be sent,
     and return 0 on success.  If no certificate was selected then the
     number of certificates should be set to zero.  The value (-1)
     indicates error and the handshake will be terminated.  If both
     certificates are set in the credentials and a callback is
     available, the callback takes predence.

     *Since:* 3.0

gnutls_certificate_set_verify_flags
-----------------------------------

 -- Function: void gnutls_certificate_set_verify_flags
          (gnutls_certificate_credentials_t RES, unsigned int FLAGS)
     RES: is a gnutls_certificate_credentials_t type

     FLAGS: are the flags

     This function will set the flags to be used for verification of
     certificates and override any defaults.  The provided flags must be
     an OR of the 'gnutls_certificate_verify_flags' enumerations.

gnutls_certificate_set_verify_function
--------------------------------------

 -- Function: void gnutls_certificate_set_verify_function
          (gnutls_certificate_credentials_t CRED,
          gnutls_certificate_verify_function * FUNC)
     CRED: is a 'gnutls_certificate_credentials_t' type.

     FUNC: is the callback function

     This function sets a callback to be called when peer's certificate
     has been received in order to verify it on receipt rather than
     doing after the handshake is completed.

     The callback's function prototype is: int
     (*callback)(gnutls_session_t);

     If the callback function is provided then gnutls will call it, in
     the handshake, just after the certificate message has been
     received.  To verify or obtain the certificate the
     'gnutls_certificate_verify_peers2()' ,
     'gnutls_certificate_type_get()' , 'gnutls_certificate_get_peers()'
     functions can be used.

     The callback function should return 0 for the handshake to continue
     or non-zero to terminate.

     *Since:* 2.10.0

gnutls_certificate_set_verify_limits
------------------------------------

 -- Function: void gnutls_certificate_set_verify_limits
          (gnutls_certificate_credentials_t RES, unsigned int MAX_BITS,
          unsigned int MAX_DEPTH)
     RES: is a gnutls_certificate_credentials type

     MAX_BITS: is the number of bits of an acceptable certificate
     (default 8200)

     MAX_DEPTH: is maximum depth of the verification of a certificate
     chain (default 5)

     This function will set some upper limits for the default
     verification function, 'gnutls_certificate_verify_peers2()' , to
     avoid denial of service attacks.  You can set them to zero to
     disable limits.

gnutls_certificate_set_x509_crl
-------------------------------

 -- Function: int gnutls_certificate_set_x509_crl
          (gnutls_certificate_credentials_t RES, gnutls_x509_crl_t *
          CRL_LIST, int CRL_LIST_SIZE)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CRL_LIST: is a list of trusted CRLs.  They should have been
     verified before.

     CRL_LIST_SIZE: holds the size of the crl_list

     This function adds the trusted CRLs in order to verify client or
     server certificates.  In case of a client this is not required to
     be called if the certificates are not verified using
     'gnutls_certificate_verify_peers2()' .  This function may be called
     multiple times.

     *Returns:* number of CRLs processed, or a negative error code on
     error.

     *Since:* 2.4.0

gnutls_certificate_set_x509_crl_file
------------------------------------

 -- Function: int gnutls_certificate_set_x509_crl_file
          (gnutls_certificate_credentials_t RES, const char * CRLFILE,
          gnutls_x509_crt_fmt_t TYPE)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CRLFILE: is a file containing the list of verified CRLs (DER or PEM
     list)

     TYPE: is PEM or DER

     This function adds the trusted CRLs in order to verify client or
     server certificates.  In case of a client this is not required to
     be called if the certificates are not verified using
     'gnutls_certificate_verify_peers2()' .  This function may be called
     multiple times.

     *Returns:* number of CRLs processed or a negative error code on
     error.

gnutls_certificate_set_x509_crl_mem
-----------------------------------

 -- Function: int gnutls_certificate_set_x509_crl_mem
          (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
          CRL, gnutls_x509_crt_fmt_t TYPE)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CRL: is a list of trusted CRLs.  They should have been verified
     before.

     TYPE: is DER or PEM

     This function adds the trusted CRLs in order to verify client or
     server certificates.  In case of a client this is not required to
     be called if the certificates are not verified using
     'gnutls_certificate_verify_peers2()' .  This function may be called
     multiple times.

     *Returns:* number of CRLs processed, or a negative error code on
     error.

gnutls_certificate_set_x509_key
-------------------------------

 -- Function: int 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)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CERT_LIST: contains a certificate list (path) for the specified
     private key

     CERT_LIST_SIZE: holds the size of the certificate list

     KEY: is a 'gnutls_x509_privkey_t' key

     This function sets a certificate/private key pair in the
     gnutls_certificate_credentials_t type.  This function may be called
     more than once, in case multiple keys/certificates exist for the
     server.  For clients that wants to send more than their own end
     entity certificate (e.g., also an intermediate CA cert) then put
     the certificate chain in 'cert_list' .

     Note that the certificates and keys provided, can be safely
     deinitialized after this function is called.

     If that function fails to load the 'res' type is at an undefined
     state, 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 to other functions to refer
     to the added key-pair.

     *Returns:* On success this functions returns zero, and otherwise a
     negative value on error (see above for modifying that behavior).

     *Since:* 2.4.0

gnutls_certificate_set_x509_key_file
------------------------------------

 -- Function: int gnutls_certificate_set_x509_key_file
          (gnutls_certificate_credentials_t RES, const char * CERTFILE,
          const char * KEYFILE, gnutls_x509_crt_fmt_t TYPE)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CERTFILE: is a file that containing the certificate list (path) for
     the specified private key, in PKCS7 format, or a list of
     certificates

     KEYFILE: is a file that contains the private key

     TYPE: is PEM or DER

     This function sets a certificate/private key pair in the
     gnutls_certificate_credentials_t type.  This function may be called
     more than once, in case multiple keys/certificates exist for the
     server.  For clients that need to send more than its own end entity
     certificate, e.g., also an intermediate CA cert, then the
     'certfile' must contain the ordered certificate chain.

     Note that the names in the certificate provided will be considered
     when selecting the appropriate certificate to use (in case of
     multiple certificate/key pairs).

     This function can also accept URLs at 'keyfile' and 'certfile' .
     In that case it will use the private key and certificate indicated
     by the URLs.  Note that the supported URLs are the ones indicated
     by 'gnutls_url_is_supported()' .

     In case the 'certfile' is provided as a PKCS '11' URL, then the
     certificate, and its present issuers in the token are imported
     (i.e., forming the required trust chain).

     If that function fails to load the 'res' structure is at an
     undefined state, 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 to other functions to refer
     to the added key-pair.

     *Returns:* On success this functions returns zero, and otherwise a
     negative value on error (see above for modifying that behavior).

     *Since:* 3.1.11

gnutls_certificate_set_x509_key_file2
-------------------------------------

 -- Function: int 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)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CERTFILE: is a file that containing the certificate list (path) for
     the specified private key, in PKCS7 format, or a list of
     certificates

     KEYFILE: is a file that contains the private key

     TYPE: is PEM or DER

     PASS: is the password of the key

     FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t

     This function sets a certificate/private key pair in the
     gnutls_certificate_credentials_t type.  This function may be called
     more than once, in case multiple keys/certificates exist for the
     server.  For clients that need to send more than its own end entity
     certificate, e.g., also an intermediate CA cert, then the
     'certfile' must contain the ordered certificate chain.

     Note that the names in the certificate provided will be considered
     when selecting the appropriate certificate to use (in case of
     multiple certificate/key pairs).

     This function can also accept URLs at 'keyfile' and 'certfile' .
     In that case it will use the private key and certificate indicated
     by the URLs.  Note that the supported URLs are the ones indicated
     by 'gnutls_url_is_supported()' .  Before GnuTLS 3.4.0 when a URL
     was specified, the 'pass' part was ignored and a PIN callback had
     to be registered, this is no longer the case in current releases.

     In case the 'certfile' is provided as a PKCS '11' URL, then the
     certificate, and its present issuers in the token are imported
     (i.e., forming the required trust chain).

     If that function fails to load the 'res' structure is at an
     undefined state, 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 to other functions to refer
     to the added key-pair.

     *Returns:* On success this functions returns zero, and otherwise a
     negative value on error (see above for modifying that behavior).

gnutls_certificate_set_x509_key_mem
-----------------------------------

 -- Function: int gnutls_certificate_set_x509_key_mem
          (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
          CERT, const gnutls_datum_t * KEY, gnutls_x509_crt_fmt_t TYPE)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CERT: contains a certificate list (path) for the specified private
     key

     KEY: is the private key, or 'NULL'

     TYPE: is PEM or DER

     This function sets a certificate/private key pair in the
     gnutls_certificate_credentials_t type.  This function may be called
     more than once, in case multiple keys/certificates exist for the
     server.

     Note that the keyUsage (2.5.29.15) PKIX extension in X.509
     certificates is supported.  This means that certificates intended
     for signing cannot be used for ciphersuites that require
     encryption.

     If the certificate and the private key are given in PEM encoding
     then the strings that hold their values must be null terminated.

     The 'key' may be 'NULL' if you are using a sign callback, see
     'gnutls_sign_callback_set()' .

     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 to other functions to refer
     to the added key-pair.

     *Returns:* On success this functions returns zero, and otherwise a
     negative value on error (see above for modifying that behavior).

gnutls_certificate_set_x509_key_mem2
------------------------------------

 -- Function: int 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)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CERT: contains a certificate list (path) for the specified private
     key

     KEY: is the private key, or 'NULL'

     TYPE: is PEM or DER

     PASS: is the key's password

     FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t

     This function sets a certificate/private key pair in the
     gnutls_certificate_credentials_t type.  This function may be called
     more than once, in case multiple keys/certificates exist for the
     server.

     Note that the keyUsage (2.5.29.15) PKIX extension in X.509
     certificates is supported.  This means that certificates intended
     for signing cannot be used for ciphersuites that require
     encryption.

     If the certificate and the private key are given in PEM encoding
     then the strings that hold their values must be null terminated.

     The 'key' may be 'NULL' if you are using a sign callback, see
     'gnutls_sign_callback_set()' .

     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 to other functions to refer
     to the added key-pair.

     *Returns:* On success this functions returns zero, and otherwise a
     negative value on error (see above for modifying that behavior).

gnutls_certificate_set_x509_simple_pkcs12_file
----------------------------------------------

 -- Function: int gnutls_certificate_set_x509_simple_pkcs12_file
          (gnutls_certificate_credentials_t RES, const char *
          PKCS12FILE, gnutls_x509_crt_fmt_t TYPE, const char * PASSWORD)
     RES: is a 'gnutls_certificate_credentials_t' type.

     PKCS12FILE: filename of file containing PKCS'12' blob.

     TYPE: is PEM or DER of the 'pkcs12file' .

     PASSWORD: optional password used to decrypt PKCS'12' file, bags and
     keys.

     This function sets a certificate/private key pair and/or a CRL in
     the gnutls_certificate_credentials_t type.  This function may be
     called more than once (in case multiple keys/certificates exist for
     the server).

     PKCS'12' files with a MAC, encrypted bags and PKCS '8' private keys
     are supported.  However, only password based security, and the same
     password for all operations, are supported.

     PKCS'12' file may contain many keys and/or certificates, and this
     function will try to auto-detect based on the key ID the
     certificate and key pair to use.  If the PKCS'12' file contain the
     issuer of the selected certificate, it will be appended to the
     certificate to form a chain.

     If more than one private keys are stored in the PKCS'12' file, then
     only one key will be read (and it is undefined which one).

     It is believed that the limitations of this function is acceptable
     for most usage, and that any more flexibility would introduce
     complexity that would make it harder to use this functionality at
     all.

     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 to other functions to refer
     to the added key-pair.

     *Returns:* On success this functions returns zero, and otherwise a
     negative value on error (see above for modifying that behavior).

gnutls_certificate_set_x509_simple_pkcs12_mem
---------------------------------------------

 -- Function: int gnutls_certificate_set_x509_simple_pkcs12_mem
          (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
          P12BLOB, gnutls_x509_crt_fmt_t TYPE, const char * PASSWORD)
     RES: is a 'gnutls_certificate_credentials_t' type.

     P12BLOB: the PKCS'12' blob.

     TYPE: is PEM or DER of the 'pkcs12file' .

     PASSWORD: optional password used to decrypt PKCS'12' file, bags and
     keys.

     This function sets a certificate/private key pair and/or a CRL in
     the gnutls_certificate_credentials_t type.  This function may be
     called more than once (in case multiple keys/certificates exist for
     the server).

     Encrypted PKCS'12' bags and PKCS'8' private keys are supported.
     However, only password based security, and the same password for
     all operations, are supported.

     PKCS'12' file may contain many keys and/or certificates, and this
     function will try to auto-detect based on the key ID the
     certificate and key pair to use.  If the PKCS'12' file contain the
     issuer of the selected certificate, it will be appended to the
     certificate to form a chain.

     If more than one private keys are stored in the PKCS'12' file, then
     only one key will be read (and it is undefined which one).

     It is believed that the limitations of this function is acceptable
     for most usage, and that any more flexibility would introduce
     complexity that would make it harder to use this functionality at
     all.

     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 to other functions to refer
     to the added key-pair.

     *Returns:* On success this functions returns zero, and otherwise a
     negative value on error (see above for modifying that behavior).

     *Since:* 2.8.0

gnutls_certificate_set_x509_system_trust
----------------------------------------

 -- 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

gnutls_certificate_set_x509_trust
---------------------------------

 -- Function: int gnutls_certificate_set_x509_trust
          (gnutls_certificate_credentials_t RES, gnutls_x509_crt_t *
          CA_LIST, int CA_LIST_SIZE)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CA_LIST: is a list of trusted CAs

     CA_LIST_SIZE: holds the size of the CA list

     This function adds the trusted CAs in order to verify client or
     server certificates.  In case of a client this is not required to
     be called if the certificates are not verified using
     'gnutls_certificate_verify_peers2()' .  This function may be called
     multiple times.

     In case of a server the CAs set here will be sent to the client if
     a certificate request is sent.  This can be disabled using
     'gnutls_certificate_send_x509_rdn_sequence()' .

     *Returns:* the number of certificates processed or a negative error
     code on error.

     *Since:* 2.4.0

gnutls_certificate_set_x509_trust_dir
-------------------------------------

 -- Function: int gnutls_certificate_set_x509_trust_dir
          (gnutls_certificate_credentials_t CRED, const char * CA_DIR,
          gnutls_x509_crt_fmt_t TYPE)
     CRED: is a 'gnutls_certificate_credentials_t' type.

     CA_DIR: is a directory containing the list of trusted CAs (DER or
     PEM list)

     TYPE: is PEM or DER

     This function adds the trusted CAs present in the directory in
     order to verify client or server certificates.  This function is
     identical to 'gnutls_certificate_set_x509_trust_file()' but loads
     all certificates in a directory.

     *Returns:* the number of certificates processed

     *Since:* 3.3.6

gnutls_certificate_set_x509_trust_file
--------------------------------------

 -- Function: int gnutls_certificate_set_x509_trust_file
          (gnutls_certificate_credentials_t CRED, const char * CAFILE,
          gnutls_x509_crt_fmt_t TYPE)
     CRED: is a 'gnutls_certificate_credentials_t' type.

     CAFILE: is a file containing the list of trusted CAs (DER or PEM
     list)

     TYPE: is PEM or DER

     This function adds the trusted CAs in order to verify client or
     server certificates.  In case of a client this is not required to
     be called if the certificates are not verified using
     'gnutls_certificate_verify_peers2()' .  This function may be called
     multiple times.

     In case of a server the names of the CAs set here will be sent to
     the client if a certificate request is sent.  This can be disabled
     using 'gnutls_certificate_send_x509_rdn_sequence()' .

     This function can also accept URLs.  In that case it will import
     all certificates that are marked as trusted.  Note that the
     supported URLs are the ones indicated by
     'gnutls_url_is_supported()' .

     *Returns:* the number of certificates processed

gnutls_certificate_set_x509_trust_mem
-------------------------------------

 -- Function: int gnutls_certificate_set_x509_trust_mem
          (gnutls_certificate_credentials_t RES, const gnutls_datum_t *
          CA, gnutls_x509_crt_fmt_t TYPE)
     RES: is a 'gnutls_certificate_credentials_t' type.

     CA: is a list of trusted CAs or a DER certificate

     TYPE: is DER or PEM

     This function adds the trusted CAs in order to verify client or
     server certificates.  In case of a client this is not required to
     be called if the certificates are not verified using
     'gnutls_certificate_verify_peers2()' .  This function may be called
     multiple times.

     In case of a server the CAs set here will be sent to the client if
     a certificate request is sent.  This can be disabled using
     'gnutls_certificate_send_x509_rdn_sequence()' .

     *Returns:* the number of certificates processed or a negative error
     code on error.

gnutls_certificate_type_get
---------------------------

 -- Function: gnutls_certificate_type_t gnutls_certificate_type_get
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     This function returns the type of the certificate that is
     negotiated for this side to send to the peer.  The certificate type
     is by default X.509, unless an alternative certificate type is
     enabled by 'gnutls_init()' and negotiated during the session.

     Resumed sessions will return the certificate type that was
     negotiated and used in the original session.

     As of version 3.6.4 it is recommended to use
     'gnutls_certificate_type_get2()' which is more fine-grained.

     *Returns:* the currently used 'gnutls_certificate_type_t'
     certificate type as negotiated for 'our' side of the connection.

gnutls_certificate_type_get2
----------------------------

 -- Function: gnutls_certificate_type_t gnutls_certificate_type_get2
          (gnutls_session_t SESSION, gnutls_ctype_target_t TARGET)
     SESSION: is a 'gnutls_session_t' type.

     TARGET: is a 'gnutls_ctype_target_t' type.

     This function returns the type of the certificate that a side is
     negotiated to use.  The certificate type is by default X.509,
     unless an alternative certificate type is enabled by
     'gnutls_init()' and negotiated during the session.

     The 'target' parameter specifies whether to request the negotiated
     certificate type for the client ('GNUTLS_CTYPE_CLIENT' ), or for
     the server ('GNUTLS_CTYPE_SERVER' ).  Additionally, in P2P mode
     connection set up where you don't know in advance who will be
     client and who will be server you can use the flag
     ('GNUTLS_CTYPE_OURS' ) and ('GNUTLS_CTYPE_PEERS' ) to retrieve the
     corresponding certificate types.

     Resumed sessions will return the certificate type that was
     negotiated and used in the original session.  That is, this
     function can be used to reliably determine the type of the
     certificate returned by 'gnutls_certificate_get_peers()' .

     *Returns:* the currently used 'gnutls_certificate_type_t'
     certificate type for the client or the server.

     *Since:* 3.6.4

gnutls_certificate_type_get_id
------------------------------

 -- Function: gnutls_certificate_type_t gnutls_certificate_type_get_id
          (const char * NAME)
     NAME: is a certificate type name

     The names are compared in a case insensitive way.

     *Returns:* a 'gnutls_certificate_type_t' for the specified in a
     string certificate type, or 'GNUTLS_CRT_UNKNOWN' on error.

gnutls_certificate_type_get_name
--------------------------------

 -- Function: const char * gnutls_certificate_type_get_name
          (gnutls_certificate_type_t TYPE)
     TYPE: is a certificate type

     Convert a 'gnutls_certificate_type_t' type to a string.

     *Returns:* a string that contains the name of the specified
     certificate type, or 'NULL' in case of unknown types.

gnutls_certificate_type_list
----------------------------

 -- Function: const gnutls_certificate_type_t *
          gnutls_certificate_type_list ( VOID)

     Get a list of certificate types.

     *Returns:* a (0)-terminated list of 'gnutls_certificate_type_t'
     integers indicating the available certificate types.

gnutls_certificate_verification_status_print
--------------------------------------------

 -- Function: int gnutls_certificate_verification_status_print (unsigned
          int STATUS, gnutls_certificate_type_t TYPE, gnutls_datum_t *
          OUT, unsigned int FLAGS)
     STATUS: The status flags to be printed

     TYPE: The certificate type

     OUT: Newly allocated datum with (0) terminated string.

     FLAGS: should be zero

     This function will pretty print the status of a verification
     process - eg.  the one obtained by
     'gnutls_certificate_verify_peers3()' .

     The output 'out' needs to be deallocated using 'gnutls_free()' .

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

     *Since:* 3.1.4

gnutls_certificate_verify_peers
-------------------------------

 -- Function: int gnutls_certificate_verify_peers (gnutls_session_t
          SESSION, gnutls_typed_vdata_st * DATA, unsigned int ELEMENTS,
          unsigned int * STATUS)
     SESSION: is a gnutls session

     DATA: an array of typed data

     ELEMENTS: the number of data elements

     STATUS: is the output of the verification

     This function will verify the peer's certificate and store the the
     status in the 'status' variable as a bitwise OR of
     gnutls_certificate_status_t values or zero if the certificate is
     trusted.  Note that value in 'status' is set only when the return
     value of this function is success (i.e, failure to trust a
     certificate does not imply a negative return value).  The default
     verification flags used by this function can be overridden using
     'gnutls_certificate_set_verify_flags()' .  See the documentation of
     'gnutls_certificate_verify_peers2()' for details in the
     verification process.

     This function will take into account the stapled OCSP responses
     sent by the server, as well as the following X.509 certificate
     extensions: Name Constraints, Key Usage, and Basic Constraints
     (pathlen).

     The acceptable 'data' types are 'GNUTLS_DT_DNS_HOSTNAME' ,
     'GNUTLS_DT_RFC822NAME' and 'GNUTLS_DT_KEY_PURPOSE_OID' .  The
     former two accept as data a null-terminated hostname or email
     address, and the latter a null-terminated object identifier (e.g.,
     'GNUTLS_KP_TLS_WWW_SERVER' ).

     If a DNS hostname is provided then this function will compare the
     hostname in the certificate against the given.  If names do not
     match the 'GNUTLS_CERT_UNEXPECTED_OWNER' status flag will be set.
     If a key purpose OID is provided and the end-certificate contains
     the extended key usage PKIX extension, it will be required to be
     have the provided key purpose or be marked for any purpose,
     otherwise verification status will have the
     'GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE' flag set.

     To avoid denial of service attacks some default upper limits
     regarding the certificate key size and chain size are set.  To
     override them use 'gnutls_certificate_set_verify_limits()' .

     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 this function will
     return 'GNUTLS_E_INVALID_REQUEST' .

     *Returns:* 'GNUTLS_E_SUCCESS' (0) when the validation is performed,
     or a negative error code otherwise.  A successful error code means
     that the 'status' parameter must be checked to obtain the
     validation status.

     *Since:* 3.3.0

gnutls_certificate_verify_peers2
--------------------------------

 -- Function: int gnutls_certificate_verify_peers2 (gnutls_session_t
          SESSION, unsigned int * STATUS)
     SESSION: is a gnutls session

     STATUS: is the output of the verification

     This function will verify the peer's certificate and store the
     status in the 'status' variable as a bitwise OR of
     gnutls_certificate_status_t values or zero if the certificate is
     trusted.  Note that value in 'status' is set only when the return
     value of this function is success (i.e, failure to trust a
     certificate does not imply a negative return value).  The default
     verification flags used by this function can be overridden using
     'gnutls_certificate_set_verify_flags()' .

     This function will take into account the stapled OCSP responses
     sent by the server, as well as the following X.509 certificate
     extensions: Name Constraints, Key Usage, and Basic Constraints
     (pathlen).

     Note that you must also check the peer's name in order to check if
     the verified certificate belongs to the actual peer, see
     'gnutls_x509_crt_check_hostname()' , or use
     'gnutls_certificate_verify_peers3()' .

     To avoid denial of service attacks some default upper limits
     regarding the certificate key size and chain size are set.  To
     override them use 'gnutls_certificate_set_verify_limits()' .

     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 this function will
     return 'GNUTLS_E_INVALID_REQUEST' .

     *Returns:* 'GNUTLS_E_SUCCESS' (0) when the validation is performed,
     or a negative error code otherwise.  A successful error code means
     that the 'status' parameter must be checked to obtain the
     validation status.

gnutls_certificate_verify_peers3
--------------------------------

 -- Function: int gnutls_certificate_verify_peers3 (gnutls_session_t
          SESSION, const char * HOSTNAME, unsigned int * STATUS)
     SESSION: is a gnutls session

     HOSTNAME: is the expected name of the peer; may be 'NULL'

     STATUS: is the output of the verification

     This function will verify the peer's certificate and store the the
     status in the 'status' variable as a bitwise OR of
     gnutls_certificate_status_t values or zero if the certificate is
     trusted.  Note that value in 'status' is set only when the return
     value of this function is success (i.e, failure to trust a
     certificate does not imply a negative return value).  The default
     verification flags used by this function can be overridden using
     'gnutls_certificate_set_verify_flags()' .  See the documentation of
     'gnutls_certificate_verify_peers2()' for details in the
     verification process.

     This function will take into account the stapled OCSP responses
     sent by the server, as well as the following X.509 certificate
     extensions: Name Constraints, Key Usage, and Basic Constraints
     (pathlen).

     If the 'hostname' provided is non-NULL then this function will
     compare the hostname in the certificate against it.  The comparison
     will follow the RFC6125 recommendations.  If names do not match the
     'GNUTLS_CERT_UNEXPECTED_OWNER' status flag will be set.

     In order to verify the purpose of the end-certificate (by checking
     the extended key usage), use 'gnutls_certificate_verify_peers()' .

     To avoid denial of service attacks some default upper limits
     regarding the certificate key size and chain size are set.  To
     override them use 'gnutls_certificate_set_verify_limits()' .

     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 this function will
     return 'GNUTLS_E_INVALID_REQUEST' .

     *Returns:* 'GNUTLS_E_SUCCESS' (0) when the validation is performed,
     or a negative error code otherwise.  A successful error code means
     that the 'status' parameter must be checked to obtain the
     validation status.

     *Since:* 3.1.4

gnutls_check_version
--------------------

 -- Function: const char * gnutls_check_version (const char *
          REQ_VERSION)
     REQ_VERSION: version string to compare with, or 'NULL' .

     Check the GnuTLS Library version against the provided string.  See
     'GNUTLS_VERSION' for a suitable 'req_version' string.

     See also 'gnutls_check_version_numeric()' , which provides this
     functionality as a macro.

     *Returns:* Check that the version of the library is at minimum the
     one given as a string in 'req_version' and return the actual
     version string of the library; return 'NULL' if the condition is
     not met.  If 'NULL' is passed to this function no check is done and
     only the version string is returned.

gnutls_cipher_get
-----------------

 -- Function: gnutls_cipher_algorithm_t gnutls_cipher_get
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Get the currently used cipher.

     *Returns:* the currently used cipher, a 'gnutls_cipher_algorithm_t'
     type.

gnutls_cipher_get_id
--------------------

 -- Function: gnutls_cipher_algorithm_t gnutls_cipher_get_id (const char
          * NAME)
     NAME: is a cipher algorithm name

     The names are compared in a case insensitive way.

     *Returns:* return a 'gnutls_cipher_algorithm_t' value corresponding
     to the specified cipher, or 'GNUTLS_CIPHER_UNKNOWN' on error.

gnutls_cipher_get_key_size
--------------------------

 -- Function: size_t gnutls_cipher_get_key_size
          (gnutls_cipher_algorithm_t ALGORITHM)
     ALGORITHM: is an encryption algorithm

     This function returns the key size of the provided algorithm.

     *Returns:* length (in bytes) of the given cipher's key size, or 0
     if the given cipher is invalid.

gnutls_cipher_get_name
----------------------

 -- Function: const char * gnutls_cipher_get_name
          (gnutls_cipher_algorithm_t ALGORITHM)
     ALGORITHM: is an encryption algorithm

     Convert a 'gnutls_cipher_algorithm_t' type to a string.

     *Returns:* a pointer to a string that contains the name of the
     specified cipher, or 'NULL' .

gnutls_cipher_list
------------------

 -- Function: const gnutls_cipher_algorithm_t * gnutls_cipher_list (
          VOID)

     Get a list of supported cipher algorithms.  Note that not
     necessarily all ciphers are supported as TLS cipher suites.  For
     example, DES is not supported as a cipher suite, but is supported
     for other purposes (e.g., PKCS'8' or similar).

     This function is not thread safe.

     *Returns:* a (0)-terminated list of 'gnutls_cipher_algorithm_t'
     integers indicating the available ciphers.

gnutls_cipher_suite_get_name
----------------------------

 -- Function: const char * gnutls_cipher_suite_get_name
          (gnutls_kx_algorithm_t KX_ALGORITHM, gnutls_cipher_algorithm_t
          CIPHER_ALGORITHM, gnutls_mac_algorithm_t MAC_ALGORITHM)
     KX_ALGORITHM: is a Key exchange algorithm

     CIPHER_ALGORITHM: is a cipher algorithm

     MAC_ALGORITHM: is a MAC algorithm

     Note that the full cipher suite name must be prepended by TLS or
     SSL depending of the protocol in use.

     *Returns:* a string that contains the name of a TLS cipher suite,
     specified by the given algorithms, or 'NULL' .

gnutls_cipher_suite_info
------------------------

 -- Function: const char * gnutls_cipher_suite_info (size_t IDX,
          unsigned char * CS_ID, gnutls_kx_algorithm_t * KX,
          gnutls_cipher_algorithm_t * CIPHER, gnutls_mac_algorithm_t *
          MAC, gnutls_protocol_t * MIN_VERSION)
     IDX: index of cipher suite to get information about, starts on 0.

     CS_ID: output buffer with room for 2 bytes, indicating cipher suite
     value

     KX: output variable indicating key exchange algorithm, or 'NULL' .

     CIPHER: output variable indicating cipher, or 'NULL' .

     MAC: output variable indicating MAC algorithm, or 'NULL' .

     MIN_VERSION: output variable indicating TLS protocol version, or
     'NULL' .

     Get information about supported cipher suites.  Use the function
     iteratively to get information about all supported cipher suites.
     Call with idx=0 to get information about first cipher suite, then
     idx=1 and so on until the function returns NULL.

     *Returns:* the name of 'idx' cipher suite, and set the information
     about the cipher suite in the output variables.  If 'idx' is out of
     bounds, 'NULL' is returned.

gnutls_credentials_clear
------------------------

 -- Function: void gnutls_credentials_clear (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Clears all the credentials previously set in this session.

gnutls_credentials_get
----------------------

 -- Function: int gnutls_credentials_get (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 to return

     CRED: will contain the credentials.

     Returns the previously provided credentials structures.

     For 'GNUTLS_CRD_ANON' , 'cred' will 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' will 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' will be
     'gnutls_certificate_credentials_t' .

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     *Since:* 3.3.3

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.

gnutls_db_check_entry
---------------------

 -- Function: int gnutls_db_check_entry (gnutls_session_t SESSION,
          gnutls_datum_t SESSION_ENTRY)
     SESSION: is a 'gnutls_session_t' type.

     SESSION_ENTRY: is the session data (not key)

     This function has no effect.

     *Returns:* Returns 'GNUTLS_E_EXPIRED' , if the database entry has
     expired or 0 otherwise.

     *Deprecated:* This function is deprecated.

gnutls_db_check_entry_expire_time
---------------------------------

 -- Function: time_t gnutls_db_check_entry_expire_time (gnutls_datum_t *
          ENTRY)
     ENTRY: is a pointer to a 'gnutls_datum_t' type.

     This function returns the time that this entry will expire.  It can
     be used for database entry expiration.

     *Returns:* The time this entry will expire, or zero on error.

     *Since:* 3.6.5

gnutls_db_check_entry_time
--------------------------

 -- Function: time_t gnutls_db_check_entry_time (gnutls_datum_t * ENTRY)
     ENTRY: is a pointer to a 'gnutls_datum_t' type.

     This function returns the time that this entry was active.  It can
     be used for database entry expiration.

     *Returns:* The time this entry was created, or zero on error.

gnutls_db_get_default_cache_expiration
--------------------------------------

 -- Function: unsigned gnutls_db_get_default_cache_expiration ( VOID)

     Returns the expiration time (in seconds) of stored sessions for
     resumption.

gnutls_db_get_ptr
-----------------

 -- Function: void * gnutls_db_get_ptr (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Get db function pointer.

     *Returns:* the pointer that will be sent to db store, retrieve and
     delete functions, as the first argument.

gnutls_db_remove_session
------------------------

 -- Function: void gnutls_db_remove_session (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     This function will remove the current session data from the session
     database.  This will prevent future handshakes reusing these
     session data.  This function should be called if a session was
     terminated abnormally, and before 'gnutls_deinit()' is called.

     Normally 'gnutls_deinit()' will remove abnormally terminated
     sessions.

gnutls_db_set_cache_expiration
------------------------------

 -- Function: void gnutls_db_set_cache_expiration (gnutls_session_t
          SESSION, int SECONDS)
     SESSION: is a 'gnutls_session_t' type.

     SECONDS: is the number of seconds.

     Set the expiration time for resumed sessions.  The default is 21600
     (size hours) at the time of writing.

     The maximum value that can be set using this function is 604800 (7
     days).

gnutls_db_set_ptr
-----------------

 -- Function: void gnutls_db_set_ptr (gnutls_session_t SESSION, void *
          PTR)
     SESSION: is a 'gnutls_session_t' type.

     PTR: is the pointer

     Sets the pointer that will be provided to db store, retrieve and
     delete functions, as the first argument.

gnutls_db_set_remove_function
-----------------------------

 -- Function: void gnutls_db_set_remove_function (gnutls_session_t
          SESSION, gnutls_db_remove_func REM_FUNC)
     SESSION: is a 'gnutls_session_t' type.

     REM_FUNC: is the function.

     Sets the function that will be used to remove data from the resumed
     sessions database.  This function must return 0 on success.

     The first argument to 'rem_func' will be null unless
     'gnutls_db_set_ptr()' has been called.

gnutls_db_set_retrieve_function
-------------------------------

 -- Function: void gnutls_db_set_retrieve_function (gnutls_session_t
          SESSION, gnutls_db_retr_func RETR_FUNC)
     SESSION: is a 'gnutls_session_t' type.

     RETR_FUNC: is the function.

     Sets the function that will be used to retrieve data from the
     resumed sessions database.  This function must return a
     gnutls_datum_t containing the data on success, or a gnutls_datum_t
     containing null and 0 on failure.

     The datum's data must be allocated using the function
     'gnutls_malloc()' .

     The first argument to 'retr_func' will be null unless
     'gnutls_db_set_ptr()' has been called.

gnutls_db_set_store_function
----------------------------

 -- Function: void gnutls_db_set_store_function (gnutls_session_t
          SESSION, gnutls_db_store_func STORE_FUNC)
     SESSION: is a 'gnutls_session_t' type.

     STORE_FUNC: is the function

     Sets the function that will be used to store data in the resumed
     sessions database.  This function must return 0 on success.

     The first argument to 'store_func' will be null unless
     'gnutls_db_set_ptr()' has been called.

gnutls_deinit
-------------

 -- 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.

gnutls_dh_get_group
-------------------

 -- Function: int gnutls_dh_get_group (gnutls_session_t SESSION,
          gnutls_datum_t * RAW_GEN, gnutls_datum_t * RAW_PRIME)
     SESSION: is a gnutls session

     RAW_GEN: will hold the generator.

     RAW_PRIME: will hold the prime.

     This function will return the group parameters used in the last
     Diffie-Hellman key exchange with the peer.  These are the prime and
     the generator used.  This function should be used for both
     anonymous and ephemeral Diffie-Hellman.  The output parameters must
     be freed with 'gnutls_free()' .

     Note, that the prime and generator are exported as non-negative
     integers and may include a leading zero byte.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_dh_get_peers_public_bits
-------------------------------

 -- Function: int gnutls_dh_get_peers_public_bits (gnutls_session_t
          SESSION)
     SESSION: is a gnutls session

     Get the Diffie-Hellman public key bit size.  Can be used for both
     anonymous and ephemeral Diffie-Hellman.

     *Returns:* The public key bit size used in the last Diffie-Hellman
     key exchange with the peer, or a negative error code in case of
     error.

gnutls_dh_get_prime_bits
------------------------

 -- Function: int gnutls_dh_get_prime_bits (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     This function will return the bits of the prime used in the last
     Diffie-Hellman key exchange with the peer.  Should be used for both
     anonymous and ephemeral Diffie-Hellman.  Note that some ciphers,
     like RSA and DSA without DHE, do not use a Diffie-Hellman key
     exchange, and then this function will return 0.

     *Returns:* The Diffie-Hellman bit strength is returned, or 0 if no
     Diffie-Hellman key exchange was done, or a negative error code on
     failure.

gnutls_dh_get_pubkey
--------------------

 -- Function: int gnutls_dh_get_pubkey (gnutls_session_t SESSION,
          gnutls_datum_t * RAW_KEY)
     SESSION: is a gnutls session

     RAW_KEY: will hold the public key.

     This function will return the peer's public key used in the last
     Diffie-Hellman key exchange.  This function should be used for both
     anonymous and ephemeral Diffie-Hellman.  The output parameters must
     be freed with 'gnutls_free()' .

     Note, that public key is exported as non-negative integer and may
     include a leading zero byte.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_dh_get_secret_bits
-------------------------

 -- Function: int gnutls_dh_get_secret_bits (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     This function will return the bits used in the last Diffie-Hellman
     key exchange with the peer.  Should be used for both anonymous and
     ephemeral Diffie-Hellman.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_dh_params_cpy
--------------------

 -- Function: int gnutls_dh_params_cpy (gnutls_dh_params_t DST,
          gnutls_dh_params_t SRC)
     DST: Is the destination parameters, which should be initialized.

     SRC: Is the source parameters

     This function will copy the DH parameters structure from source to
     destination.  The destination should be already initialized.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_dh_params_deinit
-----------------------

 -- Function: void gnutls_dh_params_deinit (gnutls_dh_params_t
          DH_PARAMS)
     DH_PARAMS: The parameters

     This function will deinitialize the DH parameters type.

gnutls_dh_params_export2_pkcs3
------------------------------

 -- Function: int gnutls_dh_params_export2_pkcs3 (gnutls_dh_params_t
          PARAMS, gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
     PARAMS: Holds the DH parameters

     FORMAT: the format of output params.  One of PEM or DER.

     OUT: will contain a PKCS3 DHParams structure PEM or DER encoded

     This function will export the given dh parameters to a PKCS3
     DHParams structure.  This is the format generated by "openssl
     dhparam" tool.  The data in 'out' will be allocated using
     'gnutls_malloc()' .

     If the structure is PEM encoded, it will have a header of "BEGIN DH
     PARAMETERS".

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     *Since:* 3.1.3

gnutls_dh_params_export_pkcs3
-----------------------------

 -- Function: int gnutls_dh_params_export_pkcs3 (gnutls_dh_params_t
          PARAMS, gnutls_x509_crt_fmt_t FORMAT, unsigned char *
          PARAMS_DATA, size_t * PARAMS_DATA_SIZE)
     PARAMS: Holds the DH parameters

     FORMAT: the format of output params.  One of PEM or DER.

     PARAMS_DATA: will contain a PKCS3 DHParams structure PEM or DER
     encoded

     PARAMS_DATA_SIZE: holds the size of params_data (and will be
     replaced by the actual size of parameters)

     This function will export the given dh parameters to a PKCS3
     DHParams structure.  This is the format generated by "openssl
     dhparam" tool.  If the buffer provided is not long enough to hold
     the output, then GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.

     If the structure is PEM encoded, it will have a header of "BEGIN DH
     PARAMETERS".

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_dh_params_export_raw
---------------------------

 -- Function: int gnutls_dh_params_export_raw (gnutls_dh_params_t
          PARAMS, gnutls_datum_t * PRIME, gnutls_datum_t * GENERATOR,
          unsigned int * BITS)
     PARAMS: Holds the DH parameters

     PRIME: will hold the new prime

     GENERATOR: will hold the new generator

     BITS: if non null will hold the secret key's number of bits

     This function will export the pair of prime and generator for use
     in the Diffie-Hellman key exchange.  The new parameters will be
     allocated using 'gnutls_malloc()' and will be stored in the
     appropriate datum.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_dh_params_generate2
--------------------------

 -- Function: int gnutls_dh_params_generate2 (gnutls_dh_params_t
          DPARAMS, unsigned int BITS)
     DPARAMS: The parameters

     BITS: is the prime's number of bits

     This function will generate a new pair of prime and generator for
     use in the Diffie-Hellman key exchange.  This may take long time.

     It is recommended not to set the number of bits directly, but use
     'gnutls_sec_param_to_pk_bits()' instead.  Also note that the DH
     parameters are only useful to servers.  Since clients use the
     parameters sent by the server, it's of no use to call this in
     client side.

     The parameters generated are of the DSA form.  It also is possible
     to generate provable parameters (following the Shawe-Taylor
     algorithm), using 'gnutls_x509_privkey_generate2()' with DSA option
     and the 'GNUTLS_PRIVKEY_FLAG_PROVABLE' flag set.  These can the be
     imported with 'gnutls_dh_params_import_dsa()' .

     It is no longer recommended for applications to generate
     parameters.  See the "Parameter generation" section in the manual.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_dh_params_import_dsa
---------------------------

 -- Function: int gnutls_dh_params_import_dsa (gnutls_dh_params_t
          DH_PARAMS, gnutls_x509_privkey_t KEY)
     DH_PARAMS: The parameters

     KEY: holds a DSA private key

     This function will import the prime and generator of the DSA key
     for use in the Diffie-Hellman key exchange.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_dh_params_import_pkcs3
-----------------------------

 -- Function: int gnutls_dh_params_import_pkcs3 (gnutls_dh_params_t
          PARAMS, const gnutls_datum_t * PKCS3_PARAMS,
          gnutls_x509_crt_fmt_t FORMAT)
     PARAMS: The parameters

     PKCS3_PARAMS: should contain a PKCS3 DHParams structure PEM or DER
     encoded

     FORMAT: the format of params.  PEM or DER.

     This function will extract the DHParams found in a PKCS3 formatted
     structure.  This is the format generated by "openssl dhparam" tool.

     If the structure is PEM encoded, it should have a header of "BEGIN
     DH PARAMETERS".

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_dh_params_import_raw
---------------------------

 -- Function: int gnutls_dh_params_import_raw (gnutls_dh_params_t
          DH_PARAMS, const gnutls_datum_t * PRIME, const gnutls_datum_t
          * GENERATOR)
     DH_PARAMS: The parameters

     PRIME: holds the new prime

     GENERATOR: holds the new generator

     This function will replace the pair of prime and generator for use
     in the Diffie-Hellman key exchange.  The new parameters should be
     stored in the appropriate gnutls_datum.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_dh_params_import_raw2
----------------------------

 -- Function: int gnutls_dh_params_import_raw2 (gnutls_dh_params_t
          DH_PARAMS, const gnutls_datum_t * PRIME, const gnutls_datum_t
          * GENERATOR, unsigned KEY_BITS)
     DH_PARAMS: The parameters

     PRIME: holds the new prime

     GENERATOR: holds the new generator

     KEY_BITS: the private key bits (set to zero when unknown)

     This function will replace the pair of prime and generator for use
     in the Diffie-Hellman key exchange.  The new parameters should be
     stored in the appropriate gnutls_datum.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_dh_params_init
---------------------

 -- Function: int gnutls_dh_params_init (gnutls_dh_params_t * DH_PARAMS)
     DH_PARAMS: The parameters

     This function will initialize the DH parameters type.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_dh_set_prime_bits
------------------------

 -- Function: void gnutls_dh_set_prime_bits (gnutls_session_t SESSION,
          unsigned int BITS)
     SESSION: is a 'gnutls_session_t' type.

     BITS: is the number of bits

     This function sets the number of bits, for use in a Diffie-Hellman
     key exchange.  This is used both in DH ephemeral and DH anonymous
     cipher suites.  This will set the minimum size of the prime that
     will be used for the handshake.

     In the client side it sets the minimum accepted number of bits.  If
     a server sends a prime with less bits than that
     'GNUTLS_E_DH_PRIME_UNACCEPTABLE' will be returned by the handshake.

     Note that this function will warn via the audit log for value that
     are believed to be weak.

     The function has no effect in server side.

     Note that since 3.1.7 this function is deprecated.  The minimum
     number of bits is set by the priority string level.  Also this
     function must be called after 'gnutls_priority_set_direct()' or the
     set value may be overridden by the selected priority options.

gnutls_digest_get_id
--------------------

 -- Function: gnutls_digest_algorithm_t gnutls_digest_get_id (const char
          * NAME)
     NAME: is a digest algorithm name

     Convert a string to a 'gnutls_digest_algorithm_t' value.  The names
     are compared in a case insensitive way.

     *Returns:* a 'gnutls_digest_algorithm_t' id of the specified MAC
     algorithm string, or 'GNUTLS_DIG_UNKNOWN' on failure.

gnutls_digest_get_name
----------------------

 -- Function: const char * gnutls_digest_get_name
          (gnutls_digest_algorithm_t ALGORITHM)
     ALGORITHM: is a digest algorithm

     Convert a 'gnutls_digest_algorithm_t' value to a string.

     *Returns:* a string that contains the name of the specified digest
     algorithm, or 'NULL' .

gnutls_digest_get_oid
---------------------

 -- Function: const char * gnutls_digest_get_oid
          (gnutls_digest_algorithm_t ALGORITHM)
     ALGORITHM: is a digest algorithm

     Convert a 'gnutls_digest_algorithm_t' value to its object
     identifier.

     *Returns:* a string that contains the object identifier of the
     specified digest algorithm, or 'NULL' .

     *Since:* 3.4.3

gnutls_digest_list
------------------

 -- Function: const gnutls_digest_algorithm_t * gnutls_digest_list (
          VOID)

     Get a list of hash (digest) algorithms supported by GnuTLS.

     This function is not thread safe.

     *Returns:* Return a (0)-terminated list of
     'gnutls_digest_algorithm_t' integers indicating the available
     digests.

gnutls_ecc_curve_get
--------------------

 -- Function: gnutls_ecc_curve_t gnutls_ecc_curve_get (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Returns the currently used elliptic curve for key exchange.  Only
     valid when using an elliptic curve ciphersuite.

     *Returns:* the currently used curve, a 'gnutls_ecc_curve_t' type.

     *Since:* 3.0

gnutls_ecc_curve_get_id
-----------------------

 -- Function: gnutls_ecc_curve_t gnutls_ecc_curve_get_id (const char *
          NAME)
     NAME: is a curve name

     The names are compared in a case insensitive way.

     *Returns:* return a 'gnutls_ecc_curve_t' value corresponding to the
     specified curve, or 'GNUTLS_ECC_CURVE_INVALID' on error.

     *Since:* 3.4.3

gnutls_ecc_curve_get_name
-------------------------

 -- Function: const char * gnutls_ecc_curve_get_name (gnutls_ecc_curve_t
          CURVE)
     CURVE: is an ECC curve

     Convert a 'gnutls_ecc_curve_t' value to a string.

     *Returns:* a string that contains the name of the specified curve
     or 'NULL' .

     *Since:* 3.0

gnutls_ecc_curve_get_oid
------------------------

 -- Function: const char * gnutls_ecc_curve_get_oid (gnutls_ecc_curve_t
          CURVE)
     CURVE: is an ECC curve

     Convert a 'gnutls_ecc_curve_t' value to its object identifier.

     *Returns:* a string that contains the OID of the specified curve or
     'NULL' .

     *Since:* 3.4.3

gnutls_ecc_curve_get_pk
-----------------------

 -- Function: gnutls_pk_algorithm_t gnutls_ecc_curve_get_pk
          (gnutls_ecc_curve_t CURVE)
     CURVE: is an ECC curve

     *Returns:* the public key algorithm associated with the named curve
     or 'GNUTLS_PK_UNKNOWN' .

     *Since:* 3.5.0

gnutls_ecc_curve_get_size
-------------------------

 -- Function: int gnutls_ecc_curve_get_size (gnutls_ecc_curve_t CURVE)
     CURVE: is an ECC curve

     *Returns:* the size in bytes of the curve or 0 on failure.

     *Since:* 3.0

gnutls_ecc_curve_list
---------------------

 -- Function: const gnutls_ecc_curve_t * gnutls_ecc_curve_list ( VOID)

     Get the list of supported elliptic curves.

     This function is not thread safe.

     *Returns:* Return a (0)-terminated list of 'gnutls_ecc_curve_t'
     integers indicating the available curves.

gnutls_error_is_fatal
---------------------

 -- 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.

gnutls_error_to_alert
---------------------

 -- 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.

gnutls_est_record_overhead_size
-------------------------------

 -- Function: size_t gnutls_est_record_overhead_size (gnutls_protocol_t
          VERSION, gnutls_cipher_algorithm_t CIPHER,
          gnutls_mac_algorithm_t MAC, gnutls_compression_method_t COMP,
          unsigned int FLAGS)
     VERSION: is a 'gnutls_protocol_t' value

     CIPHER: is a 'gnutls_cipher_algorithm_t' value

     MAC: is a 'gnutls_mac_algorithm_t' value

     COMP: is a 'gnutls_compression_method_t' value (ignored)

     FLAGS: must be zero

     This function will return the set size in bytes of the overhead due
     to TLS (or DTLS) per record.

     Note that this function may provide inacurate values when TLS
     extensions that modify the record format are negotiated.  In these
     cases a more accurate value can be obtained using
     'gnutls_record_overhead_size()' after a completed handshake.

     *Since:* 3.2.2

gnutls_ext_get_current_msg
--------------------------

 -- Function: unsigned gnutls_ext_get_current_msg (gnutls_session_t
          SESSION)
     SESSION: a 'gnutls_session_t' opaque pointer

     This function allows an extension handler to obtain the message
     this extension is being called from.  The returned value is a
     single entry of the 'gnutls_ext_flags_t' enumeration.  That is, if
     an extension was registered with the 'GNUTLS_EXT_FLAG_HRR' and
     'GNUTLS_EXT_FLAG_EE' flags, the value when called during parsing of
     the encrypted extensions message will be 'GNUTLS_EXT_FLAG_EE' .

     If not called under an extension handler, its value is undefined.

     *Since:* 3.6.3

gnutls_ext_get_data
-------------------

 -- Function: int gnutls_ext_get_data (gnutls_session_t SESSION,
          unsigned TLS_ID, gnutls_ext_priv_data_t * DATA)
     SESSION: a 'gnutls_session_t' opaque pointer

     TLS_ID: the numeric id of the extension

     DATA: a pointer to the private data to retrieve

     This function retrieves any data previously stored with
     'gnutls_ext_set_data()' .

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.4.0

gnutls_ext_get_name
-------------------

 -- Function: const char * gnutls_ext_get_name (unsigned int EXT)
     EXT: is a TLS extension numeric ID

     Convert a TLS extension numeric ID to a printable string.

     *Returns:* a pointer to a string that contains the name of the
     specified cipher, or 'NULL' .

gnutls_ext_raw_parse
--------------------

 -- Function: int gnutls_ext_raw_parse (void * CTX,
          gnutls_ext_raw_process_func CB, const gnutls_datum_t * DATA,
          unsigned int FLAGS)
     CTX: a pointer to pass to callback function

     CB: callback function to process each extension found

     DATA: TLS extension data

     FLAGS: should be zero or 'GNUTLS_EXT_RAW_FLAG_TLS_CLIENT_HELLO' or
     'GNUTLS_EXT_RAW_FLAG_DTLS_CLIENT_HELLO'

     This function iterates through the TLS extensions as passed in
     'data' , passing the individual extension data to callback.  The
     'data' must conform to Extension extensions<0..2^16-1> format.

     If flags is 'GNUTLS_EXT_RAW_TLS_FLAG_CLIENT_HELLO' then this
     function will parse the extension data from the position, as if the
     packet in 'data' is a client hello (without record or handshake
     headers) - as provided by 'gnutls_handshake_set_hook_function()' .

     The return value of the callback will be propagated.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.  On
     unknown flags it returns 'GNUTLS_E_INVALID_REQUEST' .

     *Since:* 3.6.3

gnutls_ext_register
-------------------

 -- Function: int gnutls_ext_register (const char * NAME, int ID,
          gnutls_ext_parse_type_t PARSE_TYPE, gnutls_ext_recv_func
          RECV_FUNC, gnutls_ext_send_func SEND_FUNC,
          gnutls_ext_deinit_data_func DEINIT_FUNC, gnutls_ext_pack_func
          PACK_FUNC, gnutls_ext_unpack_func UNPACK_FUNC)
     NAME: the name of the extension to register

     ID: the numeric TLS id of the extension

     PARSE_TYPE: the parse type of the extension (see
     gnutls_ext_parse_type_t)

     RECV_FUNC: a function to receive the data

     SEND_FUNC: a function to send the data

     DEINIT_FUNC: a function deinitialize any private data

     PACK_FUNC: a function which serializes the extension's private data
     (used on session packing for resumption)

     UNPACK_FUNC: a function which will deserialize the extension's
     private data

     This function will register a new extension type.  The extension
     will remain registered until 'gnutls_global_deinit()' is called.
     If the extension type is already registered then
     'GNUTLS_E_ALREADY_REGISTERED' will be returned.

     Each registered extension can store temporary data into the
     gnutls_session_t structure using 'gnutls_ext_set_data()' , and they
     can be retrieved using 'gnutls_ext_get_data()' .

     Any extensions registered with this function are valid for the
     client and TLS1.2 server hello (or encrypted extensions for
     TLS1.3).

     This function is not thread safe.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.4.0

gnutls_ext_set_data
-------------------

 -- Function: void gnutls_ext_set_data (gnutls_session_t SESSION,
          unsigned TLS_ID, gnutls_ext_priv_data_t DATA)
     SESSION: a 'gnutls_session_t' opaque pointer

     TLS_ID: the numeric id of the extension

     DATA: the private data to set

     This function allows an extension handler to store data in the
     current session and retrieve them later on.  The set data will be
     deallocated using the gnutls_ext_deinit_data_func.

     *Since:* 3.4.0

gnutls_fingerprint
------------------

 -- Function: int gnutls_fingerprint (gnutls_digest_algorithm_t ALGO,
          const gnutls_datum_t * DATA, void * RESULT, size_t *
          RESULT_SIZE)
     ALGO: is a digest algorithm

     DATA: is the data

     RESULT: is the place where the result will be copied (may be null).

     RESULT_SIZE: should hold the size of the result.  The actual size
     of the returned result will also be copied there.

     This function will calculate a fingerprint (actually a hash), of
     the given data.  The result is not printable data.  You should
     convert it to hex, or to something else printable.

     This is the usual way to calculate a fingerprint of an X.509 DER
     encoded certificate.  Note however that the fingerprint of an
     OpenPGP certificate is not just a hash and cannot be calculated
     with this function.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_fips140_mode_enabled
---------------------------

 -- Function: unsigned gnutls_fips140_mode_enabled ( VOID)

     Checks whether this library is in FIPS140 mode.  The returned value
     corresponds to the library mode as set with
     'gnutls_fips140_set_mode()' .

     If 'gnutls_fips140_set_mode()' was called with
     'GNUTLS_FIPS140_SET_MODE_THREAD' then this function will return the
     current thread's FIPS140 mode, otherwise the global value is
     returned.

     *Returns:* return non-zero if true or zero if false.

     *Since:* 3.3.0

gnutls_fips140_set_mode
-----------------------

 -- Function: void gnutls_fips140_set_mode (gnutls_fips_mode_t MODE,
          unsigned FLAGS)
     MODE: the FIPS140-2 mode to switch to

     FLAGS: should be zero or 'GNUTLS_FIPS140_SET_MODE_THREAD'

     That function is not thread-safe when changing the mode with no
     flags (globally), and should be called prior to creating any
     threads.  Its behavior with no flags after threads are created is
     undefined.

     When the flag 'GNUTLS_FIPS140_SET_MODE_THREAD' is specified then
     this call will change the FIPS140-2 mode for this particular thread
     and not for the whole process.  That way an application can utilize
     this function to set and reset mode for specific operations.

     This function never fails but will be a no-op if used when the
     library is not in FIPS140-2 mode.  When asked to switch to unknown
     values for 'mode' or to 'GNUTLS_FIPS140_SELFTESTS' mode, the
     library switches to 'GNUTLS_FIPS140_STRICT' mode.

     *Since:* 3.6.2

gnutls_global_deinit
--------------------

 -- Function: void gnutls_global_deinit ( VOID)

     This function deinitializes the global data, that were initialized
     using 'gnutls_global_init()' .

     Since GnuTLS 3.3.0 this function is no longer necessary to be
     explicitly called.  GnuTLS will automatically deinitialize on
     library destructor.  See 'gnutls_global_init()' for disabling the
     implicit initialization/deinitialization.

gnutls_global_init
------------------

 -- Function: int gnutls_global_init ( VOID)

     Since GnuTLS 3.3.0 this function is no longer necessary to be
     explicitly called.  To disable the implicit call (in a library
     constructor) of this function set the environment variable
     'GNUTLS_NO_EXPLICIT_INIT' to 1.

     This function performs any required precalculations, detects the
     supported CPU capabilities and initializes the underlying
     cryptographic backend.  In order to free any resources taken by
     this call you should 'gnutls_global_deinit()' when gnutls usage is
     no longer needed.

     This function increments a global counter, so that
     'gnutls_global_deinit()' only releases resources when it has been
     called as many times as 'gnutls_global_init()' .  This is useful
     when GnuTLS is used by more than one library in an application.
     This function can be called many times, but will only do something
     the first time.

     A subsequent call of this function if the initial has failed will
     return the same error code.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_global_set_audit_log_function
------------------------------------

 -- 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

gnutls_global_set_log_function
------------------------------

 -- Function: void gnutls_global_set_log_function (gnutls_log_func
          LOG_FUNC)
     LOG_FUNC: it's a log function

     This is the function where you set the logging function gnutls is
     going to use.  This function only accepts a character array.
     Normally you may not use this function since it is only used for
     debugging purposes.

     'gnutls_log_func' is of the form, void (*gnutls_log_func)( int
     level, const char*);

gnutls_global_set_log_level
---------------------------

 -- Function: void gnutls_global_set_log_level (int LEVEL)
     LEVEL: it's an integer from 0 to 99.

     This is the function that allows you to set the log level.  The
     level is an integer between 0 and 9.  Higher values mean more
     verbosity.  The default value is 0.  Larger values should only be
     used with care, since they may reveal sensitive information.

     Use a log level over 10 to enable all debugging options.

gnutls_global_set_mutex
-----------------------

 -- Function: void gnutls_global_set_mutex (mutex_init_func INIT,
          mutex_deinit_func DEINIT, mutex_lock_func LOCK,
          mutex_unlock_func UNLOCK)
     INIT: mutex initialization function

     DEINIT: mutex deinitialization function

     LOCK: mutex locking function

     UNLOCK: mutex unlocking function

     With this function you are allowed to override the default mutex
     locks used in some parts of gnutls and dependent libraries.  This
     function should be used if you have complete control of your
     program and libraries.  Do not call this function from a library,
     or preferably from any application unless really needed to.  GnuTLS
     will use the appropriate locks for the running system.

     Note that since the move to implicit initialization of GnuTLS on
     library load, calling this function will deinitialize the library,
     and re-initialize it after the new locking functions are set.

     This function must be called prior to any other gnutls function.

     *Since:* 2.12.0

gnutls_global_set_time_function
-------------------------------

 -- Function: void gnutls_global_set_time_function (gnutls_time_func
          TIME_FUNC)
     TIME_FUNC: it's the system time function, a 'gnutls_time_func()'
     callback.

     This is the function where you can override the default system time
     function.  The application provided function should behave the same
     as the standard function.

     *Since:* 2.12.0

gnutls_gost_paramset_get_name
-----------------------------

 -- Function: const char * gnutls_gost_paramset_get_name
          (gnutls_gost_paramset_t PARAM)
     PARAM: is a GOST 28147 param set

     Convert a 'gnutls_gost_paramset_t' value to a string.

     *Returns:* a string that contains the name of the specified GOST
     param set, or 'NULL' .

     *Since:* 3.6.3

gnutls_gost_paramset_get_oid
----------------------------

 -- Function: const char * gnutls_gost_paramset_get_oid
          (gnutls_gost_paramset_t PARAM)
     PARAM: is a GOST 28147 param set

     Convert a 'gnutls_gost_paramset_t' value to its object identifier.

     *Returns:* a string that contains the object identifier of the
     specified GOST param set, or 'NULL' .

     *Since:* 3.6.3

gnutls_group_get
----------------

 -- Function: gnutls_group_t gnutls_group_get (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Returns the currently used group for key exchange.  Only valid when
     using an elliptic curve or DH ciphersuite.

     *Returns:* the currently used group, a 'gnutls_group_t' type.

     *Since:* 3.6.0

gnutls_group_get_id
-------------------

 -- Function: gnutls_group_t gnutls_group_get_id (const char * NAME)
     NAME: is a group name

     The names are compared in a case insensitive way.

     *Returns:* return a 'gnutls_group_t' value corresponding to the
     specified group, or 'GNUTLS_GROUP_INVALID' on error.

     *Since:* 3.6.0

gnutls_group_get_name
---------------------

 -- Function: const char * gnutls_group_get_name (gnutls_group_t GROUP)
     GROUP: is an element from 'gnutls_group_t'

     Convert a 'gnutls_group_t' value to a string.

     *Returns:* a string that contains the name of the specified group
     or 'NULL' .

     *Since:* 3.6.0

gnutls_group_list
-----------------

 -- Function: const gnutls_group_t * gnutls_group_list ( VOID)

     Get the list of supported elliptic curves.

     This function is not thread safe.

     *Returns:* Return a (0)-terminated list of 'gnutls_group_t'
     integers indicating the available groups.

     *Since:* 3.6.0

gnutls_handshake
----------------

 -- 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.

gnutls_handshake_description_get_name
-------------------------------------

 -- Function: const char * gnutls_handshake_description_get_name
          (gnutls_handshake_description_t TYPE)
     TYPE: is a handshake message description

     Convert a 'gnutls_handshake_description_t' value to a string.

     *Returns:* a string that contains the name of the specified
     handshake message or 'NULL' .

gnutls_handshake_get_last_in
----------------------------

 -- Function: gnutls_handshake_description_t
          gnutls_handshake_get_last_in (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     This function is only useful to check where the last performed
     handshake failed.  If the previous handshake succeed or was not
     performed at all then no meaningful value will be returned.

     Check 'gnutls_handshake_description_t' in gnutls.h for the
     available handshake descriptions.

     *Returns:* the last handshake message type received, a
     'gnutls_handshake_description_t' .

gnutls_handshake_get_last_out
-----------------------------

 -- Function: gnutls_handshake_description_t
          gnutls_handshake_get_last_out (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     This function is only useful to check where the last performed
     handshake failed.  If the previous handshake succeed or was not
     performed at all then no meaningful value will be returned.

     Check 'gnutls_handshake_description_t' in gnutls.h for the
     available handshake descriptions.

     *Returns:* the last handshake message type sent, a
     'gnutls_handshake_description_t' .

gnutls_handshake_set_hook_function
----------------------------------

 -- 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.

gnutls_handshake_set_max_packet_length
--------------------------------------

 -- Function: void gnutls_handshake_set_max_packet_length
          (gnutls_session_t SESSION, size_t MAX)
     SESSION: is a 'gnutls_session_t' type.

     MAX: is the maximum number.

     This function will set the maximum size of all handshake messages.
     Handshakes over this size are rejected with
     'GNUTLS_E_HANDSHAKE_TOO_LARGE' error code.  The default value is
     128kb which is typically large enough.  Set this to 0 if you do not
     want to set an upper limit.

     The reason for restricting the handshake message sizes are to limit
     Denial of Service attacks.

     Note that the maximum handshake size was increased to 128kb from
     48kb in GnuTLS 3.5.5.

gnutls_handshake_set_post_client_hello_function
-----------------------------------------------

 -- Function: void gnutls_handshake_set_post_client_hello_function
          (gnutls_session_t SESSION, gnutls_handshake_simple_hook_func
          FUNC)
     SESSION: is a 'gnutls_session_t' type.

     FUNC: is the function to be called

     This function will set a callback to be called after the client
     hello has been received (callback valid in server side only).  This
     allows the server to adjust settings based on received extensions.

     Those settings could be ciphersuites, requesting certificate, or
     anything else except for version negotiation (this is done before
     the hello message is parsed).

     This callback must return 0 on success or a gnutls error code to
     terminate the handshake.

     Since GnuTLS 3.3.5 the callback is allowed to return
     'GNUTLS_E_AGAIN' or 'GNUTLS_E_INTERRUPTED' to put the handshake on
     hold.  In that case 'gnutls_handshake()' will return
     'GNUTLS_E_INTERRUPTED' and can be resumed when needed.

     *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.

gnutls_handshake_set_private_extensions
---------------------------------------

 -- Function: void gnutls_handshake_set_private_extensions
          (gnutls_session_t SESSION, int ALLOW)
     SESSION: is a 'gnutls_session_t' type.

     ALLOW: is an integer (0 or 1)

     This function will enable or disable the use of private cipher
     suites (the ones that start with 0xFF). By default or if 'allow' is
     0 then these cipher suites will not be advertised nor used.

     Currently GnuTLS does not include such cipher-suites or compression
     algorithms.

     Enabling the private ciphersuites when talking to other than gnutls
     servers and clients may cause interoperability problems.

gnutls_handshake_set_random
---------------------------

 -- Function: int gnutls_handshake_set_random (gnutls_session_t SESSION,
          const gnutls_datum_t * RANDOM)
     SESSION: is a 'gnutls_session_t' type.

     RANDOM: a random value of 32-bytes

     This function will explicitly set the server or client hello random
     value in the subsequent TLS handshake.  The random value should be
     a 32-byte value.

     Note that this function should not normally be used as gnutls will
     select automatically a random value for the handshake.

     This function should not be used when resuming a session.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

     Since 3.1.9

gnutls_handshake_set_timeout
----------------------------

 -- 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

gnutls_heartbeat_allowed
------------------------

 -- Function: unsigned gnutls_heartbeat_allowed (gnutls_session_t
          SESSION, unsigned int TYPE)
     SESSION: is a 'gnutls_session_t' type.

     TYPE: one of 'GNUTLS_HB_LOCAL_ALLOWED_TO_SEND' and
     'GNUTLS_HB_PEER_ALLOWED_TO_SEND'

     This function will check whether heartbeats are allowed to be sent
     or received in this session.

     *Returns:* Non zero if heartbeats are allowed.

     *Since:* 3.1.2

gnutls_heartbeat_enable
-----------------------

 -- Function: void gnutls_heartbeat_enable (gnutls_session_t SESSION,
          unsigned int TYPE)
     SESSION: is a 'gnutls_session_t' type.

     TYPE: one of the GNUTLS_HB_* flags

     If this function is called with the
     'GNUTLS_HB_PEER_ALLOWED_TO_SEND' 'type' , GnuTLS will allow
     heartbeat messages to be received.  Moreover it also request the
     peer to accept heartbeat messages.  This function must be called
     prior to TLS handshake.

     If the 'type' used is 'GNUTLS_HB_LOCAL_ALLOWED_TO_SEND' , then the
     peer will be asked to accept heartbeat messages but not send ones.

     The function 'gnutls_heartbeat_allowed()' can be used to test
     Whether locally generated heartbeat messages can be accepted by the
     peer.

     *Since:* 3.1.2

gnutls_heartbeat_get_timeout
----------------------------

 -- Function: unsigned int gnutls_heartbeat_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 ping message.  This function
     is useful when ping is used in non-blocking mode, to estimate when
     to call 'gnutls_heartbeat_ping()' if no packets have been received.

     *Returns:* the remaining time in milliseconds.

     *Since:* 3.1.2

gnutls_heartbeat_ping
---------------------

 -- Function: int gnutls_heartbeat_ping (gnutls_session_t SESSION,
          size_t DATA_SIZE, unsigned int MAX_TRIES, unsigned int FLAGS)
     SESSION: is a 'gnutls_session_t' type.

     DATA_SIZE: is the length of the ping payload.

     MAX_TRIES: if flags is 'GNUTLS_HEARTBEAT_WAIT' then this sets the
     number of retransmissions.  Use zero for indefinite (until
     timeout).

     FLAGS: if 'GNUTLS_HEARTBEAT_WAIT' then wait for pong or timeout
     instead of returning immediately.

     This function sends a ping to the peer.  If the 'flags' is set to
     'GNUTLS_HEARTBEAT_WAIT' then it waits for a reply from the peer.

     Note that it is highly recommended to use this function with the
     flag 'GNUTLS_HEARTBEAT_WAIT' , or you need to handle
     retransmissions and timeouts manually.

     The total TLS data transmitted as part of the ping message are
     given by the following formula: MAX(16, 'data_size'
     )+'gnutls_record_overhead_size()' +3.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.1.2

gnutls_heartbeat_pong
---------------------

 -- Function: int gnutls_heartbeat_pong (gnutls_session_t SESSION,
          unsigned int FLAGS)
     SESSION: is a 'gnutls_session_t' type.

     FLAGS: should be zero

     This function replies to a ping by sending a pong to the peer.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.1.2

gnutls_heartbeat_set_timeouts
-----------------------------

 -- Function: void gnutls_heartbeat_set_timeouts (gnutls_session_t
          SESSION, unsigned int RETRANS_TIMEOUT, unsigned int
          TOTAL_TIMEOUT)
     SESSION: is a 'gnutls_session_t' type.

     RETRANS_TIMEOUT: The time at which a retransmission will occur in
     milliseconds

     TOTAL_TIMEOUT: The time at which the connection will be aborted, in
     milliseconds.

     This function will override the timeouts for the DTLS heartbeat
     protocol.  The retransmission timeout is the time after which a
     message from the peer is not received, the previous request will be
     retransmitted.  The total timeout is the time after which the
     handshake will be aborted with 'GNUTLS_E_TIMEDOUT' .

     *Since:* 3.1.2

gnutls_hex2bin
--------------

 -- Function: int gnutls_hex2bin (const char * HEX_DATA, size_t
          HEX_SIZE, void * BIN_DATA, size_t * BIN_SIZE)
     HEX_DATA: string with data in hex format

     HEX_SIZE: size of hex data

     BIN_DATA: output array with binary data

     BIN_SIZE: when calling should hold maximum size of 'bin_data' , on
     return will hold actual length of 'bin_data' .

     Convert a buffer with hex data to binary data.  This function
     unlike 'gnutls_hex_decode()' can parse hex data with separators
     between numbers.  That is, it ignores any non-hex characters.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 2.4.0

gnutls_hex_decode
-----------------

 -- Function: int gnutls_hex_decode (const gnutls_datum_t * HEX_DATA,
          void * RESULT, size_t * RESULT_SIZE)
     HEX_DATA: contain the encoded data

     RESULT: the place where decoded data will be copied

     RESULT_SIZE: holds the size of the result

     This function will decode the given encoded data, using the hex
     encoding used by PSK password files.

     Initially 'result_size' must hold the maximum size available in
     'result' , and on return it will contain the number of bytes
     written.

     *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
     not long enough, 'GNUTLS_E_PARSING_ERROR' on invalid hex data, or 0
     on success.

gnutls_hex_decode2
------------------

 -- Function: int gnutls_hex_decode2 (const gnutls_datum_t * HEX_DATA,
          gnutls_datum_t * RESULT)
     HEX_DATA: contain the encoded data

     RESULT: the result in an allocated string

     This function will decode the given encoded data, using the hex
     encoding used by PSK password files.

     *Returns:* 'GNUTLS_E_PARSING_ERROR' on invalid hex data, or 0 on
     success.

gnutls_hex_encode
-----------------

 -- Function: int gnutls_hex_encode (const gnutls_datum_t * DATA, char *
          RESULT, size_t * RESULT_SIZE)
     DATA: contain the raw data

     RESULT: the place where hex data will be copied

     RESULT_SIZE: holds the size of the result

     This function will convert the given data to printable data, using
     the hex encoding, as used in the PSK password files.

     Note that the size of the result includes the null terminator.

     *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
     not long enough, or 0 on success.

gnutls_hex_encode2
------------------

 -- Function: int gnutls_hex_encode2 (const gnutls_datum_t * DATA,
          gnutls_datum_t * RESULT)
     DATA: contain the raw data

     RESULT: the result in an allocated string

     This function will convert the given data to printable data, using
     the hex encoding, as used in the PSK password files.

     Note that the size of the result does NOT include the null
     terminator.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

gnutls_idna_map
---------------

 -- Function: int gnutls_idna_map (const char * INPUT, unsigned ILEN,
          gnutls_datum_t * OUT, unsigned FLAGS)
     INPUT: contain the UTF-8 formatted domain name

     ILEN: the length of the provided string

     OUT: the result in an null-terminated allocated string

     FLAGS: should be zero

     This function will convert the provided UTF-8 domain name, to its
     IDNA mapping in an allocated variable.  Note that depending on the
     flags the used gnutls library was compiled with, the output of this
     function may vary (i.e., may be IDNA2008, or IDNA2003).

     To force IDNA2008 specify the flag 'GNUTLS_IDNA_FORCE_2008' .  In
     the case GnuTLS is not compiled with the necessary dependencies,
     'GNUTLS_E_UNIMPLEMENTED_FEATURE' will be returned to indicate that
     gnutls is unable to perform the requested conversion.

     Note also, that this function will return an empty string if an
     empty string is provided as input.

     *Returns:* 'GNUTLS_E_INVALID_UTF8_STRING' on invalid UTF-8 data, or
     0 on success.

     *Since:* 3.5.8

gnutls_idna_reverse_map
-----------------------

 -- Function: int gnutls_idna_reverse_map (const char * INPUT, unsigned
          ILEN, gnutls_datum_t * OUT, unsigned FLAGS)
     INPUT: contain the ACE (IDNA) formatted domain name

     ILEN: the length of the provided string

     OUT: the result in an null-terminated allocated UTF-8 string

     FLAGS: should be zero

     This function will convert an ACE (ASCII-encoded) domain name to a
     UTF-8 domain name.

     If GnuTLS is compiled without IDNA support, then this function will
     return 'GNUTLS_E_UNIMPLEMENTED_FEATURE' .

     Note also, that this function will return an empty string if an
     empty string is provided as input.

     *Returns:* A negative error code on error, or 0 on success.

     *Since:* 3.5.8

gnutls_init
-----------

 -- 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_key_generate
-------------------

 -- Function: int gnutls_key_generate (gnutls_datum_t * KEY, unsigned
          int KEY_SIZE)
     KEY: is a pointer to a 'gnutls_datum_t' which will contain a newly
     created key

     KEY_SIZE: the number of bytes of the key

     Generates a random key of 'key_size' bytes.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
     error code.

     *Since:* 3.0

gnutls_kx_get
-------------

 -- Function: gnutls_kx_algorithm_t gnutls_kx_get (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Get the currently used key exchange algorithm.

     This function will return 'GNUTLS_KX_ECDHE_RSA' , or
     'GNUTLS_KX_DHE_RSA' under TLS 1.3, to indicate an elliptic curve DH
     key exchange or a finite field one.  The precise group used is
     available by calling 'gnutls_group_get()' instead.

     *Returns:* the key exchange algorithm used in the last handshake, a
     'gnutls_kx_algorithm_t' value.

gnutls_kx_get_id
----------------

 -- Function: gnutls_kx_algorithm_t gnutls_kx_get_id (const char * NAME)
     NAME: is a KX name

     Convert a string to a 'gnutls_kx_algorithm_t' value.  The names are
     compared in a case insensitive way.

     *Returns:* an id of the specified KX algorithm, or
     'GNUTLS_KX_UNKNOWN' on error.

gnutls_kx_get_name
------------------

 -- Function: const char * gnutls_kx_get_name (gnutls_kx_algorithm_t
          ALGORITHM)
     ALGORITHM: is a key exchange algorithm

     Convert a 'gnutls_kx_algorithm_t' value to a string.

     *Returns:* a pointer to a string that contains the name of the
     specified key exchange algorithm, or 'NULL' .

gnutls_kx_list
--------------

 -- Function: const gnutls_kx_algorithm_t * gnutls_kx_list ( VOID)

     Get a list of supported key exchange algorithms.

     This function is not thread safe.

     *Returns:* a (0)-terminated list of 'gnutls_kx_algorithm_t'
     integers indicating the available key exchange algorithms.

gnutls_load_file
----------------

 -- Function: int gnutls_load_file (const char * FILENAME,
          gnutls_datum_t * DATA)
     FILENAME: the name of the file to load

     DATA: Where the file will be stored

     This function will load a file into a datum.  The data are zero
     terminated but the terminating null is not included in length.  The
     returned data are allocated using 'gnutls_malloc()' .

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

     Since 3.1.0

gnutls_mac_get
--------------

 -- Function: gnutls_mac_algorithm_t gnutls_mac_get (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Get the currently used MAC algorithm.

     *Returns:* the currently used mac algorithm, a
     'gnutls_mac_algorithm_t' value.

gnutls_mac_get_id
-----------------

 -- Function: gnutls_mac_algorithm_t gnutls_mac_get_id (const char *
          NAME)
     NAME: is a MAC algorithm name

     Convert a string to a 'gnutls_mac_algorithm_t' value.  The names
     are compared in a case insensitive way.

     *Returns:* a 'gnutls_mac_algorithm_t' id of the specified MAC
     algorithm string, or 'GNUTLS_MAC_UNKNOWN' on failure.

gnutls_mac_get_key_size
-----------------------

 -- Function: size_t gnutls_mac_get_key_size (gnutls_mac_algorithm_t
          ALGORITHM)
     ALGORITHM: is an encryption algorithm

     Returns the size of the MAC key used in TLS.

     *Returns:* length (in bytes) of the given MAC key size, or 0 if the
     given MAC algorithm is invalid.

gnutls_mac_get_name
-------------------

 -- Function: const char * gnutls_mac_get_name (gnutls_mac_algorithm_t
          ALGORITHM)
     ALGORITHM: is a MAC algorithm

     Convert a 'gnutls_mac_algorithm_t' value to a string.

     *Returns:* a string that contains the name of the specified MAC
     algorithm, or 'NULL' .

gnutls_mac_list
---------------

 -- Function: const gnutls_mac_algorithm_t * gnutls_mac_list ( VOID)

     Get a list of hash algorithms for use as MACs.  Note that not
     necessarily all MACs are supported in TLS cipher suites.  This
     function is not thread safe.

     *Returns:* Return a (0)-terminated list of 'gnutls_mac_algorithm_t'
     integers indicating the available MACs.

gnutls_memcmp
-------------

 -- Function: int gnutls_memcmp (const void * S1, const void * S2,
          size_t N)
     S1: the first address to compare

     S2: the second address to compare

     N: the size of memory to compare

     This function will operate similarly to 'memcmp()' , but will
     operate on time that depends only on the size of the string.  That
     is will not return early if the strings don't match on the first
     byte.

     *Returns:* non zero on difference and zero if the buffers are
     identical.

     *Since:* 3.4.0

gnutls_memset
-------------

 -- Function: void gnutls_memset (void * DATA, int C, size_t SIZE)
     DATA: the memory to set

     C: the constant byte to fill the memory with

     SIZE: the size of memory

     This function will operate similarly to 'memset()' , but will not
     be optimized out by the compiler.

     *Since:* 3.4.0

gnutls_ocsp_status_request_enable_client
----------------------------------------

 -- Function: int gnutls_ocsp_status_request_enable_client
          (gnutls_session_t SESSION, gnutls_datum_t * RESPONDER_ID,
          size_t RESPONDER_ID_SIZE, gnutls_datum_t * EXTENSIONS)
     SESSION: is a 'gnutls_session_t' type.

     RESPONDER_ID: ignored, must be 'NULL'

     RESPONDER_ID_SIZE: ignored, must be zero

     EXTENSIONS: ignored, must be 'NULL'

     This function is to be used by clients to request OCSP response
     from the server, using the "status_request" TLS extension.  Only
     OCSP status type is supported.

     Previous versions of GnuTLS supported setting 'responder_id' and
     'extensions' fields, but due to the difficult semantics of the
     parameter usage, and other issues, this support was removed since
     3.6.0 and these parameters must be set to 'NULL' .

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     *Since:* 3.1.3

gnutls_ocsp_status_request_get
------------------------------

 -- Function: int gnutls_ocsp_status_request_get (gnutls_session_t
          SESSION, gnutls_datum_t * RESPONSE)
     SESSION: is a 'gnutls_session_t' type.

     RESPONSE: a 'gnutls_datum_t' with DER encoded OCSP response

     This function returns the OCSP status response received from the
     TLS server.  The 'response' should be treated as constant.  If no
     OCSP response is available then
     'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     *Since:* 3.1.3

gnutls_ocsp_status_request_get2
-------------------------------

 -- Function: int gnutls_ocsp_status_request_get2 (gnutls_session_t
          SESSION, unsigned IDX, gnutls_datum_t * RESPONSE)
     SESSION: is a 'gnutls_session_t' type.

     IDX: the index of peer's certificate

     RESPONSE: a 'gnutls_datum_t' with DER encoded OCSP response

     This function returns the OCSP status response received from the
     TLS server for the certificate index provided.  The index
     corresponds to certificates as returned by
     gnutls_certificate_get_peers.  When index is zero this function
     operates identically to 'gnutls_ocsp_status_request_get()' .

     The returned 'response' should be treated as constant.  If no OCSP
     response is available for the given index then
     'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     *Since:* 3.6.3

gnutls_ocsp_status_request_is_checked
-------------------------------------

 -- Function: int gnutls_ocsp_status_request_is_checked
          (gnutls_session_t SESSION, unsigned int FLAGS)
     SESSION: is a gnutls session

     FLAGS: should be zero or 'GNUTLS_OCSP_SR_IS_AVAIL'

     When flags are zero this function returns non-zero if a valid OCSP
     status response was included in the TLS handshake.  That is, an
     OCSP status response which is not too old or superseded.  It
     returns zero otherwise.

     When the flag 'GNUTLS_OCSP_SR_IS_AVAIL' is specified, the function
     returns non-zero if an OCSP status response was included in the
     handshake even if it was invalid.  Otherwise, if no OCSP status
     response was included, it returns zero.  The
     'GNUTLS_OCSP_SR_IS_AVAIL' flag was introduced in GnuTLS 3.4.0.

     This is a helper function when needing to decide whether to perform
     an explicit OCSP validity check on the peer's certificate.  Should
     be called after any of gnutls_certificate_verify_peers*() are
     called.

     *Returns:* non zero if the response was valid, or a zero if it
     wasn't sent, or sent and was invalid.

     *Since:* 3.1.4

gnutls_oid_to_digest
--------------------

 -- Function: gnutls_digest_algorithm_t gnutls_oid_to_digest (const char
          * OID)
     OID: is an object identifier

     Converts a textual object identifier to a
     'gnutls_digest_algorithm_t' value.

     *Returns:* a 'gnutls_digest_algorithm_t' id of the specified digest
     algorithm, or 'GNUTLS_DIG_UNKNOWN' on failure.

     *Since:* 3.4.3

gnutls_oid_to_ecc_curve
-----------------------

 -- Function: gnutls_ecc_curve_t gnutls_oid_to_ecc_curve (const char *
          OID)
     OID: is a curve's OID

     *Returns:* return a 'gnutls_ecc_curve_t' value corresponding to the
     specified OID, or 'GNUTLS_ECC_CURVE_INVALID' on error.

     *Since:* 3.4.3

gnutls_oid_to_gost_paramset
---------------------------

 -- Function: gnutls_gost_paramset_t gnutls_oid_to_gost_paramset (const
          char * OID)
     OID: is an object identifier

     Converts a textual object identifier to a 'gnutls_gost_paramset_t'
     value.

     *Returns:* a 'gnutls_gost_paramset_get_oid' of the specified GOST
     28147 param st, or 'GNUTLS_GOST_PARAMSET_UNKNOWN' on failure.

     *Since:* 3.6.3

gnutls_oid_to_mac
-----------------

 -- Function: gnutls_mac_algorithm_t gnutls_oid_to_mac (const char *
          OID)
     OID: is an object identifier

     Converts a textual object identifier typically from PKCS'5' values
     to a 'gnutls_mac_algorithm_t' value.

     *Returns:* a 'gnutls_mac_algorithm_t' id of the specified digest
     algorithm, or 'GNUTLS_MAC_UNKNOWN' on failure.

     *Since:* 3.5.4

gnutls_oid_to_pk
----------------

 -- Function: gnutls_pk_algorithm_t gnutls_oid_to_pk (const char * OID)
     OID: is an object identifier

     Converts a textual object identifier to a 'gnutls_pk_algorithm_t'
     value.

     *Returns:* a 'gnutls_pk_algorithm_t' id of the specified digest
     algorithm, or 'GNUTLS_PK_UNKNOWN' on failure.

     *Since:* 3.4.3

gnutls_oid_to_sign
------------------

 -- Function: gnutls_sign_algorithm_t gnutls_oid_to_sign (const char *
          OID)
     OID: is an object identifier

     Converts a textual object identifier to a 'gnutls_sign_algorithm_t'
     value.

     *Returns:* a 'gnutls_sign_algorithm_t' id of the specified digest
     algorithm, or 'GNUTLS_SIGN_UNKNOWN' on failure.

     *Since:* 3.4.3

gnutls_openpgp_send_cert
------------------------

 -- Function: void gnutls_openpgp_send_cert (gnutls_session_t SESSION,
          gnutls_openpgp_crt_status_t STATUS)
     SESSION: is a gnutls session

     STATUS: is ignored

     This function is no-op.

     *Returns:* 'GNUTLS_E_UNIMPLEMENTED_FEATURE' .

gnutls_packet_deinit
--------------------

 -- Function: void gnutls_packet_deinit (gnutls_packet_t PACKET)
     PACKET: is a pointer to a 'gnutls_packet_st' structure.

     This function will deinitialize all data associated with the
     received packet.

     *Since:* 3.3.5

gnutls_packet_get
-----------------

 -- Function: void gnutls_packet_get (gnutls_packet_t PACKET,
          gnutls_datum_t * DATA, unsigned char * SEQUENCE)
     PACKET: is a 'gnutls_packet_t' type.

     DATA: will contain the data present in the 'packet' structure (may
     be 'NULL' )

     SEQUENCE: the 8-bytes of the packet sequence number (may be 'NULL'
     )

     This function returns the data and sequence number associated with
     the received packet.

     *Since:* 3.3.5

gnutls_pem_base64_decode
------------------------

 -- Function: int gnutls_pem_base64_decode (const char * HEADER, const
          gnutls_datum_t * B64_DATA, unsigned char * RESULT, size_t *
          RESULT_SIZE)
     HEADER: A null terminated string with the PEM header (eg.
     CERTIFICATE)

     B64_DATA: contain the encoded data

     RESULT: the place where decoded data will be copied

     RESULT_SIZE: holds the size of the result

     This function will decode the given encoded data.  If the header
     given is non 'NULL' this function will search for "---BEGIN header"
     and decode only this part.  Otherwise it will decode the first PEM
     packet found.

     *Returns:* On success 'GNUTLS_E_SUCCESS' (0) is returned,
     'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned if the buffer given is
     not long enough, or 0 on success.

gnutls_pem_base64_decode2
-------------------------

 -- Function: int gnutls_pem_base64_decode2 (const char * HEADER, const
          gnutls_datum_t * B64_DATA, gnutls_datum_t * RESULT)
     HEADER: The PEM header (eg.  CERTIFICATE)

     B64_DATA: contains the encoded data

     RESULT: the location of decoded data

     This function will decode the given encoded data.  The decoded data
     will be allocated, and stored into result.  If the header given is
     non null this function will search for "---BEGIN header" and decode
     only this part.  Otherwise it will decode the first PEM packet
     found.

     You should use 'gnutls_free()' to free the returned data.

     Note, that prior to GnuTLS 3.4.0 this function was available under
     the name 'gnutls_pem_base64_decode_alloc()' .  There is
     compatibility macro pointing to this function.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

     *Since:* 3.4.0

gnutls_pem_base64_encode
------------------------

 -- Function: int gnutls_pem_base64_encode (const char * MSG, const
          gnutls_datum_t * DATA, char * RESULT, size_t * RESULT_SIZE)
     MSG: is a message to be put in the header (may be 'NULL' )

     DATA: contain the raw data

     RESULT: the place where base64 data will be copied

     RESULT_SIZE: holds the size of the result

     This function will convert the given data to printable data, using
     the base64 encoding.  This is the encoding used in PEM messages.

     The output string will be null terminated, although the output size
     will not include the terminating null.

     *Returns:* On success 'GNUTLS_E_SUCCESS' (0) is returned,
     'GNUTLS_E_SHORT_MEMORY_BUFFER' is returned if the buffer given is
     not long enough, or 0 on success.

gnutls_pem_base64_encode2
-------------------------

 -- Function: int gnutls_pem_base64_encode2 (const char * HEADER, const
          gnutls_datum_t * DATA, gnutls_datum_t * RESULT)
     HEADER: is a message to be put in the encoded header (may be 'NULL'
     )

     DATA: contains the raw data

     RESULT: will hold the newly allocated encoded data

     This function will convert the given data to printable data, using
     the base64 encoding.  This is the encoding used in PEM messages.
     This function will allocate the required memory to hold the encoded
     data.

     You should use 'gnutls_free()' to free the returned data.

     Note, that prior to GnuTLS 3.4.0 this function was available under
     the name 'gnutls_pem_base64_encode_alloc()' .  There is
     compatibility macro pointing to this function.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

     *Since:* 3.4.0

gnutls_perror
-------------

 -- Function: void gnutls_perror (int ERROR)
     ERROR: is a GnuTLS error code, a negative error code

     This function is like 'perror()' .  The only difference is that it
     accepts an error number returned by a gnutls function.

gnutls_pk_algorithm_get_name
----------------------------

 -- Function: const char * gnutls_pk_algorithm_get_name
          (gnutls_pk_algorithm_t ALGORITHM)
     ALGORITHM: is a pk algorithm

     Convert a 'gnutls_pk_algorithm_t' value to a string.

     *Returns:* a string that contains the name of the specified public
     key algorithm, or 'NULL' .

gnutls_pk_bits_to_sec_param
---------------------------

 -- 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

gnutls_pk_get_id
----------------

 -- Function: gnutls_pk_algorithm_t gnutls_pk_get_id (const char * NAME)
     NAME: is a string containing a public key algorithm name.

     Convert a string to a 'gnutls_pk_algorithm_t' value.  The names are
     compared in a case insensitive way.  For example,
     gnutls_pk_get_id("RSA") will return 'GNUTLS_PK_RSA' .

     *Returns:* a 'gnutls_pk_algorithm_t' id of the specified public key
     algorithm string, or 'GNUTLS_PK_UNKNOWN' on failures.

     *Since:* 2.6.0

gnutls_pk_get_name
------------------

 -- Function: const char * gnutls_pk_get_name (gnutls_pk_algorithm_t
          ALGORITHM)
     ALGORITHM: is a public key algorithm

     Convert a 'gnutls_pk_algorithm_t' value to a string.

     *Returns:* a pointer to a string that contains the name of the
     specified public key algorithm, or 'NULL' .

     *Since:* 2.6.0

gnutls_pk_get_oid
-----------------

 -- Function: const char * gnutls_pk_get_oid (gnutls_pk_algorithm_t
          ALGORITHM)
     ALGORITHM: is a public key algorithm

     Convert a 'gnutls_pk_algorithm_t' value to its object identifier
     string.

     *Returns:* a pointer to a string that contains the object
     identifier of the specified public key algorithm, or 'NULL' .

     *Since:* 3.4.3

gnutls_pk_list
--------------

 -- Function: const gnutls_pk_algorithm_t * gnutls_pk_list ( VOID)

     Get a list of supported public key algorithms.

     This function is not thread safe.

     *Returns:* a (0)-terminated list of 'gnutls_pk_algorithm_t'
     integers indicating the available ciphers.

     *Since:* 2.6.0

gnutls_pk_to_sign
-----------------

 -- Function: gnutls_sign_algorithm_t gnutls_pk_to_sign
          (gnutls_pk_algorithm_t PK, gnutls_digest_algorithm_t HASH)
     PK: is a public key algorithm

     HASH: a hash algorithm

     This function maps public key and hash algorithms combinations to
     signature algorithms.

     *Returns:* return a 'gnutls_sign_algorithm_t' value, or
     'GNUTLS_SIGN_UNKNOWN' on error.

gnutls_prf
----------

 -- Function: int gnutls_prf (gnutls_session_t SESSION, size_t
          LABEL_SIZE, const char * LABEL, int SERVER_RANDOM_FIRST,
          size_t EXTRA_SIZE, const char * EXTRA, 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.

     SERVER_RANDOM_FIRST: non-zero if server random field should be
     first in seed

     EXTRA_SIZE: length of the 'extra' variable.

     EXTRA: 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.

     Applies the TLS Pseudo-Random-Function (PRF) on the master secret
     and the provided data, seeded with the client and server random
     fields.  For the key expansion specified in RFC5705 see
     'gnutls_prf_rfc5705()' .

     The 'label' variable usually contains a string denoting the purpose
     for the generated data.  The 'server_random_first' indicates
     whether the client random field or the server random field should
     be first in the seed.  Non-zero indicates that the server random
     field is first, 0 that the client random field is first.

     The 'extra' 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:* This function produces identical output with
     'gnutls_prf_rfc5705()' when 'server_random_first' is set to 0 and
     'extra' is 'NULL' .  Under TLS1.3 this function will only operate
     when these conditions are true, or otherwise return
     'GNUTLS_E_INVALID_REQUEST' .

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

gnutls_prf_raw
--------------

 -- Function: int gnutls_prf_raw (gnutls_session_t SESSION, size_t
          LABEL_SIZE, const char * LABEL, size_t SEED_SIZE, const char *
          SEED, 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.

     SEED_SIZE: length of the 'seed' variable.

     SEED: 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.

     Apply the TLS Pseudo-Random-Function (PRF) on the master secret and
     the provided data.

     The 'label' variable usually contains a string denoting the purpose
     for the generated data.  The 'seed' usually contains data such as
     the client and server random, perhaps together with some additional
     data that is added to guarantee uniqueness of the output for a
     particular purpose.

     Because the output is not guaranteed to be unique for a particular
     session unless 'seed' includes the client random and server random
     fields (the PRF would output the same data on another connection
     resumed from the first one), it is not recommended to use this
     function directly.  The 'gnutls_prf()' function seeds the PRF with
     the client and server random fields directly, and is recommended if
     you want to generate pseudo random data unique for each session.

     *Note:* This function will only operate under TLS versions prior to
     1.3.  In TLS1.3 the use of PRF is replaced with HKDF and the
     generic exporters like 'gnutls_prf_rfc5705()' should be used
     instead.  Under TLS1.3 this function returns
     'GNUTLS_E_INVALID_REQUEST' .

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

gnutls_prf_rfc5705
------------------

 -- 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 keyring 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

gnutls_priority_certificate_type_list
-------------------------------------

 -- Function: int gnutls_priority_certificate_type_list
          (gnutls_priority_t PCACHE, const unsigned int ** LIST)
     PCACHE: is a 'gnutls_prioritity_t' type.

     LIST: will point to an integer list

     Get a list of available certificate types in the priority
     structure.

     As of version 3.6.4 this function is an alias for
     gnutls_priority_certificate_type_list2 with the target parameter
     set to: - GNUTLS_CTYPE_SERVER, if the 'SERVER_PRECEDENCE' option is
     set - GNUTLS_CTYPE_CLIENT, otherwise.

     *Returns:* the number of certificate types, or an error code.

     *Since:* 3.0

gnutls_priority_certificate_type_list2
--------------------------------------

 -- Function: int gnutls_priority_certificate_type_list2
          (gnutls_priority_t PCACHE, const unsigned int ** LIST,
          gnutls_ctype_target_t TARGET)
     PCACHE: is a 'gnutls_prioritity_t' type.

     LIST: will point to an integer list.

     TARGET: is a 'gnutls_ctype_target_t' type.  Valid arguments are
     GNUTLS_CTYPE_CLIENT and GNUTLS_CTYPE_SERVER

     Get a list of available certificate types for the given target in
     the priority structure.

     *Returns:* the number of certificate types, or an error code.

     *Since:* 3.6.4

gnutls_priority_cipher_list
---------------------------

 -- Function: int gnutls_priority_cipher_list (gnutls_priority_t PCACHE,
          const unsigned int ** LIST)
     PCACHE: is a 'gnutls_prioritity_t' type.

     LIST: will point to an integer list

     Get a list of available ciphers in the priority structure.

     *Returns:* the number of items, or an error code.

     *Since:* 3.2.3

gnutls_priority_deinit
----------------------

 -- Function: void gnutls_priority_deinit (gnutls_priority_t
          PRIORITY_CACHE)
     PRIORITY_CACHE: is a 'gnutls_prioritity_t' type.

     Deinitializes the priority cache.

gnutls_priority_ecc_curve_list
------------------------------

 -- Function: int gnutls_priority_ecc_curve_list (gnutls_priority_t
          PCACHE, const unsigned int ** LIST)
     PCACHE: is a 'gnutls_prioritity_t' type.

     LIST: will point to an integer list

     Get a list of available elliptic curves in the priority structure.

     *Deprecated:* This function has been replaced by
     'gnutls_priority_group_list()' since 3.6.0.

     *Returns:* the number of items, or an error code.

     *Since:* 3.0

gnutls_priority_get_cipher_suite_index
--------------------------------------

 -- Function: int gnutls_priority_get_cipher_suite_index
          (gnutls_priority_t PCACHE, unsigned int IDX, unsigned int *
          SIDX)
     PCACHE: is a 'gnutls_prioritity_t' type.

     IDX: is an index number.

     SIDX: internal index of cipher suite to get information about.

     Provides the internal ciphersuite index to be used with
     'gnutls_cipher_suite_info()' .  The index 'idx' provided is an
     index kept at the priorities structure.  It might be that a valid
     priorities index does not correspond to a ciphersuite and in that
     case 'GNUTLS_E_UNKNOWN_CIPHER_SUITE' will be returned.  Once the
     last available index is crossed then
     'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned.

     *Returns:* On success it returns 'GNUTLS_E_SUCCESS' (0), or a
     negative error value otherwise.

     *Since:* 3.0.9

gnutls_priority_group_list
--------------------------

 -- Function: int gnutls_priority_group_list (gnutls_priority_t PCACHE,
          const unsigned int ** LIST)
     PCACHE: is a 'gnutls_prioritity_t' type.

     LIST: will point to an integer list

     Get a list of available groups in the priority structure.

     *Returns:* the number of items, or an error code.

     *Since:* 3.6.0

gnutls_priority_init
--------------------

 -- Function: int gnutls_priority_init (gnutls_priority_t *
          PRIORITY_CACHE, const char * PRIORITIES, const char **
          ERR_POS)
     PRIORITY_CACHE: is a 'gnutls_prioritity_t' type.

     PRIORITIES: is a string describing priorities (may be 'NULL' )

     ERR_POS: In case of an error this will have the position in the
     string the error occurred

     For applications that do not modify their crypto settings per
     release, consider using 'gnutls_priority_init2()' with
     'GNUTLS_PRIORITY_INIT_DEF_APPEND' flag instead.  We suggest to use
     centralized crypto settings handled by the GnuTLS library, and
     applications modifying the default settings to their needs.

     This function is identical to 'gnutls_priority_init2()' with zero
     flags.

     A 'NULL' 'priorities' string indicates the default priorities to be
     used (this is available since GnuTLS 3.3.0).

     *Returns:* On syntax error 'GNUTLS_E_INVALID_REQUEST' is returned,
     'GNUTLS_E_SUCCESS' on success, or an error code.

gnutls_priority_init2
---------------------

 -- Function: int gnutls_priority_init2 (gnutls_priority_t *
          PRIORITY_CACHE, const char * PRIORITIES, const char **
          ERR_POS, unsigned FLAGS)
     PRIORITY_CACHE: is a 'gnutls_prioritity_t' type.

     PRIORITIES: is a string describing priorities (may be 'NULL' )

     ERR_POS: In case of an error this will have the position in the
     string the error occurred

     FLAGS: zero or 'GNUTLS_PRIORITY_INIT_DEF_APPEND'

     Sets priorities for the ciphers, key exchange methods, and macs.
     The 'priority_cache' should be deinitialized using
     'gnutls_priority_deinit()' .

     The 'priorities' option allows you to specify a colon separated
     list of the cipher priorities to enable.  Some keywords are defined
     to provide quick access to common preferences.

     When 'flags' is set to 'GNUTLS_PRIORITY_INIT_DEF_APPEND' then the
     'priorities' specified will be appended to the default options.

     Unless there is a special need, use the "NORMAL" keyword to apply a
     reasonable security level, or "NORMAL:%COMPAT" for compatibility.

     "PERFORMANCE" means all the "secure" ciphersuites are enabled,
     limited to 128 bit ciphers and sorted by terms of speed
     performance.

     "LEGACY" the NORMAL settings for GnuTLS 3.2.x or earlier.  There is
     no verification profile set, and the allowed DH primes are
     considered weak today.

     "NORMAL" means all "secure" ciphersuites.  The 256-bit ciphers are
     included as a fallback only.  The ciphers are sorted by security
     margin.

     "PFS" means all "secure" ciphersuites that support perfect forward
     secrecy.  The 256-bit ciphers are included as a fallback only.  The
     ciphers are sorted by security margin.

     "SECURE128" means all "secure" ciphersuites of security level
     128-bit or more.

     "SECURE192" means all "secure" ciphersuites of security level
     192-bit or more.

     "SUITEB128" means all the NSA SuiteB ciphersuites with security
     level of 128.

     "SUITEB192" means all the NSA SuiteB ciphersuites with security
     level of 192.

     "NONE" means nothing is enabled.  This disables everything,
     including protocols.

     "@KEYWORD1,KEYWORD2,..."  The system administrator imposed
     settings.  The provided keyword(s) will be expanded from a
     configuration-time provided file - default is:
     /etc/gnutls/default-priorities.  Any attributes that follow it,
     will be appended to the expanded string.  If multiple keywords are
     provided, separated by commas, then the first keyword that exists
     in the configuration file will be used.  At least one of the
     keywords must exist, or this function will return an error.
     Typical usage would be to specify an application specified keyword
     first, followed by "SYSTEM" as a default fallback.  e.g., "
     'LIBVIRT' ,SYSTEM:!-VERS-SSL3.0" will first try to find a config
     file entry matching "LIBVIRT", but if that does not exist will use
     the entry for "SYSTEM". If "SYSTEM" does not exist either, an error
     will be returned.  In all cases, the SSL3.0 protocol will be
     disabled.  The system priority file entries should be formatted as
     "KEYWORD=VALUE", e.g., "SYSTEM=NORMAL:+ARCFOUR-128".

     Special keywords are "!", "-" and "+".  "!"  or "-" appended with
     an algorithm will remove this algorithm.  "+" appended with an
     algorithm will add this algorithm.

     Check the GnuTLS manual section "Priority strings" for detailed
     information.

     *Examples:*
     "NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"

     "NORMAL:+ARCFOUR-128" means normal ciphers plus ARCFOUR-128.

     "SECURE128:-VERS-SSL3.0" means that only secure ciphers are and
     enabled, SSL3.0 is disabled.

     "NONE:+VERS-TLS-ALL:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1",

     "NONE:+VERS-TLS-ALL:+AES-128-CBC:+ECDHE-RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1:+CURVE-SECP256R1",

     "SECURE256:+SECURE128",

     Note that "NORMAL:%COMPAT" is the most compatible mode.

     A 'NULL' 'priorities' string indicates the default priorities to be
     used (this is available since GnuTLS 3.3.0).

     *Returns:* On syntax error 'GNUTLS_E_INVALID_REQUEST' is returned,
     'GNUTLS_E_SUCCESS' on success, or an error code.

     *Since:* 3.6.3

gnutls_priority_kx_list
-----------------------

 -- Function: int gnutls_priority_kx_list (gnutls_priority_t PCACHE,
          const unsigned int ** LIST)
     PCACHE: is a 'gnutls_prioritity_t' type.

     LIST: will point to an integer list

     Get a list of available key exchange methods in the priority
     structure.

     *Returns:* the number of items, or an error code.

     *Since:* 3.2.3

gnutls_priority_mac_list
------------------------

 -- Function: int gnutls_priority_mac_list (gnutls_priority_t PCACHE,
          const unsigned int ** LIST)
     PCACHE: is a 'gnutls_prioritity_t' type.

     LIST: will point to an integer list

     Get a list of available MAC algorithms in the priority structure.

     *Returns:* the number of items, or an error code.

     *Since:* 3.2.3

gnutls_priority_protocol_list
-----------------------------

 -- Function: int gnutls_priority_protocol_list (gnutls_priority_t
          PCACHE, const unsigned int ** LIST)
     PCACHE: is a 'gnutls_prioritity_t' type.

     LIST: will point to an integer list

     Get a list of available TLS version numbers in the priority
     structure.

     *Returns:* the number of protocols, or an error code.

     *Since:* 3.0

gnutls_priority_set
-------------------

 -- Function: int gnutls_priority_set (gnutls_session_t SESSION,
          gnutls_priority_t PRIORITY)
     SESSION: is a 'gnutls_session_t' type.

     PRIORITY: is a 'gnutls_priority_t' type.

     Sets the priorities to use on the ciphers, key exchange methods,
     and macs.  Note that this function is expected to be called once
     per session; when called multiple times (e.g., before a
     re-handshake, the caller should make sure that any new settings are
     not incompatible with the original session).

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code on
     error.

gnutls_priority_set_direct
--------------------------

 -- Function: int gnutls_priority_set_direct (gnutls_session_t SESSION,
          const char * PRIORITIES, const char ** ERR_POS)
     SESSION: is a 'gnutls_session_t' type.

     PRIORITIES: is a string describing priorities

     ERR_POS: In case of an error this will have the position in the
     string the error occurred

     Sets the priorities to use on the ciphers, key exchange methods,
     and macs.  This function avoids keeping a priority cache and is
     used to directly set string priorities to a TLS session.  For
     documentation check the 'gnutls_priority_init()' .

     To use a reasonable default, consider using
     'gnutls_set_default_priority()' , or
     'gnutls_set_default_priority_append()' instead of this function.

     *Returns:* On syntax error 'GNUTLS_E_INVALID_REQUEST' is returned,
     'GNUTLS_E_SUCCESS' on success, or an error code.

gnutls_priority_sign_list
-------------------------

 -- Function: int gnutls_priority_sign_list (gnutls_priority_t PCACHE,
          const unsigned int ** LIST)
     PCACHE: is a 'gnutls_prioritity_t' type.

     LIST: will point to an integer list

     Get a list of available signature algorithms in the priority
     structure.

     *Returns:* the number of algorithms, or an error code.

     *Since:* 3.0

gnutls_priority_string_list
---------------------------

 -- Function: const char * gnutls_priority_string_list (unsigned ITER,
          unsigned int FLAGS)
     ITER: an integer counter starting from zero

     FLAGS: one of 'GNUTLS_PRIORITY_LIST_INIT_KEYWORDS' ,
     'GNUTLS_PRIORITY_LIST_SPECIAL'

     Can be used to iterate all available priority strings.  Due to
     internal implementation details, there are cases where this
     function can return the empty string.  In that case that string
     should be ignored.  When no strings are available it returns 'NULL'
     .

     *Returns:* a priority string

     *Since:* 3.4.0

gnutls_protocol_get_id
----------------------

 -- Function: gnutls_protocol_t gnutls_protocol_get_id (const char *
          NAME)
     NAME: is a protocol name

     The names are compared in a case insensitive way.

     *Returns:* an id of the specified protocol, or
     'GNUTLS_VERSION_UNKNOWN' on error.

gnutls_protocol_get_name
------------------------

 -- Function: const char * gnutls_protocol_get_name (gnutls_protocol_t
          VERSION)
     VERSION: is a (gnutls) version number

     Convert a 'gnutls_protocol_t' value to a string.

     *Returns:* a string that contains the name of the specified TLS
     version (e.g., "TLS1.0"), or 'NULL' .

gnutls_protocol_get_version
---------------------------

 -- Function: gnutls_protocol_t gnutls_protocol_get_version
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Get TLS version, a 'gnutls_protocol_t' value.

     *Returns:* The version of the currently used protocol.

gnutls_protocol_list
--------------------

 -- Function: const gnutls_protocol_t * gnutls_protocol_list ( VOID)

     Get a list of supported protocols, e.g.  SSL 3.0, TLS 1.0 etc.

     This function is not thread safe.

     *Returns:* a (0)-terminated list of 'gnutls_protocol_t' integers
     indicating the available protocols.

gnutls_psk_allocate_client_credentials
--------------------------------------

 -- Function: int gnutls_psk_allocate_client_credentials
          (gnutls_psk_client_credentials_t * SC)
     SC: is a pointer to a 'gnutls_psk_server_credentials_t' type.

     Allocate a gnutls_psk_client_credentials_t structure.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_psk_allocate_server_credentials
--------------------------------------

 -- Function: int gnutls_psk_allocate_server_credentials
          (gnutls_psk_server_credentials_t * SC)
     SC: is a pointer to a 'gnutls_psk_server_credentials_t' type.

     Allocate a gnutls_psk_server_credentials_t structure.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_psk_client_get_hint
--------------------------

 -- Function: const char * gnutls_psk_client_get_hint (gnutls_session_t
          SESSION)
     SESSION: is a gnutls session

     The PSK identity hint may give the client help in deciding which
     username to use.  This should only be called in case of PSK
     authentication and in case of a client.

     *Note:* there is no hint in TLS 1.3, so this function will return
     'NULL' if TLS 1.3 has been negotiated.

     *Returns:* the identity hint of the peer, or 'NULL' in case of an
     error or if TLS 1.3 is being used.

     *Since:* 2.4.0

gnutls_psk_free_client_credentials
----------------------------------

 -- Function: void gnutls_psk_free_client_credentials
          (gnutls_psk_client_credentials_t SC)
     SC: is a 'gnutls_psk_client_credentials_t' type.

     Free a gnutls_psk_client_credentials_t structure.

gnutls_psk_free_server_credentials
----------------------------------

 -- Function: void gnutls_psk_free_server_credentials
          (gnutls_psk_server_credentials_t SC)
     SC: is a 'gnutls_psk_server_credentials_t' type.

     Free a gnutls_psk_server_credentials_t structure.

gnutls_psk_server_get_username
------------------------------

 -- Function: const char * gnutls_psk_server_get_username
          (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     This should only be called in case of PSK authentication and in
     case of a server.

     *Returns:* the username of the peer, or 'NULL' in case of an error.

gnutls_psk_set_client_credentials
---------------------------------

 -- Function: int gnutls_psk_set_client_credentials
          (gnutls_psk_client_credentials_t RES, const char * USERNAME,
          const gnutls_datum_t * KEY, gnutls_psk_key_flags FLAGS)
     RES: is a 'gnutls_psk_client_credentials_t' type.

     USERNAME: is the user's zero-terminated userid

     KEY: is the user's key

     FLAGS: indicate the format of the key, either 'GNUTLS_PSK_KEY_RAW'
     or 'GNUTLS_PSK_KEY_HEX' .

     This function sets the username and password, in a
     gnutls_psk_client_credentials_t type.  Those will be used in PSK
     authentication.  '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 key
     can be either in raw byte format or in Hex format (without the 0x
     prefix).

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_psk_set_client_credentials_function
------------------------------------------

 -- 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.

gnutls_psk_set_params_function
------------------------------

 -- Function: void gnutls_psk_set_params_function
          (gnutls_psk_server_credentials_t RES, gnutls_params_function *
          FUNC)
     RES: is a gnutls_psk_server_credentials_t type

     FUNC: is the function to be called

     This function will set a callback in order for the server to get
     the Diffie-Hellman or RSA parameters for PSK authentication.  The
     callback should return 'GNUTLS_E_SUCCESS' (0) on success.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

gnutls_psk_set_server_credentials_file
--------------------------------------

 -- 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.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_psk_set_server_credentials_function
------------------------------------------

 -- Function: void gnutls_psk_set_server_credentials_function
          (gnutls_psk_server_credentials_t CRED,
          gnutls_psk_server_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 user's
     PSK credentials.  The callback's function form is: int
     (*callback)(gnutls_session_t, const char* username, gnutls_datum_t*
     key);

     'username' contains the actual username.  The 'key' must be filled
     in using the 'gnutls_malloc()' .

     In case the callback returned a negative number then gnutls will
     assume that the username does not exist.

     The callback function will only be called once per handshake.  The
     callback function should return 0 on success, while -1 indicates an
     error.

gnutls_psk_set_server_credentials_hint
--------------------------------------

 -- Function: int gnutls_psk_set_server_credentials_hint
          (gnutls_psk_server_credentials_t RES, const char * HINT)
     RES: is a 'gnutls_psk_server_credentials_t' type.

     HINT: is the PSK identity hint string

     This function sets the identity hint, in a
     'gnutls_psk_server_credentials_t' type.  This hint is sent to the
     client to help it chose a good PSK credential (i.e., username and
     password).

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

     *Since:* 2.4.0

gnutls_psk_set_server_dh_params
-------------------------------

 -- Function: void gnutls_psk_set_server_dh_params
          (gnutls_psk_server_credentials_t RES, gnutls_dh_params_t
          DH_PARAMS)
     RES: is a gnutls_psk_server_credentials_t type

     DH_PARAMS: is a structure that holds Diffie-Hellman parameters.

     This function will set the Diffie-Hellman parameters for an
     anonymous server to use.  These parameters will be used in
     Diffie-Hellman exchange with PSK cipher suites.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

gnutls_psk_set_server_known_dh_params
-------------------------------------

 -- Function: int gnutls_psk_set_server_known_dh_params
          (gnutls_psk_server_credentials_t RES, gnutls_sec_param_t
          SEC_PARAM)
     RES: is a gnutls_psk_server_credentials_t type

     SEC_PARAM: is an option of the 'gnutls_sec_param_t' enumeration

     This function will set the Diffie-Hellman parameters for a PSK
     server to use.  These parameters will be used in Ephemeral
     Diffie-Hellman cipher suites and will be selected from the FFDHE
     set of RFC7919 according to the security level provided.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

     *Since:* 3.5.6

gnutls_psk_set_server_params_function
-------------------------------------

 -- Function: void gnutls_psk_set_server_params_function
          (gnutls_psk_server_credentials_t RES, gnutls_params_function *
          FUNC)
     RES: is a 'gnutls_certificate_credentials_t' type

     FUNC: is the function to be called

     This function will set a callback in order for the server to get
     the Diffie-Hellman parameters for PSK authentication.  The callback
     should return 'GNUTLS_E_SUCCESS' (0) on success.

     *Deprecated:* This function is unnecessary and discouraged on
     GnuTLS 3.6.0 or later.  Since 3.6.0, DH parameters are negotiated
     following RFC7919.

gnutls_random_art
-----------------

 -- Function: int gnutls_random_art (gnutls_random_art_t TYPE, const
          char * KEY_TYPE, unsigned int KEY_SIZE, void * FPR, size_t
          FPR_SIZE, gnutls_datum_t * ART)
     TYPE: The type of the random art (for now only
     'GNUTLS_RANDOM_ART_OPENSSH' is supported)

     KEY_TYPE: The type of the key (RSA, DSA etc.)

     KEY_SIZE: The size of the key in bits

     FPR: The fingerprint of the key

     FPR_SIZE: The size of the fingerprint

     ART: The returned random art

     This function will convert a given fingerprint to an "artistic"
     image.  The returned image is allocated using 'gnutls_malloc()' ,
     is null-terminated but art->size will not account the terminating
     null.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_range_split
------------------

 -- Function: int gnutls_range_split (gnutls_session_t SESSION, const
          gnutls_range_st * ORIG, gnutls_range_st * NEXT,
          gnutls_range_st * REMAINDER)
     SESSION: is a 'gnutls_session_t' type

     ORIG: is the original range provided by the user

     NEXT: is the returned range that can be conveyed in a TLS record

     REMAINDER: is the returned remaining range

     This function should be used when it is required to hide the length
     of very long data that cannot be directly provided to
     'gnutls_record_send_range()' .  In that case this function should
     be called with the desired length hiding range in 'orig' .  The
     returned 'next' value should then be used in the next call to
     'gnutls_record_send_range()' with the partial data.  That process
     should be repeated until 'remainder' is (0,0).

     *Returns:* 0 in case splitting succeeds, non zero in case of error.
     Note that 'orig' is not changed, while the values of 'next' and
     'remainder' are modified to store the resulting values.

gnutls_reauth
-------------

 -- Function: int gnutls_reauth (gnutls_session_t SESSION, unsigned int
          FLAGS)
     SESSION: is a 'gnutls_session_t' type.

     FLAGS: must be zero

     This function performs the post-handshake authentication for TLS
     1.3.  The post-handshake authentication is initiated by the server
     by calling this function.  Clients respond when
     'GNUTLS_E_REAUTH_REQUEST' has been seen while receiving data.

     The non-fatal errors expected by this function are:
     'GNUTLS_E_INTERRUPTED' , 'GNUTLS_E_AGAIN' , as well as
     'GNUTLS_E_GOT_APPLICATION_DATA' when called on server side.

     The former two interrupt the authentication procedure due to the
     transport layer being interrupted, and the latter because there
     were pending data prior to peer initiating the re-authentication.
     The server should read/process that data as unauthenticated and
     retry calling 'gnutls_reauth()' .

     When this function is called under TLS1.2 or earlier or the peer
     didn't advertise post-handshake auth, it always fails with
     'GNUTLS_E_INVALID_REQUEST' .  The verification of the received
     peers certificate is delegated to the session or credentials
     verification callbacks.  A server can check whether post handshake
     authentication is supported by the client by checking the session
     flags with 'gnutls_session_get_flags()' .

     Prior to calling this function in server side, the function
     'gnutls_certificate_server_set_request()' must be called setting
     expectations for the received certificate (request or require).  If
     none are set this function will return with
     'GNUTLS_E_INVALID_REQUEST' .

     Note that post handshake authentication is available irrespective
     of the initial negotiation type (PSK or certificate).  In all cases
     however, certificate credentials must be set to the session prior
     to calling this function.

     *Returns:* 'GNUTLS_E_SUCCESS' on a successful authentication,
     otherwise a negative error code.

gnutls_record_can_use_length_hiding
-----------------------------------

 -- Function: unsigned gnutls_record_can_use_length_hiding
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     If the session supports length-hiding padding, you can invoke
     'gnutls_record_send_range()' to send a message whose length is
     hidden in the given range.  If the session does not support length
     hiding padding, you can use the standard 'gnutls_record_send()'
     function, or 'gnutls_record_send_range()' making sure that the
     range is the same as the length of the message you are trying to
     send.

     *Returns:* true (1) if the current session supports length-hiding
     padding, false (0) if the current session does not.

gnutls_record_check_corked
--------------------------

 -- Function: size_t gnutls_record_check_corked (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     This function checks if there pending corked data in the gnutls
     buffers -see 'gnutls_record_cork()' .

     *Returns:* Returns the size of the corked data or zero.

     *Since:* 3.2.8

gnutls_record_check_pending
---------------------------

 -- 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.

gnutls_record_cork
------------------

 -- 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

gnutls_record_disable_padding
-----------------------------

 -- Function: void gnutls_record_disable_padding (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Used to disabled padding in TLS 1.0 and above.  Normally you do not
     need to use this function, but there are buggy clients that
     complain if a server pads the encrypted data.  This of course will
     disable protection against statistical attacks on the data.

     This function is defunct since 3.1.7.  Random padding is disabled
     by default unless requested using 'gnutls_record_send_range()' .

gnutls_record_discard_queued
----------------------------

 -- Function: size_t gnutls_record_discard_queued (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     This function discards all queued to be sent packets in a TLS or
     DTLS session.  These are the packets queued after an interrupted
     'gnutls_record_send()' .

     *Returns:* The number of bytes discarded.

     *Since:* 3.4.0

gnutls_record_get_direction
---------------------------

 -- 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.

gnutls_record_get_max_early_data_size
-------------------------------------

 -- Function: size_t gnutls_record_get_max_early_data_size
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     This function returns the maximum early data size in this
     connection.  This property can only be set to servers.  The client
     may be provided with the maximum allowed size through the
     "early_data" extension of the NewSessionTicket handshake message.

     *Returns:* The maximum early data size in this connection.

     *Since:* 3.6.5

gnutls_record_get_max_size
--------------------------

 -- Function: size_t gnutls_record_get_max_size (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Get the record size.  The maximum record size is negotiated by the
     client after the first handshake message.

     *Returns:* The maximum record packet size in this connection.

gnutls_record_get_state
-----------------------

 -- Function: int gnutls_record_get_state (gnutls_session_t SESSION,
          unsigned READ, gnutls_datum_t * MAC_KEY, gnutls_datum_t * IV,
          gnutls_datum_t * CIPHER_KEY, unsigned char [8] SEQ_NUMBER)
     SESSION: is a 'gnutls_session_t' type

     READ: if non-zero the read parameters are returned, otherwise the
     write

     MAC_KEY: the key used for MAC (if a MAC is used)

     IV: the initialization vector or nonce used

     CIPHER_KEY: the cipher key

     SEQ_NUMBER: A 64-bit sequence number

     This function will return the parameters of the current record
     state.  These are only useful to be provided to an external
     off-loading device or subsystem.  The returned values should be
     considered constant and valid for the lifetime of the session.

     In that case, to sync the state back you must call
     'gnutls_record_set_state()' .

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

     Since 3.4.0

gnutls_record_overhead_size
---------------------------

 -- Function: size_t gnutls_record_overhead_size (gnutls_session_t
          SESSION)
     SESSION: is 'gnutls_session_t'

     This function will return the size in bytes of the overhead due to
     TLS (or DTLS) per record.  On certain occasions (e.g., CBC ciphers)
     the returned value is the maximum possible overhead.

     *Since:* 3.2.2

gnutls_record_recv
------------------

 -- 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' .

gnutls_record_recv_early_data
-----------------------------

 -- Function: ssize_t gnutls_record_recv_early_data (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 can be used by a searver to retrieve data sent early
     in the handshake processes when resuming a session.  This is used
     to implement a zero-roundtrip (0-RTT) mode.  It has the same
     semantics as 'gnutls_record_recv()' .

     This function can be called either in a handshake hook, or after
     the handshake is complete.

     *Returns:* The number of bytes received and zero when early data
     reading is complete.  A negative error code is returned in case of
     an error.  If no early data is received during the handshake, this
     function returns 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' .  The
     number of bytes received might be less than the requested
     'data_size' .

     *Since:* 3.6.5

gnutls_record_recv_packet
-------------------------

 -- Function: ssize_t gnutls_record_recv_packet (gnutls_session_t
          SESSION, gnutls_packet_t * PACKET)
     SESSION: is a 'gnutls_session_t' type.

     PACKET: the structure that will hold the packet data

     This is a lower-level function than 'gnutls_record_recv()' and
     allows to directly receive the whole decrypted packet.  That avoids
     a memory copy, and is intended to be used by applications seeking
     high performance.

     The received packet is accessed using 'gnutls_packet_get()' and
     must be deinitialized using 'gnutls_packet_deinit()' .  The
     returned packet will be 'NULL' if the return value is zero (EOF).

     *Returns:* The number of bytes received and zero on EOF (for stream
     connections).  A negative error code is returned in case of an
     error.

     *Since:* 3.3.5

gnutls_record_recv_seq
----------------------

 -- 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

gnutls_record_send
------------------

 -- 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; alternatively you could provide a
     'NULL' pointer for data, and 0 for size.  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.

gnutls_record_send2
-------------------

 -- Function: ssize_t gnutls_record_send2 (gnutls_session_t SESSION,
          const void * DATA, size_t DATA_SIZE, size_t PAD, unsigned
          FLAGS)
     SESSION: is a 'gnutls_session_t' type.

     DATA: contains the data to send

     DATA_SIZE: is the length of the data

     PAD: padding to be added to the record

     FLAGS: must be zero

     This function is identical to 'gnutls_record_send()' except that it
     takes an extra argument to specify padding to be added the record.
     To determine the maximum size of padding, use
     'gnutls_record_get_max_size()' and 'gnutls_record_overhead_size()'
     .

     Note that in order for GnuTLS to provide constant time processing
     of padding and data in TLS1.3, the flag 'GNUTLS_SAFE_PADDING_CHECK'
     must be used in 'gnutls_init()' .

     *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.

     *Since:* 3.6.3

gnutls_record_send_early_data
-----------------------------

 -- Function: ssize_t gnutls_record_send_early_data (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 can be used by a client to send data early in the
     handshake processes when resuming a session.  This is used to
     implement a zero-roundtrip (0-RTT) mode.  It has the same semantics
     as 'gnutls_record_send()' .

     There may be a limit to the amount of data sent as early data.  Use
     'gnutls_record_get_max_early_data_size()' to check the limit.  If
     the limit exceeds, this function returns
     'GNUTLS_E_RECORD_LIMIT_REACHED' .

     *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.

     *Since:* 3.6.5

gnutls_record_send_range
------------------------

 -- Function: ssize_t gnutls_record_send_range (gnutls_session_t
          SESSION, const void * DATA, size_t DATA_SIZE, const
          gnutls_range_st * RANGE)
     SESSION: is a 'gnutls_session_t' type.

     DATA: contains the data to send.

     DATA_SIZE: is the length of the data.

     RANGE: is the range of lengths in which the real data length must
     be hidden.

     This function operates like 'gnutls_record_send()' but, while
     'gnutls_record_send()' adds minimal padding to each TLS record,
     this function uses the TLS extra-padding feature to conceal the
     real data size within the range of lengths provided.  Some TLS
     sessions do not support extra padding (e.g.  stream ciphers in
     standard TLS or SSL3 sessions).  To know whether the current
     session supports extra padding, and hence length hiding, use the
     'gnutls_record_can_use_length_hiding()' function.

     *Note:* This function currently is limited to blocking sockets.

     *Returns:* The number of bytes sent (that is data_size in a
     successful invocation), or a negative error code.

gnutls_record_set_max_early_data_size
-------------------------------------

 -- Function: int gnutls_record_set_max_early_data_size
          (gnutls_session_t SESSION, size_t SIZE)
     SESSION: is a 'gnutls_session_t' type.

     SIZE: is the new size

     This function sets the maximum early data size in this connection.
     This property can only be set to servers.  The client may be
     provided with the maximum allowed size through the "early_data"
     extension of the NewSessionTicket handshake message.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     *Since:* 3.6.4

gnutls_record_set_max_size
--------------------------

 -- Function: ssize_t gnutls_record_set_max_size (gnutls_session_t
          SESSION, size_t SIZE)
     SESSION: is a 'gnutls_session_t' type.

     SIZE: is the new size

     This function sets the maximum record packet size in this
     connection.

     The requested record size does get in effect immediately only while
     sending data.  The receive part will take effect after a successful
     handshake.

     Prior to 3.6.4, this function was implemented using a TLS extension
     called 'max record size', which limits the acceptable values to
     512(=2^9), 1024(=2^10), 2048(=2^11) and 4096(=2^12).  Since 3.6.4,
     it uses another TLS extension called 'record size limit', which
     doesn't have the limitation, as long as the value ranges between
     512 and 16384.  Note that not all TLS implementations use or even
     understand those extension.

     In TLS 1.3, the value is the length of plaintext content plus its
     padding, excluding content type octet.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_record_set_state
-----------------------

 -- Function: int gnutls_record_set_state (gnutls_session_t SESSION,
          unsigned READ, const unsigned char [8] SEQ_NUMBER)
     SESSION: is a 'gnutls_session_t' type

     READ: if non-zero the read parameters are returned, otherwise the
     write

     SEQ_NUMBER: A 64-bit sequence number

     This function will set the sequence number in the current record
     state.  This function is useful if sending and receiving are
     offloaded from gnutls.  That is, if 'gnutls_record_get_state()' was
     used.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

     Since 3.4.0

gnutls_record_set_timeout
-------------------------

 -- Function: void gnutls_record_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 receive timeout for the record layer to the
     provided value.  Use an 'ms' value of zero to disable timeout (the
     default), or 'GNUTLS_INDEFINITE_TIMEOUT' , to set an indefinite
     timeout.

     This function requires to set a pull timeout callback.  See
     'gnutls_transport_set_pull_timeout_function()' .

     *Since:* 3.1.7

gnutls_record_uncork
--------------------

 -- 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

gnutls_rehandshake
------------------

 -- 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.

gnutls_safe_renegotiation_status
--------------------------------

 -- 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

gnutls_sec_param_get_name
-------------------------

 -- Function: const char * gnutls_sec_param_get_name (gnutls_sec_param_t
          PARAM)
     PARAM: is a security parameter

     Convert a 'gnutls_sec_param_t' value to a string.

     *Returns:* a pointer to a string that contains the name of the
     specified security level, or 'NULL' .

     *Since:* 2.12.0

gnutls_sec_param_to_pk_bits
---------------------------

 -- 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

gnutls_sec_param_to_symmetric_bits
----------------------------------

 -- Function: unsigned int gnutls_sec_param_to_symmetric_bits
          (gnutls_sec_param_t PARAM)
     PARAM: is a security parameter

     This function will return the number of bits that correspond to
     symmetric cipher strength for the given security parameter.

     *Returns:* The number of bits, or (0).

     *Since:* 3.3.0

gnutls_server_name_get
----------------------

 -- Function: int gnutls_server_name_get (gnutls_session_t SESSION, void
          * DATA, size_t * DATA_LENGTH, unsigned int * TYPE, unsigned
          int INDX)
     SESSION: is a 'gnutls_session_t' type.

     DATA: will hold the data

     DATA_LENGTH: will hold the data length.  Must hold the maximum size
     of data.

     TYPE: will hold the server name indicator type

     INDX: is the index of the server_name

     This function will allow you to get the name indication (if any), a
     client has sent.  The name indication may be any of the enumeration
     gnutls_server_name_type_t.

     If 'type' is GNUTLS_NAME_DNS, then this function is to be used by
     servers that support virtual hosting, and the data will be a null
     terminated IDNA ACE string (prior to GnuTLS 3.4.0 it was a UTF-8
     string).

     If 'data' has not enough size to hold the server name
     GNUTLS_E_SHORT_MEMORY_BUFFER is returned, and 'data_length' will
     hold the required size.

     'indx' is used to retrieve more than one server names (if sent by
     the client).  The first server name has an index of 0, the second 1
     and so on.  If no name with the given index exists
     GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, on UTF-8
     decoding error 'GNUTLS_E_IDNA_ERROR' is returned, otherwise a
     negative error code is returned.

gnutls_server_name_set
----------------------

 -- Function: int gnutls_server_name_set (gnutls_session_t SESSION,
          gnutls_server_name_type_t TYPE, const void * NAME, size_t
          NAME_LENGTH)
     SESSION: is a 'gnutls_session_t' type.

     TYPE: specifies the indicator type

     NAME: is a string that contains the server name.

     NAME_LENGTH: holds the length of name excluding the terminating
     null byte

     This function is to be used by clients that want to inform (via a
     TLS extension mechanism) the server of the name they connected to.
     This should be used by clients that connect to servers that do
     virtual hosting.

     The value of 'name' depends on the 'type' type.  In case of
     'GNUTLS_NAME_DNS' , a UTF-8 null-terminated domain name string,
     without the trailing dot, is expected.

     IPv4 or IPv6 addresses are not permitted to be set by this
     function.  If the function is called with a name of 'name_length'
     zero it will clear all server names set.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

gnutls_session_channel_binding
------------------------------

 -- Function: int gnutls_session_channel_binding (gnutls_session_t
          SESSION, gnutls_channel_binding_t CBTYPE, gnutls_datum_t * CB)
     SESSION: is a 'gnutls_session_t' type.

     CBTYPE: an 'gnutls_channel_binding_t' enumeration type

     CB: output buffer array with data

     Extract given channel binding data of the 'cbtype' (e.g.,
     'GNUTLS_CB_TLS_UNIQUE' ) type.

     *Returns:* 'GNUTLS_E_SUCCESS' on success,
     'GNUTLS_E_UNIMPLEMENTED_FEATURE' if the 'cbtype' is unsupported,
     'GNUTLS_E_CHANNEL_BINDING_NOT_AVAILABLE' if the data is not
     currently available, or an error code.

     *Since:* 2.12.0

gnutls_session_enable_compatibility_mode
----------------------------------------

 -- Function: void gnutls_session_enable_compatibility_mode
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     This function can be used to disable certain (security) features in
     TLS in order to maintain maximum compatibility with buggy clients.
     Because several trade-offs with security are enabled, if required
     they will be reported through the audit subsystem.

     Normally only servers that require maximum compatibility with
     everything out there, need to call this function.

     Note that this function must be called after any call to
     gnutls_priority functions.

     *Since:* 2.1.4

gnutls_session_etm_status
-------------------------

 -- Function: unsigned gnutls_session_etm_status (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Get the status of the encrypt-then-mac extension negotiation.  This
     is in accordance to rfc7366

     *Returns:* Non-zero if the negotiation was successful or zero
     otherwise.

gnutls_session_ext_master_secret_status
---------------------------------------

 -- Function: unsigned gnutls_session_ext_master_secret_status
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Get the status of the extended master secret extension negotiation.
     This is in accordance to RFC7627.  That information is also
     available to the more generic 'gnutls_session_get_flags()' .

     *Returns:* Non-zero if the negotiation was successful or zero
     otherwise.

gnutls_session_ext_register
---------------------------

 -- Function: int gnutls_session_ext_register (gnutls_session_t SESSION,
          const char * NAME, int ID, gnutls_ext_parse_type_t PARSE_TYPE,
          gnutls_ext_recv_func RECV_FUNC, gnutls_ext_send_func
          SEND_FUNC, gnutls_ext_deinit_data_func DEINIT_FUNC,
          gnutls_ext_pack_func PACK_FUNC, gnutls_ext_unpack_func
          UNPACK_FUNC, unsigned FLAGS)
     SESSION: the session for which this extension will be set

     NAME: the name of the extension to register

     ID: the numeric id of the extension

     PARSE_TYPE: the parse type of the extension (see
     gnutls_ext_parse_type_t)

     RECV_FUNC: a function to receive the data

     SEND_FUNC: a function to send the data

     DEINIT_FUNC: a function deinitialize any private data

     PACK_FUNC: a function which serializes the extension's private data
     (used on session packing for resumption)

     UNPACK_FUNC: a function which will deserialize the extension's
     private data

     FLAGS: must be zero or flags from 'gnutls_ext_flags_t'

     This function will register a new extension type.  The extension
     will be only usable within the registered session.  If the
     extension type is already registered then
     'GNUTLS_E_ALREADY_REGISTERED' will be returned, unless the flag
     'GNUTLS_EXT_FLAG_OVERRIDE_INTERNAL' is specified.  The latter flag
     when specified can be used to override certain extensions
     introduced after 3.6.0.  It is expected to be used by applications
     which handle custom extensions that are not currently supported in
     GnuTLS, but direct support for them may be added in the future.

     Each registered extension can store temporary data into the
     gnutls_session_t structure using 'gnutls_ext_set_data()' , and they
     can be retrieved using 'gnutls_ext_get_data()' .

     The validity of the extension registered can be given by the
     appropriate flags of 'gnutls_ext_flags_t' .  If no validity is
     given, then the registered extension will be valid for client and
     TLS1.2 server hello (or encrypted extensions for TLS1.3).

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.5.5

gnutls_session_force_valid
--------------------------

 -- Function: void gnutls_session_force_valid (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Clears the invalid flag in a session.  That means that sessions
     were corrupt or invalid data were received can be re-used.  Use
     only when debugging or experimenting with the TLS protocol.  Should
     not be used in typical applications.

gnutls_session_get_data
-----------------------

 -- Function: int gnutls_session_get_data (gnutls_session_t SESSION,
          void * SESSION_DATA, size_t * SESSION_DATA_SIZE)
     SESSION: is a 'gnutls_session_t' type.

     SESSION_DATA: is a pointer to space to hold the session.

     SESSION_DATA_SIZE: is the session_data's size, or it will be set by
     the function.

     Returns all session parameters needed to be stored to support
     resumption, in a pre-allocated buffer.

     See 'gnutls_session_get_data2()' for more information.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_session_get_data2
------------------------

 -- Function: int gnutls_session_get_data2 (gnutls_session_t SESSION,
          gnutls_datum_t * DATA)
     SESSION: is a 'gnutls_session_t' type.

     DATA: is a pointer to a datum that will hold the session.

     Returns necessary parameters to support resumption.  The client
     should call this function and store the returned session data.  A
     session can be resumed later by calling 'gnutls_session_set_data()'
     with the returned data.  Note that under TLS 1.3, it is recommended
     for clients to use session parameters only once, to prevent
     passive-observers from correlating the different connections.

     The returned 'data' are allocated and must be released using
     'gnutls_free()' .

     This function will fail if called prior to handshake completion.
     In case of false start TLS, the handshake completes only after data
     have been successfully received from the peer.

     Under TLS1.3 session resumption is possible only after a session
     ticket is received by the client.  To ensure that such a ticket has
     been received use 'gnutls_session_get_flags()' and check for flag
     'GNUTLS_SFLAGS_SESSION_TICKET' ; if this flag is not set, this
     function will wait for a new ticket within an estimated rountrip,
     and if not received will return dummy data which cannot lead to
     resumption.

     To get notified when new tickets are received by the server use
     'gnutls_handshake_set_hook_function()' to wait for
     'GNUTLS_HANDSHAKE_NEW_SESSION_TICKET' messages.  Each call of
     'gnutls_session_get_data2()' after a ticket is received, will
     return session resumption data corresponding to the last received
     ticket.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_session_get_desc
-----------------------

 -- Function: char * gnutls_session_get_desc (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     This function returns a string describing the current session.  The
     string is null terminated and allocated using 'gnutls_malloc()' .

     If initial negotiation is not complete when this function is
     called, 'NULL' will be returned.

     *Returns:* a description of the protocols and algorithms in the
     current session.

     *Since:* 3.1.10

gnutls_session_get_flags
------------------------

 -- Function: unsigned gnutls_session_get_flags (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     This function will return a series (ORed) of flags, applicable for
     the current session.

     This replaces individual informational functions such as
     'gnutls_safe_renegotiation_status()' ,
     'gnutls_session_ext_master_secret_status()' , etc.

     *Returns:* An ORed sequence of flags (see 'gnutls_session_flags_t'
     )

     *Since:* 3.5.0

gnutls_session_get_id
---------------------

 -- Function: int gnutls_session_get_id (gnutls_session_t SESSION, void
          * SESSION_ID, size_t * SESSION_ID_SIZE)
     SESSION: is a 'gnutls_session_t' type.

     SESSION_ID: is a pointer to space to hold the session id.

     SESSION_ID_SIZE: initially should contain the maximum 'session_id'
     size and will be updated.

     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 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' .

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_session_get_id2
----------------------

 -- 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

gnutls_session_get_master_secret
--------------------------------

 -- Function: void gnutls_session_get_master_secret (gnutls_session_t
          SESSION, gnutls_datum_t * SECRET)
     SESSION: is a 'gnutls_session_t' type.

     SECRET: the session's master secret

     This function returns pointers to the master secret used in the TLS
     session.  The pointers are not to be modified or deallocated.

     *Since:* 3.5.0

gnutls_session_get_ptr
----------------------

 -- Function: void * gnutls_session_get_ptr (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Get user pointer for session.  Useful in callbacks.  This is the
     pointer set with 'gnutls_session_set_ptr()' .

     *Returns:* the user given pointer from the session structure, or
     'NULL' if it was never set.

gnutls_session_get_random
-------------------------

 -- Function: void gnutls_session_get_random (gnutls_session_t SESSION,
          gnutls_datum_t * CLIENT, gnutls_datum_t * SERVER)
     SESSION: is a 'gnutls_session_t' type.

     CLIENT: the client part of the random

     SERVER: the server part of the random

     This function returns pointers to the client and server random
     fields used in the TLS handshake.  The pointers are not to be
     modified or deallocated.

     If a client random value has not yet been established, the output
     will be garbage.

     *Since:* 3.0

gnutls_session_get_verify_cert_status
-------------------------------------

 -- Function: unsigned int gnutls_session_get_verify_cert_status
          (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     This function returns the status of the verification when initiated
     via auto-verification, i.e., by 'gnutls_session_set_verify_cert2()'
     or 'gnutls_session_set_verify_cert()' .  If no certificate
     verification was occurred then the return value would be set to
     ((unsigned int)-1).

     The certificate verification status is the same as in
     'gnutls_certificate_verify_peers()' .

     *Returns:* the certificate verification status.

     *Since:* 3.4.6

gnutls_session_is_resumed
-------------------------

 -- 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.

gnutls_session_key_update
-------------------------

 -- Function: int gnutls_session_key_update (gnutls_session_t SESSION,
          unsigned FLAGS)
     SESSION: is a 'gnutls_session_t' type.

     FLAGS: zero of 'GNUTLS_KU_PEER'

     This function will update/refresh the session keys when the TLS
     protocol is 1.3 or better.  The peer is notified of the update by
     sending a message, so this function should be treated similarly to
     'gnutls_record_send()' -i.e., it may return 'GNUTLS_E_AGAIN' or
     'GNUTLS_E_INTERRUPTED' .

     When this flag 'GNUTLS_KU_PEER' is specified, this function in
     addition to updating the local keys, will ask the peer to refresh
     its keys too.

     If the negotiated version is not TLS 1.3 or better this function
     will return 'GNUTLS_E_INVALID_REQUEST' .

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.6.3

gnutls_session_resumption_requested
-----------------------------------

 -- 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.

gnutls_session_set_data
-----------------------

 -- Function: int gnutls_session_set_data (gnutls_session_t SESSION,
          const void * SESSION_DATA, size_t SESSION_DATA_SIZE)
     SESSION: is a 'gnutls_session_t' type.

     SESSION_DATA: is a pointer to space to hold the session.

     SESSION_DATA_SIZE: is the session's size

     Sets all session parameters, in order to resume a previously
     established session.  The session data given must be the one
     returned by 'gnutls_session_get_data()' .  This function should be
     called before 'gnutls_handshake()' .

     Keep in mind that session resuming is advisory.  The server may
     choose not to resume the session, thus a full handshake will be
     performed.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_session_set_id
---------------------

 -- Function: int gnutls_session_set_id (gnutls_session_t SESSION, const
          gnutls_datum_t * SID)
     SESSION: is a 'gnutls_session_t' type.

     SID: the session identifier

     This function sets the session ID to be used in a client hello.
     This is a function intended for exceptional uses.  Do not use this
     function unless you are implementing a custom protocol.

     To set session resumption parameters use
     'gnutls_session_set_data()' instead.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

     *Since:* 3.2.1

gnutls_session_set_premaster
----------------------------

 -- Function: int gnutls_session_set_premaster (gnutls_session_t
          SESSION, unsigned int ENTITY, gnutls_protocol_t VERSION,
          gnutls_kx_algorithm_t KX, gnutls_cipher_algorithm_t CIPHER,
          gnutls_mac_algorithm_t MAC, gnutls_compression_method_t COMP,
          const gnutls_datum_t * MASTER, const gnutls_datum_t *
          SESSION_ID)
     SESSION: is a 'gnutls_session_t' type.

     ENTITY: GNUTLS_SERVER or GNUTLS_CLIENT

     VERSION: the TLS protocol version

     KX: the key exchange method

     CIPHER: the cipher

     MAC: the MAC algorithm

     COMP: the compression method (ignored)

     MASTER: the master key to use

     SESSION_ID: the session identifier

     This function sets the premaster secret in a session.  This is a
     function intended for exceptional uses.  Do not use this function
     unless you are implementing a legacy protocol.  Use
     'gnutls_session_set_data()' instead.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

gnutls_session_set_ptr
----------------------

 -- Function: void gnutls_session_set_ptr (gnutls_session_t SESSION,
          void * PTR)
     SESSION: is a 'gnutls_session_t' type.

     PTR: is the user pointer

     This function will set (associate) the user given pointer 'ptr' to
     the session structure.  This pointer can be accessed with
     'gnutls_session_get_ptr()' .

gnutls_session_set_verify_cert
------------------------------

 -- 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

gnutls_session_set_verify_cert2
-------------------------------

 -- Function: void gnutls_session_set_verify_cert2 (gnutls_session_t
          SESSION, gnutls_typed_vdata_st * DATA, unsigned ELEMENTS,
          unsigned FLAGS)
     SESSION: is a gnutls session

     DATA: an array of typed data

     ELEMENTS: the number of data elements

     FLAGS: flags for certificate verification -
     'gnutls_certificate_verify_flags'

     This function instructs GnuTLS to verify the peer's certificate
     using the provided typed data information.  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 acceptable typed data are the same as in
     'gnutls_certificate_verify_peers()' , and once set must remain
     valid for the lifetime of the session.  More precisely they should
     be available during any subsequent handshakes.

     If 'flags' is provided which contain a profile, this function
     should be called after any session priority setting functions.

     *Since:* 3.4.6

gnutls_session_set_verify_function
----------------------------------

 -- Function: void gnutls_session_set_verify_function (gnutls_session_t
          SESSION, gnutls_certificate_verify_function * FUNC)
     SESSION: is a 'gnutls_session_t' type.

     FUNC: is the callback function

     This function sets a callback to be called when peer's certificate
     has been received in order to verify it on receipt rather than
     doing after the handshake is completed.  This overrides any
     callback set using 'gnutls_certificate_set_verify_function()' .

     The callback's function prototype is: int
     (*callback)(gnutls_session_t);

     If the callback function is provided then gnutls will call it, in
     the handshake, just after the certificate message has been
     received.  To verify or obtain the certificate the
     'gnutls_certificate_verify_peers2()' ,
     'gnutls_certificate_type_get()' , 'gnutls_certificate_get_peers()'
     functions can be used.

     The callback function should return 0 for the handshake to continue
     or non-zero to terminate.

     *Since:* 3.4.6

gnutls_session_supplemental_register
------------------------------------

 -- Function: int gnutls_session_supplemental_register (gnutls_session_t
          SESSION, const char * NAME,
          gnutls_supplemental_data_format_type_t TYPE,
          gnutls_supp_recv_func RECV_FUNC, gnutls_supp_send_func
          SEND_FUNC, unsigned FLAGS)
     SESSION: the session for which this will be registered

     NAME: the name of the supplemental data to register

     TYPE: the type of the supplemental data format

     RECV_FUNC: the function to receive the data

     SEND_FUNC: the function to send the data

     FLAGS: must be zero

     This function will register a new supplemental data type (rfc4680).
     The registered supplemental functions will be used for that
     specific session.  The provided 'type' must be an unassigned type
     in 'gnutls_supplemental_data_format_type_t' .

     If the type is already registered or handled by GnuTLS internally
     'GNUTLS_E_ALREADY_REGISTERED' will be returned.

     As supplemental data are not defined under TLS 1.3, this function
     will disable TLS 1.3 support for the given session.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.5.5

gnutls_session_ticket_enable_client
-----------------------------------

 -- Function: int gnutls_session_ticket_enable_client (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Request that the client should attempt session resumption using
     SessionTicket.  This call is typically unnecessary as session
     tickets are enabled by default.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
     error code.

     *Since:* 2.10.0

gnutls_session_ticket_enable_server
-----------------------------------

 -- 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

gnutls_session_ticket_key_generate
----------------------------------

 -- 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

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.

gnutls_set_default_priority
---------------------------

 -- Function: int gnutls_set_default_priority (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Sets the default priority on the ciphers, key exchange methods, and
     macs.  This is the recommended method of setting the defaults, in
     order to promote consistency between applications using GnuTLS, and
     to allow GnuTLS using applications to update settings in par with
     the library.  For client applications which require maximum
     compatibility consider calling
     'gnutls_session_enable_compatibility_mode()' after this function.

     For an application to specify additional options to priority string
     consider using 'gnutls_set_default_priority_append()' .

     To allow a user to override the defaults (e.g., when a user
     interface or configuration file is available), the functions
     'gnutls_priority_set_direct()' or 'gnutls_priority_set()' can be
     used.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

     *Since:* 2.1.4

gnutls_set_default_priority_append
----------------------------------

 -- Function: int gnutls_set_default_priority_append (gnutls_session_t
          SESSION, const char * ADD_PRIO, const char ** ERR_POS,
          unsigned FLAGS)
     SESSION: is a 'gnutls_session_t' type.

     ADD_PRIO: is a string describing priorities to be appended to
     default

     ERR_POS: In case of an error this will have the position in the
     string the error occurred

     FLAGS: must be zero

     Sets the default priority on the ciphers, key exchange methods, and
     macs with the additional options in 'add_prio' .  This is the
     recommended method of setting the defaults when only few additional
     options are to be added.  This promotes consistency between
     applications using GnuTLS, and allows GnuTLS using applications to
     update settings in par with the library.

     The 'add_prio' string should start as a normal priority string,
     e.g., '-VERS-TLS-ALL:+VERS-TLS1.3:%COMPAT' or '%FORCE_ETM'. That
     is, it must not start with ':'.

     To allow a user to override the defaults (e.g., when a user
     interface or configuration file is available), the functions
     'gnutls_priority_set_direct()' or 'gnutls_priority_set()' can be
     used.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.

     *Since:* 3.6.3

gnutls_sign_algorithm_get
-------------------------

 -- Function: int gnutls_sign_algorithm_get (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Returns the signature algorithm that is (or will be) used in this
     session by the server to sign data.  This function should be used
     only with TLS 1.2 or later.

     *Returns:* The sign algorithm or 'GNUTLS_SIGN_UNKNOWN' .

     *Since:* 3.1.1

gnutls_sign_algorithm_get_client
--------------------------------

 -- Function: int gnutls_sign_algorithm_get_client (gnutls_session_t
          SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Returns the signature algorithm that is (or will be) used in this
     session by the client to sign data.  This function should be used
     only with TLS 1.2 or later.

     *Returns:* The sign algorithm or 'GNUTLS_SIGN_UNKNOWN' .

     *Since:* 3.1.11

gnutls_sign_algorithm_get_requested
-----------------------------------

 -- Function: int gnutls_sign_algorithm_get_requested (gnutls_session_t
          SESSION, size_t INDX, gnutls_sign_algorithm_t * ALGO)
     SESSION: is a 'gnutls_session_t' type.

     INDX: is an index of the signature algorithm to return

     ALGO: the returned certificate type will be stored there

     Returns the signature algorithm specified by index that was
     requested by the peer.  If the specified index has no data
     available this function returns
     'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' .  If the negotiated TLS
     version does not support signature algorithms then
     'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned even for
     the first index.  The first index is 0.

     This function is useful in the certificate callback functions to
     assist in selecting the correct certificate.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise an error code is returned.

     *Since:* 2.10.0

gnutls_sign_get_hash_algorithm
------------------------------

 -- Function: gnutls_digest_algorithm_t gnutls_sign_get_hash_algorithm
          (gnutls_sign_algorithm_t SIGN)
     SIGN: is a signature algorithm

     This function returns the digest algorithm corresponding to the
     given signature algorithms.

     *Since:* 3.1.1

     *Returns:* return a 'gnutls_digest_algorithm_t' value, or
     'GNUTLS_DIG_UNKNOWN' on error.

gnutls_sign_get_id
------------------

 -- Function: gnutls_sign_algorithm_t gnutls_sign_get_id (const char *
          NAME)
     NAME: is a sign algorithm name

     The names are compared in a case insensitive way.

     *Returns:* return a 'gnutls_sign_algorithm_t' value corresponding
     to the specified algorithm, or 'GNUTLS_SIGN_UNKNOWN' on error.

gnutls_sign_get_name
--------------------

 -- Function: const char * gnutls_sign_get_name (gnutls_sign_algorithm_t
          ALGORITHM)
     ALGORITHM: is a sign algorithm

     Convert a 'gnutls_sign_algorithm_t' value to a string.

     *Returns:* a string that contains the name of the specified sign
     algorithm, or 'NULL' .

gnutls_sign_get_oid
-------------------

 -- Function: const char * gnutls_sign_get_oid (gnutls_sign_algorithm_t
          SIGN)
     SIGN: is a sign algorithm

     Convert a 'gnutls_sign_algorithm_t' value to its object identifier.

     *Returns:* a string that contains the object identifier of the
     specified sign algorithm, or 'NULL' .

     *Since:* 3.4.3

gnutls_sign_get_pk_algorithm
----------------------------

 -- Function: gnutls_pk_algorithm_t gnutls_sign_get_pk_algorithm
          (gnutls_sign_algorithm_t SIGN)
     SIGN: is a signature algorithm

     This function returns the public key algorithm corresponding to the
     given signature algorithms.  Note that there may be multiple public
     key algorithms supporting a particular signature type; when dealing
     with such algorithms use instead
     'gnutls_sign_supports_pk_algorithm()' .

     *Since:* 3.1.1

     *Returns:* return a 'gnutls_pk_algorithm_t' value, or
     'GNUTLS_PK_UNKNOWN' on error.

gnutls_sign_is_secure
---------------------

 -- Function: unsigned gnutls_sign_is_secure (gnutls_sign_algorithm_t
          ALGORITHM)
     ALGORITHM: is a sign algorithm

     *Returns:* Non-zero if the provided signature algorithm is
     considered to be secure.

gnutls_sign_is_secure2
----------------------

 -- Function: unsigned gnutls_sign_is_secure2 (gnutls_sign_algorithm_t
          ALGORITHM, unsigned int FLAGS)
     ALGORITHM: is a sign algorithm

     FLAGS: zero or 'GNUTLS_SIGN_FLAG_SECURE_FOR_CERTS'

     *Returns:* Non-zero if the provided signature algorithm is
     considered to be secure.

gnutls_sign_list
----------------

 -- Function: const gnutls_sign_algorithm_t * gnutls_sign_list ( VOID)

     Get a list of supported public key signature algorithms.

     *Returns:* a (0)-terminated list of 'gnutls_sign_algorithm_t'
     integers indicating the available ciphers.

gnutls_sign_supports_pk_algorithm
---------------------------------

 -- Function: unsigned gnutls_sign_supports_pk_algorithm
          (gnutls_sign_algorithm_t SIGN, gnutls_pk_algorithm_t PK)
     SIGN: is a signature algorithm

     PK: is a public key algorithm

     This function returns non-zero if the public key algorithm
     corresponds to the given signature algorithm.  That is, if that
     signature can be generated from the given private key algorithm.

     *Since:* 3.6.0

     *Returns:* return non-zero when the provided algorithms are
     compatible.

gnutls_srp_allocate_client_credentials
--------------------------------------

 -- Function: int gnutls_srp_allocate_client_credentials
          (gnutls_srp_client_credentials_t * SC)
     SC: is a pointer to a 'gnutls_srp_server_credentials_t' type.

     Allocate a gnutls_srp_client_credentials_t structure.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
     error code.

gnutls_srp_allocate_server_credentials
--------------------------------------

 -- Function: int gnutls_srp_allocate_server_credentials
          (gnutls_srp_server_credentials_t * SC)
     SC: is a pointer to a 'gnutls_srp_server_credentials_t' type.

     Allocate a gnutls_srp_server_credentials_t structure.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
     error code.

gnutls_srp_base64_decode
------------------------

 -- Function: int gnutls_srp_base64_decode (const gnutls_datum_t *
          B64_DATA, char * RESULT, size_t * RESULT_SIZE)
     B64_DATA: contain the encoded data

     RESULT: the place where decoded data will be copied

     RESULT_SIZE: holds the size of the result

     This function will decode the given encoded data, using the base64
     encoding found in libsrp.

     Note that 'b64_data' should be null terminated.

     Warning!  This base64 encoding is not the "standard" encoding, so
     do not use it for non-SRP purposes.

     *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
     not long enough, or 0 on success.

gnutls_srp_base64_decode2
-------------------------

 -- Function: int gnutls_srp_base64_decode2 (const gnutls_datum_t *
          B64_DATA, gnutls_datum_t * RESULT)
     B64_DATA: contains the encoded data

     RESULT: the place where decoded data lie

     This function will decode the given encoded data.  The decoded data
     will be allocated, and stored into result.  It will decode using
     the base64 algorithm as used in libsrp.

     You should use 'gnutls_free()' to free the returned data.

     Warning!  This base64 encoding is not the "standard" encoding, so
     do not use it for non-SRP purposes.

     *Returns:* 0 on success, or an error code.

gnutls_srp_base64_encode
------------------------

 -- Function: int gnutls_srp_base64_encode (const gnutls_datum_t * DATA,
          char * RESULT, size_t * RESULT_SIZE)
     DATA: contain the raw data

     RESULT: the place where base64 data will be copied

     RESULT_SIZE: holds the size of the result

     This function will convert the given data to printable data, using
     the base64 encoding, as used in the libsrp.  This is the encoding
     used in SRP password files.  If the provided buffer is not long
     enough GNUTLS_E_SHORT_MEMORY_BUFFER is returned.

     Warning!  This base64 encoding is not the "standard" encoding, so
     do not use it for non-SRP purposes.

     *Returns:* 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
     not long enough, or 0 on success.

gnutls_srp_base64_encode2
-------------------------

 -- Function: int gnutls_srp_base64_encode2 (const gnutls_datum_t *
          DATA, gnutls_datum_t * RESULT)
     DATA: contains the raw data

     RESULT: will hold the newly allocated encoded data

     This function will convert the given data to printable data, using
     the base64 encoding.  This is the encoding used in SRP password
     files.  This function will allocate the required memory to hold the
     encoded data.

     You should use 'gnutls_free()' to free the returned data.

     Warning!  This base64 encoding is not the "standard" encoding, so
     do not use it for non-SRP purposes.

     *Returns:* 0 on success, or an error code.

gnutls_srp_free_client_credentials
----------------------------------

 -- Function: void gnutls_srp_free_client_credentials
          (gnutls_srp_client_credentials_t SC)
     SC: is a 'gnutls_srp_client_credentials_t' type.

     Free a gnutls_srp_client_credentials_t structure.

gnutls_srp_free_server_credentials
----------------------------------

 -- Function: void gnutls_srp_free_server_credentials
          (gnutls_srp_server_credentials_t SC)
     SC: is a 'gnutls_srp_server_credentials_t' type.

     Free a gnutls_srp_server_credentials_t structure.

gnutls_srp_server_get_username
------------------------------

 -- Function: const char * gnutls_srp_server_get_username
          (gnutls_session_t SESSION)
     SESSION: is a gnutls session

     This function will return the username of the peer.  This should
     only be called in case of SRP authentication and in case of a
     server.  Returns NULL in case of an error.

     *Returns:* SRP username of the peer, or NULL in case of error.

gnutls_srp_set_client_credentials
---------------------------------

 -- Function: int gnutls_srp_set_client_credentials
          (gnutls_srp_client_credentials_t RES, const char * USERNAME,
          const char * PASSWORD)
     RES: is a 'gnutls_srp_client_credentials_t' type.

     USERNAME: is the user's userid

     PASSWORD: is the user's password

     This function sets the username and password, in a
     'gnutls_srp_client_credentials_t' type.  Those will be used in SRP
     authentication.  '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()' .

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
     error code.

gnutls_srp_set_client_credentials_function
------------------------------------------

 -- 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.

gnutls_srp_set_prime_bits
-------------------------

 -- Function: void gnutls_srp_set_prime_bits (gnutls_session_t SESSION,
          unsigned int BITS)
     SESSION: is a 'gnutls_session_t' type.

     BITS: is the number of bits

     This function sets the minimum accepted number of bits, for use in
     an SRP key exchange.  If zero, the default 2048 bits will be used.

     In the client side it sets the minimum accepted number of bits.  If
     a server sends a prime with less bits than that
     'GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER' will be returned by the
     handshake.

     This function has no effect in server side.

     *Since:* 2.6.0

gnutls_srp_set_server_credentials_file
--------------------------------------

 -- 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.

gnutls_srp_set_server_credentials_function
------------------------------------------

 -- 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.

gnutls_srp_set_server_fake_salt_seed
------------------------------------

 -- Function: void gnutls_srp_set_server_fake_salt_seed
          (gnutls_srp_server_credentials_t CRED, const gnutls_datum_t *
          SEED, unsigned int SALT_LENGTH)
     CRED: is a 'gnutls_srp_server_credentials_t' type

     SEED: is the seed data, only needs to be valid until the function
     returns; size of the seed must be greater than zero

     SALT_LENGTH: is the length of the generated fake salts

     This function sets the seed that is used to generate salts for
     invalid (non-existent) usernames.

     In order to prevent attackers from guessing valid usernames, when a
     user does not exist gnutls generates a salt and a verifier and
     proceeds with the protocol as usual.  The authentication will
     ultimately fail, but the client cannot tell whether the username is
     valid (exists) or invalid.

     If an attacker learns the seed, given a salt (which is part of the
     handshake) which was generated when the seed was in use, it can
     tell whether or not the authentication failed because of an unknown
     username.  This seed cannot be used to reveal application data or
     passwords.

     'salt_length' should represent the salt length your application
     uses.  Generating fake salts longer than 20 bytes is not supported.

     By default the seed is a random value, different each time a
     'gnutls_srp_server_credentials_t' is allocated and fake salts are
     16 bytes long.

     *Since:* 3.3.0

gnutls_srp_verifier
-------------------

 -- Function: int gnutls_srp_verifier (const char * USERNAME, const char
          * PASSWORD, const gnutls_datum_t * SALT, const gnutls_datum_t
          * GENERATOR, const gnutls_datum_t * PRIME, gnutls_datum_t *
          RES)
     USERNAME: is the user's name

     PASSWORD: is the user's password

     SALT: should be some randomly generated bytes

     GENERATOR: is the generator of the group

     PRIME: is the group's prime

     RES: where the verifier will be stored.

     This function will create an SRP verifier, as specified in RFC2945.
     The 'prime' and 'generator' should be one of the static parameters
     defined in gnutls/gnutls.h or may be generated.

     The verifier will be allocated with 'gnutls_malloc' () and will be
     stored in 'res' using binary format.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
     error code.

gnutls_srtp_get_keys
--------------------

 -- Function: int gnutls_srtp_get_keys (gnutls_session_t SESSION, void *
          KEY_MATERIAL, unsigned int KEY_MATERIAL_SIZE, gnutls_datum_t *
          CLIENT_KEY, gnutls_datum_t * CLIENT_SALT, gnutls_datum_t *
          SERVER_KEY, gnutls_datum_t * SERVER_SALT)
     SESSION: is a 'gnutls_session_t' type.

     KEY_MATERIAL: Space to hold the generated key material

     KEY_MATERIAL_SIZE: The maximum size of the key material

     CLIENT_KEY: The master client write key, pointing inside the key
     material

     CLIENT_SALT: The master client write salt, pointing inside the key
     material

     SERVER_KEY: The master server write key, pointing inside the key
     material

     SERVER_SALT: The master server write salt, pointing inside the key
     material

     This is a helper function to generate the keying material for SRTP.
     It requires the space of the key material to be pre-allocated
     (should be at least 2x the maximum key size and salt size).  The
     'client_key' , 'client_salt' , 'server_key' and 'server_salt' are
     convenience datums that point inside the key material.  They may be
     'NULL' .

     *Returns:* On success the size of the key material is returned,
     otherwise, 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
     not sufficient, or a negative error code.

     Since 3.1.4

gnutls_srtp_get_mki
-------------------

 -- Function: int gnutls_srtp_get_mki (gnutls_session_t SESSION,
          gnutls_datum_t * MKI)
     SESSION: is a 'gnutls_session_t' type.

     MKI: will hold the MKI

     This function exports the negotiated Master Key Identifier,
     received by the peer if any.  The returned value in 'mki' should be
     treated as constant and valid only during the session's lifetime.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     Since 3.1.4

gnutls_srtp_get_profile_id
--------------------------

 -- Function: int gnutls_srtp_get_profile_id (const char * NAME,
          gnutls_srtp_profile_t * PROFILE)
     NAME: The name of the profile to look up

     PROFILE: Will hold the profile id

     This function allows you to look up a profile based on a string.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     Since 3.1.4

gnutls_srtp_get_profile_name
----------------------------

 -- Function: const char * gnutls_srtp_get_profile_name
          (gnutls_srtp_profile_t PROFILE)
     PROFILE: The profile to look up a string for

     This function allows you to get the corresponding name for a SRTP
     protection profile.

     *Returns:* On success, the name of a SRTP profile as a string,
     otherwise NULL.

     Since 3.1.4

gnutls_srtp_get_selected_profile
--------------------------------

 -- Function: int gnutls_srtp_get_selected_profile (gnutls_session_t
          SESSION, gnutls_srtp_profile_t * PROFILE)
     SESSION: is a 'gnutls_session_t' type.

     PROFILE: will hold the profile

     This function allows you to get the negotiated SRTP profile.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     Since 3.1.4

gnutls_srtp_set_mki
-------------------

 -- Function: int gnutls_srtp_set_mki (gnutls_session_t SESSION, const
          gnutls_datum_t * MKI)
     SESSION: is a 'gnutls_session_t' type.

     MKI: holds the MKI

     This function sets the Master Key Identifier, to be used by this
     session (if any).

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     Since 3.1.4

gnutls_srtp_set_profile
-----------------------

 -- Function: int gnutls_srtp_set_profile (gnutls_session_t SESSION,
          gnutls_srtp_profile_t PROFILE)
     SESSION: is a 'gnutls_session_t' type.

     PROFILE: is the profile id to add.

     This function is to be used by both clients and servers, to declare
     what SRTP profiles they support, to negotiate with the peer.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error code is returned.

     Since 3.1.4

gnutls_srtp_set_profile_direct
------------------------------

 -- Function: int gnutls_srtp_set_profile_direct (gnutls_session_t
          SESSION, const char * PROFILES, const char ** ERR_POS)
     SESSION: is a 'gnutls_session_t' type.

     PROFILES: is a string that contains the supported SRTP profiles,
     separated by colons.

     ERR_POS: In case of an error this will have the position in the
     string the error occurred, may be NULL.

     This function is to be used by both clients and servers, to declare
     what SRTP profiles they support, to negotiate with the peer.

     *Returns:* On syntax error 'GNUTLS_E_INVALID_REQUEST' is returned,
     'GNUTLS_E_SUCCESS' on success, or an error code.

     Since 3.1.4

gnutls_store_commitment
-----------------------

 -- 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

gnutls_store_pubkey
-------------------

 -- 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

gnutls_strerror
---------------

 -- Function: const char * gnutls_strerror (int ERROR)
     ERROR: is a GnuTLS error code, a negative error code

     This function is similar to strerror.  The difference is that it
     accepts an error number returned by a gnutls function; In case of
     an unknown error a descriptive string is sent instead of 'NULL' .

     Error codes are always a negative error code.

     *Returns:* A string explaining the GnuTLS error message.

gnutls_strerror_name
--------------------

 -- Function: const char * gnutls_strerror_name (int ERROR)
     ERROR: is an error returned by a gnutls function.

     Return the GnuTLS error code define as a string.  For example,
     gnutls_strerror_name (GNUTLS_E_DH_PRIME_UNACCEPTABLE) will return
     the string "GNUTLS_E_DH_PRIME_UNACCEPTABLE".

     *Returns:* A string corresponding to the symbol name of the error
     code.

     *Since:* 2.6.0

gnutls_supplemental_get_name
----------------------------

 -- Function: const char * gnutls_supplemental_get_name
          (gnutls_supplemental_data_format_type_t TYPE)
     TYPE: is a supplemental data format type

     Convert a 'gnutls_supplemental_data_format_type_t' value to a
     string.

     *Returns:* a string that contains the name of the specified
     supplemental data format type, or 'NULL' for unknown types.

gnutls_supplemental_recv
------------------------

 -- Function: void gnutls_supplemental_recv (gnutls_session_t SESSION,
          unsigned DO_RECV_SUPPLEMENTAL)
     SESSION: is a 'gnutls_session_t' type.

     DO_RECV_SUPPLEMENTAL: non-zero in order to expect supplemental data

     This function is to be called by an extension handler to instruct
     gnutls to attempt to receive supplemental data during the handshake
     process.

     *Since:* 3.4.0

gnutls_supplemental_register
----------------------------

 -- Function: int gnutls_supplemental_register (const char * NAME,
          gnutls_supplemental_data_format_type_t TYPE,
          gnutls_supp_recv_func RECV_FUNC, gnutls_supp_send_func
          SEND_FUNC)
     NAME: the name of the supplemental data to register

     TYPE: the type of the supplemental data format

     RECV_FUNC: the function to receive the data

     SEND_FUNC: the function to send the data

     This function will register a new supplemental data type (rfc4680).
     The registered data will remain until 'gnutls_global_deinit()' is
     called.  The provided 'type' must be an unassigned type in
     'gnutls_supplemental_data_format_type_t' .  If the type is already
     registered or handled by GnuTLS internally
     'GNUTLS_E_ALREADY_REGISTERED' will be returned.

     This function is not thread safe.  As supplemental data are not
     defined under TLS 1.3, this function will disable TLS 1.3 support
     globally.

     *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
     error code.

     *Since:* 3.4.0

gnutls_supplemental_send
------------------------

 -- Function: void gnutls_supplemental_send (gnutls_session_t SESSION,
          unsigned DO_SEND_SUPPLEMENTAL)
     SESSION: is a 'gnutls_session_t' type.

     DO_SEND_SUPPLEMENTAL: non-zero in order to send supplemental data

     This function is to be called by an extension handler to instruct
     gnutls to send supplemental data during the handshake process.

     *Since:* 3.4.0

gnutls_system_recv_timeout
--------------------------

 -- Function: int gnutls_system_recv_timeout (gnutls_transport_ptr_t
          PTR, unsigned int MS)
     PTR: A file descriptor (wrapped in a gnutls_transport_ptr_t
     pointer)

     MS: The number of milliseconds to wait.

     Wait for data to be received from the provided socket ( 'ptr' )
     within a timeout period in milliseconds, using 'select()' on the
     provided 'ptr' .

     This function is provided as a helper for constructing custom
     callbacks for 'gnutls_transport_set_pull_timeout_function()' ,
     which can be used if you rely on socket file descriptors.

     Returns -1 on error, 0 on timeout, positive value if data are
     available for reading.

     *Since:* 3.4.0

gnutls_tdb_deinit
-----------------

 -- Function: void gnutls_tdb_deinit (gnutls_tdb_t TDB)
     TDB: The structure to be deinitialized

     This function will deinitialize a public key trust storage
     structure.

gnutls_tdb_init
---------------

 -- Function: int gnutls_tdb_init (gnutls_tdb_t * TDB)
     TDB: A pointer to the type to be initialized

     This function will initialize a public key trust storage structure.

     *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
     otherwise a negative error value.

gnutls_tdb_set_store_commitment_func
------------------------------------

 -- Function: void gnutls_tdb_set_store_commitment_func (gnutls_tdb_t
          TDB, gnutls_tdb_store_commitment_func CSTORE)
     TDB: The trust storage

     CSTORE: The commitment storage function

     This function will associate a commitment (hash) storage function
     with the trust storage structure.  The function is of the following
     form.

     int gnutls_tdb_store_commitment_func(const char* db_name, const
     char* host, const char* service, time_t expiration,
     gnutls_digest_algorithm_t, const gnutls_datum_t* hash);

     The 'db_name' should be used to pass any private data to this
     function.

gnutls_tdb_set_store_func
-------------------------

 -- Function: void gnutls_tdb_set_store_func (gnutls_tdb_t TDB,
          gnutls_tdb_store_func STORE)
     TDB: The trust storage

     STORE: The storage function

     This function will associate a storage function with the trust
     storage structure.  The function is of the following form.

     int gnutls_tdb_store_func(const char* db_name, const char* host,
     const char* service, time_t expiration, const gnutls_datum_t*
     pubkey);

     The 'db_name' should be used to pass any private data to this
     function.

gnutls_tdb_set_verify_func
--------------------------

 -- Function: void gnutls_tdb_set_verify_func (gnutls_tdb_t TDB,
          gnutls_tdb_verify_func VERIFY)
     TDB: The trust storage

     VERIFY: The verification function

     This function will associate a retrieval function with the trust
     storage structure.  The function is of the following form.

     int gnutls_tdb_verify_func(const char* db_name, const char* host,
     const char* service, const gnutls_datum_t* pubkey);

     The verify function should return zero on a match,
     'GNUTLS_E_CERTIFICATE_KEY_MISMATCH' if there is a mismatch and any
     other negative error code otherwise.

     The 'db_name' should be used to pass any private data to this
     function.

gnutls_transport_get_int
------------------------

 -- Function: int gnutls_transport_get_int (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Used to get the first argument of the transport function (like PUSH
     and PULL). This must have been set using
     'gnutls_transport_set_int()' .

     *Returns:* The first argument of the transport function.

     *Since:* 3.1.9

gnutls_transport_get_int2
-------------------------

 -- Function: void gnutls_transport_get_int2 (gnutls_session_t SESSION,
          int * RECV_INT, int * SEND_INT)
     SESSION: is a 'gnutls_session_t' type.

     RECV_INT: will hold the value for the pull function

     SEND_INT: will hold the value for the push function

     Used to get the arguments of the transport functions (like PUSH and
     PULL). These should have been set using
     'gnutls_transport_set_int2()' .

     *Since:* 3.1.9

gnutls_transport_get_ptr
------------------------

 -- Function: gnutls_transport_ptr_t gnutls_transport_get_ptr
          (gnutls_session_t SESSION)
     SESSION: is a 'gnutls_session_t' type.

     Used to get the first argument of the transport function (like PUSH
     and PULL). This must have been set using
     'gnutls_transport_set_ptr()' .

     *Returns:* The first argument of the transport function.

gnutls_transport_get_ptr2
-------------------------

 -- Function: void gnutls_transport_get_ptr2 (gnutls_session_t SESSION,
          gnutls_transport_ptr_t * RECV_PTR, gnutls_transport_ptr_t *
          SEND_PTR)
     SESSION: is a 'gnutls_session_t' type.

     RECV_PTR: will hold the value for the pull function

     SEND_PTR: will hold the value for the push function

     Used to get the arguments of the transport functions (like PUSH and
     PULL). These should have been set using
     'gnutls_transport_set_ptr2()' .

gnutls_transport_set_errno
--------------------------

 -- 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_transport_set_errno_function
-----------------------------------

 -- Function: void gnutls_transport_set_errno_function (gnutls_session_t
          SESSION, gnutls_errno_func ERRNO_FUNC)
     SESSION: is a 'gnutls_session_t' type.

     ERRNO_FUNC: a callback function similar to 'write()'

     This is the function where you set a function to retrieve errno
     after a failed push or pull operation.

     'errno_func' is of the form, int
     (*gnutls_errno_func)(gnutls_transport_ptr_t); and should return the
     errno.

     *Since:* 2.12.0

gnutls_transport_set_int
------------------------

 -- Function: void gnutls_transport_set_int (gnutls_session_t SESSION,
          int FD)
     SESSION: is a 'gnutls_session_t' type.

     FD: is the socket descriptor for the connection.

     This function sets the first argument of the transport function,
     such as 'send()' and 'recv()' for the default callbacks using the
     system's socket API.

     This function is equivalent to calling 'gnutls_transport_set_ptr()'
     with the descriptor, but requires no casts.

     *Since:* 3.1.9

gnutls_transport_set_int2
-------------------------

 -- Function: void gnutls_transport_set_int2 (gnutls_session_t SESSION,
          int RECV_FD, int SEND_FD)
     SESSION: is a 'gnutls_session_t' type.

     RECV_FD: is socket descriptor for the pull function

     SEND_FD: is socket descriptor for the push function

     This function sets the first argument of the transport functions,
     such as 'send()' and 'recv()' for the default callbacks using the
     system's socket API. With this function you can set two different
     descriptors for receiving and sending.

     This function is equivalent to calling
     'gnutls_transport_set_ptr2()' with the descriptors, but requires no
     casts.

     *Since:* 3.1.9

gnutls_transport_set_ptr
------------------------

 -- Function: void gnutls_transport_set_ptr (gnutls_session_t SESSION,
          gnutls_transport_ptr_t PTR)
     SESSION: is a 'gnutls_session_t' type.

     PTR: is the value.

     Used to set the first argument of the transport function (for push
     and pull callbacks).  In berkeley style sockets this function will
     set the connection descriptor.

gnutls_transport_set_ptr2
-------------------------

 -- Function: void gnutls_transport_set_ptr2 (gnutls_session_t SESSION,
          gnutls_transport_ptr_t RECV_PTR, gnutls_transport_ptr_t
          SEND_PTR)
     SESSION: is a 'gnutls_session_t' type.

     RECV_PTR: is the value for the pull function

     SEND_PTR: is the value for the push function

     Used to set the first argument of the transport function (for push
     and pull callbacks).  In berkeley style sockets this function will
     set the connection descriptor.  With this function you can use two
     different pointers for receiving and sending.

gnutls_transport_set_pull_function
----------------------------------

 -- 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);

gnutls_transport_set_pull_timeout_function
------------------------------------------

 -- 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, and for calculating the DTLS
     mode timeouts.

     In short, this callback should 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()'
     .  For compatibility with future GnuTLS versions it is recommended
     to always set this function when a custom pull function is
     registered.

     The helper function 'gnutls_system_recv_timeout()' is provided to
     simplify writing callbacks.

     *Since:* 3.0

gnutls_transport_set_push_function
----------------------------------

 -- 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);

gnutls_transport_set_vec_push_function
--------------------------------------

 -- 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

gnutls_url_is_supported
-----------------------

 -- Function: unsigned gnutls_url_is_supported (const char * URL)
     URL: A URI to be tested

     Check whether the provided 'url' is supported.  Depending on the
     system libraries GnuTLS may support pkcs11, tpmkey or other URLs.

     *Returns:* return non-zero if the given URL is supported, and zero
     if it is not known.

     *Since:* 3.1.0

gnutls_utf8_password_normalize
------------------------------

 -- Function: int gnutls_utf8_password_normalize (const unsigned char *
          PASSWORD, unsigned PLEN, gnutls_datum_t * OUT, unsigned FLAGS)
     PASSWORD: contain the UTF-8 formatted password

     PLEN: the length of the provided password

     OUT: the result in an null-terminated allocated string

     FLAGS: should be zero

     This function will convert the provided UTF-8 password according to
     the normalization rules in RFC7613.

     If the flag 'GNUTLS_UTF8_IGNORE_ERRS' is specified, any UTF-8
     encoding errors will be ignored, and in that case the output will
     be a copy of the input.

     *Returns:* 'GNUTLS_E_INVALID_UTF8_STRING' on invalid UTF-8 data, or
     0 on success.

     *Since:* 3.5.7

gnutls_verify_stored_pubkey
---------------------------

 -- 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