Next: SRP credentials, Up: Associating the credentials [Contents][Index]
When using certificates the server is required to have at least one certificate and private key pair. Clients may not hold such a pair, but a server could require it. In this section we discuss general issues applying to both client and server certificates. The next section will elaborate on issues arising from client authentication only.
gnutls_certificate_allocate_credentialsgnutls_certificate_free_credentialsAfter the credentials structures are initialized, the certificate and key pair must be loaded. This occurs before any TLS session is initialized, and the same structures are reused for multiple sessions. Depending on the certificate type different loading functions are available, as shown below. For X.509 certificates, the functions will accept and use a certificate chain that leads to a trusted authority. The certificate chain 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_memgnutls_certificate_set_x509_keygnutls_certificate_set_x509_key_filegnutls_certificate_set_openpgp_key_memgnutls_certificate_set_openpgp_keygnutls_certificate_set_openpgp_key_filegnutls_certificate_set_keyIf multiple certificates are used with the functions above each client’s request will be served with the certificate that matches the requested name (see Server name indication).
As an alternative to loading from files or buffers, a callback may be used for the server or the client to 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_functiongnutls_sign_algorithm_get_requestedThe functions above do not handle the requested server name automatically. A server would need to check the name requested by the client using gnutls_server_name_get, and serve the appropriate certificate.
In a handshake, the negotiated cipher suite depends on the
certificate’s parameters, so some key exchange methods might not be
available with all 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.
If a certificate is to be requested from the client during the handshake, the server will send a certificate request message. This behavior is controlled gnutls_certificate_server_set_request. The request contains a list of the acceptable by the server certificate signers. This list is constructed using the trusted certificate authorities of the server. In cases where the server supports a large number of certificate authorities it makes sense not to advertise all of the names to save bandwidth. That can be controlled using the function gnutls_certificate_send_x509_rdn_sequence. This however will have the side-effect of not restricting the client to certificates signed by server’s acceptable signers.
session: is a gnutls_session_t structure.
req: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE
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.
session: is a pointer to a gnutls_session_t structure.
status: is 0 or 1
If status is non zero, this function will order gnutls not to send the rdnSequence in the certificate request message. That is the server will not advertise its trusted CAs to the peer. If status is zero then the default behaviour will take effect, which is to advertise the server’s trusted CAs.
This function has no effect in clients, and in authentication methods other than certificate with X.509 certificates.
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_filegnutls_certificate_set_openpgp_keyring_fileThe peer’s certificate is not automatically verified and one should call gnutls_certificate_verify_peers2 after a successful handshake to verify the certificate’s signature. Alternative the verification can occur during the handshake by using gnutls_certificate_set_verify_function.
In order to report a detailed verification output, an alternative way has to be used. For that, one should call gnutls_certificate_get_peers to obtain the raw certificate of the peer and verify it using the functions discussed in X.509 certificates.
session: is a gnutls session
status: is the output of the verification
This function will try to verify the peer’s certificate and return
its status (trusted, invalid etc.). The value of status should
be one or more of the gnutls_certificate_status_t enumerated
elements bitwise or’d. To avoid denial of service attacks some
default upper limits regarding the certificate key size and chain
size are set. To override them use
gnutls_certificate_set_verify_limits() .
Note that you must also check the peer’s name in order to check if the verified certificate belongs to the actual peer.
This function uses gnutls_x509_crt_list_verify() with the CAs in
the credentials as trusted CAs.
Returns: a negative error code on error and GNUTLS_E_SUCCESS (0) on success.
cred: is a gnutls_certificate_credentials_t structure.
func: is the callback function
This function sets a callback to be called when peer’s certificate has been received in order to verify it on receipt rather than doing after the handshake is completed.
The callback’s function prototype is: int (*callback)(gnutls_session_t);
If the callback function is provided then gnutls will call it, in the
handshake, just after the certificate message has been received.
To verify or obtain the certificate the gnutls_certificate_verify_peers2() ,
gnutls_certificate_type_get() , gnutls_certificate_get_peers() functions
can be used.
The callback function should return 0 for the handshake to continue or non-zero to terminate.
Since: 2.10.0
Next: SRP credentials, Up: Associating the credentials [Contents][Index]