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)
pkcs7: should contain a
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
unsigned_attrs: Any additional attributes to be included in the unsigned ones (or
dig: The digest algorithm to use for signing
flags: Should be zero or one of
This function will add a signature in the provided PKCS
for the provided data. Multiple signatures can be made with different
The available flags are:
GNUTLS_PKCS7_WRITE_SPKI . They are explained in the
Returns: On success,
GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value.
The signed data will be embedded in the structure.
The signing time will be included in the structure.
The signer’s certificate will be included in the cert list.
Use the signer’s key identifier instead of name.
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)