cuberite/polarssl
1
0
Fork 0
mirror of https://github.com/cuberite/polarssl.git synced 2025-11-04 04:32:24 -05:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation of old X.509 CRT verification functions

Browse Source 
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.
This commit is contained in:
Hanno Becker 2019-03-27 11:48:40 +00:00
parent 5c8df78feb
commit 902451db8b
1 changed files with 52 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
include/mbedtls/x509_crt.h
View File

@ -371,7 +371,7 @@ int mbedtls_x509_crt_verify_info( char *buf, size_t size, const char *prefix,
uint32_t flags ); uint32_t flags );
/** /**
* \brief Verify the certificate signature * \brief Verify a chain of certificates.
* *
* The verify callback is a user-supplied callback that * The verify callback is a user-supplied callback that
* can clear / modify / add flags for a certificate. If set, * 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 * specific peers you know) - in that case, the self-signed
* certificate doesn't need to have the CA bit set. * certificate doesn't need to have the CA bit set.
* *
* \param crt a certificate (chain) to be verified * \param crt The certificate chain to be verified.
* \param trust_ca the list of trusted CAs (see note above) * \param trust_ca The list of trusted CAs.
* \param ca_crl the list of CRLs for trusted CAs (see note above) * \param ca_crl The list of CRLs for trusted CAs.
* \param cn expected Common Name (can be set to * \param cn The expected Common Name. This may be \c NULL if the
* NULL if the CN must not be verified) * CN need not be verified.
* \param flags result of the verification * \param flags The address at which to store the result of the verification.
* \param f_vrfy verification function * \param f_vrfy The verification callback to use. See the documentation
* \param p_vrfy verification parameter * 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, * \return \c 0 if the chain is valid with respect to the
* MBEDTLS_ERR_X509_CERT_VERIFY_FAILED if the chain was verified * passed CN, CAs, CRLs and security profile.
* but found to be invalid, in which case *flags will have one * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
* or more MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX * certificate chain verification failed. In this case,
* flags set, or another error (and flags set to 0xffffffff) * \c *flags will have one or more
* in case of a fatal error encountered during the * \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX
* verification process. * 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, int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt,
mbedtls_x509_crt *trust_ca, mbedtls_x509_crt *trust_ca,
@ -436,7 +439,8 @@ int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt,
void *p_vrfy ); 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 * \note Same as \c mbedtls_x509_crt_verify(), but with explicit
* security profile. * security profile.
@ -445,22 +449,26 @@ int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt,
* for ECDSA) apply to all certificates: trusted root, * for ECDSA) apply to all certificates: trusted root,
* intermediate CAs if any, and end entity certificate. * intermediate CAs if any, and end entity certificate.
* *
* \param crt a certificate (chain) to be verified * \param crt The certificate chain to be verified.
* \param trust_ca the list of trusted CAs * \param trust_ca The list of trusted CAs.
* \param ca_crl the list of CRLs for trusted CAs * \param ca_crl The list of CRLs for trusted CAs.
* \param profile security profile for verification * \param profile The security profile to use for the verification.
* \param cn expected Common Name (can be set to * \param cn The expected Common Name. This may be \c NULL if the
* NULL if the CN must not be verified) * CN need not be verified.
* \param flags result of the verification * \param flags The address at which to store the result of the verification.
* \param f_vrfy verification function * \param f_vrfy The verification callback to use. See the documentation
* \param p_vrfy verification parameter * 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 * \return \c 0 if the chain is valid with respect to the
* in which case *flags will have one or more * passed CN, CAs, CRLs and security profile.
* MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX flags * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
* set, * certificate chain verification failed. In this case,
* or another error in case of a fatal error encountered * \c *flags will have one or more
* during the verification process. * \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, int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt,
mbedtls_x509_crt *trust_ca, 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 * but can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking. * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
* *
* \param crt a certificate (chain) to be verified * \param crt The certificate chain to be verified.
* \param trust_ca the list of trusted CAs * \param trust_ca The list of trusted CAs.
* \param ca_crl the list of CRLs for trusted CAs * \param ca_crl The list of CRLs for trusted CAs.
* \param profile security profile for verification * \param profile The security profile to use for the verification.
* \param cn expected Common Name (can be set to * \param cn The expected Common Name. This may be \c NULL if the
* NULL if the CN must not be verified) * CN need not be verified.
* \param flags result of the verification * \param flags The address at which to store the result of the verification.
* \param f_vrfy verification function * \param f_vrfy The verification callback to use. See the documentation
* \param p_vrfy verification parameter * of mbedtls_x509_crt_verify() for more information.
* \param rs_ctx restart context (NULL to disable restart) * \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 See \c mbedtls_crt_verify_with_profile(), or
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of