diff options
Diffstat (limited to 'doc/gnutls.info-3')
| -rw-r--r-- | doc/gnutls.info-3 | 14926 |
1 files changed, 14926 insertions, 0 deletions
diff --git a/doc/gnutls.info-3 b/doc/gnutls.info-3 new file mode 100644 index 0000000..ecd772c --- /dev/null +++ b/doc/gnutls.info-3 @@ -0,0 +1,14926 @@ +This is gnutls.info, produced by makeinfo version 6.8 from gnutls.texi. + +This manual is last updated 9 February 2023 for version 3.7.9 of GnuTLS. + +Copyright (C) 2001-2023 Free Software Foundation, Inc.\\ Copyright (C) +2001-2023 Nikos Mavrogiannopoulos + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". +INFO-DIR-SECTION Software libraries +START-INFO-DIR-ENTRY +* GnuTLS: (gnutls). GNU Transport Layer Security Library. +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION System Administration +START-INFO-DIR-ENTRY +* certtool: (gnutls)certtool Invocation. Manipulate certificates and keys. +* gnutls-serv: (gnutls)gnutls-serv Invocation. GnuTLS test server. +* gnutls-cli: (gnutls)gnutls-cli Invocation. GnuTLS test client. +* gnutls-cli-debug: (gnutls)gnutls-cli-debug Invocation. GnuTLS debug client. +* psktool: (gnutls)psktool Invocation. Simple TLS-Pre-Shared-Keys manager. +* srptool: (gnutls)srptool Invocation. Simple SRP password tool. +END-INFO-DIR-ENTRY + + +File: gnutls.info, Node: Echo server with SRP authentication, Next: Echo server with anonymous authentication, Prev: Echo server with PSK authentication, Up: More advanced client and servers + +7.3.10 Echo server with SRP authentication +------------------------------------------ + +This is a server which supports SRP authentication. It is also possible +to combine this functionality with a certificate server. Here it is +separate for simplicity. + +/* This example code is placed in the public domain. */ + +#ifdef HAVE_CONFIG_H +#include <config.h> +#endif + +#include <stdio.h> +#include <stdlib.h> +#include <errno.h> +#include <sys/types.h> +#include <sys/socket.h> +#include <arpa/inet.h> +#include <netinet/in.h> +#include <string.h> +#include <unistd.h> +#include <gnutls/gnutls.h> + +#define SRP_PASSWD "tpasswd" +#define SRP_PASSWD_CONF "tpasswd.conf" + +#define KEYFILE "key.pem" +#define CERTFILE "cert.pem" +#define CAFILE "/etc/ssl/certs/ca-certificates.crt" + +#define LOOP_CHECK(rval, cmd) \ + do { \ + rval = cmd; \ + } while(rval == GNUTLS_E_AGAIN || rval == GNUTLS_E_INTERRUPTED) + +/* This is a sample TLS-SRP echo server. + */ + +#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_srp_server_credentials_t srp_cred; + gnutls_certificate_credentials_t cert_cred; + char buffer[MAX_BUF + 1]; + int optval = 1; + char name[256]; + + strcpy(name, "Echo Server"); + + 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(); + + /* SRP_PASSWD a password file (created with the included srptool utility) + */ + gnutls_srp_allocate_server_credentials(&srp_cred); + gnutls_srp_set_server_credentials_file(srp_cred, SRP_PASSWD, + SRP_PASSWD_CONF); + + gnutls_certificate_allocate_credentials(&cert_cred); + gnutls_certificate_set_x509_trust_file(cert_cred, CAFILE, + GNUTLS_X509_FMT_PEM); + gnutls_certificate_set_x509_key_file(cert_cred, CERTFILE, KEYFILE, + GNUTLS_X509_FMT_PEM); + + /* TCP 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("%s ready. Listening to port '%d'.\n\n", name, PORT); + + client_len = sizeof(sa_cli); + for (;;) { + gnutls_init(&session, GNUTLS_SERVER); + gnutls_priority_set_direct(session, + "NORMAL" + ":-KX-ALL:+SRP:+SRP-DSS:+SRP-RSA", + NULL); + gnutls_credentials_set(session, GNUTLS_CRD_SRP, srp_cred); + /* for the certificate authenticated ciphersuites. + */ + gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, + cert_cred); + + /* We don't request any certificate from the client. + * If we did we would need to verify it. One way of + * doing that is shown in the "Verifying a certificate" + * example. + */ + gnutls_certificate_server_set_request(session, + GNUTLS_CERT_IGNORE); + + sd = accept(listen_sd, (struct sockaddr *) &sa_cli, + &client_len); + + printf("- connection from %s, port %d\n", + inet_ntop(AF_INET, &sa_cli.sin_addr, topbuf, + sizeof(topbuf)), ntohs(sa_cli.sin_port)); + + gnutls_transport_set_int(session, sd); + + LOOP_CHECK(ret, gnutls_handshake(session)); + if (ret < 0) { + close(sd); + gnutls_deinit(session); + fprintf(stderr, + "*** Handshake has failed (%s)\n\n", + gnutls_strerror(ret)); + continue; + } + printf("- Handshake was completed\n"); + printf("- User %s was connected\n", + gnutls_srp_server_get_username(session)); + + /* print_info(session); */ + + for (;;) { + LOOP_CHECK(ret, gnutls_record_recv(session, buffer, MAX_BUF)); + + if (ret == 0) { + printf + ("\n- Peer has closed the GnuTLS connection\n"); + break; + } else if (ret < 0 + && gnutls_error_is_fatal(ret) == 0) { + fprintf(stderr, "*** Warning: %s\n", + gnutls_strerror(ret)); + } else if (ret < 0) { + fprintf(stderr, "\n*** Received corrupted " + "data(%d). Closing the connection.\n\n", + ret); + break; + } else if (ret > 0) { + /* echo data back to the client + */ + gnutls_record_send(session, buffer, ret); + } + } + printf("\n"); + /* do not wait for the peer to close the connection. */ + LOOP_CHECK(ret, gnutls_bye(session, GNUTLS_SHUT_WR)); + + close(sd); + gnutls_deinit(session); + + } + close(listen_sd); + + gnutls_srp_free_server_credentials(srp_cred); + gnutls_certificate_free_credentials(cert_cred); + + gnutls_global_deinit(); + + return 0; + +} + + +File: gnutls.info, Node: Echo server with anonymous authentication, Next: Helper functions for TCP connections, Prev: Echo server with SRP authentication, Up: More advanced client and servers + +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; + +} + + +File: gnutls.info, Node: Helper functions for TCP connections, Next: Helper functions for UDP connections, Prev: Echo server with anonymous authentication, Up: More advanced client and servers + +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); +} + + +File: gnutls.info, Node: Helper functions for UDP connections, Prev: Helper functions for TCP connections, Up: More advanced client and servers + +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); +} + + +File: gnutls.info, Node: OCSP example, Next: Miscellaneous examples, Prev: More advanced client and servers, Up: GnuTLS application examples + +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); + if (!hostname) { + fprintf(stderr, "error: cannot allocate memory\n"); + exit(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_file(cert_file, RF_BINARY, &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; +} + + +File: gnutls.info, Node: Miscellaneous examples, Prev: OCSP example, Up: GnuTLS application examples + +7.5 Miscellaneous examples +========================== + +* Menu: + +* Checking for an alert:: +* X.509 certificate parsing example:: +* Listing the ciphersuites in a priority string:: +* PKCS12 structure generation example:: + + +File: gnutls.info, Node: Checking for an alert, Next: X.509 certificate parsing example, Up: 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)); + } +} + + +File: gnutls.info, Node: X.509 certificate parsing example, Next: Listing the ciphersuites in a priority string, Prev: Checking for an alert, Up: Miscellaneous examples + +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); + + } +} + + +File: gnutls.info, Node: Listing the ciphersuites in a priority string, Next: PKCS12 structure generation example, Prev: X.509 certificate parsing example, Up: Miscellaneous examples + +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; +} + + +File: gnutls.info, Node: PKCS12 structure generation example, Prev: Listing the ciphersuites in a priority string, Up: Miscellaneous examples + +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 *fp; + + /* 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; + } + + fp = fopen(OUTFILE, "w"); + if (fp == NULL) { + fprintf(stderr, "cannot open file\n"); + return 1; + } + fwrite(pkcs12_struct, 1, pkcs12_struct_size, fp); + fclose(fp); + + gnutls_pkcs12_bag_deinit(bag); + gnutls_pkcs12_bag_deinit(key_bag); + gnutls_pkcs12_deinit(pkcs12); + + return 0; +} + + +File: gnutls.info, Node: System-wide configuration of the library, Next: Using GnuTLS as a cryptographic library, Prev: GnuTLS application examples, Up: Top + +8 System-wide configuration of the library +****************************************** + +GnuTLS 3.6.9 introduced a system-wide configuration of the library which +can be used to disable or mark algorithms and protocols as insecure +system-wide, overriding the library defaults. The format of this +configuration file is of an INI file, with the hash ('#') allowed for +commenting. It intentionally does not allow switching algorithms or +protocols which were disabled or marked as insecure during compile time +to the secure set. This is to prevent the feature from being used to +attack the system. Unknown options or sections in the configuration +file are skipped unless the environment variable +'GNUTLS_SYSTEM_PRIORITY_FAIL_ON_INVALID' is set to 1, where it would +cause the library to exit on unknown options. + +The location of the default configuration file is '/etc/gnutls/config', +but its actual location may be overridden during compile time or at +run-time using the 'GNUTLS_SYSTEM_PRIORITY_FILE' environment variable. +The file used can be queried using *note +gnutls_get_system_config_file::. + + -- Function: const char * gnutls_get_system_config_file ( VOID) + + Returns the filename of the system wide configuration file to be + loaded by the library. + + *Returns:* a constant pointer to the config file path + + *Since:* 3.6.9 + +* Menu: + +* Application-specific priority strings:: +* Disabling algorithms and protocols:: +* Querying for disabled algorithms and protocols:: +* Overriding the parameter verification profile:: +* Overriding the default priority string:: +* Enabling/Disabling system/acceleration protocols:: + + +File: gnutls.info, Node: Application-specific priority strings, Next: Disabling algorithms and protocols, Up: System-wide configuration of the library + +8.1 Application-specific priority strings +========================================= + +It is possible to specify custom cipher priority strings, in addition to +the default priority strings ('NORMAL', 'PERFORMANCE', etc.). These can +be used either by individual applications, or even as the default option +if the library is compiled with the configuration option +'--with-default-priority-string'. In the latter case the defined +priority string will be used for applications using *note +gnutls_set_default_priority:: or *note +gnutls_set_default_priority_append::. + +The priority strings can be specified in the global section of the +configuration file, or in the section named '[priorities]'. The format +is ''KEYWORD = VALUE'', e.g., + +When used they may be followed by additional options that will be +appended to the system string (e.g., ''@EXAMPLE-PRIORITY:+SRP''). +''EXAMPLE-PRIORITY=NORMAL:+ARCFOUR-128''. Since version 3.5.1 +applications are allowed to specify fallback keywords such as +@KEYWORD1,@KEYWORD2, and the first valid keyword will be used. + +The following example configuration defines a priority string called +'@SYSTEM'. When set, its full settings can be queried using 'gnutls-cli +--priority @SYSTEM --list'. + + [priorities] + SYSTEM = NORMAL:-AES-128-CBC:-AES-256-CBC + + +File: gnutls.info, Node: Disabling algorithms and protocols, Next: Querying for disabled algorithms and protocols, Prev: Application-specific priority strings, Up: System-wide configuration of the library + +8.2 Disabling algorithms and protocols +====================================== + +The approach above works well to create consistent system-wide settings +for cooperative GnuTLS applications. When an application however does +not use the *note gnutls_set_default_priority:: or *note +gnutls_set_default_priority_append:: functions, the method is not +sufficient to prevent applications from using protocols or algorithms +forbidden by a local policy. The override method described below +enables the deprecation of algorithms and protocols system-wide for all +applications. + +The available options must be set in the '[overrides]' section of the +configuration file and can be + * 'insecure-sig-for-cert': to mark the signature algorithm as + insecure when used in certificates. + * 'insecure-sig': to mark the signature algorithm as insecure for any + use. + * 'insecure-hash': to mark the hash algorithm as insecure for digital + signature use (provides a more generic way to disable digital + signatures for broken hash algorithms). + * 'disabled-curve': to disable the specified elliptic curve. + * 'disabled-version': to disable the specified TLS versions. + * 'tls-disabled-cipher': to disable the specified ciphers for use in + the TLS or DTLS protocols. + * 'tls-disabled-mac': to disable the specified MAC algorithms for use + in the TLS or DTLS protocols. + * 'tls-disabled-group': to disable the specified group for use in the + TLS or DTLS protocols. + * 'tls-disabled-kx': to disable the specified key exchange algorithms + for use in the TLS or DTLS protocols (applies to TLS1.2 or + earlier). + +Each of the options can be repeated multiple times when multiple values +need to be disabled or enabled. + +The valid values for the options above can be found in the 'Protocols', +'Digests' 'PK-signatures', 'Protocols', 'Ciphers', and 'MACs' fields of +the output of 'gnutls-cli --list'. + +Sometimes the system administrator wants to enable only specific +algorithms, despite the library defaults. GnuTLS provides an +alternative mode of overriding: allowlisting. + +As shown below in the examples, it is hard to use this mode correctly, +as it requires understanding of how algorithms are used underneath by +the protocols. Allowlisting configuration mode is intended to be used +by the operating system vendors that prefer laying out the library +defaults exhaustively from scratch instead on depending on gnutls +presets, such as 'NORMAL'. Applications are then expected to optionally +disable or enable only a subset algorithms on top of the vendor-provided +configuration. + +In the allowlisting mode, all the algorithms are initially marked as +insecure or disabled, and shall be explicitly turned on by the options +listed below in the '[overrides]' section. As the allowlisting mode is +mutually exclusive to the blocklisting mode, the options listed above +for the blocklisting mode are forbidden in the allowlisting mode, and +vice versa. + + * 'secure-sig-for-cert': to mark the signature algorithm as secure + when used in certificates. + * 'secure-sig': to mark the signature algorithm as secure for any + use. + * 'secure-hash': to mark the hash algorithm as secure for digital + signature use (provides a more generic way to enable digital + signatures for broken hash algorithms). + * 'enabled-curve': to enable the specified elliptic curve. + * 'enabled-version': to enable the specified TLS versions. + * 'tls-enabled-cipher': to enable the specified ciphers for use in + the TLS or DTLS protocols. + * 'tls-enabled-mac': to enable the specified MAC algorithms for use + in the TLS or DTLS protocols. + * 'tls-enabled-group': to enable the specified group for use in the + TLS or DTLS protocols. + * 'tls-enabled-kx': to enable the specified key exchange algorithms + for use in the TLS or DTLS protocols (applies to TLS1.2 or + earlier). + +The allowlisting mode can be enabled by adding 'override-mode = +allowlist' in the '[global]' section. + +The following functions allow the applications to modify the setting. + +'INT *note gnutls_ecc_curve_set_enabled:: (gnutls_ecc_curve_t CURVE, unsigned int ENABLED)' +'INT *note gnutls_sign_set_secure:: (gnutls_sign_algorithm_t SIGN, unsigned int SECURE)' +'INT *note gnutls_sign_set_secure_for_certs:: (gnutls_sign_algorithm_t SIGN, unsigned int SECURE)' +'INT *note gnutls_digest_set_secure:: (gnutls_digest_algorithm_t DIG, unsigned int SECURE)' +'INT *note gnutls_protocol_set_enabled:: (gnutls_protocol_t VERSION, unsigned int ENABLED)' + +When the allowlisting mode is in effect, a '@SYSTEM' priority string is +automatically constructed from the options in the '[overrides]' section. +For this reason, the above functions should be called before the +'@SYSTEM' priority is used. + +8.2.1 Examples +-------------- + +The following example marks as insecure all digital signature algorithms +which depend on SHA384, as well as the RSA-SHA1 signature algorithm. + + [overrides] + insecure-hash = sha384 + insecure-sig = rsa-sha1 + +The following example marks RSA-SHA256 as insecure for use in +certificates and disables the TLS1.0 and TLS1.1 protocols. + + [overrides] + insecure-sig-for-cert = rsa-sha256 + disabled-version = tls1.0 + disabled-version = tls1.1 + +The following example disables the 'AES-128-CBC' and 'AES-256-CBC' +ciphers, the 'HMAC-SHA1' MAC algorithm and the 'GROUP-FFDHE8192' group +for TLS and DTLS protocols. + + [overrides] + tls-disabled-cipher = aes-128-cbc + tls-disabled-cipher = aes-256-cbc + tls-disabled-mac = sha1 + tls-disabled-group = group-ffdhe8192 + +The following example demonstrates the use of the allowlisting mode. +All the signature algorithms are disabled by default but 'RSA-SHA256'. +Note that the hash algorithm 'SHA256' also needs to be explicitly +enabled. + + [global] + override-mode = allowlist + + [overrides] + secure-hash = sha256 + secure-sig = rsa-sha256 + +To enable a TLS ciphersuite in the allowlist mode requires a more +verbose configuration, explicitly listing algorithm dependencies. The +following example enables TLS_AES_128_GCM_SHA256, using the SECP256R1 +curve for signing and key exchange. + + [global] + override-mode = allowlist + + [overrides] + secure-hash = sha256 + enabled-curve = secp256r1 + secure-sig = ecdsa-secp256r1-sha256 + enabled-version = tls1.3 + tls-enabled-cipher = aes-128-gcm + tls-enabled-mac = aead + tls-enabled-group = secp256r1 + + +File: gnutls.info, Node: Querying for disabled algorithms and protocols, Next: Overriding the parameter verification profile, Prev: Disabling algorithms and protocols, Up: System-wide configuration of the library + +8.3 Querying for disabled algorithms and protocols +================================================== + +When necessary applications can query whether a particular algorithm or +protocol has been marked as insecure or disabled system-wide. Digital +signatures can be queried using the following algorithms. +'UNSIGNED *note gnutls_sign_is_secure:: (gnutls_sign_algorithm_t ALGORITHM)' +'UNSIGNED *note gnutls_sign_is_secure2:: (gnutls_sign_algorithm_t ALGORITHM, unsigned int FLAGS)' + +Any disabled protocol versions or elliptic curves will not show up in +the lists provided by the following functions. + +'CONST GNUTLS_PROTOCOL_T * *note gnutls_protocol_list:: ( VOID)' +'CONST GNUTLS_GROUP_T * *note gnutls_group_list:: ( VOID)' +'CONST GNUTLS_ECC_CURVE_T * *note gnutls_ecc_curve_list:: ( VOID)' + +It is not possible to query for insecure hash algorithms directly (only +indirectly through the signature API). + + +File: gnutls.info, Node: Overriding the parameter verification profile, Next: Overriding the default priority string, Prev: Querying for disabled algorithms and protocols, Up: System-wide configuration of the library + +8.4 Overriding the parameter verification profile +================================================= + +When verifying a certificate or TLS session parameters, GnuTLS uses a +set of profiles associated with the session to determine whether the +parameters seen in the session are acceptable. For example, whether the +RSA public key size as seen on the wire, or the Diffie-Hellman +parameters for the session. These profiles are normally set using the +'%PROFILE' priority string (see *note Priority Strings:: and *note +Selecting cryptographic key sizes::). + +It is possible to set the low bar profile that applications cannot +override using the following. + + [overrides] + + # do not allow applications use the LOW or VERY-WEAK profiles. + min-verification-profile = legacy + + + +File: gnutls.info, Node: Overriding the default priority string, Next: Enabling/Disabling system/acceleration protocols, Prev: Overriding the parameter verification profile, Up: System-wide configuration of the library + +8.5 Overriding the default priority string +========================================== + +GnuTLS uses default priority string which is defined at compiled time. +Usually it is set to 'NORMAL'. This override allows to set the default +priority string to something more appropriate for a given deployment. + +Below example sets a more specific default priority string. + [overrides] + default-priority-string = SECURE128:-VERS-TLS-ALL:+VERS-TLS1.3 + + + +File: gnutls.info, Node: Enabling/Disabling system/acceleration protocols, Prev: Overriding the default priority string, Up: System-wide configuration of the library + +8.6 Enabling/Disabling system/acceleration protocols +==================================================== + +The following options can overwrite default behavior of protocols +system-wide. + [global] + ktls = true + + +8.6.1 Enabling KTLS +------------------- + +When GnuTLS is build with -–enable-ktls configuration, KTLS is disabled +by default. This can be enabled by setting 'ktls = true' in '[global]' +section. + + +File: gnutls.info, Node: Using GnuTLS as a cryptographic library, Next: Other included programs, Prev: System-wide configuration of the library, Up: Top + +9 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 *note 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. + +* Menu: + +* Symmetric algorithms:: +* Public key algorithms:: +* Cryptographic Message Syntax / PKCS7:: +* Hash and MAC functions:: +* Random number generation:: +* Overriding algorithms:: + + ---------- Footnotes ---------- + + (1) See <https://www.lysator.liu.se/~nisse/nettle/>. + + +File: gnutls.info, Node: Symmetric algorithms, Next: Public key algorithms, Up: Using GnuTLS as a cryptographic library + +9.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 *note +Figure 9.1: gnutls_cipher_algorithm_t. 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 ciphers under the AEAD APIs +for new applications as they are designed to minimize the misuse of +cryptographic primitives. + +'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 (AEAD). +'GNUTLS_CIPHER_AES_256_GCM' + AES in GCM mode with 256-bit keys (AEAD). +'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 (AEAD). +'GNUTLS_CIPHER_CAMELLIA_256_GCM' + CAMELLIA in GCM mode with 256-bit keys (AEAD). +'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 (AEAD). +'GNUTLS_CIPHER_AES_256_CCM' + AES in CCM mode with 256-bit keys (AEAD). +'GNUTLS_CIPHER_AES_128_CCM_8' + AES in CCM mode with 64-bit tag and 128-bit keys (AEAD). +'GNUTLS_CIPHER_AES_256_CCM_8' + AES in CCM mode with 64-bit tag and 256-bit keys (AEAD). +'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_AES_128_XTS' + AES in XTS mode with 128-bit key + 128bit tweak key. +'GNUTLS_CIPHER_AES_256_XTS' + AES in XTS mode with 256-bit key + 256bit tweak key. Note that the + XTS ciphers are message oriented. The whole message needs to be + provided with a single call, because cipher-stealing requires to + know where the message actually terminates in order to be able to + compute where the stealing occurs. +'GNUTLS_CIPHER_GOST28147_TC26Z_CNT' + GOST 28147-89 (Magma) cipher in CNT mode with TC26 Z S-box. +'GNUTLS_CIPHER_CHACHA20_64' + Chacha20 cipher with 64-bit nonces and 64-bit block counters. +'GNUTLS_CIPHER_CHACHA20_32' + Chacha20 cipher with 96-bit nonces and 32-bit block counters. +'GNUTLS_CIPHER_AES_128_SIV' + AES in SIV mode with 128-bit key. +'GNUTLS_CIPHER_AES_256_SIV' + AES in SIV mode with 256-bit key. Note that the SIV ciphers can + only be used with the AEAD interface, and the IV plays a role as + the authentication tag while it is prepended to the cipher text. +'GNUTLS_CIPHER_AES_192_GCM' + AES in GCM mode with 192-bit keys (AEAD). +'GNUTLS_CIPHER_MAGMA_CTR_ACPKM' + GOST R 34.12-2015 (Magma) cipher in CTR-ACPKM mode. +'GNUTLS_CIPHER_KUZNYECHIK_CTR_ACPKM' + GOST R 34.12-2015 (Kuznyechik) cipher in CTR-ACPKM mode. +'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 9.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; these ciphers are +marked with the AEAD keyword on the table above. The AEAD cipher API 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 *note gnutls_aead_cipher_init:: (gnutls_aead_cipher_hd_t * HANDLE, gnutls_cipher_algorithm_t CIPHER, const gnutls_datum_t * KEY)' +'INT *note 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 *note 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 *note 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 *note gnutls_cipher_init:: (gnutls_cipher_hd_t * HANDLE, gnutls_cipher_algorithm_t CIPHER, const gnutls_datum_t * KEY, const gnutls_datum_t * IV)' +'INT *note gnutls_cipher_encrypt2:: (gnutls_cipher_hd_t HANDLE, const void * PTEXT, size_t PTEXT_LEN, void * CTEXT, size_t CTEXT_LEN)' +'INT *note gnutls_cipher_decrypt2:: (gnutls_cipher_hd_t HANDLE, const void * CTEXT, size_t CTEXT_LEN, void * PTEXT, size_t PTEXT_LEN)' +'VOID *note gnutls_cipher_set_iv:: (gnutls_cipher_hd_t HANDLE, void * IV, size_t IVLEN)' +'VOID *note gnutls_cipher_deinit:: (gnutls_cipher_hd_t HANDLE)' + +'INT *note gnutls_cipher_add_auth:: (gnutls_cipher_hd_t HANDLE, const void * PTEXT, size_t PTEXT_SIZE)' +'INT *note 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> + + +File: gnutls.info, Node: Public key algorithms, Next: Cryptographic Message Syntax / PKCS7, Prev: Symmetric algorithms, Up: Using GnuTLS as a cryptographic library + +9.2 Public key algorithms +========================= + +Public key cryptography algorithms such as RSA, DSA and ECDSA, are +accessed using the abstract key API in *note 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 *note gnutls_privkey_init:: (gnutls_privkey_t * KEY)' +'INT *note gnutls_privkey_import_url:: (gnutls_privkey_t KEY, const char * URL, unsigned int FLAGS)' +'INT *note 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 *note 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 *note 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 *note gnutls_privkey_deinit:: (gnutls_privkey_t KEY)' + +'INT *note gnutls_pubkey_init:: (gnutls_pubkey_t * KEY)' +'INT *note gnutls_pubkey_import_url:: (gnutls_pubkey_t KEY, const char * URL, unsigned int FLAGS)' +'INT *note gnutls_pubkey_import_x509:: (gnutls_pubkey_t KEY, gnutls_x509_crt_t CRT, unsigned int FLAGS)' +'INT *note 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 *note 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 *note gnutls_pubkey_deinit:: (gnutls_pubkey_t KEY)' + +Keys stored in memory can be imported using functions like *note +gnutls_privkey_import_x509_raw::, while keys on smart cards or HSMs +should be imported using their PKCS#11 URL with *note +gnutls_privkey_import_url::. + +If any of the smart card operations require PIN, that should be provided +either by setting the global PIN function (*note +gnutls_pkcs11_set_pin_function::), or better with the targeted to +structures functions such as *note gnutls_privkey_set_pin_function::. + +9.2.1 Key generation +-------------------- + +All supported key types (including RSA, DSA, ECDSA, Ed25519, Ed448) can +be generated with GnuTLS. They can be generated with the simpler *note +gnutls_privkey_generate:: or with the more advanced *note +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 + + +File: gnutls.info, Node: Cryptographic Message Syntax / PKCS7, Next: Hash and MAC functions, Prev: Public key algorithms, Up: Using GnuTLS as a cryptographic library + +9.3 Cryptographic Message Syntax / PKCS7 +======================================== + +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 *note gnutls_pkcs7_init:: (gnutls_pkcs7_t * PKCS7)' +'VOID *note gnutls_pkcs7_deinit:: (gnutls_pkcs7_t PKCS7)' +'INT *note gnutls_pkcs7_export2:: (gnutls_pkcs7_t PKCS7, gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)' +'INT *note gnutls_pkcs7_import:: (gnutls_pkcs7_t PKCS7, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)' +'INT *note 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 *note +gnutls_pkcs7_sign:: function is the data signing function. + +'INT *note gnutls_pkcs7_verify_direct:: (gnutls_pkcs7_t PKCS7, gnutls_x509_crt_t SIGNER, unsigned IDX, const gnutls_datum_t * DATA, unsigned FLAGS)' +'INT *note 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 9.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 *note gnutls_pkcs7_get_signature_count:: (gnutls_pkcs7_t PKCS7)' +'INT *note gnutls_pkcs7_get_signature_info:: (gnutls_pkcs7_t PKCS7, unsigned IDX, gnutls_pkcs7_signature_info_st * INFO)' +'INT *note gnutls_pkcs7_get_crt_count:: (gnutls_pkcs7_t PKCS7)' +'INT *note gnutls_pkcs7_get_crt_raw2:: (gnutls_pkcs7_t PKCS7, unsigned INDX, gnutls_datum_t * CERT)' +'INT *note gnutls_pkcs7_get_crl_count:: (gnutls_pkcs7_t PKCS7)' +'INT *note 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 *note gnutls_pkcs7_set_crt_raw:: (gnutls_pkcs7_t PKCS7, const gnutls_datum_t * CRT)' +'INT *note gnutls_pkcs7_set_crt:: (gnutls_pkcs7_t PKCS7, gnutls_x509_crt_t CRT)' +'INT *note gnutls_pkcs7_set_crl_raw:: (gnutls_pkcs7_t PKCS7, const gnutls_datum_t * CRL)' +'INT *note gnutls_pkcs7_set_crl:: (gnutls_pkcs7_t PKCS7, gnutls_x509_crl_t CRL)' + + +File: gnutls.info, Node: Hash and MAC functions, Next: Random number generation, Prev: Cryptographic Message Syntax / PKCS7, Up: Using GnuTLS as a cryptographic library + +9.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 +*note Figure 9.3: gnutls_mac_algorithm_t. 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 (requires nonce). +'GNUTLS_MAC_UMAC_128' + The UMAC-128 MAC algorithm (requires nonce). +'GNUTLS_MAC_AES_CMAC_128' + The AES-CMAC-128 MAC algorithm. +'GNUTLS_MAC_AES_CMAC_256' + The AES-CMAC-256 MAC algorithm. +'GNUTLS_MAC_AES_GMAC_128' + The AES-GMAC-128 MAC algorithm (requires nonce). +'GNUTLS_MAC_AES_GMAC_192' + The AES-GMAC-192 MAC algorithm (requires nonce). +'GNUTLS_MAC_AES_GMAC_256' + The AES-GMAC-256 MAC algorithm (requires nonce). +'GNUTLS_MAC_GOST28147_TC26Z_IMIT' + The GOST 28147-89 working in IMIT mode with TC26 Z S-box. +'GNUTLS_MAC_SHAKE_128' + Reserved; unimplemented. +'GNUTLS_MAC_SHAKE_256' + Reserved; unimplemented. +'GNUTLS_MAC_MAGMA_OMAC' + GOST R 34.12-2015 (Magma) in OMAC (CMAC) mode. +'GNUTLS_MAC_KUZNYECHIK_OMAC' + GOST R 34.12-2015 (Kuznyechik) in OMAC (CMAC) mode. + + +Figure 9.3: The supported MAC and HMAC algorithms. + +'INT *note gnutls_hmac_init:: (gnutls_hmac_hd_t * DIG, gnutls_mac_algorithm_t ALGORITHM, const void * KEY, size_t KEYLEN)' +'INT *note gnutls_hmac:: (gnutls_hmac_hd_t HANDLE, const void * PTEXT, size_t PTEXT_LEN)' +'VOID *note gnutls_hmac_output:: (gnutls_hmac_hd_t HANDLE, void * DIGEST)' +'VOID *note gnutls_hmac_deinit:: (gnutls_hmac_hd_t HANDLE, void * DIGEST)' +'UNSIGNED *note gnutls_hmac_get_len:: (gnutls_mac_algorithm_t ALGORITHM)' +'INT *note 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 *note Figure 9.4: +gnutls_digest_algorithm_t. + +'INT *note gnutls_hash_init:: (gnutls_hash_hd_t * DIG, gnutls_digest_algorithm_t ALGORITHM)' +'INT *note gnutls_hash:: (gnutls_hash_hd_t HANDLE, const void * PTEXT, size_t PTEXT_LEN)' +'VOID *note gnutls_hash_output:: (gnutls_hash_hd_t HANDLE, void * DIGEST)' +'VOID *note gnutls_hash_deinit:: (gnutls_hash_hd_t HANDLE, void * DIGEST)' +'UNSIGNED *note gnutls_hash_get_len:: (gnutls_digest_algorithm_t ALGORITHM)' +'INT *note gnutls_hash_fast:: (gnutls_digest_algorithm_t ALGORITHM, const void * PTEXT, size_t PTEXT_LEN, void * DIGEST)' +'INT *note 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. +'GNUTLS_DIG_SHAKE_128' + Reserved; unimplemented. +'GNUTLS_DIG_SHAKE_256' + Reserved; unimplemented. + + +Figure 9.4: The supported hash algorithms. + + +File: gnutls.info, Node: Random number generation, Next: Overriding algorithms, Prev: Hash and MAC functions, Up: Using GnuTLS as a cryptographic library + +9.5 Random number generation +============================ + +Access to the random number generator is provided using the *note +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 9.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 *note Random Number Generators-internals:: for more information on +the random number generator operation. + + +File: gnutls.info, Node: Overriding algorithms, Prev: Random number generation, Up: Using GnuTLS as a cryptographic library + +9.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 *note 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. + + *Deprecated:* since 3.7.0 it is no longer possible to override + cipher implementation + + *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. + + *Deprecated:* since 3.7.0 it is no longer possible to override + cipher implementation + + *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. + + *Deprecated:* since 3.7.0 it is no longer possible to override + cipher implementation + + *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. + + *Deprecated:* since 3.7.0 it is no longer possible to override + cipher implementation + + *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative + error code. + + *Since:* 3.4.0 + + +File: gnutls.info, Node: Other included programs, Next: Internal architecture of GnuTLS, Prev: Using GnuTLS as a cryptographic library, Up: Top + +10 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. + +* Menu: + +* gnutls-cli Invocation:: Invoking gnutls-cli +* gnutls-serv Invocation:: Invoking gnutls-serv +* gnutls-cli-debug Invocation:: Invoking gnutls-cli-debug + + +File: gnutls.info, Node: gnutls-cli Invocation, Next: gnutls-serv Invocation, Up: Other included programs + +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. + +gnutls-cli help/usage ('-?') +---------------------------- + +The text printed is the same whether selected with the 'help' option +('--help') or the 'more-help' option ('--more-help'). 'more-help' will +print the usage text by passing it through a pager program. 'more-help' +is disabled on platforms without a working 'fork(2)' function. The +'PAGER' environment variable is used to select the program, defaulting +to 'more'. Both will exit with a status code of 0. + + gnutls-cli - GnuTLS client + Usage: gnutls-cli [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [hostname] + + None: + + -d, --debug=num Enable debugging + - it must be in the range: + 0 to 9999 + -V, --verbose More verbose output + --tofu Enable trust on first use authentication + --strict-tofu Fail to connect if a certificate is unknown or a known certificate has changed + --dane Enable DANE certificate verification (DNSSEC) + --local-dns Use the local DNS server for DNSSEC resolving + --ca-verification Enable CA certificate verification + - enabled by default + - disabled as '--no-ca-verification' + --ocsp Enable OCSP certificate verification + -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 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 + - prohibits the option 'save-ocsp-multi' + --save-ocsp-multi=str Save all OCSP responses provided by the peer in this file + - prohibits the option 'save-ocsp' + --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' + --rawpkkeyfile=str Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use + --rawpkfile=str Raw public-key file to use + - requires the option 'rawpkkeyfile' + --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 + --compress-cert=str Compress certificate + -b, --heartbeat Activate heartbeat support + --recordsize=num The maximum record size to advertise + - 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 + --list-config Reports the configuration of the library + --logfile=str Redirect informational messages to a specific file + --keymatexport=str Label used for exporting keying material + --keymatexportsize=num Size of the exported keying material + --waitresumption Block waiting for the resumption data under TLS1.3 + --ca-auto-retrieve Enable automatic retrieval of missing CA certificates + + Version, usage and configuration options: + + -v, --version[=arg] output version information and exit + -h, --help display extended usage information and exit + -!, --more-help extended usage information passed thru pager + + Options are specified by doubled hyphens and their name or by a single + hyphen and the flag character. + 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. + + Please send bug reports to: <bugs@gnutls.org> + + +debug option (-d). +------------------ + +This is the "enable debugging" option. This option takes a +ArgumentType.NUMBER argument. Specifies the debug level. + +tofu option. +------------ + +This is the "enable trust on first use authentication" option. 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 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 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 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 +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 ArgumentType.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 ArgumentType.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, *note the +starttls-proto option documentation: gnutls-cli starttls-proto. + +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 ArgumentType.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. + +save-ocsp-multi option. +----------------------- + +This is the "save all ocsp responses provided by the peer in this file" +option. This option takes a ArgumentType.STRING argument. + +This option has some usage constraints. It: + * must not appear in combination with any of the following options: + save-ocsp. + +The file will contain a list of PEM encoded OCSP status responses if any +were provided by the peer, starting with the one for the peer's server +certificate. + +dh-bits option. +--------------- + +This is the "the minimum number of bits allowed for dh" option. This +option takes a ArgumentType.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 +ArgumentType.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 + +rawpkkeyfile option. +-------------------- + +This is the "private key file (pkcs #8 or pkcs #12) or pkcs #11 url to +use" option. This option takes a ArgumentType.STRING argument. In +order to instruct the application to negotiate raw public keys one must +enable the respective certificate types via the priority strings (i.e. +CTYPE-CLI-* and CTYPE-SRV-* flags). + +Check the GnuTLS manual on section "Priority strings" for more +information on how to set certificate types. + +rawpkfile option. +----------------- + +This is the "raw public-key file to use" option. This option takes a +ArgumentType.STRING argument. + +This option has some usage constraints. It: + * must appear in combination with the following options: + rawpkkeyfile. + +In order to instruct the application to negotiate raw public keys one +must enable the respective certificate types via the priority strings +(i.e. CTYPE-CLI-* and CTYPE-SRV-* flags). + +Check the GnuTLS manual on section "Priority strings" for more +information on how to set certificate types. + +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 +ArgumentType.STRING argument. This option will set and enable the +Application Layer Protocol Negotiation (ALPN) in the TLS protocol. + +compress-cert option. +--------------------- + +This is the "compress certificate" option. This option takes a +ArgumentType.STRING argument. This option sets a supported compression +method for certificate compression. + +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 ArgumentType.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 ArgumentType.FILE argument. This will override the default +options in /etc/gnutls/pkcs11.conf + +logfile option. +--------------- + +This is the "redirect informational messages to a specific file" option. +This option takes a ArgumentType.STRING argument. Redirect +informational messages to a specific file. The file may be /dev/null +also to make the gnutls client quiet to use it in piped server +connections where only the server communication may appear on stdout. + +waitresumption option. +---------------------- + +This is the "block waiting for the resumption data under tls1.3" option. +This option makes the client to block waiting for the resumption data +under TLS1.3. The option has effect only when -resume is provided. + +ca-auto-retrieve option. +------------------------ + +This is the "enable automatic retrieval of missing ca certificates" +option. This option enables the client to automatically retrieve the +missing intermediate CA certificates in the certificate chain, based on +the Authority Information Access (AIA) extension. + +version option (-v). +-------------------- + +This is the "output version information and exit" option. This option +takes a ArgumentType.KEYWORD argument. Output version of program and +exit. The default mode is 'v', a simple version. The 'c' mode will +print copyright information and 'n' will print the full copyright +notice. + +help option (-h). +----------------- + +This is the "display extended usage information and exit" option. +Display usage information and exit. + +more-help option (-!). +---------------------- + +This is the "extended usage information passed thru pager" option. Pass +the extended usage information through a pager. + +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 using raw public-key authentication +---------------------------------------------- + +To connect to a server using raw public-key authentication, you need to +enable the option to negotiate raw public-keys via the priority strings +such as in the example below. + $ ./gnutls-cli -p 5556 localhost --priority NORMAL:-CTYPE-CLI-ALL:+CTYPE-CLI-RAWPK \ + --rawpkkeyfile cli.key.pem \ + --rawpkfile cli.rawpk.pem + Processed 1 client raw public key pair... + Resolving 'localhost'... + Connecting to '127.0.0.1:5556'... + - Successfully sent 1 certificate(s) to server. + - Server has requested a certificate. + - Certificate type: X.509 + - Got a certificate list of 1 certificates. + - Certificate[0] info: + - skipped + - Description: (TLS1.3-Raw Public Key-X.509)-(ECDHE-SECP256R1)-(RSA-PSS-RSAE-SHA256)-(AES-256-GCM) + - Options: + - Handshake was completed + + - Simple Client Mode: + +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. + + +File: gnutls.info, Node: gnutls-serv Invocation, Next: gnutls-cli-debug Invocation, Prev: gnutls-cli Invocation, Up: Other included programs + +Invoking gnutls-serv +==================== + +Server program that listens to incoming TLS connections. + +gnutls-serv help/usage ('-?') +----------------------------- + +The text printed is the same whether selected with the 'help' option +('--help') or the 'more-help' option ('--more-help'). 'more-help' will +print the usage text by passing it through a pager program. 'more-help' +is disabled on platforms without a working 'fork(2)' function. The +'PAGER' environment variable is used to select the program, defaulting +to 'more'. Both will exit with a status code of 0. + + gnutls-serv - GnuTLS server + Usage: gnutls-serv [ -<flag> [<val>] | --<name>[{=| }<val>] ]... + + None: + + -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 + --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 2147483648 + --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 + --crlf Do not replace CRLF by LF in Echo server mode + -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 + --compress-cert=str Compress certificate + -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 + --x509certfile=str X.509 Certificate file or PKCS #11 URL to use + --rawpkkeyfile=str Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use + --rawpkfile=str Raw public-key file to use + - requires the option 'rawpkkeyfile' + --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 + --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 + --keymatexport=str Label used for exporting keying material + --keymatexportsize=num Size of the exported keying material + --recordsize=num The maximum record size to advertise + - it must be in the range: + 0 to 16384 + --httpdata=file The data used as HTTP response + - file must pre-exist + + Version, usage and configuration options: + + -v, --version[=arg] output version information and exit + -h, --help display extended usage information and exit + -!, --more-help extended usage information passed thru pager + + Options are specified by doubled hyphens and their name or by a single + hyphen and the flag character. + + Server program that listens to incoming TLS connections. + + Please send bug reports to: <bugs@gnutls.org> + + +debug option (-d). +------------------ + +This is the "enable debugging" option. This option takes a +ArgumentType.NUMBER argument. Specifies the debug level. + +sni-hostname option. +-------------------- + +This is the "server's hostname for server name extension" option. This +option takes a ArgumentType.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 ArgumentType.STRING argument. 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. + +compress-cert option. +--------------------- + +This is the "compress certificate" option. This option takes a +ArgumentType.STRING argument. This option sets a supported compression +method for certificate compression. + +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 +ArgumentType.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 ArgumentType.STRING argument. 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 ArgumentType.STRING argument. 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, *note the x509keyfile +option documentation: gnutls-serv x509keyfile. + +x509dsacertfile option. +----------------------- + +This is an alias for the 'x509certfile' option, *note the x509certfile +option documentation: gnutls-serv x509certfile. + +x509ecckeyfile option. +---------------------- + +This is an alias for the 'x509keyfile' option, *note the x509keyfile +option documentation: gnutls-serv x509keyfile. + +x509ecccertfile option. +----------------------- + +This is an alias for the 'x509certfile' option, *note the x509certfile +option documentation: gnutls-serv x509certfile. + +rawpkkeyfile option. +-------------------- + +This is the "private key file (pkcs #8 or pkcs #12) or pkcs #11 url to +use" option. This option takes a ArgumentType.STRING argument. Specify +the private key file or URI to use; it must correspond to the raw +public-key specified in -rawpkfile. Multiple key pairs can be specified +with this option and in that case each occurrence of keyfile must be +followed by the corresponding rawpkfile or vice-versa. + +In order to instruct the application to negotiate raw public keys one +must enable the respective certificate types via the priority strings +(i.e. CTYPE-CLI-* and CTYPE-SRV-* flags). + +Check the GnuTLS manual on section "Priority strings" for more +information on how to set certificate types. + +rawpkfile option. +----------------- + +This is the "raw public-key file to use" option. This option takes a +ArgumentType.STRING argument. + +This option has some usage constraints. It: + * must appear in combination with the following options: + rawpkkeyfile. + +Specify the raw public-key file to use; it must correspond to the +private key specified in -rawpkkeyfile. Multiple key pairs can be +specified with this option and in that case each occurrence of keyfile +must be followed by the corresponding rawpkfile or vice-versa. + +In order to instruct the application to negotiate raw public keys one +must enable the respective certificate types via the priority strings +(i.e. CTYPE-CLI-* and CTYPE-SRV-* flags). + +Check the GnuTLS manual on section "Priority strings" for more +information on how to set certificate types. + +ocsp-response option. +--------------------- + +This is the "the ocsp response to send to client" option. This option +takes a ArgumentType.STRING argument. 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 ArgumentType.FILE argument. This will override the default +options in /etc/gnutls/pkcs11.conf + +version option (-v). +-------------------- + +This is the "output version information and exit" option. This option +takes a ArgumentType.KEYWORD argument. Output version of program and +exit. The default mode is 'v', a simple version. The 'c' mode will +print copyright information and 'n' will print the full copyright +notice. + +help option (-h). +----------------- + +This is the "display extended usage information and exit" option. +Display usage information and exit. + +more-help option (-!). +---------------------- + +This is the "extended usage information passed thru pager" option. Pass +the extended usage information through a pager. + +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 + +If you want a server with support for raw public-keys we can also add +these credentials. Note however that there is no identity information +linked to these keys as is the case with regular x509 certificates. +Authentication must be done via different means. Also we need to +explicitly enable raw public-key certificates via the priority strings. + + gnutls-serv --http --priority NORMAL:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK \ + --rawpkfile srv.rawpk.pem \ + --rawpkkeyfile srv.key.pem + +Finally, we start the server with all the earlier parameters and you get +this command: + + gnutls-serv --http --priority NORMAL:+PSK:+SRP:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK \ + --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 \ + --rawpkfile srv.rawpk.pem \ + --rawpkkeyfile srv.key.pem + + +File: gnutls.info, Node: gnutls-cli-debug Invocation, Prev: gnutls-serv Invocation, Up: Other included programs + +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. + +gnutls-cli-debug help/usage ('-?') +---------------------------------- + +The text printed is the same whether selected with the 'help' option +('--help') or the 'more-help' option ('--more-help'). 'more-help' will +print the usage text by passing it through a pager program. 'more-help' +is disabled on platforms without a working 'fork(2)' function. The +'PAGER' environment variable is used to select the program, defaulting +to 'more'. Both will exit with a status code of 0. + + gnutls-cli-debug - GnuTLS debug client + Usage: gnutls-cli-debug [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [hostname] + + None: + + -d, --debug=num Enable debugging + - it must be in the range: + 0 to 9999 + -V, --verbose More verbose output + -p, --port=num The port to connect to + - it must be in the range: + 0 to 65536 + --app-proto 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) + + Version, usage and configuration options: + + -v, --version[=arg] output version information and exit + -h, --help display extended usage information and exit + -!, --more-help extended usage information passed thru pager + + Options are specified by doubled hyphens and their name or by a single + hyphen and the flag character. + 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. + + Please send bug reports to: <bugs@gnutls.org> + + +debug option (-d). +------------------ + +This is the "enable debugging" option. This option takes a +ArgumentType.NUMBER argument. Specifies the debug level. + +app-proto option. +----------------- + +This is an alias for the 'starttls-proto' option, *note the +starttls-proto option documentation: gnutls-cli-debug starttls-proto. + +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 ArgumentType.STRING +argument. Specify the application layer protocol for STARTTLS. If the +protocol is supported, gnutls-cli will proceed to the TLS negotiation. + +version option (-v). +-------------------- + +This is the "output version information and exit" option. This option +takes a ArgumentType.KEYWORD argument. Output version of program and +exit. The default mode is 'v', a simple version. The 'c' mode will +print copyright information and 'n' will print the full copyright +notice. + +help option (-h). +----------------- + +This is the "display extended usage information and exit" option. +Display usage information and exit. + +more-help option (-!). +---------------------- + +This is the "extended usage information passed thru pager" option. Pass +the extended usage information through a pager. + +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 + + +File: gnutls.info, Node: Internal architecture of GnuTLS, Next: Upgrading from previous versions, Prev: Other included programs, Up: Top + +11 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. + +* Menu: + +* The TLS Protocol:: +* TLS Handshake Protocol:: +* TLS Authentication Methods:: +* TLS Hello Extension Handling:: +* Cryptographic Backend:: +* Random Number Generators-internals:: +* FIPS140-2 mode:: + + +File: gnutls.info, Node: The TLS Protocol, Next: TLS Handshake Protocol, Up: Internal architecture of GnuTLS + +11.1 The TLS Protocol +===================== + +The main use case for the TLS protocol is shown in *note Figure 11.1: +fig-client-server. 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 11.1: TLS protocol use case. + + +File: gnutls.info, Node: TLS Handshake Protocol, Next: TLS Authentication Methods, Prev: The TLS Protocol, Up: Internal architecture of GnuTLS + +11.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 *note Figure 11.2: +fig-gnutls-handshake. + + + + + +Figure 11.2: GnuTLS handshake state machine. + +Also the way the input is processed varies per ciphersuite. Several +implementations of the internal handlers are available and *note +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 *note Figure 11.3: fig-gnutls-handshake-sequence. + + + + + +Figure 11.3: GnuTLS handshake process sequence. + + +File: gnutls.info, Node: TLS Authentication Methods, Next: TLS Hello Extension Handling, Prev: TLS Handshake Protocol, Up: Internal architecture of GnuTLS + +11.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 + + +File: gnutls.info, Node: TLS Hello Extension Handling, Next: Cryptographic Backend, Prev: TLS Authentication Methods, Up: Internal architecture of GnuTLS + +11.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 *note gnutls_session_ext_register:: or *note +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 *note gnutls_session_ext_register:: or *note +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 *note 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 [*note 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 *note +gnutls_session_supplemental_register::, or *note +gnutls_supplemental_register:: at some point in your program. + + +File: gnutls.info, Node: Cryptographic Backend, Next: Random Number Generators-internals, Prev: TLS Hello Extension Handling, Up: Internal architecture of GnuTLS + +11.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 *note Figure 11.4: fig-crypto-layers. + + + + + +Figure 11.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. + + * *note gnutls_crypto_register_cipher::: To register a cipher + algorithm. + + * *note gnutls_crypto_register_aead_cipher::: To register an AEAD + cipher algorithm. + + * *note gnutls_crypto_register_mac::: To register a MAC algorithm. + + * *note 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 *note 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'. + + +File: gnutls.info, Node: Random Number Generators-internals, Next: FIPS140-2 mode, Prev: Cryptographic Backend, Up: Internal architecture of GnuTLS + +11.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 *note 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 *note 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 [*note 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. + + +File: gnutls.info, Node: FIPS140-2 mode, Prev: Random Number Generators-internals, Up: Internal architecture of GnuTLS + +11.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. + +There are two distinct library states with regard to FIPS140-2: the +FIPS140-2 mode is _installed_ if '/etc/system-fips' is present, and the +FIPS140-2 mode is _enabled_ if '/proc/sys/crypto/fips_enabled' contains +'1', which is typically set with the "fips=1" kernel command line +option. + +When the FIPS140-2 mode is installed, the operation of the library is +modified as follows. + + * 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 + +When the FIPS140-2 mode is enabled, The operation of the library is in +addition modified as follows. + + * Only approved by FIPS140-2 algorithms are enabled + * Only approved by FIPS140-2 key lengths are allowed for key + generation + * 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 *note Figure +11.5: gnutls_fips_mode_t, 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 *note 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 +*note gnutls_fips140_set_mode:: which can switch to alternative modes as +in *note Figure 11.5: gnutls_fips_mode_t. + +'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 11.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); + +Service indicator +----------------- + +The above restrictions may not cover all the requirements in every usage +context, and as the FIPS140 standard evolves (like FIPS140-3), GnuTLS +may not be able to add new restrictions without breaking compatibility. + +Therefore an additional set of API functions is provided to communicate +with the user whether any approved mode of operations is performed +within a given context. + +'INT *note gnutls_fips140_context_init:: (gnutls_fips140_context_t * CONTEXT)' +'VOID *note gnutls_fips140_context_deinit:: (gnutls_fips140_context_t CONTEXT)' +'INT *note gnutls_fips140_push_context:: (gnutls_fips140_context_t CONTEXT)' +'INT *note gnutls_fips140_pop_context:: ( VOID)' + +The 'gnutls_fips140_context_t' represents the FIPS140-2 mode of +operation. It can be attached to the current execution thread with +*note gnutls_fips140_push_context:: and its internal state will be +updated until it is detached with *note gnutls_fips140_pop_context::. +Afterwards *note gnutls_fips140_get_operation_state:: allows the user to +examine whether any approved (or non-approved) security function is +invoked. + + -- Function: gnutls_fips140_operation_state_t + gnutls_fips140_get_operation_state (gnutls_fips140_context_t + CONTEXT) + CONTEXT: a 'gnutls_fips140_context_t' + + Get the previous operation state of 'context' in terms of FIPS. + + *Returns:* a 'gnutls_fips140_operation_state_t' + + *Since:* 3.7.3 + + +File: gnutls.info, Node: Upgrading from previous versions, Next: Support, Prev: Internal architecture of GnuTLS, Up: Top + +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 *note 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 *note gnutls_record_check_pending:: has + to be used to achieve the same functionality as described in *note + 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 + *note gnutls_record_check_pending:: has + to be used, as described in + *note Asynchronous operation:: + +'gnutls_session_get_server_random',They are replaced by the safer function +'gnutls_session_get_client_random'*note gnutls_session_get_random:: + +'gnutls_session_get_master_secret'Replaced by the keying material exporters + discussed in + *note Deriving keys for other applications/protocols:: + +'gnutls_transport_set_global_errno'Replaced by using the system's errno + facility or + *note gnutls_transport_set_errno::. + +'gnutls_x509_privkey_verify_data'Replaced by + *note gnutls_pubkey_verify_data2::. + +'gnutls_certificate_verify_peers'Replaced by + *note 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 + *note 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 + *note gnutls_pubkey_verify_hash2:: is + provided and is functionally equivalent + and safer to use. + +'gnutls_pubkey_verify_data'The function + *note 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 + *note 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',*note 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',*note gnutls_pubkey_verify_hash2::. + +'gnutls_pubkey_verify_data',*note gnutls_pubkey_verify_data2::. + +'gnutls_x509_crt_get_verify_algorithm',No replacement; a similar function is + *note gnutls_x509_crt_get_signature_algorithm::. + +'gnutls_pubkey_get_verify_algorithm',No replacement; a similar function is + *note gnutls_pubkey_get_preferred_hash_algorithm::. + +'gnutls_certificate_type_set_priority',*note 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',*note gnutls_privkey_import_ext3:: +'gnutls_sign_callback_set' +'gnutls_x509_crt_verify_hash'*note gnutls_pubkey_verify_hash2:: + +'gnutls_x509_crt_verify_data'*note gnutls_pubkey_verify_data2:: + +'gnutls_privkey_sign_raw_data'*note 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 [*note TLSSRP::] spec parameters to +outside the protect clients from MitM attacks. +[*note 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'. + +*note gnutls_x509_crt_sign::,These signing functions will no longer +*note gnutls_x509_crl_sign::,sign using SHA1, but with a secure hash +*note gnutls_x509_crq_sign::algorithm. + +*note gnutls_certificate_set_ocsp_status_request_file::This 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 + *note gnutls_certificate_set_flags::. + +The callback It is replaced with +*note gnutls_privkey_import_ext3::*note gnutls_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. *note gnutls_session_key_update:: and + *note 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 *note gnutls_session_get_id2::. +1.3. +*note gnutls_pkcs11_privkey_generate3::,These functions no longer create an +*note gnutls_pkcs11_copy_secret_key::,exportable key by default; they require +*note gnutls_pkcs11_copy_x509_privkey2::the flag + 'GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE' + to do so. + +*note gnutls_db_set_retrieve_function::,These functions are no longer relevant +*note gnutls_db_set_store_function::,under TLS 1.3; resumption under TLS 1.3 +*note gnutls_db_set_remove_function::is done via session tickets, c.f. + *note gnutls_session_ticket_enable_server::. + +*note gnutls_session_get_data2::,These functions may introduce a slight +*note gnutls_session_get_data::delay under TLS 1.3 for few milliseconds. + Check output of + *note gnutls_session_get_flags:: for + GNUTLS_SFLAGS_SESSION_TICKET before + calling this function to avoid delays. + To work efficiently under TLS 1.3 this + function requires the application setting + *note gnutls_transport_set_pull_timeout_function::. + +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 + *note gnutls_supplemental_register:: or + *note 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. + + + +File: gnutls.info, Node: Support, Next: Error codes, Prev: Upgrading from previous versions, Up: Top + +Appendix B Support +****************** + +* Menu: + +* Getting help:: +* Commercial Support:: +* Bug Reports:: +* Contributing:: +* Certification:: + + +File: gnutls.info, Node: Getting help, Next: Commercial Support, Up: 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 *note Bug Reports::. + + +File: gnutls.info, Node: Commercial Support, Next: Bug Reports, Prev: Getting help, Up: Support + +B.2 Commercial Support +====================== + +Commercial support is available for users of GnuTLS. See +<https://www.gnutls.org/commercial.html> for more information. + + +File: gnutls.info, Node: Bug Reports, Next: Contributing, Prev: Commercial Support, Up: Support + +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' + + +File: gnutls.info, Node: Contributing, Next: Certification, Prev: Bug Reports, Up: Support + +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 *note 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. + + +File: gnutls.info, Node: Certification, Prev: Contributing, Up: Support + +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 *note FIPS140-2 mode:: for more information. + + +File: gnutls.info, Node: Error codes, Next: Supported ciphersuites, Prev: Support, Up: Top + +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. +-430 GNUTLS_E_X509_DUPLICATE_EXTENSIONDuplicate extension in + X.509 certificate. + + +File: gnutls.info, Node: Supported ciphersuites, Next: API reference, Prev: Error codes, Up: Top + +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 +TLS_GOSTR341112_256_28147_CNT_IMIT 0xC1 0x02 TLS1.2 + +Certificate types +================= + +'X.509' +'Raw Public Key' + +Protocols +========= + +'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-192-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' +'CHACHA20-32' +'CHACHA20-64' +'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' +'AES-128-XTS' +'AES-256-XTS' +'AES-128-SIV' +'AES-256-SIV' +'GOST28147-TC26Z-CNT' +'MAGMA-CTR-ACPKM' +'KUZNYECHIK-CTR-ACPKM' +'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' +'AES-CMAC-128' +'AES-CMAC-256' +'AES-GMAC-128' +'AES-GMAC-192' +'AES-GMAC-256' +'GOST28147-TC26Z-IMIT' +'OMAC-MAGMA' +'OMAC-KUZNYECHIK' + +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' +'VKO-GOST-12' +'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)' +'EdDSA (Ed448)' +'DH' +'ECDH (X25519)' +'ECDH (X448)' + +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' +'EdDSA-Ed448' +'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 +====== + +'SECP256R1' +'SECP384R1' +'SECP521R1' +'X25519' +'GC256B' +'GC512A' +'X448' +'FFDHE2048' +'FFDHE3072' +'FFDHE4096' +'FFDHE6144' +'FFDHE8192' + + +File: gnutls.info, Node: API reference, Next: Copying Information, Prev: Supported ciphersuites, Up: Top + +Appendix E API reference +************************ + +* Menu: + +* Core TLS API:: +* Datagram TLS API:: +* X509 certificate API:: +* PKCS 7 API:: +* OCSP API:: +* PKCS 12 API:: +* PKCS 11 API:: +* TPM API:: +* Abstract key API:: +* Socket specific API:: +* DANE API:: +* Cryptographic API:: +* Compatibility API:: + + +File: gnutls.info, Node: Core TLS API, Next: Datagram TLS API, Up: 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_alert_set_read_function +------------------------------ + + -- Function: void gnutls_alert_set_read_function (gnutls_session_t + SESSION, gnutls_alert_read_func FUNC) + SESSION: is 'gnutls_session_t' type + + FUNC: is the function to be called + + This function will set a callback to be called when an alert + message is being sent. + + *Since:* 3.7.0 + +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, + GNUTLS_CERT_IGNORE + + This function specifies if we (in case of a server) are going to + send a certificate request message to the client. If 'req' is + GNUTLS_CERT_REQUIRE then the server will return the + 'GNUTLS_E_NO_CERTIFICATE_FOUND' error if the peer does not provide + a certificate. If you do not call this function then the client + will not be asked to send a certificate. Invoking the function + with 'req' GNUTLS_CERT_IGNORE has the same effect. + +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, the number of loaded responses is returned, + otherwise a negative error code. + + *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 + + This function returns the ciphersuite name under TLS1.2 or earlier + versions when provided with individual algorithms. The full cipher + suite name must be prepended by TLS or SSL depending of the + protocol in use. + + To get a description of the current ciphersuite across versions, it + is recommended to use 'gnutls_session_get_desc()' . + + *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_ciphersuite_get +---------------------- + + -- Function: const char * gnutls_ciphersuite_get (gnutls_session_t + SESSION) + SESSION: is a 'gnutls_session_t' type. + + Get the canonical name of negotiated TLS ciphersuite. The names + returned by this function match the IANA registry, with one + exception: + + TLS_DHE_DSS_RC4_128_SHA { 0x00, 0x66 } + + which is reserved for compatibility. + + To get a detailed description of the current ciphersuite, it is + recommended to use 'gnutls_session_get_desc()' . + + *Returns:* a string that contains the canonical name of a TLS + ciphersuite, or 'NULL' if the handshake is not completed. + + *Since:* 3.7.4 + +gnutls_compress_certificate_get_selected_method +----------------------------------------------- + + -- Function: gnutls_compression_method_t + gnutls_compress_certificate_get_selected_method + (gnutls_session_t SESSION) + SESSION: is a 'gnutls_session_t' type. + + This function returns the certificate compression method that has + been selected to compress the certificate before sending it to the + peer. The selection is done based on the local list of supported + compression methods and the peer's requested compression methods. + + *Returns:* selected certificate compression method. + + Since 3.7.4 + +gnutls_compress_certificate_set_methods +--------------------------------------- + + -- Function: int gnutls_compress_certificate_set_methods + (gnutls_session_t SESSION, const gnutls_compression_method_t * + METHODS, size_t METHODS_LEN) + SESSION: is a 'gnutls_session_t' type. + + METHODS: is a list of supported compression methods. + + METHODS_LEN: number of compression methods in 'methods' + + This function sets the supported compression methods for + certificate compression for the given session. The list of + supported compression methods will be used for a) requesting the + compression of peer's certificate and b) selecting the method to + compress the local certificate before sending it to the peer. The + order of compression methods inside the list does matter as the + method that appears earlier in the list will be preffered before + the later ones. Note that even if you set the list of supported + compression methods, the compression might not be used if the peer + does not support any of your chosen compression methods. + + The list of supported compression methods must meet the following + criteria: Argument 'methods' must be an array of valid compression + methods of type 'gnutls_compression_method_t' . Argument + 'methods_len' must contain the number of compression methods stored + in the 'methods' array and must be within range <1, 127>. The + length constraints are defined by + 'MIN_COMPRESS_CERTIFICATE_METHODS' and + 'MAX_COMPRESS_CERTIFICATE_METHODS' macros located in the header + file compress_certificate.h. + + If either 'methods' or 'methods_len' is equal to 0, current list of + supported compression methods will be unset. + + *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative + error code. + + Since 3.7.4 + +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 + (6 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_import_raw3 +---------------------------- + + -- Function: int gnutls_dh_params_import_raw3 (gnutls_dh_params_t + DH_PARAMS, const gnutls_datum_t * PRIME, const gnutls_datum_t + * Q, const gnutls_datum_t * GENERATOR) + DH_PARAMS: The parameters + + PRIME: holds the new prime + + Q: holds the subgroup if available, otherwise NULL + + 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_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_digest_set_secure +------------------------ + + -- Function: int gnutls_digest_set_secure (gnutls_digest_algorithm_t + DIG, unsigned int SECURE) + DIG: is a digest algorithm + + SECURE: whether to mark the digest algorithm secure + + Modify the previous system wide setting that marked 'dig' as secure + or insecure. This only has effect when the algorithm is enabled + through the allowlisting mode in the configuration file, or when + the setting is modified with a prior call to this function. + + *Since:* 3.7.3 + +gnutls_early_cipher_get +----------------------- + + -- Function: gnutls_cipher_algorithm_t gnutls_early_cipher_get + (gnutls_session_t SESSION) + SESSION: is a 'gnutls_session_t' type. + + Get the cipher algorithm used for encrypting early data. + + *Returns:* the cipher used for early data, a + 'gnutls_cipher_algorithm_t' type. + + *Since:* 3.7.2 + +gnutls_early_prf_hash_get +------------------------- + + -- Function: gnutls_digest_algorithm_t gnutls_early_prf_hash_get (const + gnutls_session_t SESSION) + SESSION: is a 'gnutls_session_t' type. + + Get the hash algorithm used as a PRF to derive keys for encrypting + early data in TLS 1.3. + + *Returns:* the hash algorithm used for early data, a + 'gnutls_digest_algorithm_t' value. + + *Since:* 3.7.2 + +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_ecc_curve_set_enabled +---------------------------- + + -- Function: int gnutls_ecc_curve_set_enabled (gnutls_ecc_curve_t + CURVE, unsigned int ENABLED) + CURVE: is an ECC curve + + ENABLED: whether to enable the curve + + Modify the previous system wide setting that marked 'curve' as + enabled or disabled. Calling this fuction is allowed only if + allowlisting mode is set in the configuration file, and only if the + system-wide TLS priority string has not been initialized yet. The + intended usage is to provide applications with a way to expressly + deviate from the distribution or site defaults inherited from the + configuration file. The modification is composable with further + modifications performed through the priority string mechanism. + + This function is not thread-safe and is intended to be called in + the main thread at the beginning of the process execution. + + *Returns:* 0 on success or negative error code otherwise. + + *Since:* 3.7.3 + +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 inaccurate 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_get_name2 +-------------------- + + -- Function: const char * gnutls_ext_get_name2 (gnutls_session_t + SESSION, unsigned int TLS_ID, gnutls_ext_parse_type_t + PARSE_POINT) + SESSION: a 'gnutls_session_t' opaque pointer + + TLS_ID: is a TLS extension numeric ID + + PARSE_POINT: the parse type of the extension + + 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_POINT, 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_POINT: 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_context_deinit +----------------------------- + + -- Function: void gnutls_fips140_context_deinit + (gnutls_fips140_context_t CONTEXT) + CONTEXT: a 'gnutls_fips140_context_t' + + Uninitialize and release the FIPS context 'context' . + + *Since:* 3.7.3 + +gnutls_fips140_context_init +--------------------------- + + -- Function: int gnutls_fips140_context_init (gnutls_fips140_context_t + * CONTEXT) + CONTEXT: location to store 'gnutls_fips140_context_t' + + Create and initialize the FIPS context object. + + *Returns:* 0 upon success, a negative error code otherwise + + *Since:* 3.7.3 + +gnutls_fips140_get_operation_state +---------------------------------- + + -- Function: gnutls_fips140_operation_state_t + gnutls_fips140_get_operation_state (gnutls_fips140_context_t + CONTEXT) + CONTEXT: a 'gnutls_fips140_context_t' + + Get the previous operation state of 'context' in terms of FIPS. + + *Returns:* a 'gnutls_fips140_operation_state_t' + + *Since:* 3.7.3 + +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_pop_context +-------------------------- + + -- Function: int gnutls_fips140_pop_context ( VOID) + + Dissociate the FIPS context currently active on the current thread, + reverting to the previously active context. If a cryptographic + operation is ongoing in the current thread, e.g., + 'gnutls_aead_cipher_init()' is called but + 'gnutls_aead_cipher_deinit()' is not yet called, it returns an + error 'GNUTLS_E_INVALID_REQUEST' . + + This function is no-op if FIPS140 is not compiled in nor enabled at + run-time. + + *Returns:* 0 upon success, a negative error code otherwise + + *Since:* 3.7.3 + +gnutls_fips140_push_context +--------------------------- + + -- Function: int gnutls_fips140_push_context (gnutls_fips140_context_t + CONTEXT) + CONTEXT: a 'gnutls_fips140_context_t' + + Associate the FIPS 'context' to the current thread, diverting the + currently active context. If a cryptographic operation is ongoing + in the current thread, e.g., 'gnutls_aead_cipher_init()' is called + but 'gnutls_aead_cipher_deinit()' is not yet called, it returns an + error 'GNUTLS_E_INVALID_REQUEST' . + + The operation state of 'context' will be reset to + 'GNUTLS_FIPS140_OP_INITIAL' . + + This function is no-op if FIPS140 is not compiled in nor enabled at + run-time. + + *Returns:* 0 upon success, a negative error code otherwise + + *Since:* 3.7.3 + +gnutls_fips140_run_self_tests +----------------------------- + + -- Function: int gnutls_fips140_run_self_tests ( VOID) + + Manually perform the second round of the FIPS140 self-tests, + including: + + - Known answer tests (KAT) for the selected set of symmetric + cipher, MAC, public key, KDF, and DRBG - Library integrity checks + + Upon failure with FIPS140 mode enabled, it makes the library + unusable. This function is not thread-safe. + + *Returns:* 0 upon success, a negative error code otherwise + + *Since:* 3.7.7 + +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_get_library_config +------------------------- + + -- Function: const gnutls_library_config_st * gnutls_get_library_config + ( VOID) + + Returns the library configuration as key value pairs. Currently + defined keys are: + + - fips-module-name: the name of the FIPS140 module + + - fips-module-version: the version of the FIPS140 module + + - libgnutls-soname: the SONAME of the library itself + + - libnettle-soname: the library SONAME of linked libnettle + + - libhogweed-soname: the library SONAME of linked libhogweed + + - libgmp-soname: the library SONAME of linked libgmp + + - hardware-features: enabled hardware support features + + - tls-features: enabled TLS protocol features + + *Returns:* a NUL-terminated 'gnutls_library_config_st' array + + *Since:* 3.7.3 + +gnutls_get_system_config_file +----------------------------- + + -- Function: const char * gnutls_get_system_config_file ( VOID) + + Returns the filename of the system wide configuration file to be + loaded by the library. + + *Returns:* a constant pointer to the config file path + + *Since:* 3.6.9 + +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_IMPLICIT_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. It is thread safe since GnuTLS 3.3.0. + + 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. + + This function must be called prior to any other GnuTLS function; + otherwise the behavior is undefined. + + *Deprecated:* This function is discouraged on GnuTLS 3.7.3 or + later. + + *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_read_function +---------------------------------- + + -- Function: void gnutls_handshake_set_read_function (gnutls_session_t + SESSION, gnutls_handshake_read_func FUNC) + SESSION: is 'gnutls_session_t' type + + FUNC: is the function to be called + + This function will set a callback to be called when a handshake + message is being sent. + + *Since:* 3.7.0 + +gnutls_handshake_set_secret_function +------------------------------------ + + -- Function: void gnutls_handshake_set_secret_function + (gnutls_session_t SESSION, gnutls_handshake_secret_func FUNC) + SESSION: is a 'gnutls_session_t' type. + + FUNC: the secret func + + This function will set a callback to be called when a new traffic + secret is installed. + + *Since:* 3.7.0 + +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_handshake_write +---------------------- + + -- Function: int gnutls_handshake_write (gnutls_session_t SESSION, + gnutls_record_encryption_level_t LEVEL, const void * DATA, + size_t DATA_SIZE) + SESSION: is a 'gnutls_session_t' type. + + LEVEL: the current encryption level for reading a handshake message + + DATA: the (const) handshake data to be processed + + DATA_SIZE: the size of data + + This function processes a handshake message in the encryption level + specified with 'level' . Prior to calling this function, a + handshake read callback must be set on 'session' . Use + 'gnutls_handshake_set_read_function()' to do this. + + *Since:* 3.7.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()' . + + Note that this function is not designed for reading sensitive + materials, such as private keys, on practical applications. When + the reading fails in the middle, the partially loaded content might + remain on memory. + + *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: unsigned 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, superseded or marks the + certificate as revoked. 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. + + This function is always usable on client side, but on server side + only under TLS 1.3, which is the first version of TLS that allows + cliend-side OCSP responses. + + *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_early +---------------- + + -- Function: int gnutls_prf_early (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. + + This function is similar to 'gnutls_prf_rfc5705()' , but only works + in TLS 1.3 or later to export early keying material. + + Note that the keying material is only available after the + ClientHello message is processed and before the application traffic + keys are established. Therefore this function shall be called in a + handshake hook function for 'GNUTLS_HANDSHAKE_CLIENT_HELLO' . + + 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.6.8 + +gnutls_prf_hash_get +------------------- + + -- Function: gnutls_digest_algorithm_t gnutls_prf_hash_get (const + gnutls_session_t SESSION) + SESSION: is a 'gnutls_session_t' type. + + Get the currently used hash algorithm. In TLS 1.3, the hash + algorithm is used for both the key derivation function and + handshake message authentication code. In TLS 1.2, it matches the + hash algorithm used for PRF. + + *Returns:* the currently used hash algorithm, a + 'gnutls_digest_algorithm_t' value. + + *Since:* 3.6.13 + +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 keying material from TLS/DTLS session to an application, as + specified in RFC5705. + + In the TLS versions prior to 1.3, it applies the TLS + Pseudo-Random-Function (PRF) on the master secret and the provided + data, seeded with the client and server random fields. + + In TLS 1.3, it applies HKDF on the exporter master secret derived + from the master secret. + + The 'label' variable usually contains a string denoting the purpose + for the generated data. + + The 'context' variable can be used to add more data to the seed, + after the random variables. It can be used to make sure the + generated output is strongly connected to some additional data + (e.g., a string used in user authentication). + + The output is placed in 'out' , which must be pre-allocated. + + Note that, to provide the RFC5705 context, the 'context' variable + must be non-null. + + *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code. + + *Since:* 3.4.4 + +gnutls_priority_certificate_type_list +------------------------------------- + + -- Function: int gnutls_priority_certificate_type_list + (gnutls_priority_t PCACHE, const unsigned int ** LIST) + PCACHE: is a 'gnutls_priority_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_priority_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_priority_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_priority_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_priority_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_priority_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_priority_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_priority_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_priority_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/config. + 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_priority_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_priority_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_priority_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_priority_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_protocol_set_enabled +--------------------------- + + -- Function: int gnutls_protocol_set_enabled (gnutls_protocol_t + VERSION, unsigned int ENABLED) + VERSION: is a (gnutls) version number + + ENABLED: whether to enable the protocol + + Control the previous system-wide setting that marked 'version' as + enabled or disabled. Calling this fuction is allowed only if + allowlisting mode is set in the configuration file, and only if the + system-wide TLS priority string has not been initialized yet. The + intended usage is to provide applications with a way to expressly + deviate from the distribution or site defaults inherited from the + configuration file. The modification is composable with further + modifications performed through the priority string mechanism. + + This function is not thread-safe and is intended to be called in + the main thread at the beginning of the process execution. + + *Returns:* 0 on success or negative error code otherwise. + + *Since:* 3.7.3 + +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. + + The returned pointer should be considered constant (do not free) + and valid for the lifetime of the session. + + This function will return 'NULL' if the username has embedded NULL + bytes. In that case, 'gnutls_psk_server_get_username2()' should be + used to retrieve the username. + + *Returns:* the username of the peer, or 'NULL' in case of an error, + or if the username has embedded NULLs. + +gnutls_psk_server_get_username2 +------------------------------- + + -- Function: int gnutls_psk_server_get_username2 (gnutls_session_t + SESSION, gnutls_datum_t * USERNAME) + SESSION: is a gnutls session + + USERNAME: a datum that will be filled in by this function + + Return a pointer to the username of the peer in the supplied datum. + Does not need to be null-terminated. + + This should only be called in case of PSK authentication and in + case of a server. + + The returned pointer should be considered constant (do not free) + and valid for the lifetime of the session. + + *Returns:* 'GNUTLS_E_SUCCESS' , or a negative value 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_credentials2 +---------------------------------- + + -- Function: int gnutls_psk_set_client_credentials2 + (gnutls_psk_client_credentials_t RES, const gnutls_datum_t * + USERNAME, const gnutls_datum_t * KEY, gnutls_psk_key_flags + FLAGS) + RES: is a 'gnutls_psk_client_credentials_t' type. + + USERNAME: is the 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 is identical to 'gnutls_psk_set_client_credentials()' + , except that it allows a non-null-terminated username to be + introduced. + + *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_client_credentials_function2 +------------------------------------------- + + -- Function: void gnutls_psk_set_client_credentials_function2 + (gnutls_psk_client_credentials_t CRED, + gnutls_psk_client_credentials_function2 * 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, + gnutls_datum_t* username, gnutls_datum_t* key); + + This callback function has the same semantics as that of + 'gnutls_psk_set_client_credentials_function()' , but it allows + non-string usernames to be used. + + 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. + + Each entry in the file consists of a username, followed by a colon + (':') and a hex-encoded key. If the username contains a colon or + any other special character, it can be hex-encoded preceded by a + '#'. + + *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, + otherwise an error code is returned. + +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_function2 +------------------------------------------- + + -- Function: void gnutls_psk_set_server_credentials_function2 + (gnutls_psk_server_credentials_t CRED, + gnutls_psk_server_credentials_function2 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 gnutls_datum_t* username, + gnutls_datum_t* key); + + This callback function has the same semantics as that of + 'gnutls_psk_set_server_credentials_function()' , but it allows + non-string usernames to be used. + + '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 DTLS + session. These are the packets queued after an interrupted + 'gnutls_record_send()' . + + This function can only be used with transports where 'send()' is an + all-or-nothing operation (e.g., UDP). When partial writes are + allowed this function will cause session errors. + + *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 server 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, or provide a 'NULL' pointer for + 'data' and 0 for 'data_size' , in order to write the same data as + before. If you wish to discard the previous data instead of + retrying, you must call 'gnutls_record_discard_queued()' before + calling this function with different parameters. Note that the + latter works only on special transports (e.g., UDP). cf. + 'gnutls_record_get_direction()' . + + Note that in DTLS this function will return the + 'GNUTLS_E_LARGE_PACKET' error code if the send data exceed the data + MTU value - as returned by 'gnutls_dtls_get_data_mtu()' . The + errno value EMSGSIZE also maps to 'GNUTLS_E_LARGE_PACKET' . Note + that since 3.2.13 this function can be called under cork in DTLS + mode, and will refuse to send data over the MTU size by returning + 'GNUTLS_E_LARGE_PACKET' . + + *Returns:* The number of bytes sent, or a negative error code. The + number of bytes sent might be less than 'data_size' . The maximum + number of bytes this function can send in a single call depends on + the negotiated maximum record size. + +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_file +----------------------- + + -- Function: ssize_t gnutls_record_send_file (gnutls_session_t SESSION, + int FD, off_t * OFFSET, size_t COUNT) + SESSION: is a 'gnutls_session_t' type. + + FD: file descriptor from which to read data. + + OFFSET: Is relative to file offset, denotes the starting location + for reading. after function returns, it point to position + following last read byte. + + COUNT: is the length of the data in bytes to be read from file and + send. + + This function sends data from 'fd' . If KTLS (kernel TLS) is + enabled, it will use the 'sendfile()' system call to avoid overhead + of copying data between user space and the kernel. Otherwise, this + functionality is merely emulated by calling 'read()' and + 'gnutls_record_send()' . If this implementation is suboptimal, + check whether KTLS is enabled using + 'gnutls_transport_is_ktls_enabled()' . + + If 'offset' is NULL then file offset is incremented by number of + bytes send, otherwise file offset remains unchanged. + + *Returns:* The number of bytes sent, or a negative error code. + +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_recv_size +------------------------------- + + -- Function: ssize_t gnutls_record_set_max_recv_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 amount of plaintext received in a + record in this connection. + + The limit is also negotiated through a TLS extension called 'record + size limit'. Note that while the 'record size limit' extension is + preferred, not all TLS implementations use or even understand the + extension. + + *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, + otherwise a negative error code is returned. + + *Since:* 3.6.8 + +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 amount of plaintext sent and + received in a record in this connection. + + Prior to 3.6.4, this function was implemented using a TLS extension + called 'max fragment length', which limits the acceptable values to + 512(=2^9), 1024(=2^10), 2048(=2^11) and 4096(=2^12). + + Since 3.6.4, the limit is also negotiated through a new TLS + extension called 'record size limit', which doesn't have the + limitation, as long as the value ranges between 512 and 16384. + Note that while the 'record size limit' extension is preferred, not + all TLS implementations use or even understand the extension. + + *Deprecated:* if the client can assume that the 'record size limit' + extension is supported by the server, we recommend using + 'gnutls_record_set_max_recv_size()' instead. + + *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_POINT, 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_POINT: 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 roundtrip, + 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. + + Note that this function under TLS1.3 requires a callback to be set + with 'gnutls_transport_set_pull_timeout_function()' for successful + operation. There was a bug before 3.6.10 which could make this + function fail if that callback was not set. On later versions if + not set, the function will return a successful error code, but will + return dummy data that cannot lead to a resumption. + + *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_keylog_function +---------------------------------- + + -- Function: gnutls_keylog_func gnutls_session_get_keylog_function + (const gnutls_session_t SESSION) + SESSION: is 'gnutls_session_t' type + + This function will return the callback function set using + 'gnutls_session_set_keylog_function()' . + + *Returns:* The function set or 'NULL' otherwise. + + *Since:* 3.6.13 + +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. + + This function is only applicable under TLS 1.2 or earlier versions. + + *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_keylog_function +---------------------------------- + + -- Function: void gnutls_session_set_keylog_function (gnutls_session_t + SESSION, gnutls_keylog_func FUNC) + SESSION: is 'gnutls_session_t' type + + FUNC: is the function to be called + + This function will set a callback to be called when a new secret is + derived and installed during handshake. + + *Since:* 3.6.13 + +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. This + function is not thread safe. + + *Returns:* a (0)-terminated list of 'gnutls_sign_algorithm_t' + integers indicating the available ciphers. + +gnutls_sign_set_secure +---------------------- + + -- Function: int gnutls_sign_set_secure (gnutls_sign_algorithm_t SIGN, + unsigned int SECURE) + SIGN: the sign algorithm + + SECURE: whether to mark the sign algorithm secure + + Modify the previous system wide setting that marked 'sign' as + secure or insecure. Calling this function is allowed only if + allowlisting mode is set in the configuration file, and only if the + system-wide TLS priority string has not been initialized yet. The + intended usage is to provide applications with a way to expressly + deviate from the distribution or site defaults inherited from the + configuration file. The modification is composable with further + modifications performed through the priority string mechanism. + + This function is not thread-safe and is intended to be called in + the main thread at the beginning of the process execution. + + Even when 'secure' is true, 'sign' is not marked as secure for the + use in certificates. Use 'gnutls_sign_set_secure_for_certs()' to + mark it secure as well for certificates. + + *Returns:* 0 on success or negative error code otherwise. + + *Since:* 3.7.3 + +gnutls_sign_set_secure_for_certs +-------------------------------- + + -- Function: int gnutls_sign_set_secure_for_certs + (gnutls_sign_algorithm_t SIGN, unsigned int SECURE) + SIGN: the sign algorithm + + SECURE: whether to mark the sign algorithm secure for certificates + + Modify the previous system wide setting that marked 'sign' as + secure or insecure for the use in certificates. Calling this + fuction is allowed only if allowlisting mode is set in the + configuration file, and only if the system-wide TLS priority string + has not been initialized yet. The intended usage is to provide + applications with a way to expressly deviate from the distribution + or site defaults inherited from the configuration file. The + modification is composable with further modifications performed + through the priority string mechanism. + + This function is not thread-safe and is intended to be called in + the main thread at the beginning of the process execution. When + 'secure' is true, 'sign' is marked as secure for any use unlike + 'gnutls_sign_set_secure()' . Otherwise, it is marked as insecure + only for the use in certificates. Use 'gnutls_sign_set_secure()' + to mark it insecure for any uses. + + *Returns:* 0 on success or negative error code otherwise. + + *Since:* 3.7.3 + +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, under TLS1.3 and for + enforcing the DTLS mode timeouts when in blocking mode. + + For compatibility with future GnuTLS versions this callback must be + set when a custom pull function is registered. The callback will + not be used when the session is in TLS mode with non-blocking + sockets. That is, when 'GNUTLS_NONBLOCK' is specified for a TLS + session in 'gnutls_init()' . + + The helper function 'gnutls_system_recv_timeout()' is provided to + simplify writing callbacks. + + *Since:* 3.0 + +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 + |