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.

• 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

• gnutls_certificate_set_retrieve_function

As an alternative, a callback may be used so the server or the client specifies the certificate and the key at the handshake time using gnutls_certificate_set_retrieve_function. 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.

• gnutls_sign_algorithm_get_requested

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 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 The X.509 trust model.

• gnutls_certificate_verify_peers2

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.

• gnutls_certificate_set_verify_function

Note that the DHE key exchange methods are generally slower(7) than plain RSA and require Diffie Hellman parameters to be generated and associated with a credentials structure, by the server. For more information check the Parameter generation section. The key exchange algorithms for OpenPGP and X.509 certificates are shown in tab:key-exchange.

Table 4.1: Supported key exchange algorithms.