From ca8c3b434c39cc5f7e52c2553d54d8da3de69745 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Thu, 23 Aug 2018 15:46:33 +0100 Subject: [PATCH 1/3] Improve documentation of mbedtls_x509_crt_parse() Fixes #1883. --- include/mbedtls/x509_crt.h | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h index ac23cffe8..8f1cc0c9f 100644 --- a/include/mbedtls/x509_crt.h +++ b/include/mbedtls/x509_crt.h @@ -175,19 +175,34 @@ int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *bu size_t buflen ); /** - * \brief Parse one or more certificates and add them - * to the chained list. Parses permissively. If some - * certificates can be parsed, the result is the number - * of failed certificates it encountered. If none complete - * correctly, the first error is returned. + * \brief Parse one DER-encoded or multiple concatenated PEM-encoded + * certificates and add them to the chained list. * - * \param chain points to the start of the chain - * \param buf buffer holding the certificate data in PEM or DER format - * \param buflen size of the buffer - * (including the terminating null byte for PEM data) + * For PEM-encoded CRTs, the function parses permissively: + * If at least one certificate can be parsed, the function + * returns the number of certificates for which parsing failed + * (hence \c 0 if all certificates were parsed successfully). + * If no certificate could be parsed, the function returns + * the first (negative) error encountered during parsing. + * + * PEM encoded certificates may be interleaved by other data + * such as human readable descriptions of their content, as + * long as the certificates are enclosed in the PEM specific + * '-----{BEGIN/END} CERTIFICATE-----' delimiters. + * + * \param chain The chain to which to add the parsed certificates. + * \param buf The buffer holding the certificate data in PEM or DER format. + * For certificates in PEM encoding, this may be a concatenation + * of multiple certificates; for DER encoding, the buffer must + * comprise exactly one certificate. + * \param buflen The size of \p buf, including the terminating \c NULL byte + * in case of PEM encoded data. + * + * \return \c 0 if all certificates were parsed successfully. + * \return The (positive) number of certificates that couldn't + * be parsed if parsing was partly successful (see above). + * \return A negative X509- or PEM-specific error code otherwise. * - * \return 0 if all certificates parsed successfully, a positive number - * if partly successful or a specific X509 or PEM error code */ int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen ); From ca16cf67da8bbe1b674930ceb7aad9c14bc4c198 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Thu, 23 Aug 2018 16:14:00 +0100 Subject: [PATCH 2/3] Improve wording --- include/mbedtls/x509_crt.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h index 8f1cc0c9f..5482ea463 100644 --- a/include/mbedtls/x509_crt.h +++ b/include/mbedtls/x509_crt.h @@ -175,7 +175,7 @@ int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *bu size_t buflen ); /** - * \brief Parse one DER-encoded or multiple concatenated PEM-encoded + * \brief Parse one DER-encoded or one or more concatenated PEM-encoded * certificates and add them to the chained list. * * For PEM-encoded CRTs, the function parses permissively: @@ -201,7 +201,7 @@ int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *bu * \return \c 0 if all certificates were parsed successfully. * \return The (positive) number of certificates that couldn't * be parsed if parsing was partly successful (see above). - * \return A negative X509- or PEM-specific error code otherwise. + * \return A negative X509 or PEM error code otherwise. * */ int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen ); From 6728d3cfdbc311baf9c7645f5387aba6215a1c6f Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Fri, 24 Aug 2018 10:01:17 +0100 Subject: [PATCH 3/3] Improve documentation of mbedtls_x509_crt_parse() --- include/mbedtls/x509_crt.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h index 5482ea463..2c3c758e9 100644 --- a/include/mbedtls/x509_crt.h +++ b/include/mbedtls/x509_crt.h @@ -178,8 +178,8 @@ int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *bu * \brief Parse one DER-encoded or one or more concatenated PEM-encoded * certificates and add them to the chained list. * - * For PEM-encoded CRTs, the function parses permissively: - * If at least one certificate can be parsed, the function + * For CRTs in PEM encoding, the function parses permissively: + * if at least one certificate can be parsed, the function * returns the number of certificates for which parsing failed * (hence \c 0 if all certificates were parsed successfully). * If no certificate could be parsed, the function returns