diff options
author | Dave Rodgman <dave.rodgman@arm.com> | 2022-12-05 16:24:29 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-12-05 16:24:29 +0000 |
commit | 80f8c679c5a8949c288314a07a9a4dcf31759b74 (patch) | |
tree | b4d8c43ae49376f067f9cb13e11a711ac0c52d78 | |
parent | e1cda441a0345e7e31f649a8915ba49dd5e3bbf1 (diff) | |
parent | dbcbf44d650cff6d84e3838068b56587a74f742c (diff) | |
download | mbedtls-80f8c679c5a8949c288314a07a9a4dcf31759b74.tar.gz |
Merge pull request #6709 from daverodgman/pkcs7-docs
Add warnings & disable PKCS #7 by default
-rw-r--r-- | ChangeLog.d/pkcs7-parser.txt | 13 | ||||
-rw-r--r-- | include/mbedtls/mbedtls_config.h | 6 | ||||
-rw-r--r-- | include/mbedtls/pkcs7.h | 37 |
3 files changed, 37 insertions, 19 deletions
diff --git a/ChangeLog.d/pkcs7-parser.txt b/ChangeLog.d/pkcs7-parser.txt deleted file mode 100644 index 7f85f0ce1..000000000 --- a/ChangeLog.d/pkcs7-parser.txt +++ /dev/null @@ -1,13 +0,0 @@ -Features - * Added partial support for parsing the PKCS7 cryptographic message syntax, - as defined in RFC 2315. Currently, support is limited to the following: - - Only the signed data content type, version 1 is supported. - - Only DER encoding is supported. - - Only a single digest algorithm per message is supported. - - Only 0 or 1, certificate is supported per message, which must be in - X509 format. - - There is no support for certificate-revocation lists. - - The authenticated and unauthenticated attribute fields of SignerInfo - must be empty. - Many thanks to Daniel Axtens, Nayna Jain, and Nick Child from IBM for - contributing this feature. diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index c719073c2..826ab6459 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -2817,6 +2817,10 @@ /** * \def MBEDTLS_PKCS7_C * + * This feature is a work in progress and not ready for production. Testing and + * validation is incomplete, and handling of malformed inputs may not be robust. + * The API may change. + * * Enable PKCS7 core for using PKCS7 formatted signatures. * RFC Link - https://tools.ietf.org/html/rfc2315 * @@ -2828,7 +2832,7 @@ * * This module is required for the PKCS7 parsing modules. */ -#define MBEDTLS_PKCS7_C +//#define MBEDTLS_PKCS7_C /** * \def MBEDTLS_PKCS12_C diff --git a/include/mbedtls/pkcs7.h b/include/mbedtls/pkcs7.h index 52895ac2b..79ab82fff 100644 --- a/include/mbedtls/pkcs7.h +++ b/include/mbedtls/pkcs7.h @@ -22,6 +22,11 @@ */ /** + * This feature is a work in progress and not ready for production. The API may + * change. Furthermore, please note that the implementation has only been + * validated with well-formed inputs, not yet with untrusted inputs (which is + * almost always the case in practice). + * * Note: For the time being, this implementation of the PKCS7 cryptographic * message syntax is a partial implementation of RFC 2315. * Differences include: @@ -179,7 +184,7 @@ void mbedtls_pkcs7_init( mbedtls_pkcs7 *pkcs7 ); * * \param pkcs7 The pkcs7 structure to be filled by parser for the output. * \param buf The buffer holding the DER encoded pkcs7. - * \param buflen The size in Bytes of \p buf. + * \param buflen The size in bytes of \p buf. * * \note This function makes an internal copy of the PKCS7 buffer * \p buf. In particular, \p buf may be destroyed or reused @@ -192,7 +197,18 @@ int mbedtls_pkcs7_parse_der( mbedtls_pkcs7 *pkcs7, const unsigned char *buf, const size_t buflen ); /** - * \brief Verification of PKCS7 signature. + * \brief Verification of PKCS7 signature against a caller-supplied + * certificate. + * + * For each signer in the PKCS structure, this function computes + * a signature over the supplied data, using the supplied + * certificate and the same digest algorithm as specified by the + * signer. It then compares this signature against the + * signer's signature; verification succeeds if any comparison + * matches. + * + * This function does not use the certificates held within the + * PKCS7 structure itself. * * \param pkcs7 PKCS7 structure containing signature. * \param cert Certificate containing key to verify signature. @@ -202,7 +218,7 @@ int mbedtls_pkcs7_parse_der( mbedtls_pkcs7 *pkcs7, const unsigned char *buf, * \note This function internally calculates the hash on the supplied * plain data for signature verification. * - * \return A negative error code on failure. + * \return 0 if the signature verifies, or a negative error code on failure. */ int mbedtls_pkcs7_signed_data_verify( mbedtls_pkcs7 *pkcs7, const mbedtls_x509_crt *cert, @@ -210,7 +226,18 @@ int mbedtls_pkcs7_signed_data_verify( mbedtls_pkcs7 *pkcs7, size_t datalen ); /** - * \brief Verification of PKCS7 signature. + * \brief Verification of PKCS7 signature against a caller-supplied + * certificate. + * + * For each signer in the PKCS structure, this function computes + * a signature over the supplied hash, using the supplied + * certificate and the same digest algorithm as specified by the + * signer. It then compares this signature against the + * signer's signature; verification succeeds if any comparison + * matches. + * + * This function does not use the certificates held within the + * PKCS7 structure itself. * * \param pkcs7 PKCS7 structure containing signature. * \param cert Certificate containing key to verify signature. @@ -220,7 +247,7 @@ int mbedtls_pkcs7_signed_data_verify( mbedtls_pkcs7 *pkcs7, * \note This function is different from mbedtls_pkcs7_signed_data_verify() * in a way that it directly recieves the hash of the data. * - * \return A negative error code on failure. + * \return 0 if the signature verifies, or a negative error code on failure. */ int mbedtls_pkcs7_signed_hash_verify( mbedtls_pkcs7 *pkcs7, const mbedtls_x509_crt *cert, |