GNU TLS 2.5.2

GNU TLS
1 Preface
2 The Library
3 Introduction to TLS
4 Authentication Methods
5 More on Certificate Authentication
6 How To Use TLS in Application Protocols
- 6.1 Separate Ports
- 6.2 Upward Negotiation
7 How To Use GnuTLS in Applications
8 Included Programs
9 Function Reference
10 All the Supported Ciphersuites in GnuTLS
11 Guile Bindings
12 Internal Architecture of GnuTLS
Appendix A Copying Information
Bibliography
Function and Data Index
Concept Index

GNU TLS

1 Preface

This document tries to demonstrate and explain the GnuTLS library API. A brief introduction to the protocols and the technology involved, is also included so that an application programmer can better understand the GnuTLS purpose and actual offerings. Even if GnuTLS is a typical library software, it operates over several security and cryptographic protocols, which require the programmer to make careful and correct usage of them, otherwise he risks to offer just a false sense of security. Security and the network security terms are very general terms even for computer software thus cannot be easily restricted to a single cryptographic library. For that reason, do not consider a program secure just because it uses GnuTLS; there are several ways to compromise a program or a communication line and GnuTLS only helps with some of them.

Although this document tries to be self contained, basic network programming and PKI knowlegde is assumed in most of it. A good introduction to networking can be found in [STEVENS] (see Bibliography) and for Public Key Infrastructure in [GUTPKI] (see Bibliography).

1.1 Getting Help

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

1.2 Commercial Support

Commercial support is available for users of GnuTLS. The kind of support that can be purchased may include:

If your company provide support related to GnuTLS and would like to be mentioned here, contact the author (see Bug Reports).

1.3 Downloading and Installing

The latest version is stored in a file, e.g., ‘gnutls-2.5.2.tar.gz’ where the ‘2.5.2’ value is the highest version number in the directory.

GnuTLS uses a Linux-like development cycle: even minor version numbers indicate a stable release and a odd minor version number indicates a development release. For example, GnuTLS 1.6.3 denote a stable release since 6 is even, and GnuTLS 1.7.11 denote a development release since 7 is odd.

GnuTLS depends on Libgcrypt, and you will need to install Libgcrypt before installing GnuTLS. Libgcrypt is available from ftp://ftp.gnupg.org/gcrypt/libgcrypt. Libgcrypt needs another library, libgpg-error, and you need to install libgpg-error before installing Libgcrypt. Libgpg-error is available from ftp://ftp.gnupg.org/gcrypt/libgpg-error.

Don't forget to verify the cryptographic signature after downloading source code packages.

The package is then extracted, configured and built like many other packages that use Autoconf. For detailed information on configuring and building it, refer to the INSTALL file that is part of the distribution archive. Typically you invoke ./configure and then make check install. There are a number of compile-time parameters, as discussed below.

The X.509 part of GnuTLS needs ASN.1 functionality, from a library called libtasn1. A copy of libtasn1 is included in GnuTLS. If you want to install it separately (e.g., to make it possibly to use libtasn1 in other programs), you can get it from http://www.gnu.org/software/gnutls/download.html.

The OpenPGP part of GnuTLS uses a stripped down version of OpenCDK for parsing OpenPGP packets. It is included GnuTLS. Use parameter --disable-openpgp-authentication to disable the OpenPGP functionality in GnuTLS. Unfortunately, we didn't have resources to maintain the code in a separate library.

Regarding the Guile bindings, there are additional installation considerations, see See Guile Preparations.

1.4 Bug Reports

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

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.

1.5 Contributing

If you want to submit a patch for inclusion – from solve a typo you discovered, up to adding support for a new feature – you should submit it as a bug report (see 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. Use it.

2 The Library

In brief GnuTLS can be described as a library which offers an API to access secure communication protocols. These protocols provide privacy over insecure lines, and were designed to prevent eavesdropping, tampering, or message forgery.

Technically GnuTLS is a portable ANSI C based library which implements the TLS 1.1 and SSL 3.0 protocols (See Introduction to TLS, for a more detailed description of the protocols), accompanied with the required framework for authentication and public key infrastructure. The library is available under the GNU Lesser GPL license¹. Important features of the GnuTLS library include:

Additionally GnuTLS provides a limited emulation API for the widely used OpenSSL² library, to ease integration with existing applications.

GnuTLS consists of three independent parts, namely the “TLS protocol part”, the “Certificate part”, and the “Cryptographic backend” part. The `TLS protocol part' is the actual protocol implementation, and is entirely implemented within the GnuTLS library. The `Certificate part' consists of the certificate parsing, and verification functions which is partially implemented in the GnuTLS library. The Libtasn1³, a library which offers ASN.1 parsing capabilities, is used for the X.509 certificate parsing functions. A smaller version of OpenCDK⁴ is used for the OpenPGP key support in GnuTLS. The “Cryptographic backend” is provided by the Libgcrypt⁵ library⁶.

In order to ease integration in embedded systems, parts of the GnuTLS library can be disabled at compile time. That way a small library, with the required features, can be generated.

2.1 General Idea

A brief description of how GnuTLS works internally is shown at the figure below. This section may be easier to understand after having seen the examples (see examples).

As shown in the figure, there is a read-only global state that is initialized once by the global initialization function. This global structure, among others, contains the memory allocation functions used, and some structures needed for the ASN.1 parser. This structure is never modified by any GnuTLS function, except for the deinitialization function which frees all memory allocated in the global structure and is called after the program has permanently finished using GnuTLS.

The credentials structure is used by some authentication methods, such as certificate authentication (see Certificate Authentication). A credentials structure may contain certificates, private keys, temporary parameters for diffie hellman or RSA key exchange, and other stuff that may be shared between several TLS sessions.

This structure should be initialized using the appropriate initialization functions. For example an application which uses certificate authentication would probably initialize the credentials, using the appropriate functions, and put its trusted certificates in this structure. The next step is to associate the credentials structure with each TLS session.

A GnuTLS session contains all the required stuff for a session to handle one secure connection. This session calls directly to the transport layer functions, in order to communicate with the peer. Every session has a unique session ID shared with the peer.

Since TLS sessions can be resumed, servers would probably need a database backend to hold the session's parameters. Every GnuTLS session after a successful handshake calls the appropriate backend function (See resume, for information on initialization) to store the newly negotiated session. The session database is examined by the server just after having received the client hello⁷, and if the session ID sent by the client, matches a stored session, the stored session will be retrieved, and the new session will be a resumed one, and will share the same session ID with the previous one.

2.2 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 and receives will be disallowed. An example of a fatal error code is GNUTLS_E_DECRYPTION_FAILED. Non-fatal errors may warn about something, i.e., a warning alert was received, or indicate the some action has to be taken. This is the case with the error code GNUTLS_E_REHANDSHAKE returned by gnutls_record_recv. This error code indicates that the server requests a re-handshake. The client may ignore this request, or may reply with an alert. You can test if an error code is a fatal one by using the gnutls_error_is_fatal.

If any non fatal errors, that require an action, are to be returned by a function, these error codes will be documented in the function's reference. See Error Codes, for all the error codes.

2.3 Memory Handling

GnuTLS internally handles heap allocated objects differently, depending on the sensitivity of the data they contain. However for performance reasons, the default memory functions do not overwrite sensitive data from memory, nor protect such objects from being written to the swap. In order to change the default behavior the gnutls_global_set_mem_functions function is available which can be used to set other memory handlers than the defaults.

The Libgcrypt library on which GnuTLS depends, has such secure memory allocation functions available. These should be used in cases where even the system's swap memory is not considered secure. See the documentation of Libgcrypt for more information.

2.4 Callback Functions

There are several cases where GnuTLS may need some out of band input from your program. This is now implemented using some callback functions, which your program is expected to register.

An example of this type of functions are the push and pull callbacks which are used to specify the functions that will retrieve and send data to the transport layer.

Other callback functions such as the one set by gnutls_srp_set_server_credentials_function, may require more complicated input, including data to be allocated. These callbacks should allocate and free memory using the functions shown below.

3 Introduction to TLS

TLS stands for “Transport Layer Security” and is the successor of SSL, the Secure Sockets Layer protocol [SSL3] (see Bibliography) designed by Netscape. TLS is an Internet protocol, defined by IETF⁸, described in RFC 4346 and also in [RESCORLA] (see Bibliography). The protocol provides confidentiality, and authentication layers over any reliable transport layer. The description, below, refers to TLS 1.0 but also applies to TLS 1.1 [RFC4346] (see Bibliography) and SSL 3.0, since the differences of these protocols are minor. Older protocols such as SSL 2.0 are not discussed nor implemented in GnuTLS since they are not considered secure today. GnuTLS also supports X.509 and OpenPGP [RFC4880] (see Bibliography).

3.1 TLS Layers

TLS is a layered protocol, and consists of the Record Protocol, the Handshake Protocol and the Alert Protocol. The Record Protocol is to serve all other protocols and is above the transport layer. The Record protocol offers symmetric encryption, data authenticity, and optionally compression.

The Alert protocol offers some signaling to the other protocols. It can help informing the peer for the cause of failures and other error conditions. See The Alert Protocol, for more information. The alert protocol is above the record protocol.

The Handshake protocol is responsible for the security parameters' negotiation, the initial key exchange and authentication. See The Handshake Protocol, for more information about the handshake protocol. The protocol layering in TLS is shown in the figure below.

3.2 The Transport Layer

TLS is not limited to one transport layer, it can be used above any transport layer, as long as it is a reliable one. A set of functions is provided and their purpose is to load to GnuTLS the required callbacks to access the transport layer.

These functions accept a callback function as a parameter. The callback functions should return the number of bytes written, or -1 on error and should set errno appropriately.

In some environments, setting errno is unreliable, for example Windows have several errno variables in different CRTs, or it may be that errno is not a thread-local variable. If this is a concern to you, call gnutls_transport_set_errno with the intended errno value instead of setting errno directly.

GnuTLS currently only interprets the EINTR and EAGAIN errno values and returns the corresponding GnuTLS error codes GNUTLS_E_INTERRUPTED and GNUTLS_E_AGAIN. These values are usually returned by interrupted system calls, or when non blocking IO is used. All GnuTLS functions can be resumed (called again), if any of these error codes is returned. The error codes above refer to the system call, not the GnuTLS function, since signals do not interrupt GnuTLS' functions.

For non blocking sockets or other custom made pull/push functions the gnutls_transport_set_lowat must be called, with a zero low water mark value.

By default, if the transport functions are not set, GnuTLS will use the Berkeley Sockets functions. In this case GnuTLS will use some hacks in order for select to work, thus making it easy to add TLS support to existing TCP/IP servers.

3.3 The TLS Record Protocol

The Record protocol is the secure communications provider. Its purpose is to encrypt, authenticate and —optionally— compress packets. The following functions are available:

As you may have already noticed, the functions which access the Record protocol, are quite limited, given the importance of this protocol in TLS. This is because the Record protocol's parameters are all set by the Handshake protocol.

The Record protocol initially starts with NULL parameters, which means no encryption, and no MAC is used. Encryption and authentication begin just after the handshake protocol has finished.

3.3.1 Encryption Algorithms Used in the Record Layer

Confidentiality in the record layer is achieved by using symmetric block encryption algorithms like 3DES, AES⁹, or stream algorithms like ARCFOUR_128¹⁰. 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. Thus, if you're using the TLS protocol, a random number of blocks will be appended to data, to prevent eavesdroppers from guessing the actual data size.

3.3.2 Compression Algorithms Used in the Record Layer

The TLS record layer also supports compression. The algorithms implemented in GnuTLS can be found in the table below. All the algorithms except for DEFLATE which is referenced in [RFC3749] (see Bibliography), should be considered as GnuTLS' extensions¹¹, and should be advertised only when the peer is known to have a compliant client, to avoid interoperability problems.

The included algorithms perform really good when text, or other compressible data are to be transfered, but offer nothing on already compressed data, such as compressed images, zipped archives etc. These compression algorithms, may be useful in high bandwidth TLS tunnels, and in cases where network usage has to be minimized. As a drawback, compression increases latency.

The record layer compression in GnuTLS is implemented based on the proposal [RFC3749] (see Bibliography). The supported compression algorithms are:

3.3.3 Weaknesses and Countermeasures

Some weaknesses that may affect the security of the Record layer have been found in TLS 1.0 protocol. These weaknesses can be exploited by active attackers, and exploit the facts that

Those weaknesses were solved in TLS 1.1 [RFC4346] (see Bibliography) which is implemented in GnuTLS. For a detailed discussion see the archives of the TLS Working Group mailing list and the paper [CBCATT] (see Bibliography).

3.4 The TLS Alert Protocol

The Alert protocol is there to allow signals to be sent between peers. These signals are mostly used to inform the peer about the cause of a protocol failure. Some of these signals are used internally by the protocol and the application protocol does not have to cope with them (see GNUTLS_A_CLOSE_NOTIFY), and others refer to the application protocol solely (see GNUTLS_A_USER_CANCELLED). An alert signal includes a level indication which may be either fatal or warning. Fatal alerts always terminate the current connection, and prevent future renegotiations using the current session ID.

The alert messages are protected by the record protocol, thus the information that is included does not leak. You must take extreme care for the alert information not to leak to a possible attacker, via public log files etc.

3.5 The TLS Handshake Protocol

The Handshake protocol is responsible for the ciphersuite negotiation, the initial key exchange, and the authentication of the two peers. This is fully controlled by the application layer, thus your program has to set up the required parameters. Available functions to control the handshake protocol include:

3.5.1 TLS Cipher Suites

The Handshake Protocol of TLS negotiates cipher suites of the form TLS_DHE_RSA_WITH_3DES_CBC_SHA. The usual cipher suites contain these parameters:

The cipher suite negotiated in the handshake protocol will affect the Record Protocol, by enabling encryption and data authentication. Note that you should not over rely on TLS to negotiate the strongest available cipher suite. Do not enable ciphers and algorithms that you consider weak.

The priority functions, dicussed above, allow the application layer to enable and set priorities on the individual ciphers. It may imply that all combinations of ciphersuites are allowed, but this is not true. For several reasons, not discussed here, some combinations were not defined in the TLS protocol. The supported ciphersuites are shown in ciphersuites.

3.5.2 Client Authentication

In the case of ciphersuites that use certificate authentication, the authentication of the client is optional in TLS. A server may request a certificate from the client — using the gnutls_certificate_server_set_request function. If a certificate is to be requested from the client during the handshake, the server will send a certificate request message that contains a list of acceptable certificate signers. In GnuTLS the certificate signers list is constructed using the trusted Certificate Authorities by the server. That is the ones set using

Sending of the names of the CAs can be controlled using gnutls_certificate_send_x509_rdn_sequence. The client, then, may send a certificate, signed by one of the server's acceptable signers.

3.5.3 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. This is achieved by using the previously established keys. GnuTLS supports this feature, and the example (see ex:resume-client) illustrates a typical use of it.

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.

3.5.4 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. I.e., copy and keep the necessary parameters. See the functions:

The server side is different. A server has to specify some callback functions which store, retrieve and delete session data. These can be registered with:

It might also be useful to be able to check for expired sessions in order to remove them, and save space. The function gnutls_db_check_entry is provided for that reason.

3.6 TLS Extensions

A number of extensions to the TLS protocol have been proposed mainly in [TLSEXT] (see Bibliography). The extensions supported in GnuTLS are:

3.6.1 Maximum Fragment Length Negotiation

This extension allows a TLS implementation to negotiate a smaller value for record packet maximum length. This extension may be useful to clients with constrained capabilities. See the gnutls_record_set_max_size and the gnutls_record_get_max_size functions.

3.6.2 Server Name Indication

A common problem in HTTPS servers is the fact that the TLS protocol is not aware of the hostname that a client connects to, when the handshake procedure begins. For that reason the TLS server has no way to know which certificate to send.

This extension solves that problem within the TLS protocol, and allows a client to send the HTTP hostname before the handshake begins within the first handshake packet. The functions gnutls_server_name_set and gnutls_server_name_get can be used to enable this extension, or to retrieve the name sent by a client.

3.7 Selecting Cryptographic Key Sizes

In TLS, since a lot of algorithms are involved, it is not easy to set a consistent security level. For this reason this section will present some correspondance between key sizes of symmetric algorithms and public key algorithms based on the most conservative values of [SELKEY] (see Bibliography). Those can be used to generate certificates with appropriate key sizes as well as parameters for Diffie Hellman and SRP authentication.

Year	Symmetric key size	RSA key size, DH and SRP prime size	ECC key size
1982	56	417	105
1988	61	566	114
2002	72	1028	139
2015	82	1613	173
2028	92	2362	210
2040	101	3214	244
2050	109	4047	272

The first column provides an estimation of the year until these parameters are considered safe and the rest of the columns list the parameters for the various algorithms.

Note however that the values suggested here are nothing more than an educated guess that is valid today. There are no guarrantees that an algorithm will remain unbreakable or that these values will remain constant in time. There could be scientific breakthroughs that cannot be predicted or total failure of the current public key systems by quantum computers. On the other hand though the cryptosystems used in TLS are selected in a conservative way and such catastrophic breakthroughs or failures are believed to be unlikely.

3.8 On SSL 2 and Older Protocols

One of the initial decisions in the GnuTLS development was to implement the known security protocols for the transport layer. Initially TLS 1.0 was implemented since it was the latest at that time, and was considered to be the most advanced in security properties. Later the SSL 3.0 protocol was implemented since it is still the only protocol supported by several servers and there are no serious security vulnerabilities known.

One question that may arise is why we didn't implement SSL 2.0 in the library. There are several reasons, most important being that it has serious security flaws, unacceptable for a modern security library. Other than that, this protocol is barely used by anyone these days since it has been deprecated since 1996. The security problems in SSL 2.0 include:

Other protocols such as Microsoft's PCT 1 and PCT 2 were not implemented because they were also abandoned and deprecated by SSL 3.0 and later TLS 1.0.

3.9 On Record Padding

The TLS protocol allows for random padding of records, to make it more difficult to perform analysis on the length of exchanged messages. (In RFC 4346 this is specified in section 6.2.3.2.) GnuTLS appears to be one of few implementation that take advantage of this text, and pad records by a random length.

The TLS implementation in the Symbian operating system, frequently used by Nokia and Sony-Ericsson mobile phones, cannot handle non-minimal record padding. What happens when one of these clients handshake with a GnuTLS server is that the client will fail to compute the correct MAC for the record. The client sends a TLS alert (bad_record_mac) and disconnects. Typically this will result in error messages such as 'A TLS fatal alert has been received', 'Bad record MAC', or both, on the GnuTLS server side.

GnuTLS implements a work around for this problem. However, it has to be enabled specifically. It can be enabled by using gnutls_record_disable_padding, or gnutls_priority_set with the %COMPAT priority string.

If you implement an application that have a configuration file, we recommend that you make it possible for users or administrators to specify a GnuTLS protocol priority string, which is used by your application via gnutls_priority_set. To allow the best flexibility, make it possible to have a different priority string for different incoming IP addresses.

To enable the workaround in the gnutls-cli client or the gnutls-serv server, for testing of other implementations, use the following parameter: --priority "%COMPAT".

This problem has been discussed on mailing lists and in bug reports. This section tries to collect all pieces of information that we know about the problem. If you wish to go back to the old discussions, here are some links:

4 Authentication Methods

The TLS protocol provides confidentiality and encryption, but also offers authentication, which is a prerequisite for a secure connection. The available authentication methods in GnuTLS are:

4.1 Certificate Authentication

4.1.1 Authentication Using X.509 Certificates

X.509 certificates contain the public parameters, of a public key algorithm, and an authority's signature, which proves the authenticity of the parameters. See The X.509 trust model, for more information on X.509 protocols.

4.1.2 Authentication Using OpenPGP Keys

OpenPGP keys also contain public parameters of a public key algorithm, and signatures from several other parties. Depending on whether a signer is trusted the key is considered trusted or not. GnuTLS's OpenPGP authentication implementation is based on the [TLSPGP] (see Bibliography) proposal.

See The OpenPGP trust model, for more information about the OpenPGP trust model. For a more detailed introduction to OpenPGP and GnuPG see [GPGH] (see Bibliography).

4.1.3 Using Certificate Authentication

In GnuTLS both the OpenPGP and X.509 certificates are part of the certificate authentication and thus are handled using a common API.

When using certificates the server is required to have at least one certificate and private key pair. A client may or may not have such a pair. The certificate and key pair should be loaded, before any TLS session is initialized, in a certificate credentials structure. This should be done by using gnutls_certificate_set_x509_key_file or gnutls_certificate_set_openpgp_key_file depending on the certificate type. In the X.509 case, the functions will also accept and use a certificate list that leads to a trusted authority. The certificate list must be ordered in such way that every certificate certifies the one before it. The trusted authority's certificate need not to be included, since the peer should possess it already.

As an alternative, a callback may be used so the server or the client specify the certificate and the key at the handshake time. That callback can be set using the functions:

In a handshake, the negotiated cipher suite depends on the certificate's parameters, so not all key exchange methods will be available with some certificates. GnuTLS will disable ciphersuites that are not compatible with the key, or the enabled authentication methods. For example keys marked as sign-only, will not be able to access the plain RSA ciphersuites, but only the DHE_RSA ones. It is recommended not to use RSA keys for both signing and encryption. If possible use the same key for the DHE_RSA and RSA_EXPORT ciphersuites, which use signing, and a different key for the plain RSA ciphersuites, which use encryption. All the key exchange methods shown below are available in certificate authentication.

Note that the DHE key exchange methods are generally slower¹³ than plain RSA and require Diffie Hellman parameters to be generated and associated with a credentials structure, by the server. The RSA-EXPORT method also requires 512 bit RSA parameters, that should also be generated and associated with the credentials structure. See the functions:

Sometimes in order to avoid bottlenecks in programs it is usefull to store and read parameters from formats that can be generated by external programs such as certtool. This is possible with GnuTLS by using the following functions:

4.2 Anonymous Authentication

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

Note that the key exchange methods for anonymous authentication require Diffie Hellman parameters to be generated by the server and associated with an anonymous credentials structure.

4.3 Authentication using SRP

Authentication via the Secure Remote Password protocol, SRP¹⁴, is supported. The SRP key exchange is an extension to the TLS protocol, and it is a password based authentication (unlike X.509 or OpenPGP that use certificates). The two peers can be identified using a single password, or there can be combinations where the client is authenticated using SRP and the server using a certificate.

The advantage of SRP authentication, over other proposed secure password authentication schemes, is that SRP does not require the server to hold the user's password. This kind of protection is similar to the one used traditionally in the UNIX /etc/passwd file, where the contents of this file did not cause harm to the system security if they were revealed. The SRP needs instead of the plain password something called a verifier, which is calculated using the user's password, and if stolen cannot be used to impersonate the user. Check [TOMSRP] (see Bibliography) for a detailed description of the SRP protocol and the Stanford SRP libraries, which includes a PAM module that synchronizes the system's users passwords with the SRP password files. That way SRP authentication could be used for all the system's users.

The implementation in GnuTLS is based on paper [TLSSRP] (see Bibliography). The supported SRP key exchange methods are:

If clients supporting SRP know the username and password before the connection, should initialize the client credentials and call the function gnutls_srp_set_client_credentials. Alternatively they could specify a callback function by using the function gnutls_srp_set_client_credentials_function. This has the advantage that allows probing the server for SRP support. In that case the callback function will be called twice per handshake. The first time is before the ciphersuite is negotiated, and if the callback returns a negative error code, the callback will be called again if SRP has been negotiated. This uses a special TLS-SRP handshake idiom in order to avoid, in interactive applications, to ask the user for SRP password and username if the server does not negotiate an SRP ciphersuite.

In server side the default behaviour of GnuTLS is to read the usernames and SRP verifiers from password files. These password files are the ones used by the Stanford srp libraries and can be specified using the gnutls_srp_set_server_credentials_file. If a different password file format is to be used, then the function gnutls_srp_set_server_credentials_function, should be called, in order to set an appropriate callback.

are included in GnuTLS, and can be used to generate and maintain SRP verifiers and password files. A program to manipulate the required parameters for SRP authentication is also included. See srptool, for more information.

4.4 Authentication using PSK

Authentication using Pre-shared keys is a method to authenticate using usernames and binary keys. This protocol avoids making use of public key infrastructure and expensive calculations, thus it is suitable for constraint clients.

The implementation in GnuTLS is based on paper [TLSPSK] (see Bibliography). The supported PSK key exchange methods are:

Clients supporting PSK should supply the username and key before the connection to the client credentials by calling the function gnutls_psk_set_client_credentials. Alternatively they could specify a callback function by using the function gnutls_psk_set_client_credentials_function. This has the advantage that the callback will be called only if PSK has been negotiated.

In server side the default behaviour of GnuTLS is to read the usernames and PSK keys from a password file. The password file should contain usernames and keys in hexadecimal format. The name of the password file can be stored to the credentials structure by calling gnutls_psk_set_server_credentials_file. If a different password file format is to be used, then the function gnutls_psk_set_server_credentials_function, should be used instead.

The server can help the client chose a suitable username and password, by sending a hint. In the server, specify the hint by calling gnutls_psk_set_server_credentials_hint. The client can retrieve the hint, for example in the callback function, using gnutls_psk_client_get_hint.

There is no standard mechanism to derive a PSK key from a password specified by the TLS PSK document. However, GnuTLS provides gnutls_psk_netconf_derive_key which follows the algorithm specified in draft-ietf-netconf-tls-02.txt.

4.5 Authentication and Credentials

In GnuTLS every key exchange method is associated with a credentials type. So in order to enable to enable a specific method, the corresponding credentials type should be initialized and set using gnutls_credentials_set. A mapping is shown below.

Key exchange	Client credentials	Server credentials
`KX_RSA`
`KX_DHE_RSA`
`KX_DHE_DSS`
`KX_RSA_EXPORT`	`CRD_CERTIFICATE`	`CRD_CERTIFICATE`
`KX_SRP_RSA`	`CRD_SRP`	`CRD_SRP`
`KX_SRP_DSS`		`CRD_CERTIFICATE`
`KX_SRP`	`CRD_SRP`	`CRD_SRP`
`KX_ANON_DH`	`CRD_ANON`	`CRD_ANON`
`KX_PSK`	`CRD_PSK`	`CRD_PSK`

4.6 Parameters Stored in Credentials

Several parameters such as the ones used for Diffie-Hellman authentication are stored within the credentials structures, so all sessions can access them. Those parameters are stored in structures such as gnutls_dh_params_t and gnutls_rsa_params_t, and functions like gnutls_certificate_set_dh_params and gnutls_certificate_set_rsa_export_params can be used to associate those parameters with the given credentials structure.

Since those parameters need to be renewed from time to time and a global structure such as the credentials, may not be easy to modify since it is accessible by all sessions, an alternative interface is available using a callback function. This can be set using the gnutls_certificate_set_params_function. An example is shown below.

5 More on Certificate Authentication

5.1 The X.509 Trust Model

The X.509 protocols rely on a hierarchical trust model. In this trust model Certification Authorities (CAs) are used to certify entities. Usually more than one certification authorities exist, and certification authorities may certify other authorities to issue certificates as well, following a hierarchical model.

One needs to trust one or more CAs for his secure communications. In that case only the certificates issued by the trusted authorities are acceptable. See the figure above for a typical example. The API for handling X.509 certificates is described at section sec:x509api. Some examples are listed below.

5.1.1 X.509 Certificates

An X.509 certificate usually contains information about the certificate holder, the signer, a unique serial number, expiration dates and some other fields [RFC3280] (see Bibliography) as shown in the table below.

The certificate's subject or issuer name is not just a single string. It is a Distinguished name and in the ASN.1 notation is a sequence of several object IDs with their corresponding values. Some of available OIDs to be used in an X.509 distinguished name are defined in gnutls/x509.h.

The Version field in a certificate has values either 1 or 3 for version 3 certificates. Version 1 certificates do not support the extensions field so it is not possible to distinguish a CA from a person, thus their usage should be avoided.

The validity dates are there to indicate the date that the specific certificate was activated and the date the certificate's key would be considered invalid.

Certificate extensions are there to include information about the certificate's subject that did not fit in the typical certificate fields. Those may be e-mail addresses, flags that indicate whether the belongs to a CA etc. All the supported X.509 version 3 extensions are shown in the table below.

In GnuTLS the X.509 certificate structures are handled using the gnutls_x509_crt_t type and the corresponding private keys with the gnutls_x509_privkey_t type. All the available functions for X.509 certificate handling have their prototypes in gnutls/x509.h. An example program to demonstrate the X.509 parsing capabilities can be found at section ex:x509-info.

5.1.2 Verifying X.509 Certificate Paths

Verifying certificate paths is important in X.509 authentication. For this purpose the function gnutls_x509_crt_verify is provided. The output of this function is the bitwise OR of the elements of the gnutls_certificate_status_t enumeration. A detailed description of these elements can be found in figure below. The function gnutls_certificate_verify_peers2 is equivalent to the previous one, and will verify the peer's certificate in a TLS session.

Although the verification of a certificate path indicates that the certificate is signed by trusted authority, does not reveal anything about the peer's identity. It is required to verify if the certificate's owner is the one you expect. For more information consult [RFC2818] (see Bibliography) and section ex:verify for an example.

5.1.3 PKCS #10 Certificate Requests

A certificate request is a structure, which contain information about an applicant of a certificate service. It usually contains a private key, a distinguished name and secondary data such as a challenge password. GnuTLS supports the requests defined in PKCS #10 [RFC2986] (see Bibliography). Other certificate request's format such as PKIX's [RFC4211] (see Bibliography) are not currently supported.

In GnuTLS the PKCS #10 structures are handled using the gnutls_x509_crq_t type. An example of a certificate request generation can be found at section ex:crq.

5.1.4 PKCS #12 Structures

A PKCS #12 structure [PKCS12] (see Bibliography) usually contains a user's private keys and certificates. It is commonly used in browsers to export and import the user's identities.

In GnuTLS the PKCS #12 structures are handled using the gnutls_pkcs12_t type. This is an abstract type that may hold several gnutls_pkcs12_bag_t types. The Bag types are the holders of the actual data, which may be certificates, private keys or encrypted data. An Bag of type encrypted should be decrypted in order for its data to be accessed.

An example of a PKCS #12 structure generation can be found at section ex:pkcs12.

5.2 The OpenPGP Trust Model

The OpenPGP key authentication relies on a distributed trust model, called the “web of trust”. The “web of trust” uses a decentralized system of trusted introducers, which are the same as a CA. OpenPGP allows anyone to sign anyone's else public key. When Alice signs Bob's key, she is introducing Bob's key to anyone who trusts Alice. If someone trusts Alice to introduce keys, then Alice is a trusted introducer in the mind of that observer.

For example: If David trusts Alice to be an introducer, and Alice signed Bob's key, Dave also trusts Bob's key to be the real one.

There are some key points that are important in that model. In the example Alice has to sign Bob's key, only if she is sure that the key belongs to Bob. Otherwise she may also make Dave falsely believe that this is Bob's key. Dave has also the responsibility to know who to trust. This model is similar to real life relations.

Just see how Charlie behaves in the previous example. Although he has signed Bob's key - because he knows, somehow, that it belongs to Bob - he does not trust Bob to be an introducer. Charlie decided to trust only Kevin, for some reason. A reason could be that Bob is lazy enough, and signs other people's keys without being sure that they belong to the actual owner.

5.2.1 OpenPGP Keys

In GnuTLS the OpenPGP key structures [RFC2440] (see Bibliography) are handled using the gnutls_openpgp_crt_t type and the corresponding private keys with the gnutls_openpgp_privkey_t type. All the prototypes for the key handling functions can be found at gnutls/openpgp.h.

5.2.2 Verifying an OpenPGP Key

The verification functions of OpenPGP keys, included in GnuTLS, are simple ones, and do not use the features of the “web of trust”. For that reason, if the verification needs are complex, the assistance of external tools like GnuPG and GPGME (http://www.gnupg.org/related_software/gpgme/) is recommended.

There is one verification function in GnuTLS, the gnutls_openpgp_crt_verify_ring. This checks an OpenPGP key against a given set of public keys (keyring) and returns the key status. The key verification status is the same as in X.509 certificates, although the meaning and interpretation are different. For example an OpenPGP key may be valid, if the self signature is ok, even if no signers were found. The meaning of verification status is shown in the figure below.

5.3 Digital Signatures

In this section we will provide some information about digital signatures, how they work, and give the rationale for disabling some of the algorithms used.

Digital signatures work by using somebody's secret key to sign some arbitrary data. Then anybody else could use the public key of that person to verify the signature. Since the data may be arbitrary it is not suitable input to a cryptographic digital signature algorithm. For this reason and also for performance cryptographic hash algorithms are used to preprocess the input to the signature algorithm. This works as long as it is difficult enough to generate two different messages with the same hash algorithm output. In that case the same signature could be used as a proof for both messages. Nobody wants to sign an innocent message of donating 1 € to Greenpeace and find out that he donated 1.000.000 € to Bad Inc.

For a hash algorithm to be called cryptographic the following three requirements must hold

The last two requirements in the list are the most important in digital signatures. These protect against somebody who would like to generate two messages with the same hash output. When an algorithm is considered broken usually it means that the Collision resistance of the algorithm is less than brute force. Using the birthday paradox the brute force attack takes 2^((hash size) / 2) operations. Today colliding certificates using the MD5 hash algorithm have been generated as shown in [WEGER] (see Bibliography).

There has been cryptographic results for the SHA-1 hash algorithms as well, although they are not yet critical. Before 2004, MD5 had a presumed collision strength of 2^64, but it has been showed to have a collision strength well under 2^50. As of November 2005, it is believed that SHA-1's collision strength is around 2^63. We consider this sufficiently hard so that we still support SHA-1. We anticipate that SHA-256/386/512 will be used in publicly-distributed certificates in the future. When 2^63 can be considered too weak compared to the computer power available sometime in the future, SHA-1 will be disabled as well. The collision attacks on SHA-1 may also get better, given the new interest in tools for creating them.

5.3.1 Supported Algorithms

5.3.2 Trading Security for Interoperability

If you connect to a server and use GnuTLS' functions to verify the certificate chain, and get a GNUTLS_CERT_INSECURE_ALGORITHM validation error (see Verifying X.509 certificate paths), it means that somewhere in the certificate chain there is a certificate signed using RSA-MD2 or RSA-MD5. These two digital signature algorithms are considered broken, so GnuTLS fail when attempting to verify the certificate. In some situations, it may be useful to be able to verify the certificate chain anyway, assuming an attacker did not utilize the fact that these signatures algorithms are broken. This section will give help on how to achieve that.

First, it is important to know that you do not have to enable any of the flags discussed here to be able to use trusted root CA certificates signed using RSA-MD2 or RSA-MD5. The only attack today is that it is possible to generate certificates with colliding signatures (collision resistance); you cannot generate a certificate that has the same signature as an already existing signature (2nd preimage resistance).

This will tell the verifier algorithm to enable RSA-MD5 when verifying the certificates.

If you are using these flags, it may also be a good idea to warn the user when verification failure occur for this reason. The simplest is to not use the flags by default, and only fall back to using them after warning the user. If you wish to inspect the certificate chain yourself, you can use gnutls_certificate_get_peers to extract the raw server's certificate chain, then use gnutls_x509_crt_import to parse each of the certificates, and then use gnutls_x509_crt_get_signature_algorithm to find out the signing algorithm used for each certificate. If any of the intermediary certificates are using GNUTLS_SIGN_RSA_MD2 or GNUTLS_SIGN_RSA_MD5, you could present a warning.

6 How To Use TLS in Application Protocols

This chapter is intended to provide some hints on how to use the TLS over simple custom made application protocols. The discussion below mainly refers to the TCP/IP transport layer but may be extended to other ones too.

6.1 Separate Ports

Traditionally SSL was used in application protocols by assigning a new port number for the secure services. That way two separate ports were assigned, one for the non secure sessions, and one for the secured ones. This has the benefit that if a user requests a secure session then the client will try to connect to the secure port and fail otherwise. The only possible attack with this method is a denial of service one. The most famous example of this method is the famous “HTTP over TLS” or HTTPS protocol [RFC2818] (see Bibliography).

Despite its wide use, this method is not as good as it seems. This approach starts the TLS Handshake procedure just after the client connects on the —so called— secure port. That way the TLS protocol does not know anything about the client, and popular methods like the host advertising in HTTP do not work¹⁵. There is no way for the client to say “I connected to YYY server” before the Handshake starts, so the server cannot possibly know which certificate to use.

Other than that it requires two separate ports to run a single service, which is unnecessary complication. Due to the fact that there is a limitation on the available privileged ports, this approach was soon obsoleted.

6.2 Upward Negotiation

Other application protocols¹⁶ use a different approach to enable the secure layer. They use something called the “TLS upgrade” method. This method is quite tricky but it is more flexible. The idea is to extend the application protocol to have a “STARTTLS” request, whose purpose it to start the TLS protocols just after the client requests it. This is a really neat idea and does not require an extra port.

This method is used by almost all modern protocols and there is even the [RFC2817] (see Bibliography) paper which proposes extensions to HTTP to support it.

The tricky part, in this method, is that the “STARTTLS” request is sent in the clear, thus is vulnerable to modifications. A typical attack is to modify the messages in a way that the client is fooled and thinks that the server does not have the “STARTTLS” capability. See a typical conversation of a hypothetical protocol:

As you can see above the client was fooled, and was dummy enough to send the confidential data in the clear.

How to avoid the above attack? As you may have already thought this one is easy to avoid. The client has to ask the user before it connects whether the user requests TLS or not. If the user answered that he certainly wants the secure layer the last conversation should be:

This method, if implemented properly, is far better than the traditional method, and the security properties remain the same, since only denial of service is possible. The benefit is that the server may request additional data before the TLS Handshake protocol starts, in order to send the correct certificate, use the correct password file¹⁷, or anything else!

7 How To Use GnuTLS in Applications

7.1 Preparation

To use GnuTLS, you have to perform some changes to your sources and your build system. The necessary changes are explained in the following subsections.

7.1.1 Headers

All the data types and functions of the GnuTLS library are defined in the header file gnutls/gnutls.h. This must be included in all programs that make use of the GnuTLS library.

The extra functionality of the GnuTLS-extra library is available by including the header file gnutls/extra.h in your programs.

7.1.2 Version Check

It is often desirable to check that the version of `gnutls' used is indeed one which fits all requirements. Even with binary compatibility new features may have been introduced but due to problem with the dynamic linker an old version is actually used. So you may want to check that the version is okay right after program startup. See the function gnutls_check_version.

7.1.3 Debugging

In many cases things may not go as expected and further information, to assist debugging, from GnuTLS is desired. Those are the case where the gnutls_global_set_log_level and gnutls_global_set_log_function are to be used. Those will print verbose information on the GnuTLS functions internal flow.