Disable PKCS7 by default; improve docs
Signed-off-by: Dave Rodgman <dave.rodgman@arm.com>
diff --git a/ChangeLog.d/pkcs7-parser.txt b/ChangeLog.d/pkcs7-parser.txt
deleted file mode 100644
index 7f85f0c..0000000
--- 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 c719073..db28f06 100644
--- a/include/mbedtls/mbedtls_config.h
+++ b/include/mbedtls/mbedtls_config.h
@@ -2817,6 +2817,9 @@
/**
* \def MBEDTLS_PKCS7_C
*
+ * This feature is a work in progress and not ready for production. The API may
+ * change. Testing and validation is incomplete.
+ *
* Enable PKCS7 core for using PKCS7 formatted signatures.
* RFC Link - https://tools.ietf.org/html/rfc2315
*
@@ -2828,7 +2831,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 52895ac..59a5840 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 @@
*
* \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 @@
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 @@
* \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 signatures match, 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 @@
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 @@
* \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 signatures match, or a negative error code on failure.
*/
int mbedtls_pkcs7_signed_hash_verify( mbedtls_pkcs7 *pkcs7,
const mbedtls_x509_crt *cert,
