pkcs7.h File Reference

PKCS7 generic defines and structures https://tools.ietf.org/html/rfc2315. More...

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/asn1.h"
#include "mbedtls/x509.h"
#include "mbedtls/x509_crt.h"

Include dependency graph for pkcs7.h:

Go to the source code of this file.

Data Structures
struct	mbedtls_pkcs7_signer_info
struct	mbedtls_pkcs7_data
struct	mbedtls_pkcs7_signed_data
struct	mbedtls_pkcs7

Macros
PKCS7 Module Error codes
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: The RFC specifies 6 different content types. The only type currently supported in Mbed TLS is the signed data content type. The only supported PKCS7 Signed Data syntax version is version 1 The RFC specifies support for BER. This implementation is limited to DER only. The RFC specifies that multiple digest algorithms can be specified in the Signed Data type. Only one digest algorithm is supported in Mbed TLS. The RFC specifies the Signed Data type can contain multiple X509 or PKCS6 certificates. In Mbed TLS, this list can only contain 0 or 1 certificates and they must be in X509 format. The RFC specifies the Signed Data type can contain certificate-revocation lists (crls). This implementation has no support for crls so it is assumed to be an empty list. The RFC allows for SignerInfo structure to optionally contain unauthenticatedAttributes and authenticatedAttributes. In Mbed TLS it is assumed these fields are empty.
#define	MBEDTLS_ERR_PKCS7_INVALID_FORMAT   -0x5300
#define	MBEDTLS_ERR_PKCS7_FEATURE_UNAVAILABLE   -0x5380
#define	MBEDTLS_ERR_PKCS7_INVALID_VERSION   -0x5400
#define	MBEDTLS_ERR_PKCS7_INVALID_CONTENT_INFO   -0x5480
#define	MBEDTLS_ERR_PKCS7_INVALID_ALG   -0x5500
#define	MBEDTLS_ERR_PKCS7_INVALID_CERT   -0x5580
#define	MBEDTLS_ERR_PKCS7_INVALID_SIGNATURE   -0x5600
#define	MBEDTLS_ERR_PKCS7_INVALID_SIGNER_INFO   -0x5680
#define	MBEDTLS_ERR_PKCS7_BAD_INPUT_DATA   -0x5700
#define	MBEDTLS_ERR_PKCS7_ALLOC_FAILED   -0x5780
#define	MBEDTLS_ERR_PKCS7_VERIFY_FAIL   -0x5800
#define	MBEDTLS_ERR_PKCS7_CERT_DATE_INVALID   -0x5880

PKCS7 Supported Version
#define	MBEDTLS_PKCS7_SUPPORTED_VERSION   0x01
enum	mbedtls_pkcs7_type {   MBEDTLS_PKCS7_NONE =0 , MBEDTLS_PKCS7_DATA , MBEDTLS_PKCS7_SIGNED_DATA , MBEDTLS_PKCS7_ENVELOPED_DATA ,   MBEDTLS_PKCS7_SIGNED_AND_ENVELOPED_DATA , MBEDTLS_PKCS7_DIGESTED_DATA , MBEDTLS_PKCS7_ENCRYPTED_DATA }
typedef mbedtls_asn1_buf	mbedtls_pkcs7_buf
typedef mbedtls_asn1_named_data	mbedtls_pkcs7_name
typedef mbedtls_asn1_sequence	mbedtls_pkcs7_sequence
typedef struct mbedtls_pkcs7_signer_info	mbedtls_pkcs7_signer_info
typedef struct mbedtls_pkcs7_data	mbedtls_pkcs7_data
typedef struct mbedtls_pkcs7_signed_data	mbedtls_pkcs7_signed_data
typedef struct mbedtls_pkcs7	mbedtls_pkcs7
void	mbedtls_pkcs7_init (mbedtls_pkcs7 *pkcs7)
	Initialize pkcs7 structure. More...
int	mbedtls_pkcs7_parse_der (mbedtls_pkcs7 *pkcs7, const unsigned char *buf, const size_t buflen)
	Parse a single DER formatted pkcs7 content. More...
int	mbedtls_pkcs7_signed_data_verify (mbedtls_pkcs7 *pkcs7, const mbedtls_x509_crt *cert, const unsigned char *data, size_t datalen)
	Verification of PKCS7 signature against a caller-supplied certificate. More...
int	mbedtls_pkcs7_signed_hash_verify (mbedtls_pkcs7 *pkcs7, const mbedtls_x509_crt *cert, const unsigned char *hash, size_t hashlen)
	Verification of PKCS7 signature against a caller-supplied certificate. More...
void	mbedtls_pkcs7_free (mbedtls_pkcs7 *pkcs7)
	Unallocate all PKCS7 data and zeroize the memory. It doesn't free pkcs7 itself. It should be done by the caller. More...

Detailed Description

PKCS7 generic defines and structures https://tools.ietf.org/html/rfc2315.

Definition in file pkcs7.h.

Macro Definition Documentation

MBEDTLS_ERR_PKCS7_ALLOC_FAILED

#define MBEDTLS_ERR_PKCS7_ALLOC_FAILED   -0x5780

Allocation of memory failed.

Definition at line 75 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_BAD_INPUT_DATA

#define MBEDTLS_ERR_PKCS7_BAD_INPUT_DATA   -0x5700

Input invalid.

Definition at line 74 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_CERT_DATE_INVALID

#define MBEDTLS_ERR_PKCS7_CERT_DATE_INVALID   -0x5880

The PKCS7 date issued/expired dates are invalid

Definition at line 77 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_FEATURE_UNAVAILABLE

#define MBEDTLS_ERR_PKCS7_FEATURE_UNAVAILABLE   -0x5380

Unavailable feature, e.g. anything other than signed data.

Definition at line 67 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_INVALID_ALG

#define MBEDTLS_ERR_PKCS7_INVALID_ALG   -0x5500

The algorithm tag or value is invalid or cannot be parsed.

Definition at line 70 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_INVALID_CERT

#define MBEDTLS_ERR_PKCS7_INVALID_CERT   -0x5580

The certificate tag or value is invalid or cannot be parsed.

Definition at line 71 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_INVALID_CONTENT_INFO

#define MBEDTLS_ERR_PKCS7_INVALID_CONTENT_INFO   -0x5480

The PKCS7 content info invalid or cannot be parsed.

Definition at line 69 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_INVALID_FORMAT

#define MBEDTLS_ERR_PKCS7_INVALID_FORMAT   -0x5300

The format is invalid, e.g. different type expected.

Definition at line 66 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_INVALID_SIGNATURE

#define MBEDTLS_ERR_PKCS7_INVALID_SIGNATURE   -0x5600

Error parsing the signature

Definition at line 72 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_INVALID_SIGNER_INFO

#define MBEDTLS_ERR_PKCS7_INVALID_SIGNER_INFO   -0x5680

Error parsing the signer's info

Definition at line 73 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_INVALID_VERSION

#define MBEDTLS_ERR_PKCS7_INVALID_VERSION   -0x5400

The PKCS7 version element is invalid or cannot be parsed.

Definition at line 68 of file pkcs7.h.

MBEDTLS_ERR_PKCS7_VERIFY_FAIL

#define MBEDTLS_ERR_PKCS7_VERIFY_FAIL   -0x5800

Verification Failed

Definition at line 76 of file pkcs7.h.

MBEDTLS_PKCS7_SUPPORTED_VERSION

#define MBEDTLS_PKCS7_SUPPORTED_VERSION   0x01

Definition at line 84 of file pkcs7.h.

Typedef Documentation

mbedtls_pkcs7

typedef struct mbedtls_pkcs7 mbedtls_pkcs7

Structure holding PKCS7 structure, only signed data for now

mbedtls_pkcs7_buf

typedef mbedtls_asn1_buf mbedtls_pkcs7_buf

Type-length-value structure that allows for ASN1 using DER.

Definition at line 94 of file pkcs7.h.

mbedtls_pkcs7_data

typedef struct mbedtls_pkcs7_data mbedtls_pkcs7_data

Structure holding attached data as part of PKCS7 signed data format

mbedtls_pkcs7_name

typedef mbedtls_asn1_named_data mbedtls_pkcs7_name

Container for ASN1 named information objects. It allows for Relative Distinguished Names (e.g. cn=localhost,ou=code,etc.).

Definition at line 100 of file pkcs7.h.

mbedtls_pkcs7_sequence

typedef mbedtls_asn1_sequence mbedtls_pkcs7_sequence

Container for a sequence of ASN.1 items

Definition at line 105 of file pkcs7.h.

mbedtls_pkcs7_signed_data

typedef struct mbedtls_pkcs7_signed_data mbedtls_pkcs7_signed_data

Structure holding the signed data section

mbedtls_pkcs7_signer_info

typedef struct mbedtls_pkcs7_signer_info mbedtls_pkcs7_signer_info

Structure holding PKCS7 signer info

Enumeration Type Documentation

mbedtls_pkcs7_type

enum mbedtls_pkcs7_type

PKCS7 types

Enumerator
MBEDTLS_PKCS7_NONE
MBEDTLS_PKCS7_DATA
MBEDTLS_PKCS7_SIGNED_DATA
MBEDTLS_PKCS7_ENVELOPED_DATA
MBEDTLS_PKCS7_SIGNED_AND_ENVELOPED_DATA
MBEDTLS_PKCS7_DIGESTED_DATA
MBEDTLS_PKCS7_ENCRYPTED_DATA

Definition at line 110 of file pkcs7.h.

Function Documentation

mbedtls_pkcs7_free()

void mbedtls_pkcs7_free

(

mbedtls_pkcs7 *

pkcs7

)

Unallocate all PKCS7 data and zeroize the memory. It doesn't free pkcs7 itself. It should be done by the caller.

Parameters

pkcs7

PKCS7 structure to free.

mbedtls_pkcs7_init()

void mbedtls_pkcs7_init

(

mbedtls_pkcs7 *

pkcs7

)

Initialize pkcs7 structure.

Parameters

pkcs7

pkcs7 structure.

mbedtls_pkcs7_parse_der()

int mbedtls_pkcs7_parse_der	(	mbedtls_pkcs7 *	pkcs7,
		const unsigned char *	buf,
		const size_t	buflen
	)

Parse a single DER formatted pkcs7 content.

Parameters

pkcs7	The pkcs7 structure to be filled by parser for the output.
buf	The buffer holding the DER encoded pkcs7.
buflen	The size in bytes of buf.

Note

This function makes an internal copy of the PKCS7 buffer buf. In particular, buf may be destroyed or reused after this call returns.

Returns

The mbedtls_pkcs7_type of buf, if successful.

A negative error code on failure.

mbedtls_pkcs7_signed_data_verify()

int mbedtls_pkcs7_signed_data_verify	(	mbedtls_pkcs7 *	pkcs7,
		const mbedtls_x509_crt *	cert,
		const unsigned char *	data,
		size_t	datalen
	)

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.

Parameters

pkcs7	PKCS7 structure containing signature.
cert	Certificate containing key to verify signature.
data	Plain data on which signature has to be verified.
datalen	Length of the data.

Note

This function internally calculates the hash on the supplied plain data for signature verification.

Returns

0 if the signature verifies, or a negative error code on failure.

mbedtls_pkcs7_signed_hash_verify()

int mbedtls_pkcs7_signed_hash_verify	(	mbedtls_pkcs7 *	pkcs7,
		const mbedtls_x509_crt *	cert,
		const unsigned char *	hash,
		size_t	hashlen
	)

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.

Parameters

pkcs7	PKCS7 structure containing signature.
cert	Certificate containing key to verify signature.
hash	Hash of the plain data on which signature has to be verified.
hashlen	Length of the hash.

Note

This function is different from mbedtls_pkcs7_signed_data_verify() in a way that it directly receives the hash of the data.

Returns

0 if the signature verifies, or a negative error code on failure.