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.
int gnutls_certificate_allocate_credentials (gnutls_certificate_credentials_t * res)void gnutls_certificate_free_credentials (gnutls_certificate_credentials_t sc)After 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.
int gnutls_certificate_set_x509_key_file2 (gnutls_certificate_credentials_t res, const char * certfile, const char * keyfile, gnutls_x509_crt_fmt_t type, const char * pass, unsigned int flags)int gnutls_certificate_set_x509_key_mem2 (gnutls_certificate_credentials_t res, const gnutls_datum_t * cert, const gnutls_datum_t * key, gnutls_x509_crt_fmt_t type, const char * pass, unsigned int flags)int gnutls_certificate_set_x509_key (gnutls_certificate_credentials_t res, gnutls_x509_crt_t * cert_list, int cert_list_size, gnutls_x509_privkey_t key)int gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t res, const char * certfile, const char * keyfile, gnutls_openpgp_crt_fmt_t format)int gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t res, const gnutls_datum_t * cert, const gnutls_datum_t * key, gnutls_openpgp_crt_fmt_t format)int gnutls_certificate_set_openpgp_key (gnutls_certificate_credentials_t res, gnutls_openpgp_crt_t crt, gnutls_openpgp_privkey_t pkey)It is recommended to use the higher level functions such as gnutls_certificate_set_x509_key_file2 which accept not only file names but URLs that specify objects stored in token, or system certificates and keys (see Application-specific keys). For these cases, another important function is gnutls_certificate_set_pin_function, that allows setting a callback function to retrieve a PIN if the input keys are protected by PIN.
cred: is a gnutls_certificate_credentials_t type.
fn: A PIN callback
userdata: Data to be passed in the callback
This function will set a callback function to be used when required to access a protected object. This function overrides any other global PIN functions.
Note that this function must be called right after initialization to have effect.
Since: 3.1.0
If the imported keys and certificates need to be accessed before any TLS session is established, it is convenient to use gnutls_certificate_set_key in combination with gnutls_pcert_import_x509_raw and gnutls_privkey_import_x509_raw.
res: is a gnutls_certificate_credentials_t type.
names: is an array of DNS name of the certificate (NULL if none)
names_size: holds the size of the names list
pcert_list: contains a certificate list (path) for the specified private key
pcert_list_size: holds the size of the certificate list
key: is a gnutls_privkey_t key
This function sets a certificate/private key pair in the
gnutls_certificate_credentials_t type. This function may be
called more than once, in case multiple keys/certificates exist for
the server. For clients that wants to send more than its own end
entity certificate (e.g., also an intermediate CA cert) then put
the certificate chain in pcert_list .
Note that the pcert_list and key will become part of the credentials
structure and must not be deallocated. They will be automatically deallocated
when the res type is deinitialized.
If that function fails to load the res structure is at an undefined state, it must
not be reused to load other keys or certificates.
Returns: GNUTLS_E_SUCCESS (0) on success, or a negative error code.
Since: 3.0
If 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.
void gnutls_certificate_set_retrieve_function (gnutls_certificate_credentials_t cred, gnutls_certificate_retrieve_function * func)void gnutls_certificate_set_retrieve_function2 (gnutls_certificate_credentials_t cred, gnutls_certificate_retrieve_function2 * func)int gnutls_sign_algorithm_get_requested (gnutls_session_t session, size_t indx, gnutls_sign_algorithm_t * algo)c
The 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. Note that some of these functions require the gnutls_pcert_st structure to be
filled in. Helper functions to fill in the structure are listed below.
typedef struct gnutls_pcert_st
{
gnutls_pubkey_t pubkey;
gnutls_datum_t cert;
gnutls_certificate_type_t type;
} gnutls_pcert_st;
int gnutls_pcert_import_x509 (gnutls_pcert_st * pcert, gnutls_x509_crt_t crt, unsigned int flags)int gnutls_pcert_import_openpgp (gnutls_pcert_st * pcert, gnutls_openpgp_crt_t crt, unsigned int flags)int gnutls_pcert_import_x509_raw (gnutls_pcert_st * pcert, const gnutls_datum_t * cert, gnutls_x509_crt_fmt_t format, unsigned int flags)int gnutls_pcert_import_openpgp_raw (gnutls_pcert_st * pcert, const gnutls_datum_t * cert, gnutls_openpgp_crt_fmt_t format, gnutls_openpgp_keyid_t keyid, unsigned int flags)void gnutls_pcert_deinit (gnutls_pcert_st * pcert)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 Table 4.1 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 type.
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: a gnutls_session_t type.
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.
int gnutls_certificate_set_x509_system_trust (gnutls_certificate_credentials_t cred)int gnutls_certificate_set_x509_trust_file (gnutls_certificate_credentials_t cred, const char * cafile, gnutls_x509_crt_fmt_t type)int gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c, const char * file, gnutls_openpgp_crt_fmt_t format)The peer’s certificate will be automatically verified if gnutls_session_set_verify_cert is called prior to handshake.
Alternatively, one must set a callback function during the handshake using gnutls_certificate_set_verify_function, which will verify the peer’s certificate once received. The verification should happen using gnutls_certificate_verify_peers3 within the callback. It will verify the certificate’s signature and the owner of the certificate. That will provide a brief verification output. If a detailed output is required 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.
In both the automatic and the manual cases, the verification status returned can be printed using gnutls_certificate_verification_status_print.
session: is a gnutls session
hostname: is the expected name of the peer; may be NULL
flags: flags for certificate verification – gnutls_certificate_verify_flags
This function instructs GnuTLS to verify the peer’s certificate
using the provided hostname. If the verification fails the handshake
will also fail with GNUTLS_E_CERTIFICATE_VERIFICATION_ERROR . In that
case the verification result can be obtained using gnutls_session_get_verify_cert_status() .
The hostname pointer provided must remain valid for the lifetime
of the session. More precisely it should be available during any subsequent
handshakes. If no hostname is provided, no hostname verification
will be performed. For a more advanced verification function check
gnutls_session_set_verify_cert2() .
The gnutls_session_set_verify_cert() function is intended to be used by TLS
clients to verify the server’s certificate.
Since: 3.4.6
int gnutls_certificate_verify_peers3 (gnutls_session_t session, const char * hostname, unsigned int * status)void gnutls_certificate_set_verify_function (gnutls_certificate_credentials_t cred, gnutls_certificate_verify_function * func)Next: SRP credentials, Up: Associating the credentials [Contents][Index]