Next: , Previous: , Up: X.509 certificates   [Contents][Index]

4.1.1.7 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, unsigned clist_size, unsigned int flags)

list: The list

clist: A list of CAs

clist_size: The length of the CA list

flags: flags from gnutls_trust_list_flags_t

This function will add the given certificate authorities to the trusted list. The CAs in clist must not be deinitialized during the lifetime of list .

If the flag GNUTLS_TL_NO_DUPLICATES is specified, then this function will ensure that no duplicates will be present in the final trust list.

If the flag GNUTLS_TL_NO_DUPLICATE_KEY is specified, then this function will ensure that no certificates with the same key are present in the final trust list.

If either GNUTLS_TL_NO_DUPLICATE_KEY or GNUTLS_TL_NO_DUPLICATES are given, gnutls_x509_trust_list_deinit() must be called with parameter all being 1.

Returns: The number of added elements is returned; that includes duplicate entries.

Since: 3.0.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 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 with gnutls_x509_trust_list_verify_named_crt() or gnutls_x509_trust_list_verify_crt2() - the latter only since GnuTLS 3.4.0 and if a hostname is provided.

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 cert must not be deinitialized during the lifetime of the list .

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

Since: 3.0.0

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

list: The list

crl_list: A list of CRLs

crl_size: The length of the CRL list

flags: flags from gnutls_trust_list_flags_t

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 CRLs in crl_list must not be deinitialized during the lifetime of list .

This function must be called after gnutls_x509_trust_list_add_cas() to allow verifying the CRLs for validity. If the flag GNUTLS_TL_NO_DUPLICATES is given, then the final CRL list will not contain duplicate entries.

If the flag GNUTLS_TL_NO_DUPLICATES is given, gnutls_x509_trust_list_deinit() must be called with parameter all being 1.

If flag GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added, and if verification fails, they will be skipped.

Returns: The number of added elements is returned; that includes duplicate entries.

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 * voutput, gnutls_verify_output_function func)

list: 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.

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

The details of the verification are the same as in gnutls_x509_trust_list_verify_crt2() .

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

Since: 3.0

Function: int gnutls_x509_trust_list_verify_crt2 (gnutls_x509_trust_list_t list, gnutls_x509_crt_t * cert_list, unsigned int cert_list_size, gnutls_typed_vdata_st * data, unsigned int elements, unsigned int flags, unsigned int * voutput, gnutls_verify_output_function func)

list: The list

cert_list: is the certificate list to be verified

cert_list_size: is the certificate list size

data: an array of typed data

elements: the number of data elements

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

voutput: will hold the certificate verification output.

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

This function will attempt to verify the given certificate chain and return its status. The voutput parameter will hold an OR’ed sequence of gnutls_certificate_status_t flags.

When a certificate chain of cert_list_size with more than one certificates is provided, the verification status will apply to the first certificate in the chain that failed verification. The verification process starts from the end of the chain (from CA to end certificate). The first certificate in the chain must be the end-certificate while the rest of the members may be sorted or not.

Additionally a certificate verification profile can be specified from the ones in gnutls_certificate_verification_profiles_t by ORing the result of GNUTLS_PROFILE_TO_VFLAGS() to the verification flags.

Additional verification parameters are possible via the data types; the acceptable types are GNUTLS_DT_DNS_HOSTNAME , GNUTLS_DT_IP_ADDRESS and GNUTLS_DT_KEY_PURPOSE_OID . The former accepts as data a null-terminated hostname, and the latter a null-terminated object identifier (e.g., GNUTLS_KP_TLS_WWW_SERVER ). If a DNS hostname is provided then this function will compare the hostname in the end certificate against the given. If names do not match the GNUTLS_CERT_UNEXPECTED_OWNER status flag will be set. In addition it will consider certificates provided with gnutls_x509_trust_list_add_named_crt() .

If a key purpose OID is provided and the end-certificate contains the extended key usage PKIX extension, it will be required to match the provided OID or be marked for any purpose, otherwise verification will fail with GNUTLS_CERT_PURPOSE_MISMATCH status.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value. Note that verification failure will not result to an error code, only voutput will be updated.

Since: 3.3.8

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 * voutput, gnutls_verify_output_function func)

list: 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.

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

Additionally a certificate verification profile can be specified from the ones in gnutls_certificate_verification_profiles_t by ORing the result of GNUTLS_PROFILE_TO_VFLAGS() to the verification flags.

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

Since: 3.0.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 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: flags from gnutls_trust_list_flags_t

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. PKCS 11 URLs are also accepted, instead of files, by this function. A PKCS 11 URL implies a trust database (a specially marked module in p11-kit); the URL "pkcs11:" implies all trust databases in the system. Only a single URL specifying trust databases can be set; they cannot be stacked with multiple calls.

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 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: flags from gnutls_trust_list_flags_t

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.

If this function is used gnutls_x509_trust_list_deinit() must be called with parameter all being 1.

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 systems this function returns GNUTLS_E_UNIMPLEMENTED_FEATURE .

This function implies the flag GNUTLS_TL_NO_DUPLICATES .

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)

GNUTLS_CERT_PURPOSE_MISMATCH

The certificate or an intermediate does not match the intended purpose (extended key usage).

GNUTLS_CERT_MISSING_OCSP_STATUS

The certificate requires the server to send the certificate status, but no status was received.

GNUTLS_CERT_INVALID_OCSP_STATUS

The received OCSP status response is invalid.

GNUTLS_CERT_UNKNOWN_CRIT_EXTENSIONS

The certificate has extensions marked as critical which are not supported.

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.

Next: , Previous: , Up: X.509 certificates   [Contents][Index]