GnuTLS 3.0.19: Verifying X.509 certificate paths

4.1.3 Verifying X.509 certificate paths

Verifying certificate paths is important in X.509 authentication. For this purpose the following functions are provided.

Function: int gnutls_x509_trust_list_add_cas (gnutls_x509_trust_list_t list, const gnutls_x509_crt_t * clist, int clist_size, unsigned int flags)

list: The structure of the list

clist: A list of CAs

clist_size: The length of the CA list

flags: should be 0.

This function will add the given certificate authorities to the trusted list. The list of CAs must not be deinitialized during this structure’s lifetime.

Returns: The number of added elements is returned.

Since: 3.0

Function: int gnutls_x509_trust_list_add_named_crt (gnutls_x509_trust_list_t list, gnutls_x509_crt_t cert, const void * name, size_t name_size, unsigned int flags)

list: The structure of the list

cert: A certificate

name: An identifier for the certificate

name_size: The size of the identifier

flags: should be 0.

This function will add the given certificate to the trusted list and associate it with a name. The certificate will not be be used for verification with gnutls_x509_trust_list_verify_crt() but only with gnutls_x509_trust_list_verify_named_crt() .

In principle this function can be used to set individual "server" certificates that are trusted by the user for that specific server but for no other purposes.

The certificate must not be deinitialized during the lifetime of the trusted list.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Since: 3.0

Function: int gnutls_x509_trust_list_add_crls (gnutls_x509_trust_list_t list, const gnutls_x509_crl_t * crl_list, int crl_size, unsigned int flags, unsigned int verification_flags)

list: The structure of the list

crl_list: A list of CRLs

crl_size: The length of the CRL list

flags: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.

verification_flags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL

This function will add the given certificate revocation lists to the trusted list. The list of CRLs must not be deinitialized during this structure’s lifetime.

This function must be called after gnutls_x509_trust_list_add_cas() to allow verifying the CRLs for validity.

Returns: The number of added elements is returned.

Since: 3.0

Function: int gnutls_x509_trust_list_verify_crt (gnutls_x509_trust_list_t list, gnutls_x509_crt_t * cert_list, unsigned int cert_list_size, unsigned int flags, unsigned int * verify, gnutls_verify_output_function func)

list: The structure of the list

cert_list: is the certificate list to be verified

cert_list_size: is the certificate list size

flags: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.

verify: will hold the certificate verification output.

func: If non-null will be called on each chain element verification with the output.

This function will try to verify the given certificate and return its status.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Since: 3.0

Function: int gnutls_x509_trust_list_verify_named_crt (gnutls_x509_trust_list_t list, gnutls_x509_crt_t cert, const void * name, size_t name_size, unsigned int flags, unsigned int * verify, gnutls_verify_output_function func)

list: The structure of the list

cert: is the certificate to be verified

name: is the certificate’s name

name_size: is the certificate’s name size

flags: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.

verify: will hold the certificate verification output.

func: If non-null will be called on each chain element verification with the output.

This function will try to find a matching named certificate. If a match is found the certificate is considered valid. In addition to that this function will also check CRLs.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Since: 3.0

The verification function will verify a given certificate chain against a list of certificate authorities and certificate revocation lists, and output a bit-wise OR of elements of the gnutls_certificate_status_t enumeration shown in gnutls_certificate_status_t.

GNUTLS_CERT_INVALID: The certificate is not signed by one of the known authorities or the signature is invalid.
GNUTLS_CERT_REVOKED: Certificate is revoked by its authority. In X.509 this will be set only if CRLs are checked.
GNUTLS_CERT_SIGNER_NOT_FOUND: The certificate’s issuer is not known. This is the case if the issue is not included in the trusted certificate list. not found.
GNUTLS_CERT_SIGNER_NOT_CA: The certificateâs signer was not a CA. This may happen if this was a version 1 certificate, which is common with some CAs, or a version 3 certificate without the basic constrains extension.
GNUTLS_CERT_INSECURE_ALGORITHM: The certificate was signed using an insecure algorithm such as MD2 or MD5. These algorithms have been broken and should not be trusted.
GNUTLS_CERT_NOT_ACTIVATED: The certificate is not yet activated.
GNUTLS_CERT_EXPIRED: The certificate has expired.

Figure 4.2: The gnutls_certificate_status_t enumeration.

An example of certificate verification is shown in ex:verify2. It is also possible to have a set of certificates that are trusted for a particular server but not to authorize other certificates. This purpose is served by the functions gnutls_x509_trust_list_add_named_crt and gnutls_x509_trust_list_verify_named_crt.