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:

  * Certificate authentication

  * Anonymous authentication

  * SRP authentication

  * PSK authentication

The rule for each method is to allocate a credentials structure containing data required for authentication and associate that structure with the session using gnutls_credentials_set. Various authentication methods might require additional data to be stored in the credential structures, such as ephemeral Diffie-Hellman parameters etc. In the next paragraphs we elaborate on supported authentication methods.

gnutls_credentials_set

Certificate authentication
==========================

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 X.509 certificates, for more information on X.509 protocols.

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

More information on the OpenPGP trusted model is provided in OpenPGP certificates. For a more detailed introduction to OpenPGP and GnuPG see GPGH.

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.

gnutls_certificate_allocate_credentials,gnutls_certificate_free_credentials

After the credentials structures are initialized using the functions above, the certificate and key pair should be loaded. This should occur before any TLS session is initialized. Depending on the certificate type different loading functions are available, and are shown below. 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.

gnutls_certificate_set_x509_key,gnutls_certificate_set_x509_key_mem,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_openpgp_key_mem

gnutls_certificate_set_x509_key_file

As an alternative to loading from files, a callback may be used so that the server or the client can specify the certificate and the key at the handshake time. In that case a certificate should be selected according the peer's signature algorithm preferences. To get those preferences use gnutls_sign_algorithm_get_requested. Both functions are shown below.

gnutls_certificate_set_retrieve_function

gnutls_sign_algorithm_get_requested

Certificate verification is possible by loading the trusted authorities into the credentials structure by using the following functions, applicable to X.509 and OpenPGP certificates.

gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_openpgp_keyring_file

Note however that the peer's certificate is not automatically verified, you should call gnutls_certificate_verify_peers2, after a successful handshake or during if gnutls_certificate_set_verify_function has been used, to verify the certificate's signature. An alternative way, which reports a more detailed verification output, is to use gnutls_certificate_get_peers to obtain the raw certificate of the peer and verify it using the functions discussed in X.509 certificates.

gnutls_certificate_verify_peers2

In a handshake, the negotiated cipher suite also depends on the certificate's parameters, so some key exchange methods might not 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, that require decryption. It is not recommended to use RSA keys for both signing and encryption. If possible use a different key for the DHE_RSA which uses signing and RSA that requires decryption. All the key exchange methods shown in tab:key-exchange are available in certificate authentication.

gnutls_certificate_set_verify_function

Note that the DHE key exchange methods are generally slower (It depends on the group used.  Primes with lesser bits are always faster, but also easier to break.  See Selecting cryptographic key sizes for the acceptable security levels.) than the elliptic curves counterpart (ECDHE). Moreover the plain Diffie-Hellman key exchange requires parameters to be generated and associated with a credentials structure by the server (see Parameter generation).

Key exchange   Description

RSA
The RSA algorithm is used to encrypt a key and send it to the peer.
The certificate must allow the key to be used for encryption.

RSA_EXPORT
The RSA algorithm is used to encrypt a key and send it to the peer.
In the EXPORT algorithm, the server signs temporary RSA parameters of
512 bits --- which are considered weak --- and sends them to the
client.

DHE_RSA
The RSA algorithm is used to sign ephemeral Diffie-Hellman parameters
which are sent to the peer. The key in the certificate must allow the
key to be used for signing. Note that key exchange algorithms which
use ephemeral Diffie-Hellman parameters, offer perfect forward
secrecy. That means that even if the private key used for signing is
compromised, it cannot be used to reveal past session data.

ECDHE_RSA
The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman
parameters which are sent to the peer. The key in the certificate must allow
the key to be used for signing. It also offers perfect forward
secrecy. That means that even if the private key used for signing is
compromised, it cannot be used to reveal past session data.

DHE_DSS
The DSA algorithm is used to sign ephemeral Diffie-Hellman parameters
which are sent to the peer. The certificate must contain DSA
parameters to use this key exchange algorithm. DSA is the algorithm
of the Digital Signature Standard (DSS).

ECDHE_ECDSA
The Elliptic curve DSA algorithm is used to sign ephemeral elliptic
curve Diffie-Hellman parameters which are sent to the peer. The
certificate must contain ECDSA parameters to use this key exchange
algorithm.

Table: Supported key exchange algorithms.

Anonymous authentication
========================

The anonymous key exchange offers encryption without any indication of the peer's identity.  This kind of authentication is vulnerable to a man in the middle attack, but can be used even if there is no prior communication or shared trusted parties with the peer. Moreover it is useful when complete anonymity is required. Unless in one of the above cases, do not use anonymous authentication.

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. Check Parameter generation for more information.

The initialization functions for the credentials are shown below.

gnutls_anon_allocate_server_credentials,gnutls_anon_allocate_client_credentials,gnutls_anon_free_server_credentials,gnutls_anon_free_client_credentials

The available key exchange algorithms for anonymous authentication are shown below.

ANON_DH:
     This algorithm exchanges Diffie-Hellman parameters.

ANON_ECDH:
     This algorithm exchanges elliptic curve Diffie-Hellman parameters. It is more efficient than ANON_DH on equivalent security levels.

Authentication using SRP
========================

Authentication via the Secure Remote Password protocol, SRP (see RFC2945 for a description of 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 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 TLSSRP and the supported SRP key exchange methods are:

SRP:
     Authentication using the SRP protocol.

SRP_DSS:
     Client authentication using the SRP protocol. Server is authenticated using a certificate with DSA parameters.

SRP_RSA:
     Client authentication using the SRP protocol. Server is authenticated using a certificate with RSA parameters.

The initialization functions in SRP credentials differ between client and server.

gnutls_srp_allocate_server_credentials,gnutls_srp_allocate_client_credentials,gnutls_srp_free_server_credentials,gnutls_srp_free_client_credentials

Clients supporting SRP should set the username and password prior to connection, to the credentials structure. Alternatively gnutls_srp_set_client_credentials_function may be used instead, to specify a callback function that should return the SRP username and password. The callback is called once during the TLS handshake.

gnutls_srp_set_client_credentials

gnutls_srp_set_client_credentials_function

In server side the default behavior of GnuTLS is to read the usernames and SRP verifiers from password files. These password file format is compatible the with the Stanford srp libraries format.  If a different password file format is to be used, then gnutls_srp_set_server_credentials_function should be called, to set an appropriate callback.

gnutls_srp_set_server_credentials_file

gnutls_srp_set_server_credentials_function

Other helper functions are included in GnuTLS, 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.

gnutls_srp_verifier

gnutls_srp_base64_encode,gnutls_srp_base64_decode

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 TLSPSK. The supported PSK key exchange methods are:

PSK:
     Authentication using the PSK protocol.

DHE-PSK:
     Authentication using the PSK protocol and Diffie-Hellman key exchange.  This method offers perfect forward secrecy.

ECDHE-PSK:
     Authentication using the PSK protocol and Elliptic curve Diffie-Hellman key exchange.  This method offers perfect forward secrecy.

The initialization functions in PSK credentials differ between client and server.

gnutls_psk_allocate_server_credentials,gnutls_psk_allocate_client_credentials,gnutls_psk_free_server_credentials,gnutls_psk_free_client_credentials

Clients supporting PSK should supply the username and key before a TLS session is established.  Alternatively gnutls_psk_set_client_credentials_function can be used to specify a callback function. This has the advantage that the callback will be called only if PSK has been negotiated.

gnutls_psk_set_client_credentials

gnutls_psk_set_client_credentials_function

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

The server can help the client chose a suitable username and password, by sending a hint. Note that there is no common profile for the PSK hint and applications are discouraged to use it. A server, may specify the hint by calling gnutls_psk_set_server_credentials_hint.  The client can retrieve the hint, for example in the callback function, using gnutls_psk_client_get_hint.

gnutls_psk_set_server_credentials_file

gnutls_psk_set_server_credentials_function,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint

Helper functions to generate and maintain PSK keys are also included in GnuTLS.

gnutls_key_generate,gnutls_hex_encode,gnutls_hex_decode

Authentication and credentials
==============================

In GnuTLS every key exchange method is associated with a credentials type. For a key exchange method to be available it must be listed as a priority string (see Priority Strings) and the corresponding credentials type should be initialized and set using gnutls_credentials_set.  A mapping of the key exchange methods with the credential types is shown in tab:key-exchange-cred.

Key exchange   Client credentials   Server credentials

KX_RSA,
KX_DHE_RSA,
KX_DHE_DSS,
KX_ECDHE_RSA,
KX_ECDHE_ECDSA,
KX_RSA_EXPORT
CRD_CERTIFICATE
CRD_CERTIFICATE

KX_SRP_RSA, KX_SRP_DSS
CRD_SRP
CRD_CERTIFICATE, CRD_SRP

KX_SRP
CRD_SRP
CRD_SRP

KX_ANON_DH,
KX_ANON_ECDH
CRD_ANON
CRD_ANON

KX_PSK,
KX_DHE_PSK, KX_ECDHE_PSK
CRD_PSK
CRD_PSK

Table: Key exchange algorithms and the corresponding credential types.