Next: , Previous: , Up: Using GnuTLS as a cryptographic library   [Contents][Index]


8.2 Public key algorithms

Public key cryptography algorithms such as RSA, DSA and ECDSA, can be accessed using the abstract key API in Abstract key types. This is a high level API with the advantage of transparently handling keys in memory and keys present in smart cards.

8.2.1 PKCS #7 signing

The PKCS #7 format is common format used for digital signatures. It allows to sign by embedding the data into the signature, or creating detached signatures of the data, including a timestamp, additional certificates etc. In certain cases this format is also used to transport lists of certificates and CRLs.

The basic functions to initialize, deinitialize, import, export or print information about a PKCS #7 structure are shown 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

GNUTLS_PKCS7_EMBED_DATA

The signed data will be embedded in the structure.

GNUTLS_PKCS7_INCLUDE_TIME

The signing time will be included in the structure.

GNUTLS_PKCS7_INCLUDE_CERT

The signer’s certificate will be included in the cert list.

GNUTLS_PKCS7_WRITE_SPKI

Use the signer’s key identifier instead of name.

Figure 8.2: Flags applicable to gnutls_pkcs7_sign()

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)

Next: , Previous: , Up: Using GnuTLS as a cryptographic library   [Contents][Index]