mbedtls_x509_crt_verify() function

Verify a chain of certificates. The verify callback is a user-supplied callback that can clear / modify / add flags for a certificate. If set, the verification callback is called for each certificate in the chain (from the trust-ca down to the presented crt). The parameters for the callback are: (void *parameter, mbedtls_x509_crt *crt, int certificate_depth, int *flags). With the flags representing current flags for that specific certificate and the certificate depth from the bottom (Peer cert depth = 0). All flags left after returning from the callback are also returned to the application. The function should return 0 for anything (including invalid certificates) other than fatal error, as a non-zero return code immediately aborts the verification process. For fatal errors, a specific error code should be used (different from MBEDTLS_ERR_X509_CERT_VERIFY_FAILED which should not be returned at this point), or MBEDTLS_ERR_X509_FATAL_ERROR can be used if no better code is available.

Syntax

Show:

Summary

Declaration

Definition

from x509_crt.h:670

int mbedtls_x509_crt_verify(mbedtls_x509_crt *crt, mbedtls_x509_crt *trust_ca, mbedtls_x509_crl *ca_crl, const char *cn, uint32_t *flags, int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), void *p_vrfy);

Implemented in x509_crt.c:3151

Arguments

Argument

Declared as

Description

crt

mbedtls_x509_crt *

The certificate chain to be verified.

trust_ca

mbedtls_x509_crt *

The list of trusted CAs.

ca_crl

mbedtls_x509_crl *

The list of CRLs for trusted CAs.

const char *

The expected Common Name. This will be checked to be present in the certificate's subjectAltNames extension or, if this extension is absent, as a CN component in its Subject name. DNS names and IP addresses are fully supported, while the URI subtype is partially supported: only exact matching, without any normalization procedures described in 7.4 of RFC5280, will result in a positive URI verification. This may be \c NULL if the CN need not be verified.

flags

uint32_t *

The address at which to store the result of the verification. If the verification couldn't be completed, the flag value is set to (uint32_t) -1.

f_vrfy

int (*)(void *, mbedtls_x509_crt *, int, uint32_t *)

The verification callback to use. See the documentation of mbedtls_x509_crt_verify() for more information.

p_vrfy

void *

The context to be passed to \p f_vrfy.

Return value

\c 0 if the chain is valid with respect to the passed CN, CAs, CRLs and security profile. #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the certificate chain verification failed. In this case, \c *flags will have one or more \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX flags set. Another negative error code in case of a fatal error encountered during the verification process.

Notes

In case verification failed, the results can be displayed using \c mbedtls_x509_crt_verify_info() Same as \c mbedtls_x509_crt_verify_with_profile() with the default security profile. It is your responsibility to provide up-to-date CRLs for all trusted CAs. If no CRL is provided for the CA that was used to sign the certificate, CRL verification is skipped silently, that is *without* setting any flag. The \c trust_ca list can contain two types of certificates: (1) those of trusted root CAs, so that certificates chaining up to those CAs will be trusted, and (2) self-signed end-entity certificates to be trusted (for specific peers you know) - in that case, the self-signed certificate doesn't need to have the CA bit set.