GnuTLS 3.2.1: Verifying X.509 certificate paths

4.1.1.5 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. The verify parameter will hold an OR’ed sequence of gnutls_certificate_status_t flags.

Limitation: Pathlen constraints or key usage flags are not consulted.

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 certificate that is associated with the provided name –see gnutls_x509_trust_list_add_named_crt() . If a match is found the certificate is considered valid. In addition to that this function will also check CRLs. The verify parameter will hold an OR’ed sequence of gnutls_certificate_status_t flags.

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

Since: 3.0

Function: int gnutls_x509_trust_list_add_trust_file (gnutls_x509_trust_list_t list, const char* ca_file, const char* crl_file, gnutls_x509_crt_fmt_t type, unsigned int tl_flags, unsigned int tl_vflags)

list: The structure of the list

ca_file: A file containing a list of CAs (optional)

crl_file: A file containing a list of CRLs (optional)

type: The format of the certificates

tl_flags: GNUTLS_TL_*

tl_vflags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL

This function will add the given certificate authorities to the trusted list. pkcs11 URLs are also accepted, instead of files, by this function.

Returns: The number of added elements is returned.

Since: 3.1

Function: int gnutls_x509_trust_list_add_trust_mem (gnutls_x509_trust_list_t list, const gnutls_datum_t * cas, const gnutls_datum_t * crls, gnutls_x509_crt_fmt_t type, unsigned int tl_flags, unsigned int tl_vflags)

list: The structure of the list

cas: A buffer containing a list of CAs (optional)

crls: A buffer containing a list of CRLs (optional)

type: The format of the certificates

tl_flags: GNUTLS_TL_*

tl_vflags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL

This function will add the given certificate authorities to the trusted list.

Returns: The number of added elements is returned.

Since: 3.1

Function: int gnutls_x509_trust_list_add_system_trust (gnutls_x509_trust_list_t list, unsigned int tl_flags, unsigned int tl_vflags)

list: The structure of the list

tl_flags: GNUTLS_TL_*

tl_vflags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL

This function adds the system’s default trusted certificate authorities to the trusted list. Note that on unsupported system this function returns GNUTLS_E_UNIMPLEMENTED_FEATURE .

Returns: The number of added elements or a negative error code on error.

Since: 3.1

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 Figure 4.2. The GNUTLS_CERT_INVALID flag is always set on a verification error and more detailed flags will also be set when appropriate.

GNUTLS_CERT_INVALID: The certificate is not signed by one of the known authorities or the signature is invalid (deprecated by the flags GNUTLS_CERT_SIGNATURE_FAILURE and GNUTLS_CERT_SIGNER_NOT_FOUND ).
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 issuer is not included in the trusted certificate list.
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.
GNUTLS_CERT_SIGNATURE_FAILURE: The signature verification failed.
GNUTLS_CERT_REVOCATION_DATA_SUPERSEDED: The revocation data are old and have been superseded.
GNUTLS_CERT_UNEXPECTED_OWNER: The owner is not the expected one.
GNUTLS_CERT_REVOCATION_DATA_ISSUED_IN_FUTURE: The revocation data have a future issue date.
GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE: The certificate’s signer constraints were violated.
GNUTLS_CERT_MISMATCH: The certificate presented isn’t the expected one (TOFU)

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.