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.
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index 2e3e6e9..64ee66e 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -371,7 +371,7 @@
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 @@
* 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 @@
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 @@
* 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 @@
* 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