9.3 Cryptographic Message Syntax / PKCS7

The CMS or PKCS #7 format is a commonly used format for digital signatures. PKCS #7 is the name of the original standard when published by RSA, though today the standard is adopted by IETF under the name CMS.

The standards include multiple ways of signing a digital document, e.g., by embedding the data into the signature, or creating detached signatures of the data, including a timestamp, additional certificates etc. In certain cases the same format is also used to transport lists of certificates and CRLs.

It is a relatively popular standard to sign structures, and is being used to sign in PDF files, as well as for signing kernel modules and other structures.

In GnuTLS, the basic functions to initialize, deinitialize, import, export or print information about a PKCS #7 structure are listed below.

int gnutls_pkcs7_init (gnutls_pkcs7_t * pkcs7)

void gnutls_pkcs7_deinit (gnutls_pkcs7_t pkcs7)

int gnutls_pkcs7_export2 (gnutls_pkcs7_t pkcs7, gnutls_x509_crt_fmt_t format, gnutls_datum_t * out)

int gnutls_pkcs7_import (gnutls_pkcs7_t pkcs7, const gnutls_datum_t * data, gnutls_x509_crt_fmt_t format)

int gnutls_pkcs7_print (gnutls_pkcs7_t pkcs7, gnutls_certificate_print_formats_t format, gnutls_datum_t * out)

The following functions allow the verification of a structure using either a trust list, or individual certificates. The gnutls_pkcs7_sign function is the data signing function.

int gnutls_pkcs7_verify_direct (gnutls_pkcs7_t pkcs7, gnutls_x509_crt_t signer, unsigned idx, const gnutls_datum_t * data, unsigned flags)

int gnutls_pkcs7_verify (gnutls_pkcs7_t pkcs7, gnutls_x509_trust_list_t tl, gnutls_typed_vdata_st * vdata, unsigned int vdata_size, unsigned idx, const gnutls_datum_t * data, unsigned flags)

Function: int gnutls_pkcs7_sign (gnutls_pkcs7_t pkcs7, gnutls_x509_crt_t signer, gnutls_privkey_t signer_key, const gnutls_datum_t * data, gnutls_pkcs7_attrs_t signed_attrs, gnutls_pkcs7_attrs_t unsigned_attrs, gnutls_digest_algorithm_t dig, unsigned flags)

pkcs7: should contain a gnutls_pkcs7_t type

signer: the certificate to sign the structure

signer_key: the key to sign the structure

data: The data to be signed or NULL if the data are already embedded

signed_attrs: Any additional attributes to be included in the signed ones (or NULL )

unsigned_attrs: Any additional attributes to be included in the unsigned ones (or NULL )

dig: The digest algorithm to use for signing

flags: Should be zero or one of GNUTLS_PKCS7 flags

This function will add a signature in the provided PKCS 7 structure for the provided data. Multiple signatures can be made with different signers.

The available flags are: GNUTLS_PKCS7_EMBED_DATA , GNUTLS_PKCS7_INCLUDE_TIME , GNUTLS_PKCS7_INCLUDE_CERT , and GNUTLS_PKCS7_WRITE_SPKI . They are explained in the gnutls_pkcs7_sign_flags definition.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Since: 3.4.2

Other helper functions which allow to access the signatures, or certificates attached in the structure are listed below.

int gnutls_pkcs7_get_signature_count (gnutls_pkcs7_t pkcs7)

int gnutls_pkcs7_get_signature_info (gnutls_pkcs7_t pkcs7, unsigned idx, gnutls_pkcs7_signature_info_st * info)

int gnutls_pkcs7_get_crt_count (gnutls_pkcs7_t pkcs7)

int gnutls_pkcs7_get_crt_raw2 (gnutls_pkcs7_t pkcs7, unsigned indx, gnutls_datum_t * cert)

int gnutls_pkcs7_get_crl_count (gnutls_pkcs7_t pkcs7)

int gnutls_pkcs7_get_crl_raw2 (gnutls_pkcs7_t pkcs7, unsigned indx, gnutls_datum_t * crl)

To append certificates, or CRLs in the structure the following functions are provided.

int gnutls_pkcs7_set_crt_raw (gnutls_pkcs7_t pkcs7, const gnutls_datum_t * crt)

int gnutls_pkcs7_set_crt (gnutls_pkcs7_t pkcs7, gnutls_x509_crt_t crt)

int gnutls_pkcs7_set_crl_raw (gnutls_pkcs7_t pkcs7, const gnutls_datum_t * crl)

int gnutls_pkcs7_set_crl (gnutls_pkcs7_t pkcs7, gnutls_x509_crl_t crl)