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:

• gnutls_certificate_server_set_retrieve_function
• gnutls_certificate_client_set_retrieve_function

Certificate verification is possible by loading the trusted authorities into the credentials structure by using gnutls_certificate_set_x509_trust_file or gnutls_certificate_set_openpgp_keyring_file for openpgp keys. Note however that the peer's certificate is not automatically verified, you should call gnutls_certificate_verify_peers2, after a successful handshake, to verify the signatures of the certificate. 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 The X.509 Trust Model.

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(12) 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:

• gnutls_dh_params_generate2
• gnutls_certificate_set_dh_params
• gnutls_rsa_params_generate2
• gnutls_certificate_set_rsa_export_params

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:

• gnutls_dh_params_import_pkcs3
• gnutls_rsa_params_import_pkcs1
• gnutls_dh_params_export_pkcs3
• gnutls_rsa_params_export_pkcs1

Key exchange algorithms for OpenPGP and X.509 certificates:

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.

DHE_DSS:

The DSS 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. DSS stands for Digital Signature Standard.