From 902451db8bcac27b75b4ee200f62d77677ef9c0f Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Wed, 27 Mar 2019 11:48:40 +0000 Subject: [PATCH] Improve documentation of old X.509 CRT verification functions This commit applies the documentation improvements noticed and applied while adding the documentation for the new X.509 CRT verification API mbedtls_x509_crt_verify_with_cb() to the existing verification APIs. --- include/mbedtls/x509_crt.h | 94 +++++++++++++++++++++----------------- 1 file changed, 52 insertions(+), 42 deletions(-) diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h index 2e3e6e9a1e..64ee66e55c 100644 --- a/include/mbedtls/x509_crt.h +++ b/include/mbedtls/x509_crt.h @@ -371,7 +371,7 @@ int mbedtls_x509_crt_verify_info( char *buf, size_t size, const char *prefix, uint32_t flags ); /** - * \brief Verify the certificate signature + * \brief Verify a chain of certificates. * * The verify callback is a user-supplied callback that * can clear / modify / add flags for a certificate. If set, @@ -411,22 +411,25 @@ int mbedtls_x509_crt_verify_info( char *buf, size_t size, const char *prefix, * specific peers you know) - in that case, the self-signed * certificate doesn't need to have the CA bit set. * - * \param crt a certificate (chain) to be verified - * \param trust_ca the list of trusted CAs (see note above) - * \param ca_crl the list of CRLs for trusted CAs (see note above) - * \param cn expected Common Name (can be set to - * NULL if the CN must not be verified) - * \param flags result of the verification - * \param f_vrfy verification function - * \param p_vrfy verification parameter + * \param crt The certificate chain to be verified. + * \param trust_ca The list of trusted CAs. + * \param ca_crl The list of CRLs for trusted CAs. + * \param cn The expected Common Name. This may be \c NULL if the + * CN need not be verified. + * \param flags The address at which to store the result of the verification. + * \param f_vrfy The verification callback to use. See the documentation + * of mbedtls_x509_crt_verify() for more information. + * \param p_vrfy The context to be passed to \p f_vrfy. * - * \return 0 (and flags set to 0) if the chain was verified and valid, - * MBEDTLS_ERR_X509_CERT_VERIFY_FAILED if the chain was verified - * but found to be invalid, in which case *flags will have one - * or more MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX - * flags set, or another error (and flags set to 0xffffffff) - * in case of a fatal error encountered during the - * verification process. + * \return \c 0 if the chain is valid with respect to the + * passed CN, CAs, CRLs and security profile. + * \return #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. + * \return Another negative error code in case of a fatal error + * encountered during the verification process. */ int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt, mbedtls_x509_crt *trust_ca, @@ -436,7 +439,8 @@ int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt, void *p_vrfy ); /** - * \brief Verify the certificate signature according to profile + * \brief Verify a chain of certificates with respect to + * a configurable security profile. * * \note Same as \c mbedtls_x509_crt_verify(), but with explicit * security profile. @@ -445,22 +449,26 @@ int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt, * for ECDSA) apply to all certificates: trusted root, * intermediate CAs if any, and end entity certificate. * - * \param crt a certificate (chain) to be verified - * \param trust_ca the list of trusted CAs - * \param ca_crl the list of CRLs for trusted CAs - * \param profile security profile for verification - * \param cn expected Common Name (can be set to - * NULL if the CN must not be verified) - * \param flags result of the verification - * \param f_vrfy verification function - * \param p_vrfy verification parameter + * \param crt The certificate chain to be verified. + * \param trust_ca The list of trusted CAs. + * \param ca_crl The list of CRLs for trusted CAs. + * \param profile The security profile to use for the verification. + * \param cn The expected Common Name. This may be \c NULL if the + * CN need not be verified. + * \param flags The address at which to store the result of the verification. + * \param f_vrfy The verification callback to use. See the documentation + * of mbedtls_x509_crt_verify() for more information. + * \param p_vrfy The context to be passed to \p f_vrfy. * - * \return 0 if successful or MBEDTLS_ERR_X509_CERT_VERIFY_FAILED - * in which case *flags will have one or more - * MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX flags - * set, - * or another error in case of a fatal error encountered - * during the verification process. + * \return \c 0 if the chain is valid with respect to the + * passed CN, CAs, CRLs and security profile. + * \return #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. + * \return Another negative error code in case of a fatal error + * encountered during the verification process. */ int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt, mbedtls_x509_crt *trust_ca, @@ -477,16 +485,18 @@ int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt, * but can return early and restart according to the limit * set with \c mbedtls_ecp_set_max_ops() to reduce blocking. * - * \param crt a certificate (chain) to be verified - * \param trust_ca the list of trusted CAs - * \param ca_crl the list of CRLs for trusted CAs - * \param profile security profile for verification - * \param cn expected Common Name (can be set to - * NULL if the CN must not be verified) - * \param flags result of the verification - * \param f_vrfy verification function - * \param p_vrfy verification parameter - * \param rs_ctx restart context (NULL to disable restart) + * \param crt The certificate chain to be verified. + * \param trust_ca The list of trusted CAs. + * \param ca_crl The list of CRLs for trusted CAs. + * \param profile The security profile to use for the verification. + * \param cn The expected Common Name. This may be \c NULL if the + * CN need not be verified. + * \param flags The address at which to store the result of the verification. + * \param f_vrfy The verification callback to use. See the documentation + * of mbedtls_x509_crt_verify() for more information. + * \param p_vrfy The context to be passed to \p f_vrfy. + * \param rs_ctx The restart context to use. This may be set to \c NULL + * to disable restartable ECC. * * \return See \c mbedtls_crt_verify_with_profile(), or * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of