include/mbedtls/pkcs7.h

0001 /**
0002  * \file pkcs7.h
0003  *
0004  * \brief PKCS #7 generic defines and structures
0005  *  https://tools.ietf.org/html/rfc2315
0006  */
0007 /*
0008  *  Copyright The Mbed TLS Contributors
0009  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0010  */
0011
0012 /**
0013  * Note: For the time being, this implementation of the PKCS #7 cryptographic
0014  * message syntax is a partial implementation of RFC 2315.
0015  * Differences include:
0016  *  - The RFC specifies 6 different content types. The only type currently
0017  *    supported in Mbed TLS is the signed-data content type.
0018  *  - The only supported PKCS #7 Signed Data syntax version is version 1
0019  *  - The RFC specifies support for BER. This implementation is limited to
0020  *    DER only.
0021  *  - The RFC specifies that multiple digest algorithms can be specified
0022  *    in the Signed Data type. Only one digest algorithm is supported in Mbed TLS.
0023  *  - The RFC specifies the Signed Data type can contain multiple X.509 or PKCS #6 extended
0024  *    certificates. In Mbed TLS, this list can only contain 0 or 1 certificates
0025  *    and they must be in X.509 format.
0026  *  - The RFC specifies the Signed Data type can contain
0027  *    certificate-revocation lists (CRLs). This implementation has no support
0028  *    for CRLs so it is assumed to be an empty list.
0029  *  - The RFC allows for SignerInfo structure to optionally contain
0030  *    unauthenticatedAttributes and authenticatedAttributes. In Mbed TLS it is
0031  *    assumed these fields are empty.
0032  *  - The RFC allows for the signed Data type to contain contentInfo. This
0033  *    implementation assumes the type is DATA and the content is empty.
0034  */
0035
0036 #ifndef MBEDTLS_PKCS7_H
0037 #define MBEDTLS_PKCS7_H
0038
0039 #include "mbedtls/private_access.h"
0040
0041 #include "mbedtls/build_info.h"
0042
0043 #include "mbedtls/asn1.h"
0044 #include "mbedtls/x509_crt.h"
0045
0046 /**
0047  * \name PKCS #7 Module Error codes
0048  * \{
0049  */
0050 #define MBEDTLS_ERR_PKCS7_INVALID_FORMAT                   -0x5300  /**< The format is invalid, e.g. different type expected. */
0051 #define MBEDTLS_ERR_PKCS7_FEATURE_UNAVAILABLE              -0x5380  /**< Unavailable feature, e.g. anything other than signed data. */
0052 #define MBEDTLS_ERR_PKCS7_INVALID_VERSION                  -0x5400  /**< The PKCS #7 version element is invalid or cannot be parsed. */
0053 #define MBEDTLS_ERR_PKCS7_INVALID_CONTENT_INFO             -0x5480  /**< The PKCS #7 content info is invalid or cannot be parsed. */
0054 #define MBEDTLS_ERR_PKCS7_INVALID_ALG                      -0x5500  /**< The algorithm tag or value is invalid or cannot be parsed. */
0055 #define MBEDTLS_ERR_PKCS7_INVALID_CERT                     -0x5580  /**< The certificate tag or value is invalid or cannot be parsed. */
0056 #define MBEDTLS_ERR_PKCS7_INVALID_SIGNATURE                -0x5600  /**< Error parsing the signature */
0057 #define MBEDTLS_ERR_PKCS7_INVALID_SIGNER_INFO              -0x5680  /**< Error parsing the signer's info */
0058 #define MBEDTLS_ERR_PKCS7_BAD_INPUT_DATA                   -0x5700  /**< Input invalid. */
0059 #define MBEDTLS_ERR_PKCS7_ALLOC_FAILED                     -0x5780  /**< Allocation of memory failed. */
0060 #define MBEDTLS_ERR_PKCS7_VERIFY_FAIL                      -0x5800  /**< Verification Failed */
0061 #define MBEDTLS_ERR_PKCS7_CERT_DATE_INVALID                -0x5880  /**< The PKCS #7 date issued/expired dates are invalid */
0062 /* \} name */
0063
0064 /**
0065  * \name PKCS #7 Supported Version
0066  * \{
0067  */
0068 #define MBEDTLS_PKCS7_SUPPORTED_VERSION                           0x01
0069 /* \} name */
0070
0071 #ifdef __cplusplus
0072 extern "C" {
0073 #endif
0074
0075 /**
0076  * Type-length-value structure that allows for ASN.1 using DER.
0077  */
0078 typedef mbedtls_asn1_buf mbedtls_pkcs7_buf;
0079
0080 /**
0081  * Container for ASN.1 named information objects.
0082  * It allows for Relative Distinguished Names (e.g. cn=localhost,ou=code,etc.).
0083  */
0084 typedef mbedtls_asn1_named_data mbedtls_pkcs7_name;
0085
0086 /**
0087  * Container for a sequence of ASN.1 items
0088  */
0089 typedef mbedtls_asn1_sequence mbedtls_pkcs7_sequence;
0090
0091 /**
0092  * PKCS #7 types
0093  */
0094 typedef enum {
0095     MBEDTLS_PKCS7_NONE=0,
0096     MBEDTLS_PKCS7_DATA,
0097     MBEDTLS_PKCS7_SIGNED_DATA,
0098     MBEDTLS_PKCS7_ENVELOPED_DATA,
0099     MBEDTLS_PKCS7_SIGNED_AND_ENVELOPED_DATA,
0100     MBEDTLS_PKCS7_DIGESTED_DATA,
0101     MBEDTLS_PKCS7_ENCRYPTED_DATA,
0102 }
0103 mbedtls_pkcs7_type;
0104
0105 /**
0106  * Structure holding PKCS #7 signer info
0107  */
0108 typedef struct mbedtls_pkcs7_signer_info {
0109     int MBEDTLS_PRIVATE(version);
0110     mbedtls_x509_buf MBEDTLS_PRIVATE(serial);
0111     mbedtls_x509_name MBEDTLS_PRIVATE(issuer);
0112     mbedtls_x509_buf MBEDTLS_PRIVATE(issuer_raw);
0113     mbedtls_x509_buf MBEDTLS_PRIVATE(alg_identifier);
0114     mbedtls_x509_buf MBEDTLS_PRIVATE(sig_alg_identifier);
0115     mbedtls_x509_buf MBEDTLS_PRIVATE(sig);
0116     struct mbedtls_pkcs7_signer_info *MBEDTLS_PRIVATE(next);
0117 }
0118 mbedtls_pkcs7_signer_info;
0119
0120 /**
0121  * Structure holding the signed data section
0122  */
0123 typedef struct mbedtls_pkcs7_signed_data {
0124     int MBEDTLS_PRIVATE(version);
0125     mbedtls_pkcs7_buf MBEDTLS_PRIVATE(digest_alg_identifiers);
0126     int MBEDTLS_PRIVATE(no_of_certs);
0127     mbedtls_x509_crt MBEDTLS_PRIVATE(certs);
0128     int MBEDTLS_PRIVATE(no_of_crls);
0129     mbedtls_x509_crl MBEDTLS_PRIVATE(crl);
0130     int MBEDTLS_PRIVATE(no_of_signers);
0131     mbedtls_pkcs7_signer_info MBEDTLS_PRIVATE(signers);
0132 }
0133 mbedtls_pkcs7_signed_data;
0134
0135 /**
0136  * Structure holding PKCS #7 structure, only signed data for now
0137  */
0138 typedef struct mbedtls_pkcs7 {
0139     mbedtls_pkcs7_buf MBEDTLS_PRIVATE(raw);
0140     mbedtls_pkcs7_signed_data MBEDTLS_PRIVATE(signed_data);
0141 }
0142 mbedtls_pkcs7;
0143
0144 /**
0145  * \brief          Initialize mbedtls_pkcs7 structure.
0146  *
0147  * \param pkcs7    mbedtls_pkcs7 structure.
0148  */
0149 void mbedtls_pkcs7_init(mbedtls_pkcs7 *pkcs7);
0150
0151 /**
0152  * \brief          Parse a single DER formatted PKCS #7 detached signature.
0153  *
0154  * \param pkcs7    The mbedtls_pkcs7 structure to be filled by the parser.
0155  * \param buf      The buffer holding only the DER encoded PKCS #7 content.
0156  * \param buflen   The size in bytes of \p buf. The size must be exactly the
0157  *                 length of the DER encoded PKCS #7 content.
0158  *
0159  * \note           This function makes an internal copy of the PKCS #7 buffer
0160  *                 \p buf. In particular, \p buf may be destroyed or reused
0161  *                 after this call returns.
0162  * \note           Signatures with internal data are not supported.
0163  *
0164  * \return         The \c mbedtls_pkcs7_type of \p buf, if successful.
0165  * \return         A negative error code on failure.
0166  */
0167 int mbedtls_pkcs7_parse_der(mbedtls_pkcs7 *pkcs7, const unsigned char *buf,
0168                             const size_t buflen);
0169
0170 /**
0171  * \brief          Verification of PKCS #7 signature against a caller-supplied
0172  *                 certificate.
0173  *
0174  *                 For each signer in the PKCS structure, this function computes
0175  *                 a signature over the supplied data, using the supplied
0176  *                 certificate and the same digest algorithm as specified by the
0177  *                 signer. It then compares this signature against the
0178  *                 signer's signature; verification succeeds if any comparison
0179  *                 matches.
0180  *
0181  *                 This function does not use the certificates held within the
0182  *                 PKCS #7 structure itself, and does not check that the
0183  *                 certificate is signed by a trusted certification authority.
0184  *
0185  * \param pkcs7    mbedtls_pkcs7 structure containing signature.
0186  * \param cert     Certificate containing key to verify signature.
0187  * \param data     Plain data on which signature has to be verified.
0188  * \param datalen  Length of the data.
0189  *
0190  * \note           This function internally calculates the hash on the supplied
0191  *                 plain data for signature verification.
0192  *
0193  * \return         0 if the signature verifies, or a negative error code on failure.
0194  */
0195 int mbedtls_pkcs7_signed_data_verify(mbedtls_pkcs7 *pkcs7,
0196                                      const mbedtls_x509_crt *cert,
0197                                      const unsigned char *data,
0198                                      size_t datalen);
0199
0200 /**
0201  * \brief          Verification of PKCS #7 signature against a caller-supplied
0202  *                 certificate.
0203  *
0204  *                 For each signer in the PKCS structure, this function
0205  *                 validates a signature over the supplied hash, using the
0206  *                 supplied certificate and the same digest algorithm as
0207  *                 specified by the signer. Verification succeeds if any
0208  *                 signature is good.
0209  *
0210  *                 This function does not use the certificates held within the
0211  *                 PKCS #7 structure itself, and does not check that the
0212  *                 certificate is signed by a trusted certification authority.
0213  *
0214  * \param pkcs7    PKCS #7 structure containing signature.
0215  * \param cert     Certificate containing key to verify signature.
0216  * \param hash     Hash of the plain data on which signature has to be verified.
0217  * \param hashlen  Length of the hash.
0218  *
0219  * \note           This function is different from mbedtls_pkcs7_signed_data_verify()
0220  *                 in that it is directly passed the hash of the data.
0221  *
0222  * \return         0 if the signature verifies, or a negative error code on failure.
0223  */
0224 int mbedtls_pkcs7_signed_hash_verify(mbedtls_pkcs7 *pkcs7,
0225                                      const mbedtls_x509_crt *cert,
0226                                      const unsigned char *hash, size_t hashlen);
0227
0228 /**
0229  * \brief          Unallocate all PKCS #7 data and zeroize the memory.
0230  *                 It doesn't free \p pkcs7 itself. This should be done by the caller.
0231  *
0232  * \param pkcs7    mbedtls_pkcs7 structure to free.
0233  */
0234 void mbedtls_pkcs7_free(mbedtls_pkcs7 *pkcs7);
0235
0236 #ifdef __cplusplus
0237 }
0238 #endif
0239
0240 #endif /* pkcs7.h */