From 95a3c6e6d10eacb2df376bb943416989f62ed442 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 28 Jan 2016 17:27:45 +0100 Subject: [PATCH] x509: rework documentation for verify() - reduce redundancy between verify() and _with_profile() for readability and maintainability - improve description of parameters --- include/mbedtls/x509_crt.h | 82 +++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 40 deletions(-) diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h index 27662e1dc..a5c1b8eec 100644 --- a/include/mbedtls/x509_crt.h +++ b/include/mbedtls/x509_crt.h @@ -251,41 +251,22 @@ int mbedtls_x509_crt_verify_info( char *buf, size_t size, const char *prefix, /** * \brief Verify the certificate signature * - * 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 but a fatal error. - * - * \note In case verification failed, the results can be displayed - * using \c mbedtls_x509_crt_verify_info() - * * \note Same as \c mbedtls_x509_crt_verify_with_profile() with the - * default security profile. + * default security profile, so see that function for details. * - * \param crt a certificate to be verified - * \param trust_ca the trusted CA chain - * \param ca_crl the CRL chain for trusted CA's - * \param exp_name expected Common Name (can be set to - * NULL if the CN must not be verified) + * \param crt a certificate (chain) to be verified + * Must start with the end entity certificate, then + * intermediate CA certificates if any. + * \param trust_ca the list of trusted root CAs + * \param ca_crl the list of CRLs for trusted CAs + * \param exp_name expected name to be checked against the subjectAltName + * extension if present, or the Common Name of the Subject. + * Usually a DNS name; see note below for other name types. * \param flags result of the verification - * \param f_vrfy verification function - * \param p_vrfy verification parameter + * \param f_vrfy verification callback + * \param p_vrfy context for the verification callback * - * \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 see \c mbedtls_x509_crt_verify_with_profile() */ int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt, mbedtls_x509_crt *trust_ca, @@ -300,19 +281,40 @@ int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt, * \note Same as \c mbedtls_x509_crt_verify(), but with explicit * security profile. * + * \note In case verification failed, the results can be displayed + * using \c mbedtls_x509_crt_verify_info() + * + * \note 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 *context, 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 but + * a fatal error. + * + * \param crt a certificate (chain) to be verified + * Must start with the end entity certificate, then + * intermediate CA certificates if any. + * \param trust_ca the list of trusted root CAs + * \param ca_crl the list of CRLs for trusted CAs + * \param profile security profile for verification, see note below + * \param exp_name expected name to be checked against the subjectAltName + * extension if present, or the Common Name of the Subject. + * Usually a DNS name; see note below for other name types. + * \param flags result of the verification + * \param f_vrfy verification callback + * \param p_vrfy context for the verification callback + * * \note The restrictions on keys (RSA minimum size, allowed curves * for ECDSA) apply to all certificates: trusted root, * intermediate CAs if any, and end entity certificate. * - * \param crt a certificate to be verified - * \param trust_ca the trusted CA chain - * \param ca_crl the CRL chain for trusted CA's - * \param profile security profile for verification - * \param exp_name 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 + * \note TODO: IP addresses in exp_name * * \return 0 if successful or MBEDTLS_ERR_X509_CERT_VERIFY_FAILED * in which case *flags will have one or more