Whole document tree

www.fifi.org
    Documentation
        Manpages
        GNU Info
        Debian document tree
        Whole document tree
    Trigance web page
    Public services
    User info
    Mailing lists
    Secure server
    Multilingual usage

Whole document tree

gnutls

GNUTLS

a Transport Layer Security Library
This document applies to GNUTLS 0.3.5

By Nikos Mavroyanopoulos and Fabio Fiorina

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 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 chapter entitled "GNU Free Documentation License".

The Library

Introduction

GNUTLS is a portable library which implements the TLS 1.0 and SSL 3.0 protocols. TLS stands for 'Transport Layer Security' and is the sucessor of SSL ^1.1. TLS 1.0 ^1.2 is an Internet protocol, defined by IETF^1.3that provides confidentiality, and authentication layers over a reliable transport layer^1.4. GNUTLS implements the above protocols in reentrant way in order to be used in multiple threads of execution (without the need for Critical Sections and locks). See http://www.gnutls.org/ and http://www.gnu.org/software/gnutls/ for updated versions of the GNUTLS software and this document.

Currently GNUTLS implements:

the TLS 1.0 and SSL 3.0 protocols, without any weak algorithms^1.5
X.509 Public Key Infrastructure (with several limitations).
SRP for TLS authentication.
TLS Extension mechanism

TLS Cipher suites

TLS 1.0 supports ciphersuites like TLS_X509PKI_DHE_RSA_WITH_3DES_CBC_SHA. These ciphersuites contain three parameters:

The authentication method (X.509 PKI in the example)^1.6
The key exchange algorithm (DHE_RSA in the example)
The Symmetric encryption algorithm and mode (3DES_CBC in this example)
The MAC^1.7 algorithm used for authentication. MAC_SHA is used in the above example.

The ciphersuite that will be used in the connection is negotiated at the handshake procedure. However you must note that TLS 1.0 does not always negotiate the strongest available cipher suite. There are cases where a man in the middle attacker could make the two entities negotiate the least secure method they support. For that reason do not enable ciphers and algorithms that you consider weak.

Symmetric encryption algorithms

Confidentiality is provided by using block encryption algorithms like 3DES, AES^1.8, or stream algorithms like ARCFOUR^1.9 See fig:ciphers for a complete list. Ciphers are encryption algorithms that use a single (secret) key to encrypt and decrypt data. Block algorithms in TLS also provide protection against statistical analysis of the data. GNUTLS makes use of this property thus, if you're operating in TLS 1.0 mode, a random number of blocks will be appended to the data. This will prevent eavesdroppers from guessing the actual data size.

**Figure 1.1:** Supported cipher algorithms
$\begin{figure}\begin{tabular}{\vert l\vert p{9cm}\vert} \par \hline 3DES\_CBC & ... ... of TLS. It is a {\emph{GNUTLS}} extension. \\ \hline \end{tabular}\end{figure}$ ^1.10 ^1.11

**Figure 1.2:** Supported MAC algorithms
$\begin{figure}\begin{tabular}{\vert l\vert p{9cm}\vert} \par\hline MAC\_MD5 & MD... ...algorithm by NSA. Outputs 160 bits of data. \\ \hline \end{tabular}\end{figure}$

Authentication methods

The following authentication schemas are supported in GNUTLS :

X509 Public Key Infrastructure
Anonymous authentication
SRP authentication

Authentication using X.509 certificates

If using this kind of authentication then the key exchange methods shown in figure are available to use. Authentication in this method is performed using signed certificates by a trusted Certificate Authority (CA). Note that GNUTLS is not a generic purpose X.509 toolkit^1.12. It does only include the required, in order to use the TLS ciphersuites which require X.509 certificates.

**Figure 1.3:** Supported X.509 key exchange algorithms
$\begin{figure}\begin{tabular}{\vert l\vert p{9cm}\vert} \hline X509PKI\_RSA & Th... ...oes not support this ciphersuite. \\ \hline \end{tabular}\par \par \end{figure}$

Anonymous authentication

The anonymous key exchanges perform encryption but there is no indication of the identity of the peer. This kind of authentication is vulnerable to man in the middle attack, but this protocol can be used even if there is no prior communication or common trusted parties with the peer. Unless really required, do not use anonymous authentication. Available key exchange methods are shown in figure.

**Figure 1.4:** Supported anonymous key exchange algorithms
$\begin{figure}\begin{tabular}{\vert l\vert p{9cm}\vert} \par\hline ANON\_DH & Th... ...changes Diffie Hellman parameters. \\ \hline \end{tabular}\par\par\end{figure}$

Authentication using SRP

Authentication using the SRP^1.14is actually password authentication, since the two peers are identified by the knowledge of a password. This protocol also offers protection against off-line attacks (password file stealing etc). This is achieved since SRP does not use the plain password to perform authentication, but something called a verifier. The verifier is g^xmod (n) and x is a value calculated from the username and the password.

SRP is normaly used with a SHA based hash function, to calculate the value of x. In GNUTLS in addition to original SHA hash function, a hash function based on blowfish crypt is also supported. The blowfish crypt function has the property of variable complexity, thus the verifier may resist future attacks based on computational power, by just increasing the complexity of the function (sometimes called 'the cost').

The advantage of SRP authentication, over other proposed secure password authentication schemas, is that SRP does not require the server to hold the user's password. This kind of protection is similar to the one used traditionaly in the UNIX 'passwd' file, where the contents of this file did not cause harm to the system security if they were revealed.

Available key exchange methods are shown in figure.

**Figure 1.5:** Supported SRP key exchange algorithms
$\begin{figure}\begin{tabular}{\vert l\vert p{9cm}\vert} \par\hline SRP & Authentication using the SRP protocol. \\ \hline \end{tabular}\par\par\end{figure}$

Resuming Sessions

The gnutls_handshake() function, is expensive since a lot of calculations are performed. In order to support many fast connections to the same server a client may use session resuming. Session resuming is a feature of the TLS protocol which allows a client to connect to a server, after a successful handshake, without the expensive calculations (by using the previously established keys). GNUTLS supports this feature, and the example resume client illustrates a typical use of it (This is a modification of the simple client example). Servers only need to use the gnutls_db_set_name() function if they want to use the gdbm backend to store sessions.

Keep in mind that sessions are expired after some time (for security reasons), thus it may be normal for a server not to resume a session even if you requested that. Also note that you must enable (using the priority functions), at least the algorithms used in the last session.

Resuming internals

The resuming capability (mostly in the server side) is one of the problems of a thread-safe TLS implementations. The problem is that all threads must share information in order to be able to resume sessions. The gnutls approach is, in case of a client, to leave all the burden of resuming to the client (ie. copy and keep the nesessary parameters). See gnutls_session_get_data(), gnutls_session_get_id() and gnutls_session_set_data().

The server side is different. Here the server only specifies a DB file, using gnutls_db_set_name(). This DB file is used to store the sessions' required parameters for resuming. This means that this file contains very sensitive information, such as encryption keys. In a multi-threaded application every thread can read from the DB file and access all previously established sessions, but only one thread can write at a time. The current behaviour of gnutls is not to block to wait for the DB to be ready for writing, but continue the process normally (and do not save the parameters).

GNUTLS also provides callback functions such as: gnutls_db_set_remove_function(), gnutls_db_set_store_function(), gnutls_db_set_retrieve_function() and gnutls_db_set_ptr(). These callback functions are required in order to use a session storage method, other than the default gdbm backend.

If an alternative backend is in use, it might be usefull to be able to check for expired sessions in order to remove them, and save space. This is what gnutls_db_clean() does for the gdbm backend. GNUTLS provides the function gnutls_db_check_entry(), which takes as input session data, and returns a negative value if the data are to be removed.

Transport Layer

GNUTLS can be used above any reliable transport layer. To do this you will only need to set up the gnutls_transport_set_push_func() and gnutls_transport_set_pull_func() functions. These functions will then be used by gnutls in order to send and receive data. The functions specified should return -1 on error and should set errno appropriately. GNUTLS supports EINTR and EAGAIN errno values. These values are usually used in non blocking IO and interrupted system calls. The corresponding values (GNUTLS_E_INTERRUPTED, GNUTLS_E_AGAIN) will be returned to the caller of the gnutls function. GNUTLS functions can be resumed (called again), if any of these values is returned.

By default, if none of the above functions are called, gnutls will use the berkeley sockets functions recv() and send(). In this case gnutls will use some hacks in order for select() to work, thus making easy to add TLS support to existing servers.

Error Handling

In GNUTLS most functions return an integer type as a result. In almost all cases a zero or a positive number means success, and a negative number indicates failure, or a situation that some action has to be taken. Thus negative error codes may be fatal or not.

Fatal errors terminate the connection immediately and further sends ard receives will be disallowed. An example of a fatal error code is GNUTLS_E_MAC_FAILED. Non-fatal errors may warn about something (ie a warning alert was received), or indicate the some action has to be taken. This is the case with the error code GNUTLS_E_REHANDSHAKE returned by gnutls_read(). This error code requires a full handshake to be performed again, or an alert to be sent. You can test if an error code is a fatal one by using the gnutls_error_is_fatal().

If any non fatal errors, that require reaction, are to be returned by a function, these error codes will be documented in the function's reference.

Client Examples

This section contains examples of TLS and SSL clients, using GNUTLS .

Simple Client example with X.509 Authentication

Let's assume now that we want to create a client which communicates with servers using the X509 authentication schema. The following client is a very simple TLS client, it does not support session resuming nor any other fancy features.

#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <gnutls.h>

#define MAX_BUF 1024
#define CRLFILE "crl.pem"
#define CAFILE "ca.pem"
#define SA struct sockaddr
#define MSG "GET / HTTP/1.0\r\n\r\n"

int main()
{
   const char *PORT = "443";
   const char *SERVER = "127.0.0.1";
   int err, ret;
   int sd, ii;
   struct sockaddr_in sa;
   GNUTLS_STATE state;
   char buffer[MAX_BUF + 1];
   GNUTLS_X509PKI_CLIENT_CREDENTIALS xcred;
   const int protocol_priority[] = { GNUTLS_TLS1, GNUTLS_SSL3, 0 };
   const int kx_priority[] = { GNUTLS_KX_X509PKI_RSA, 0 };
   const int cipher_priority[] = { GNUTLS_CIPHER_3DES_CBC, GNUTLS_CIPHER_ARCFOUR, 0};
   const int comp_priority[] = { GNUTLS_COMP_ZLIB, GNUTLS_COMP_NULL, 0 };
   const int mac_priority[] = { GNUTLS_MAC_SHA, GNUTLS_MAC_MD5, 0 };


   if (gnutls_global_init() < 0) {
      fprintf(stderr, "global state initialization error\n");
      exit(1);
   }
   /* X509 stuff */
   if (gnutls_x509pki_allocate_client_sc(&xcred, 0) < 0) {  /* no client private key */
      fprintf(stderr, "memory error\n");
      exit(1);
   }
   /* set's the trusted cas file
    */
   gnutls_x509pki_set_client_trust_file(xcred, CAFILE, CRLFILE);

   /* 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, (SA *) & sa, sizeof(sa));
   if (err < 0) {
      fprintf(stderr, "Connect error\n");
      exit(1);
   }
   /* Initialize TLS state 
    */
   gnutls_init(&state, GNUTLS_CLIENT);

   /* allow both SSL3 and TLS1
    */
   gnutls_protocol_set_priority(state, protocol_priority);

   /* allow only ARCFOUR and 3DES ciphers
    * (3DES has the highest priority)
    */
   gnutls_cipher_set_priority(state, cipher_priority);

   /* only allow null compression
    */
   gnutls_compression_set_priority(state, comp_priority);

   /* use GNUTLS_KX_X509PKI_RSA
    */
   gnutls_kx_set_priority(state, kx_priority);

   /* allow the usage of both SHA and MD5
    */
   gnutls_mac_set_priority(state, mac_priority);


   /* put the x509 credentials to the current state
    */
   gnutls_cred_set(state, GNUTLS_X509PKI, xcred);


   gnutls_transport_set_ptr( state, sd);
   /* Perform the TLS handshake
    */
   ret = gnutls_handshake( state);

   if (ret < 0) {
      fprintf(stderr, "*** Handshake failed\n");
      gnutls_perror(ret);
      goto end;
   } else {
      printf("- Handshake was completed\n");
   }

   gnutls_write( state, MSG, strlen(MSG));

   ret = gnutls_read( state, buffer, MAX_BUF);
   if (gnutls_error_is_fatal(ret) == 1 || ret == 0) {
      if (ret == 0) {
         printf("- Peer has closed the GNUTLS connection\n");
         goto end;
      } else {
         fprintf(stderr, "*** Received corrupted data(%d) - server has terminated the connection abnormally\n",
                 ret);
         goto end;
      }
   } else {
      if (ret == GNUTLS_E_WARNING_ALERT_RECEIVED || ret == GNUTLS_E_FATAL_ALERT_RECEIVED)
         printf("* Received alert [%d]\n", gnutls_alert_get_last(state));
      if (ret == GNUTLS_E_REHANDSHAKE)
         printf("* Received HelloRequest message (server asked to rehandshake)\n");
         gnutls_alert_send_appropriate( state, ret); /* we don't want rehandshake */
   }

   if (ret > 0) {
      printf("- Received %d bytes: ", ret);
      for (ii = 0; ii < ret; ii++) {
         fputc(buffer[ii], stdout);
      }
      fputs("\n", stdout);
   }
   gnutls_bye( state, GNUTLS_SHUT_RDWR);

 end:

   shutdown(sd, SHUT_RDWR);     /* no more receptions */
   close(sd);

   gnutls_deinit(state);

   gnutls_x509pki_free_client_sc(xcred);

   gnutls_global_deinit();

   return 0;
}

Getting peer's information

The above example was the simplest form of a client, it didn't even check the result of the peer's certificate verification function (ie. if we have an authenticated connection). The following function does check the peer's X509 Certificate, and prints some information about the current state.

This function should be called after a successful gnutls_handshake()

#define PRINTX(x,y) if (y[0]!=0) printf(" -   %s %s\n", x, y)
#define PRINT_DN(X) PRINTX( "CN:", X.common_name); \
        PRINTX( "OU:", X.organizational_unit_name); \
        PRINTX( "O:", X.organization); \
        PRINTX( "L:", X.locality_name); \
        PRINTX( "S:", X.state_or_province_name); \
        PRINTX( "C:", X.country); \
        PRINTX( "E:", X.email)

/* This function will print some details of the
 * given state.
 */
int print_info(GNUTLS_STATE state)
{
   const char *tmp;
   GNUTLS_CredType cred;
   gnutls_DN dn;
   const gnutls_datum *cert_list;
   GNUTLS_CertificateStatus status;
   int cert_list_size = 0;
   GNUTLS_KXAlgorithm kx;


   /* print the key exchange's algorithm name
    */
   kx = gnutls_kx_get_algo(state);
   tmp = gnutls_kx_get_name(kx);
   printf("- Key Exchange: %s\n", tmp);

   cred = gnutls_auth_get_type(state);
   switch (cred) {
   case GNUTLS_ANON:
      printf("- Anonymous DH using prime of %d bits\n",
             gnutls_anon_client_get_dh_bits(state));
      break;
   case GNUTLS_X509PKI:
      /* in case of X509 PKI
       */
      cert_list = gnutls_x509pki_client_get_peer_certificate_list(state, &cert_list_size);
      status = gnutls_x509pki_client_get_peer_certificate_status(state);

      switch (status) {
      case GNUTLS_CERT_NOT_TRUSTED:
         printf("- Peer's X509 Certificate was NOT verified\n");
         break;
      case GNUTLS_CERT_EXPIRED:
         printf("- Peer's X509 Certificate was verified but is expired\n");
         break;
      case GNUTLS_CERT_TRUSTED:
         printf("- Peer's X509 Certificate was verified\n");
         break;
      case GNUTLS_CERT_NONE:
         printf("- Peer did not send any X509 Certificate.\n");
         break;
      case GNUTLS_CERT_INVALID:
         printf("- Peer's X509 Certificate was invalid\n");
         break;
      }

      /* Check if we have been using ephemeral Diffie Hellman.
       */
      if (kx == GNUTLS_KX_X509PKI_DHE_RSA || kx == GNUTLS_KX_X509PKI_DHE_DSS) {
         printf("\n- Ephemeral DH using prime of %d bits\n",
                gnutls_x509pki_server_get_dh_bits(state));
      }

      /* if the certificate list is available, then
       * print some information about it.
       */
      if (cert_list_size > 0) {
         char digest[20];
         char serial[40];
         int digest_size = sizeof(digest), i;
         int serial_size = sizeof(serial);
         char printable[120];
         char *print;

         printf(" - Certificate info:\n");

         /* Print the fingerprint of the certificate
          */
         if (gnutls_fingerprint(GNUTLS_DIG_MD5, &cert_list[0], digest, &digest_size) >= 0) {
            print = printable;
            for (i = 0; i < digest_size; i++) {
               sprintf(print, "%.2x ", (unsigned char) digest[i]);
               print += 3;
            }
            printf(" - Certificate fingerprint: %s\n", printable);
         }

         /* Print the serial number of the certificate.
          */
         if (gnutls_x509pki_extract_certificate_serial(&cert_list[0], serial, &serial_size) >= 0) {
            print = printable;
            for (i = 0; i < serial_size; i++) {
               sprintf(print, "%.2x ", (unsigned char) serial[i]);
               print += 3;
            }
            printf(" - Certificate serial number: %s\n", printable);
         }

         /* Print the version of the X.509 
          * certificate.
          */
         printf(" - Certificate version: #%d\n", gnutls_x509pki_extract_certificate_version(&cert_list[0]));

         gnutls_x509pki_extract_certificate_dn(&cert_list[0], &dn);
         PRINT_DN(dn);

         gnutls_x509pki_extract_certificate_issuer_dn(&cert_list[0], &dn);
         printf(" - Certificate Issuer's info:\n");
         PRINT_DN(dn);
      }
   }

   tmp = gnutls_protocol_get_name(gnutls_protocol_get_version(state));
   printf("- Version: %s\n", tmp);

   tmp = gnutls_compression_get_name(gnutls_compression_get_algo(state));
   printf("- Compression: %s\n", tmp);

   tmp = gnutls_cipher_get_name(gnutls_cipher_get_algo(state));
   printf("- Cipher: %s\n", tmp);

   tmp = gnutls_mac_get_name(gnutls_mac_get_algo(state));
   printf("- MAC: %s\n", tmp);

   return 0;
}

Client with Resume capability example

#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <gnutls.h>

#define MAX_BUF 1024
#define CRLFILE "crl.pem"
#define CAFILE "ca.pem"
#define SA struct sockaddr
#define MSG "GET / HTTP/1.0\r\n\r\n"

const int protocol_priority[] = { GNUTLS_TLS1, GNUTLS_SSL3, 0 };
const int kx_priority[] = { GNUTLS_KX_X509PKI_RSA, GNUTLS_KX_X509PKI_DHE_RSA, 0 };
const int cipher_priority[] = { GNUTLS_CIPHER_3DES_CBC, GNUTLS_CIPHER_ARCFOUR, 0};
const int comp_priority[] = { GNUTLS_COMP_ZLIB, GNUTLS_COMP_NULL, 0 };
const int mac_priority[] = { GNUTLS_MAC_SHA, GNUTLS_MAC_MD5, 0 };

int main()
{
   const char *PORT = "443";
   const char *SERVER = "127.0.0.1";
   int err, ret;
   int sd, ii;
   struct sockaddr_in sa;
   GNUTLS_STATE state;
   char buffer[MAX_BUF + 1];
   GNUTLS_X509PKI_CLIENT_CREDENTIALS xcred;
   /* variables used in session resuming */
   int t;
   char *session;
   char *session_id;
   int session_size;
   int session_id_size;
   char *tmp_session_id;
   int tmp_session_id_size;

   if (gnutls_global_init() < 0) {
      fprintf(stderr, "global state initialization error\n");
      exit(1);
   }
   /* X509 stuff */
   if (gnutls_x509pki_allocate_client_sc(&xcred, 0) < 0) {  /* no client private key */
      fprintf(stderr, "memory error\n");
      exit(1);
   }
   gnutls_x509pki_set_client_trust_file(xcred, CAFILE, CRLFILE);

   for (t = 0; t < 2; t++) {    /* connect 2 times to the 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, (SA *) & sa, sizeof(sa));
      if (err < 0) {
         fprintf(stderr, "Connect error");
         exit(1);
      }
      gnutls_init(&state, GNUTLS_CLIENT);

      gnutls_protocol_set_priority(state, protocol_priority);
      gnutls_cipher_set_priority(state, cipher_priority);
      gnutls_compression_set_priority(state, comp_priority);
      gnutls_kx_set_priority(state, kx_priority);
      gnutls_mac_set_priority(state, mac_priority);

      gnutls_cred_set(state, GNUTLS_X509PKI, xcred);

      if (t > 0) { /* if this is not the first time we connect */
         gnutls_session_set_data(state, session, session_size);
         free(session);
      }
      
      gnutls_set_transport_ptr( state, sd);

      /* Perform the TLS handshake
       */
      ret = gnutls_handshake( state);

      if (ret < 0) {
         fprintf(stderr, "*** Handshake failed\n");
         gnutls_perror(ret);
         goto end;
      } else {
         printf("- Handshake was completed\n");
      }

      if (t == 0) { /* the first time we connect */
         /* get the session data size */
         gnutls_session_get_data(state, NULL, &session_size);
         session = malloc(session_size);

         /* put session data to the session variable */
         gnutls_session_get_data(state, session, &session_size);

         /* keep the current session ID. This is only needed
          * in order to check if the server actually resumed this
          * connection.
          */
         gnutls_session_get_id(state, NULL, &session_id_size);
         session_id = malloc(session_id_size);
         gnutls_session_get_id(state, session_id, &session_id_size);

      } else { /* the second time we connect */

         /* check if we actually resumed the previous session */
         gnutls_session_get_id(state, NULL, &tmp_session_id_size);
         tmp_session_id = malloc(tmp_session_id_size);
         gnutls_session_get_id(state, tmp_session_id, &tmp_session_id_size);

         if (memcmp(tmp_session_id, session_id, session_id_size) == 0) {
            printf("- Previous session was resumed\n");
         } else {
            fprintf(stderr, "*** Previous session was NOT resumed\n");
         }
         free(tmp_session_id);
         free(session_id);
      }

      /* This function was defined in a previous example
       */
      print_info(state);

      gnutls_write( state, MSG, strlen(MSG));

      ret = gnutls_read( state, buffer, MAX_BUF);
      if (gnutls_error_is_fatal(ret) == 1 || ret == 0) {
         if (ret == 0) {
            printf("- Peer has closed the GNUTLS connection\n");
            goto end;
         } else {
            fprintf(stderr, "*** Received corrupted data(%d) - server has terminated the connection abnormally\n",
                    ret);
            goto end;
         }
      } else {
         if (ret == GNUTLS_E_WARNING_ALERT_RECEIVED || ret == GNUTLS_E_FATAL_ALERT_RECEIVED)
            printf("* Received alert [%d]\n", gnutls_alert_get_last(state));
         if (ret == GNUTLS_E_REHANDSHAKE) {
            printf("* Received HelloRequest message (server asked to rehandshake)\n");
            gnutls_alert_send_appropriate( state, ret); /* we don't want rehandshake */
         }
      }

      if (ret > 0) {
         printf("- Received %d bytes: ", ret);
         for (ii = 0; ii < ret; ii++) {
            fputc(buffer[ii], stdout);
         }
         fputs("\n", stdout);
      }
      gnutls_bye( state, GNUTLS_SHUT_RDWR);

    end:

      shutdown(sd, SHUT_RDWR);  /* no more receptions */
      close(sd);

      gnutls_deinit(state);

   }  /* for() */

   gnutls_x509pki_free_client_sc(xcred);

   gnutls_global_deinit();

   return 0;
}

Simple Client example with SRP Authentication

Although SRP is not part of the TLS standard, GNUTLS implements David Taylor's^1.15 proposal for using the SRP algorithm within the TLS handshake protocol. The following client is a very simple SRP-TLS client which connects to a server and authenticates using username and password.

#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <gnutls.h>

#define MAX_BUF 1024
#define USERNAME "user"
#define PASSWORD "pass"
#define SA struct sockaddr
#define MSG "GET / HTTP/1.0\r\n\r\n"

const int protocol_priority[] = { GNUTLS_TLS1, GNUTLS_SSL3, 0 };
const int kx_priority[] = { GNUTLS_KX_SRP, 0 };
const int cipher_priority[] = { GNUTLS_CIPHER_3DES_CBC, GNUTLS_CIPHER_ARCFOUR, 0};
const int comp_priority[] = { GNUTLS_COMP_NULL, 0 };
const int mac_priority[] = { GNUTLS_MAC_SHA, GNUTLS_MAC_MD5, 0 };

int main()
{
   const char *PORT = "443";
   const char *SERVER = "127.0.0.1";
   int err, ret;
   int sd, ii;
   struct sockaddr_in sa;
   GNUTLS_STATE state;
   char buffer[MAX_BUF + 1];
   GNUTLS_SRP_CLIENT_CREDENTIALS xcred;

   if (gnutls_global_init() < 0) {
      fprintf(stderr, "global state initialization error\n");
      exit(1);
   }
   if (gnutls_srp_allocate_client_sc(&xcred) < 0) {
      fprintf(stderr, "memory error\n");
      exit(1);
   }
   gnutls_srp_set_client_cred(xcred, USERNAME, PASSWORD);

   /* 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, (SA *) & sa, sizeof(sa));
   if (err < 0) {
      fprintf(stderr, "Connect error\n");
      exit(1);
   }
   /* Initialize TLS state 
    */
   gnutls_init(&state, GNUTLS_CLIENT);

   /* allow both SSL3 and TLS1
    */
   gnutls_protocol_set_priority(state, protocol_priority);
 
   /* allow only ARCFOUR and 3DES ciphers
    * (3DES has the highest priority)
    */
    gnutls_cipher_set_priority(state, cipher_priority);

   /* only allow null compression
    */
   gnutls_compression_set_priority(state, comp_priority);
 
   /* use GNUTLS_KX_SRP
    */
   gnutls_kx_set_priority(state, kx_priority);
 
   /* allow the usage of both SHA and MD5
    */
   gnutls_mac_set_priority(state, mac_priority);


   /* put the SRP credentials to the current state
    */
   gnutls_cred_set(state, GNUTLS_SRP, xcred);

   gnutls_transport_set_ptr( state, sd);

   /* Perform the TLS handshake
    */
   ret = gnutls_handshake( state);

   if (ret < 0) {
      fprintf(stderr, "*** Handshake failed\n");
      gnutls_perror(ret);
      goto end;
   } else {
      printf("- Handshake was completed\n");
   }

   gnutls_write( state, MSG, strlen(MSG));

   ret = gnutls_read( state, buffer, MAX_BUF);
   if (gnutls_error_is_fatal(ret) == 1 || ret == 0) {
      if (ret == 0) {
         printf("- Peer has closed the GNUTLS connection\n");
         goto end;
      } else {
         fprintf(stderr, "*** Received corrupted data(%d) - server has terminated the connection abnormally\n",
                 ret);
         goto end;
      }
   } else {
      if (ret == GNUTLS_E_WARNING_ALERT_RECEIVED || ret == GNUTLS_E_FATAL_ALERT_RECEIVED)
         printf("* Received alert [%d]\n", gnutls_alert_get_last(state));
      if (ret == GNUTLS_E_REHANDSHAKE)
         printf("* Received HelloRequest message (server asked to rehandshake)\n");
   }

   if (ret > 0) {
      printf("- Received %d bytes: ", ret);
      for (ii = 0; ii < ret; ii++) {
         fputc(buffer[ii], stdout);
      }
      fputs("\n", stdout);
   }
   gnutls_bye( state, 0);

 end:

   shutdown(sd, SHUT_RDWR);     /* no more receptions */
   close(sd);

   gnutls_deinit(state);

   gnutls_srp_free_client_sc(xcred);

   gnutls_global_deinit();

   return 0;
}

Server Examples

This section contains examples of TLS and SSL servers, using GNUTLS .

Echo Server with X.509 and SRP authentication

The following example is a server which supports both SRP and X509 authentication. This server also supports session resuming.

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <string.h>
#include <unistd.h>
#include <gnutls.h>

#define KEYFILE "key.pem"
#define CERTFILE "cert.pem"
#define CAFILE "ca.pem"
#define CRLFILE NULL

#define SRP_PASSWD "tpasswd"
#define SRP_PASSWD_CONF "tpasswd.conf"


/* This is a sample TCP echo server.
 */


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

/* These are global */
GNUTLS_SRP_SERVER_CREDENTIALS srp_cred;
GNUTLS_X509PKI_SERVER_CREDENTIALS x509_cred;

GNUTLS_STATE initialize_state()
{
   GNUTLS_STATE state;
   int ret;
   const int protocol_priority[] = { GNUTLS_TLS1, GNUTLS_SSL3, 0 };
   const int kx_priority[] = { GNUTLS_KX_X509PKI_RSA, GNUTLS_KX_X509PKI_DHE_RSA, GNUTLS_KX_SRP, 0 };
   const int cipher_priority[] = { GNUTLS_CIPHER_RIJNDAEL_CBC, GNUTLS_CIPHER_3DES_CBC, 0};
   const int comp_priority[] = { GNUTLS_COMP_ZLIB, GNUTLS_COMP_NULL, 0 };
   const int mac_priority[] = { GNUTLS_MAC_SHA, GNUTLS_MAC_MD5, 0 };

   gnutls_init(&state, GNUTLS_SERVER);

   /* in order to support session resuming:
    */
   if ((ret = gnutls_db_set_name(state, "gnutls-rsm.db")) < 0)
      fprintf(stderr, "*** DB error (%d)\n\n", ret);

   gnutls_protocol_set_priority(state, protocol_priority);
   gnutls_cipher_set_priority(state, cipher_priority);
   gnutls_compression_set_priority(state, comp_priority);
   gnutls_kx_set_priority(state, kx_priority);
   gnutls_mac_set_priority(state, mac_priority);

   gnutls_cred_set(state, GNUTLS_SRP, srp_cred);
   gnutls_cred_set(state, GNUTLS_X509PKI, x509_cred);

   /* request client certificate if any.
    */
   gnutls_x509pki_server_set_cert_request( state, GNUTLS_CERT_REQUEST);
   
   return state;
}

void print_info(GNUTLS_STATE state)
{
   const char *tmp;
   unsigned char sesid[32];
   int sesid_size, i;

   /* print session_id specific data */
   gnutls_session_get_id(state, sesid, &sesid_size);
   printf("\n- Session ID: ");
   for (i = 0; i < sesid_size; i++)
      printf("%.2X", sesid[i]);
   printf("\n");

   /* print srp specific data */
   if (gnutls_get_auth_type(state) == GNUTLS_SRP) {
         printf("\n- User '%s' connected\n",
                gnutls_srp_server_get_username( state));
   }

   /* print state information */
   tmp = gnutls_protocol_get_name(gnutls_protocol_get_version(state));
   printf("- Version: %s\n", tmp);

   tmp = gnutls_kx_get_name(gnutls_kx_get_algo(state));
   printf("- Key Exchange: %s\n", tmp);

   tmp =
       gnutls_compression_get_name
       (gnutls_compression_get_algo(state));
   printf("- Compression: %s\n", tmp);

   tmp = gnutls_cipher_get_name(gnutls_cipher_get_algo(state));
   printf("- Cipher: %s\n", tmp);

   tmp = gnutls_mac_get_name(gnutls_mac_get_algo(state));
   printf("- MAC: %s\n", tmp);

}



int main()
{
   int err, listen_sd, i;
   int sd, ret;
   struct sockaddr_in sa_serv;
   struct sockaddr_in sa_cli;
   int client_len;
   char topbuf[512];
   GNUTLS_STATE state;
   char buffer[MAX_BUF + 1];
   int optval = 1;
   int http = 0;
   char name[256];

   strcpy(name, "Echo Server");

   /* this must be called once in the program
    */
   if (gnutls_global_init() < 0) {
      fprintf(stderr, "global state initialization error\n");
      exit(1);
   }
   if (gnutls_x509pki_allocate_server_sc(&x509_cred, 1) < 0) {
      fprintf(stderr, "memory error\n");
      exit(1);
   }
   if (gnutls_x509pki_set_server_trust_file(x509_cred, CAFILE, CRLFILE) < 0) {
      fprintf(stderr, "X509 PARSE ERROR\nDid you have ca.pem?\n");
      exit(1);
   }
   if (gnutls_x509pki_set_server_key_file(x509_cred, CERTFILE, KEYFILE) < 0) {
      fprintf(stderr, "X509 PARSE ERROR\nDid you have key.pem and cert.pem?\n");
      exit(1);
   }
   /* SRP_PASSWD a password file (created with the included crypt utility) 
    * Read README.crypt prior to using SRP.
    */
   gnutls_srp_allocateserver_sc(&srp_cred);
   gnutls_srp_set_server_cred(srp_cred, SRP_PASSWD, SRP_PASSWD_CONF);


   /* Socket operations
    */
   listen_sd = socket(AF_INET, SOCK_STREAM, 0);
   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, &optval, sizeof(int));

   err = bind(listen_sd, (SA *) & sa_serv, sizeof(sa_serv));
   ERR(err, "bind");
   err = listen(listen_sd, 1024);
   ERR(err, "listen");

   printf("%s ready. Listening to port '%d'.\n\n", name, PORT);

   client_len = sizeof(sa_cli);
   for (;;) {
      state = initialize_state();

      sd = accept(listen_sd, (SA *) & 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_ptr( state, sd);
      ret = gnutls_handshake( state);
      if (ret < 0) {
         close(sd);
         gnutls_deinit(state);
         fprintf(stderr, "*** Handshake has failed (%s)\n\n",
                 gnutls_strerror(ret));
         continue;
      }
      printf("- Handshake was completed\n");

      print_info(state);

      i = 0;
      for (;;) {
         bzero(buffer, MAX_BUF + 1);
         ret = gnutls_read( state, buffer, MAX_BUF);

         if (gnutls_error_is_fatal(ret) == 1 || ret == 0) {
            if (ret == 0) {
               printf
                   ("\n- Peer has closed the GNUTLS connection\n");
               break;
            } else {
               fprintf(stderr,
                       "\n*** Received corrupted data(%d). Closing the connection.\n\n",
                       ret);
               break;
            }

         }
         if (ret > 0) {
            /* echo data back to the client
             */
            gnutls_write( state, buffer,
                         strlen(buffer));
         }
         if (ret == GNUTLS_E_WARNING_ALERT_RECEIVED || ret == GNUTLS_E_FATAL_ALERT_RECEIVED) {
            ret = gnutls_alert_get_last(state);
            printf("* Received alert '%d'.\n", ret);
         }
      }
      printf("\n");
      gnutls_bye( state, 1); /* do not wait for
                                 * the peer to close the connection.
                                 */

      close(sd);
      gnutls_deinit(state);

   }
   close(listen_sd);

   gnutls_x509pki_free_server_sc(x509_cred);
   gnutls_srp_free_server_sc(srp_cred);

   gnutls_global_deinit();

   return 0;

}

Function Reference

gnutls_protocol_get_version

GNUTLS_Version gnutls_protocol_get_version ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

Returns the version of the currently used protocol.

gnutls_transport_set_lowat

void gnutls_transport_set_lowat ( GNUTLS_STATE state , int num )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
int num: is the low water value.

Description

Used to set the lowat value in order for select to check if there are pending data to socket buffer. Used only if you have changed the default low water value (default is 1). Normally you will not need that function. This function is only usefull if using berkeley style sockets. Otherwise it must be called and set lowat to zero.

gnutls_transport_set_ptr

void gnutls_transport_set_ptr ( GNUTLS_STATE state , GNUTLS_SOCKET_PTR ptr )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
GNUTLS_SOCKET_PTR ptr: is the value.

Description

Used to set the first argument of the transport function (like PUSH and PULL). In berkeley style sockets this function will set the connection handle.

gnutls_transport_get_ptr

GNUTLS_SOCKET_PTR gnutls_transport_get_ptr ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

Used to get the first argument of the transport function (like PUSH and PULL). This must have been set using gnutls_transport_set_ptr().

gnutls_init

int gnutls_init ( GNUTLS_STATE * state , ConnectionEnd con_end )

Arguments

GNUTLS_STATE * state: is a pointer to a GNUTLS_STATE structure.
ConnectionEnd con_end: is used to indicate if this state is to be used for server or client. Can be one of GNUTLS_CLIENT and GNUTLS_SERVER.

Description

This function initializes the current state to null. Every state must be initialized before use, so internal structures can be allocated. This function allocates structures which can only be free'd by calling gnutls_deinit(). Returns zero on success.

gnutls_deinit

void gnutls_deinit ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

This function clears all buffers associated with the state.

gnutls_bye

int gnutls_bye ( GNUTLS_STATE state , CloseRequest how )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
CloseRequest how: is an integer

Description

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 then the TLS connection gets terminated and further receives and sends will be disallowed. If the return value is zero you may continue using the connection. GNUTLS_SHUT_RDWR actually sends an alert containing a close request and waits for the peer to reply with the same message.

In case of GNUTLS_SHUT_WR then the TLS connection 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.

This function may also return GNUTLS_E_AGAIN, or GNUTLS_E_INTERRUPTED.

gnutls_cipher_get_algo

BulkCipherAlgorithm gnutls_cipher_get_algo ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

Returns the currently used cipher.

gnutls_kx_get_algo

KXAlgorithm gnutls_kx_get_algo ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

Returns the key exchange algorithm used in the last handshake.

gnutls_mac_get_algo

MACAlgorithm gnutls_mac_get_algo ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

Returns the currently used mac algorithm.

gnutls_compression_get_algo

CompressionMethod gnutls_compression_get_algo ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

Returns the currently used compression method.

gnutls_write

ssize_t gnutls_write ( GNUTLS_STATE state , const void * data , size_t sizeofdata )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
const void * data: contains the data to send
size_t sizeofdata: is the length of the data

Description

This function has the similar semantics to write(). The only difference is that is accepts a GNUTLS state, and uses different error codes.

If the EINTR is returned by the internal push function (write()) 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 same parameters. Otherwise the write operation will be corrupted and the connection will be terminated.

Returns the number of bytes sent, or a negative error code.

gnutls_read

ssize_t gnutls_read ( GNUTLS_STATE state , void * data , size_t sizeofdata )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
void * data: contains the data to send
size_t sizeofdata: is the length of the data

Description

This function has the similar semantics to read(). The only difference is that is accepts a GNUTLS state. Also returns the number of bytes received, zero on EOF, but a negative error code in case of an error.

If this function returns GNUTLS_E_REHANDSHAKE, then you must either send an alert containing NO_RENEGOTIATION, or perform a handshake. (only a client may receive this message)

gnutls_record_get_max_size

size_t gnutls_record_get_max_size ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

This function returns the maximum record size in this connection. The maximum record size is negotiated by the client after the first handshake message.

gnutls_record_set_max_size

size_t gnutls_record_set_max_size ( GNUTLS_STATE state , size_t size )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
size_t size: is the new size

Description

This function sets the maximum record size in this connection. This property can only be set to clients. The server may choose not to accept the requested size.

Acceptable values are 2⁹, 2¹⁰, 2¹¹ and 2¹². Returns 0 on success. The requested record size does not get in effect immediately. It will be used after a successful handshake.

This function uses a TLS extension called 'max record size'. Not all TLS implementations use or even understand this extension.

gnutls_check_pending

int gnutls_check_pending ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

This function checks if there are any data to receive in the gnutls buffers. Returns the size of that data or 0. Notice that you may also use select() to check for data in the TCP connection, instead of this function. (gnutls leaves some data in the tcp buffer in order for select to work).

gnutls_rehandshake

int gnutls_rehandshake ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a a GNUTLS_STATE structure.

Description

This function will renegotiate security parameters with the client. This should only be called in case of a server.

This message informs the peer that we want to renegotiate parameters (perform a handshake).

If this function succeeds (returns 0), you must call the gnutls_handshake() function in order to negotiate the new parameters.

If the client does not wish to renegotiate parameters he will reply with an alert message, thus the return code will be GNUTLS_E_WARNING_ALERT_RECEIVED and the alert will be GNUTLS_A_NO_RENEGOTIATION.

gnutls_handshake

int gnutls_handshake ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a a GNUTLS_STATE structure.

Description

This function does the handshake of the TLS/SSL protocol, and initializes the TLS connection. Here the identity of the peer is checked automatically. This function will fail if any problem is encountered, and will return a negative error code. In case of a client, if it has been asked to resume a session, but the server didn't, then a full handshake will be performed.

This function may also return the non-fatal errors GNUTLS_E_AGAIN, or GNUTLS_E_INTERRUPTED. In that case you may resume the handshake (call this function again, until it returns ok)

gnutls_handshake_set_max_data_buffer_size

void gnutls_handshake_set_max_data_buffer_size ( GNUTLS_STATE state , int max )

Arguments

GNUTLS_STATE state: is a a GNUTLS_STATE structure.
int max: is the maximum number.

Description

This function will set the maximum size of the handshake message sequence. Since the handshake messages are kept into memory until the handshake is successful this function allows you to set the maximum number of bytes that will be kept. The default value is 128kb which is large enough. Set this to 0 if you do not want to set an upper limit.

gnutls_error_is_fatal

int gnutls_error_is_fatal ( int error )

Arguments

int error: is an error returned by a gnutls function. Error should be a negative value.

Description

If a function returns a negative value you may feed that value to this function to see if it is fatal. Returns 1 for a fatal error 0 otherwise. However you may want to check the error code manualy, since some non-fatal errors to the protocol may be fatal for you (your program).

gnutls_perror

void gnutls_perror ( int error )

Arguments

int error: is an error returned by a gnutls function. Error is always a negative value.

Description

This function is like perror(). The only difference is that it accepts an error returned by a gnutls function.

gnutls_strerror

const char* gnutls_strerror ( int error )

Arguments

int error: is an error returned by a gnutls function. Error is always a negative value.

Description

This function is similar to strerror(). The only difference is that it accepts an error (number) returned by a gnutls function.

gnutls_mac_get_name

const char * gnutls_mac_get_name ( MACAlgorithm algorithm )

Arguments

MACAlgorithm algorithm: is a MAC algorithm

Description

Returns a string that contains the name of the specified MAC algorithm.

gnutls_compression_get_name

const char * gnutls_compression_get_name ( CompressionMethod algorithm )

Arguments

CompressionMethod algorithm: is a Compression algorithm

Description

Returns a pointer to a string that contains the name of the specified compression algorithm.

gnutls_cipher_get_name

const char * gnutls_cipher_get_name ( BulkCipherAlgorithm algorithm )

Arguments

BulkCipherAlgorithm algorithm: is an encryption algorithm

Description

Returns a pointer to a string that contains the name of the specified cipher.

gnutls_kx_get_name

const char * gnutls_kx_get_name ( KXAlgorithm algorithm )

Arguments

KXAlgorithm algorithm: is a key exchange algorithm

Description

Returns a pointer to a string that contains the name of the specified key exchange algorithm.

gnutls_protocol_get_name

const char * gnutls_protocol_get_name ( GNUTLS_Version version )

Arguments

GNUTLS_Version version: is a (gnutls) version number

Description

Returns a string that contains the name of the specified TLS version.

gnutls_cipher_set_priority

int gnutls_cipher_set_priority ( GNUTLS_STATE state , GNUTLS_LIST list )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
GNUTLS_LIST list: is a 0 terminated list of BulkCipherAlgorithm elements.

Description

Sets the priority on the ciphers supported by gnutls. Priority is higher for ciphers specified before others. After specifying the ciphers you want, you should add 0. Note that the priority is set on the client. The server does not use the algorithm's priority except for disabling algorithms that were not specified.

gnutls_kx_set_priority

int gnutls_kx_set_priority ( GNUTLS_STATE state , GNUTLS_LIST list )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
GNUTLS_LIST list: is a 0 terminated list of KXAlgorithm elements.

Description

Sets the priority on the key exchange algorithms supported by gnutls. Priority is higher for algorithms specified before others. After specifying the algorithms you want, you should add 0. Note that the priority is set on the client. The server does not use the algorithm's priority except for disabling algorithms that were not specified.

gnutls_mac_set_priority

int gnutls_mac_set_priority ( GNUTLS_STATE state , GNUTLS_LIST list )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
GNUTLS_LIST list: is a 0 terminated list of MACAlgorithm elements.

Description

Sets the priority on the mac algorithms supported by gnutls. Priority is higher for algorithms specified before others. After specifying the algorithms you want, you should add 0. Note that the priority is set on the client. The server does not use the algorithm's priority except for disabling algorithms that were not specified.

gnutls_compression_set_priority

int gnutls_compression_set_priority ( GNUTLS_STATE state , GNUTLS_LIST list )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
GNUTLS_LIST list: is a 0 terminated list of CompressionMethod elements.

Description

Sets the priority on the compression algorithms supported by gnutls. Priority is higher for algorithms specified before others. After specifying the algorithms you want, you should add 0. Note that the priority is set on the client. The server does not use the algorithm's priority except for disabling algorithms that were not specified.

gnutls_protocol_set_priority

int gnutls_protocol_set_priority ( GNUTLS_STATE state , GNUTLS_LIST list )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
GNUTLS_LIST list: is a 0 terminated list of GNUTLS_Version elements.

Description

Sets the priority on the protocol versions supported by gnutls. Priority is higher for protocols specified before others. After specifying the protocols you want, you should add 0. Note that the priority is set on the client. The server does not use the protocols's priority except for disabling protocols that were not specified.

gnutls_session_get_data

int gnutls_session_get_data ( GNUTLS_STATE state , opaque* session , int * session_size )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
opaque* session: is a pointer to space to hold the session.
int * session_size: is the session's size, or it will be set by the function.

Description

Returns all session parameters - in order to support resuming. The client should call this - and keep the returned session - if he wants to resume that current version later by calling gnutls_session_set_data() This function must be called after a successful handshake.

Resuming sessions is really useful and speedups connections after a succesful one.

gnutls_session_get_id

int gnutls_session_get_id ( GNUTLS_STATE state , void* session , int * session_size )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
void* session: is a pointer to space to hold the session id.
int * session_size: is the session id's size, or it will be set by the function.

Description

Returns the current session id. This can be used if you want to check if the next session you tried to resume was actually resumed. This is because resumed sessions have the same sessionID with the original session.

Session id is some data set by the server, that identify the current session. In TLS 1.0 session id should not be more than 32 bytes.

gnutls_session_set_data

int gnutls_session_set_data ( GNUTLS_STATE state , opaque* session , int session_size )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
opaque* session: is a pointer to space to hold the session.
int session_size: is the session's size

Description

Sets all session parameters - in order to support resuming session 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.

gnutls_db_set_retrieve_function

void gnutls_db_set_retrieve_function ( GNUTLS_STATE state , DB_RETR_FUNC retr_func )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
DB_RETR_FUNC retr_func: is the function.

Description

Sets the function that will be used to retrieve data from the resumed sessions database. This function must return a gnutls_datum containing the data on success, or a gnutls_datum containing null and 0 on failure. This function should only be used if you do not plan to use the included gdbm backend.

The first argument to store_func() will be null unless gnutls_db_set_ptr() has been called.

gnutls_db_set_remove_function

void gnutls_db_set_remove_function ( GNUTLS_STATE state , DB_REMOVE_FUNC rem_func )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
DB_REMOVE_FUNC rem_func: is the function.

Description

Sets the function that will be used to remove data from the resumed sessions database. This function must return 0 on success. This function should only be used if you do not plan to use the included gdbm backend.

The first argument to rem_func() will be null unless gnutls_db_set_ptr() has been called.

gnutls_db_set_store_function

void gnutls_db_set_store_function ( GNUTLS_STATE state , DB_STORE_FUNC store_func )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
DB_STORE_FUNC store_func: is the function

Description

Sets the function that will be used to store data from the resumed sessions database. This function must remove 0 on success. This function should only be used if you do not plan to use the included gdbm backend.

The first argument to store_func() will be null unless gnutls_db_set_ptr() has been called.

gnutls_db_set_ptr

void gnutls_db_set_ptr ( GNUTLS_STATE state , void* ptr )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
void* ptr: is the pointer

Description

Sets the pointer that will be sent to db store, retrieve and delete functions, as the first argument. Should only be called if not using the gdbm backend.

gnutls_db_get_ptr

void* gnutls_db_get_ptr ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

Returns the pointer that will be sent to db store, retrieve and delete functions, as the first argument. Should only be used if not using the default (gdbm) backend.

gnutls_db_set_cache_expiration

void gnutls_db_set_cache_expiration ( GNUTLS_STATE state , int seconds )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
int seconds: is the number of seconds.

Description

Sets the expiration time for resumed sessions. The default is 3600 (one hour) at the time writing this.

gnutls_db_set_name

int gnutls_db_set_name ( GNUTLS_STATE state , char* filename )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
char* filename: is the filename for the database

Description

Sets the name of the (gdbm) database to be used to keep the sessions to be resumed. This function also creates the database - if it does not exist - and opens it for reading. You should not call this function if using an other backend than gdbm (ie. called function gnutls_db_set_store_func() etc.)

gnutls_db_check_entry

int gnutls_db_check_entry ( GNUTLS_STATE state , gnutls_datum session_entry )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
gnutls_datum session_entry: is the session data (not key)

Description

This function should only be used if not using the gdbm backend. This function returns GNUTLS_E_EXPIRED, if the database entry has expired or 0 otherwise. This function is to be used when you want to clear unnesessary session which occupy space in your backend.

gnutls_db_clean

int gnutls_db_clean ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

This function Deletes all expired records in the resumed sessions' database. This database may become huge if this function is not called. This function is also quite expensive. This function should only be called if using the gdbm backend.

gnutls_b64_encode_fmt

int gnutls_b64_encode_fmt ( const char* msg , const gnutls_datum * data , char* result , int* result_size )

Arguments

const char* msg: is a message to be put in the header
const gnutls_datum * data: contain the raw data
char* result: the place where base64 data will be copied
int* result_size: holds the size of the result

Description

This function will convert the given data to printable data, using the base64 encoding. This is the encoding used in PEM messages.

gnutls_b64_decode_fmt

int gnutls_b64_decode_fmt ( const gnutls_datum * b64_data , char* result , int* result_size )

Arguments

const gnutls_datum * b64_data: contain the encoded data
char* result: the place where decoded data will be copied
int* result_size: holds the size of the result

Description

This function will decode the given encoded data.

gnutls_cred_set

int gnutls_cred_set ( GNUTLS_STATE state , CredType type , void* cred )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
CredType type: is the type of the credentials
void* cred: is a pointer to a structure.

Description

Sets the needed credentials for the specified type. Eg username, password - or public and private keys etc. The (void* cred) parameter is a structure that depends on the specified type and on the current state (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_ANON cred should be ANON_CLIENT_CREDENTIALS in case of a client. In case of a server it should be ANON_SERVER_CREDENTIALS.

For GNUTLS_SRP cred should be SRP_CLIENT_CREDENTIALS in case of a client, and SRP_SERVER_CREDENTIALS, in case of a server.

For GNUTLS_X509PKI cred should be X509PKI_CLIENT_CREDENTIALS in case of a client, and X509PKI_SERVER_CREDENTIALS, in case of a server.

gnutls_auth_get_type

CredType gnutls_auth_get_type ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.

Description

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 X509PKI ciphersuites (key exchange algorithms: KX_RSA, KX_DHE_RSA), the same function are to be used to access the authentication data.

gnutls_srp_free_client_sc

void gnutls_srp_free_client_sc ( GNUTLS_SRP_CLIENT_CREDENTIALS sc )

Arguments

GNUTLS_SRP_CLIENT_CREDENTIALS sc: is an GNUTLS_SRP_CLIENT_CREDENTIALS structure.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) the structure.

gnutls_srp_allocate_client_sc

int gnutls_srp_allocate_client_sc ( GNUTLS_SRP_CLIENT_CREDENTIALS * sc )

Arguments

GNUTLS_SRP_CLIENT_CREDENTIALS * sc: is a pointer to an GNUTLS_SRP_CLIENT_CREDENTIALS structure.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate the structure.

gnutls_srp_set_client_cred

int gnutls_srp_set_client_cred ( GNUTLS_SRP_CLIENT_CREDENTIALS res , char * username , char * password )

Arguments

GNUTLS_SRP_CLIENT_CREDENTIALS res: is an GNUTLS_SRP_CLIENT_CREDENTIALS structure.
char * username: is the user's userid
char * password: is the user's password

gnutls_srp_free_server_sc

void gnutls_srp_free_server_sc ( GNUTLS_SRP_SERVER_CREDENTIALS sc )

Arguments

GNUTLS_SRP_SERVER_CREDENTIALS sc: is an GNUTLS_SRP_SERVER_CREDENTIALS structure.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) the structure.

gnutls_srp_allocate_server_sc

int gnutls_srp_allocate_server_sc ( GNUTLS_SRP_SERVER_CREDENTIALS * sc )

Arguments

GNUTLS_SRP_SERVER_CREDENTIALS * sc: is a pointer to an GNUTLS_SRP_SERVER_CREDENTIALS structure.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate the structure.

gnutls_srp_set_server_cred_file

int gnutls_srp_set_server_cred_file ( GNUTLS_SRP_SERVER_CREDENTIALS res , char * password_file , char * password_conf_file )

Arguments

GNUTLS_SRP_SERVER_CREDENTIALS res: is an GNUTLS_SRP_SERVER_CREDENTIALS structure.
char * password_file: is the SRP password file (tpasswd)
char * password_conf_file: is the SRP password conf file (tpasswd.conf)

gnutls_x509pki_free_sc

void gnutls_x509pki_free_sc ( GNUTLS_X509PKI_CREDENTIALS sc )

Arguments

GNUTLS_X509PKI_CREDENTIALS sc: is an GNUTLS_X509PKI_CREDENTIALS structure.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) the structure.

gnutls_x509pki_allocate_sc

int gnutls_x509pki_allocate_sc ( GNUTLS_X509PKI_CREDENTIALS * res , int ncerts )

Arguments

GNUTLS_X509PKI_CREDENTIALS * res: is a pointer to an GNUTLS_X509PKI_CREDENTIALS structure.
int ncerts: this is the number of certificate/private key pair you're going to use. This should be 1 in common sites.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate the structure.

gnutls_x509pki_set_key_file

int gnutls_x509pki_set_key_file ( GNUTLS_X509PKI_CREDENTIALS res , char * CERTFILE , char * KEYFILE )

Arguments

GNUTLS_X509PKI_CREDENTIALS res: is an GNUTLS_X509PKI_CREDENTIALS structure.
char * CERTFILE: is a PEM encoded file containing the certificate list (path) for the specified private key
char * KEYFILE: is a PEM encoded file containing a private key

Description

This function sets a certificate/private key pair in the GNUTLS_X509PKI_CREDENTIALS structure. This function may be called more than once (in case multiple keys/certificates exist for the server).

Currently only PKCS-1 PEM encoded RSA private keys are accepted by this function.

gnutls_x509pki_set_trust_file

int gnutls_x509pki_set_trust_file ( GNUTLS_X509PKI_CREDENTIALS res , char * CAFILE , char * CRLFILE )

Arguments

GNUTLS_X509PKI_CREDENTIALS res: is an GNUTLS_X509PKI_CREDENTIALS structure.
char * CAFILE: is a PEM encoded file containing trusted CAs
char * CRLFILE: is a PEM encoded file containing CRLs (ignored for now)

Description

This function sets the trusted CAs in order to verify client certificates.

gnutls_x509pki_set_dh_bits

void gnutls_x509pki_set_dh_bits ( GNUTLS_STATE state , int bits )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
int bits: is the number of bits

Description

This function sets the number of bits, for use in a Diffie Hellman key exchange. This value will only be used in case of DHE ciphersuite.

gnutls_x509pki_server_set_cert_request

void gnutls_x509pki_server_set_cert_request ( GNUTLS_STATE state , CertificateRequest req )

Arguments

GNUTLS_STATE state: is an GNUTLS_STATE structure.
CertificateRequest req: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE

Description

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 an error if the peer does not provide a certificate. If you do not call this function then the client will not be asked to send a certificate.

gnutls_x509pki_set_client_cert_callback

void gnutls_x509pki_set_client_cert_callback ( GNUTLS_STATE state , x509pki_client_cert_callback_func * func )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
x509pki_client_cert_callback_func * func: is the callback function

Description

The callback's function form is: int (*callback)(GNUTLS_STATE, gnutls_datum *client_cert, int ncerts, gnutls_datum* req_ca_cert, int nreqs);

'client_cert' contains 'ncerts' gnutls_datum structures which hold the DER encoded X.509 certificates of the client.

'req_ca_cert' contains a list with the CA names that the server considers trusted. Normaly we should send a certificate that is signed by one of these CAs. These names are DER encoded. To get a more meaningful value use the function gnutls_x509pki_extract_dn().

This function specifies what we, in case of a client, are going to do when we have to send a certificate. If this callback function is not provided then gnutls will automaticaly try to find an appropriate certificate to send.

If the callback function is provided then gnutls will call it once with NULL parameters. If the callback function returns a positive or zero number then gnutls will attempt to automaticaly choose the appropriate certificate. If gnutls fails to find an appropriate certificate, then it will call the callback function again with the appropriate parameters.

In case the callback returned a negative number then gnutls will not attempt to choose the appropriate certificate and will call again the callback function with the appropriate parameters, and rely only to the return value of the callback function.

The callback function should return the index of the certificate choosen by the user. -1 indicates that the user does not want to use client authentication.

This function returns 0 on success.

gnutls_x509pki_set_server_cert_callback

void gnutls_x509pki_set_server_cert_callback ( GNUTLS_STATE state , x509pki_server_cert_callback_func * func )

Arguments

GNUTLS_STATE state: is a GNUTLS_STATE structure.
x509pki_server_cert_callback_func * func: is the callback function

Description

The callback's function form is: int (*callback)(GNUTLS_STATE, gnutls_datum *server_cert, int ncerts);

'server_cert' contains 'ncerts' gnutls_datum structures which hold the DER encoded X.509 certificates of the server.

This function specifies what we, in case of a server, are going to do when we have to send a certificate. If this callback function is not provided then gnutls will automaticaly try to find an appropriate certificate to send. (actually send the first in the list)

In case the callback returned a negative number then gnutls will not attempt to choose the appropriate certificate and the caller function will fail.

The callback function will only be called once per handshake. The callback function should return the index of the certificate choosen by the server. -1 indicates an error.

gnutls_global_set_log_func

void gnutls_global_set_log_func ( LOG_FUNC log_func )

Arguments

LOG_FUNC log_func: it's a log function

Description

This is the function were you set the logging function gnutls is going to use. This function only accepts a character array. Normaly you may not use this function since it is only used for debugging reasons. LOG_FUNC is of the form, void (*LOG_FUNC)( const char*);

gnutls_global_init

int gnutls_global_init ( void )

Arguments

void:

Description

This function initializes the global state to defaults. Every gnutls application has a global state which holds common parameters shared by gnutls state structures. You must call gnutls_global_deinit() when gnutls usage is no longer needed Returns zero on success.

gnutls_global_deinit

void gnutls_global_deinit ( void )

Arguments

void:

Description

This function deinitializes the global state.

gnutls_transport_set_pull_func

void gnutls_transport_set_pull_func ( GNUTLS_STATE state , PULL_FUNC pull_func )

Arguments

GNUTLS_STATE state: gnutls state
PULL_FUNC pull_func: it's a function like read

Description

This is the function where you set a function for gnutls to receive data. Normaly, if you use berkeley style sockets, you may not use this function since the default (recv(2)) will probably be ok. This function should be called once and after gnutls_global_init(). PULL_FUNC is of the form, ssize_t (*PULL_FUNC)(GNUTLS_SOCKET_PTR, const void*, size_t);

gnutls_transport_set_push_func

void gnutls_transport_set_push_func ( GNUTLS_STATE state , PUSH_FUNC push_func )

Arguments

GNUTLS_STATE state: gnutls state
PUSH_FUNC push_func: it's a function like write

Description

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

This function should be called once and after gnutls_global_init(). PUSH_FUNC is of the form, ssize_t (*PUSH_FUNC)(GNUTLS_SOCKET_PTR, const void*, size_t);

gnutls_anon_free_server_sc

void gnutls_anon_free_server_sc ( GNUTLS_ANON_SERVER_CREDENTIALS sc )

Arguments

GNUTLS_ANON_SERVER_CREDENTIALS sc: is an GNUTLS_ANON_SERVER_CREDENTIALS structure.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) the structure.

gnutls_anon_allocate_server_sc

int gnutls_anon_allocate_server_sc ( GNUTLS_ANON_SERVER_CREDENTIALS * sc )

Arguments

GNUTLS_ANON_SERVER_CREDENTIALS * sc: is a pointer to an GNUTLS_ANON_SERVER_CREDENTIALS structure.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate the structure.

gnutls_anon_set_server_cred

int gnutls_anon_set_server_cred ( GNUTLS_ANON_SERVER_CREDENTIALS res , int dh_bits )

Arguments

GNUTLS_ANON_SERVER_CREDENTIALS res: is an GNUTLS_ANON_SERVER_CREDENTIALS structure.
int dh_bits: is the number of bits in DH key exchange

Description

Used to set the number of bits to use in an anonymous Diffie-Hellman, key exchange.

gnutls_anon_free_client_sc

void gnutls_anon_free_client_sc ( GNUTLS_ANON_CLIENT_CREDENTIALS sc )

Arguments

GNUTLS_ANON_CLIENT_CREDENTIALS sc: is an GNUTLS_ANON_CLIENT_CREDENTIALS structure.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) the structure.

gnutls_anon_allocate_client_sc

int gnutls_anon_allocate_client_sc ( GNUTLS_ANON_CLIENT_CREDENTIALS * sc )

Arguments

GNUTLS_ANON_CLIENT_CREDENTIALS * sc: is a pointer to an GNUTLS_ANON_CLIENT_CREDENTIALS structure.

Description

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate the structure.

gnutls_x509pki_extract_dn

int gnutls_x509pki_extract_dn ( const gnutls_datum * idn , gnutls_DN * rdn )

Arguments

const gnutls_datum * idn: should contain a DER encoded RDN sequence
gnutls_DN * rdn: a pointer to a structure to hold the name

Description

This function will return the name of the given RDN sequence. The name will be returned as a gnutls_DN structure. Returns a negative error code in case of an error.

gnutls_x509pki_extract_certificate_dn

int gnutls_x509pki_extract_certificate_dn ( const gnutls_datum * cert , gnutls_DN * ret )

Arguments

const gnutls_datum * cert: should contain an X.509 DER encoded certificate
gnutls_DN * ret: a pointer to a structure to hold the peer's name

Description

This function will return the name of the certificate holder. The name is gnutls_DN structure and is a obtained by the peer's certificate. If the certificate send by the peer is invalid, or in any other failure this function returns error. Returns a negative error code in case of an error.

gnutls_x509pki_extract_certificate_issuer_dn

int gnutls_x509pki_extract_certificate_issuer_dn ( const gnutls_datum * cert , gnutls_DN * ret )

Arguments

const gnutls_datum * cert: should contain an X.509 DER encoded certificate
gnutls_DN * ret: a pointer to a structure to hold the issuer's name

Description

This function will return the name of the issuer stated in the certificate. The name is a gnutls_DN structure and is a obtained by the peer's certificate. If the certificate send by the peer is invalid, or in any other failure this function returns error. Returns a negative error code in case of an error.

gnutls_x509pki_extract_subject_dns_name

int gnutls_x509pki_extract_subject_dns_name ( const gnutls_datum * cert , char * ret , int * ret_size )

Arguments

const gnutls_datum * cert: should contain an X.509 DER encoded certificate
char * ret: is the place where dns name will be copied to
int * ret_size: holds the size of ret.

Description

This function will return the alternative name (the dns part of it), contained in the given certificate.

This is specified in X509v3 Certificate Extensions. GNUTLS will only return the dnsName of the Alternative name, or a negative error code. Returns GNUTLS_E_MEMORY_ERROR if ret_size is not enough to hold dns name, or the size of dns name if everything was ok.

If the certificate does not have a DNS name then returns GNUTLS_E_DATA_NOT_AVAILABLE;

gnutls_x509pki_extract_certificate_activation_time

time_t gnutls_x509pki_extract_certificate_activation_time ( const gnutls_datum * cert )

Arguments

const gnutls_datum * cert: should contain an X.509 DER encoded certificate

Description

This function will return the certificate's activation time in UNIX time (ie seconds since 00:00:00 UTC January 1, 1970). Returns a (time_t) -1 in case of an error.

gnutls_x509pki_extract_certificate_expiration_time

time_t gnutls_x509pki_extract_certificate_expiration_time ( const gnutls_datum * cert )

Arguments

const gnutls_datum * cert: should contain an X.509 DER encoded certificate

Description

This function will return the certificate's expiration time in UNIX time (ie seconds since 00:00:00 UTC January 1, 1970). Returns a (time_t) -1 in case of an error.

gnutls_x509pki_extract_certificate_version

int gnutls_x509pki_extract_certificate_version ( const gnutls_datum * cert )

Arguments

const gnutls_datum * cert: is an X.509 DER encoded certificate

Description

This function will return the X.509 certificate's version (1, 2, 3). This is obtained by the X509 Certificate Version field. Returns a negative value in case of an error.

gnutls_x509pki_get_peer_certificate_status

int gnutls_x509pki_get_peer_certificate_status ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a gnutls state

Description

This function will try to verify the peer's certificate and return it's status (TRUSTED, EXPIRED etc.). The return value (status) should be one of the CertificateStatus enumerated elements. However you must also check the peer's name in order to check if the verified certificate belongs to the actual peer. Returns a negative error code in case of an error, or GNUTLS_CERT_NONE if no certificate was sent.

gnutls_x509pki_extract_certificate_serial

int gnutls_x509pki_extract_certificate_serial ( const gnutls_datum * cert , char* result , int* result_size )

Arguments

const gnutls_datum * cert: is an X.509 DER encoded certificate
char* result: The place where the serial number will be copied
int* result_size: Holds the size of the result field.

Description

This function will return the X.509 certificate's serial number. This is obtained by the X509 Certificate serialNumber field. Serial is not always a 32 or 64bit number. Some CAs use large serial numbers, thus it may be wise to handle it as something opaque. Returns a negative value in case of an error.

gnutls_x509pki_verify_certificate

int gnutls_x509pki_verify_certificate ( const gnutls_datum* cert_list , int cert_list_length , const gnutls_datum * CA_list , int CA_list_length , const gnutls_datum* CRL_list , int CRL_list_length )

Arguments

const gnutls_datum* cert_list: is the certificate list to be verified
int cert_list_length: holds the number of certificate in cert_list
const gnutls_datum * CA_list: is the CA list which will be used in verification
int CA_list_length: holds the number of CA certificate in CA_list
const gnutls_datum* CRL_list: not used
int CRL_list_length: not used

Description

This function will try to verify the given certificate list and return it's status (TRUSTED, EXPIRED etc.). The return value (status) should be one of the CertificateStatus enumerated elements. However you must also check the peer's name in order to check if the verified certificate belongs to the actual peer. Returns a negative error code in case of an error.

gnutls_srp_server_get_username

const char * gnutls_srp_server_get_username ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a gnutls state

Description

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.

gnutls_anon_server_get_dh_bits

int gnutls_anon_server_get_dh_bits ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a gnutls state

Description

This function will return the bits used in the Diffie Hellman authentication with the peer. This should only be called in case of a server. Returns a negative value in case of an error.

gnutls_anon_client_get_dh_bits

int gnutls_anon_client_get_dh_bits ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a gnutls state

Description

This function will return the bits used in the Diffie Hellman authentication with the peer. This should only be called in case of a client. Returns a negative value in case of an error.

gnutls_x509pki_get_peer_certificate_list

const gnutls_datum * gnutls_x509pki_get_peer_certificate_list ( GNUTLS_STATE state , int * list_size )

Arguments

GNUTLS_STATE state: is a gnutls state
int * list_size: is the length of the certificate list

Description

This function will return the peer's raw certificate list as sent by the peer. These certificates are DER encoded. The first certificate in the list is the peer's certificate, following the issuer's certificate, then the issuer's issuer etc. Returns NULL in case of an error, or if no certificate was sent.

gnutls_x509pki_get_dh_bits

int gnutls_x509pki_get_dh_bits ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a gnutls state

Description

This function will return the number of bits used in a Diffie Hellman Handshake. This will only occur in case of DHE_* ciphersuites. The return value may be zero if no applicable ciphersuite was used. Returns a negative value in case of an error.

gnutls_x509pki_get_certificate_request_status

int gnutls_x509pki_get_certificate_request_status ( GNUTLS_STATE state )

Arguments

GNUTLS_STATE state: is a gnutls state

Description

This function will return 0 if the peer (server) did not request client authentication or 1 otherwise. Returns a negative value in case of an error.

gnutls_fingerprint

int gnutls_fingerprint ( DigestAlgorithm algo , const gnutls_datum* data , char* result , int* result_size )

Arguments

DigestAlgorithm algo: is a digest algorithm
const gnutls_datum* data: is the data
char* result: is the place where the result will be copied.
int* result_size: should hold the size of the result. The actual size of the returned result will also be copied there.

Description

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. Returns a negative value in case of an error.

gnutls_dh_replace_params

int gnutls_dh_replace_params ( gnutls_datum prime , gnutls_datum generator , int bits )

Arguments

gnutls_datum prime: holds the new prime
gnutls_datum generator: holds the new generator
int bits: is the prime's number of bits

Description

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. This function should not be called while a key exchange is in progress.

Note that the bits value should be one of 1024, 2048, 3072 or 4096.

gnutls_dh_generate_params

int gnutls_dh_generate_params ( gnutls_datum* prime , gnutls_datum* generator , int bits )

Arguments

gnutls_datum* prime: will hold the new prime
gnutls_datum* generator: will hold the new generator
int bits: is the prime's number of bits

Description

This function will generate a new pair of prime and generator for use in the Diffie-Hellman key exchange. The new parameters will be stored in the appropriate gnutls_datum. This function is normally very slow. An other function (gnutls_dh_replace_params()) should be called in order to replace the included DH primes in the gnutls library.

Note that the bits value should be one of 1024, 2048, 3072 or 4096. Also note that the generation of new DH parameters is only usefull to servers. Clients use the parameters sent by the server, thus it's no use calling this in client side.

gnutls_alert_send

int gnutls_alert_send ( GNUTLS_STATE state , AlertLevel level , AlertDescription desc )

Arguments

GNUTLS_STATE stat