Merge pull request #6709 from daverodgman/pkcs7-docs

Add warnings & disable PKCS #7 by default
This commit is contained in:
Dave Rodgman 2022-12-05 16:24:29 +00:00 committed by GitHub
commit 80f8c679c5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 37 additions and 19 deletions

View file

@ -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.

View file

@ -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

View file

@ -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,