5.1.1 Public keys

An abstract gnutls_pubkey_t can be initialized and freed by using the functions below.

int gnutls_pubkey_init (gnutls_pubkey_t * key)

void gnutls_pubkey_deinit (gnutls_pubkey_t key)

After initialization its values can be imported from an existing structure like gnutls_x509_crt_t, or through an ASN.1 encoding of the X.509 SubjectPublicKeyInfo sequence.

int gnutls_pubkey_import_x509 (gnutls_pubkey_t key, gnutls_x509_crt_t crt, unsigned int flags)

int gnutls_pubkey_import_pkcs11 (gnutls_pubkey_t key, gnutls_pkcs11_obj_t obj, unsigned int flags)

int gnutls_pubkey_import_url (gnutls_pubkey_t key, const char * url, unsigned int flags)

int gnutls_pubkey_import_privkey (gnutls_pubkey_t key, gnutls_privkey_t pkey, unsigned int usage, unsigned int flags)

int gnutls_pubkey_import (gnutls_pubkey_t key, const gnutls_datum_t * data, gnutls_x509_crt_fmt_t format)

int gnutls_pubkey_export (gnutls_pubkey_t key, gnutls_x509_crt_fmt_t format, void * output_data, size_t * output_data_size)

Function: int gnutls_pubkey_export2 (gnutls_pubkey_t key, gnutls_x509_crt_fmt_t format, gnutls_datum_t * out)

key: Holds the certificate

format: the format of output params. One of PEM or DER.

out: will contain a certificate PEM or DER encoded

This function will export the public key to DER or PEM format. The contents of the exported data is the SubjectPublicKeyInfo X.509 structure.

The output buffer will be allocated using gnutls_malloc() .

If the structure is PEM encoded, it will have a header of "BEGIN CERTIFICATE".

Returns: In case of failure a negative error code will be returned, and 0 on success.

Since: 3.1.3

Other helper functions that allow directly importing from raw X.509 structures are shown below.

int gnutls_pubkey_import_x509_raw (gnutls_pubkey_t pkey, const gnutls_datum_t * data, gnutls_x509_crt_fmt_t format, unsigned int flags)

An important function is gnutls_pubkey_import_url which will import public keys from URLs that identify objects stored in tokens (see Smart cards and HSMs and Trusted Platform Module). A function to check for a supported by GnuTLS URL is gnutls_url_is_supported.

Function: unsigned gnutls_url_is_supported (const char * url)

url: A URI to be tested

Check whether the provided url is supported. Depending on the system libraries GnuTLS may support pkcs11, tpmkey or other URLs.

Returns: return non-zero if the given URL is supported, and zero if it is not known.

Since: 3.1.0

Additional functions are available that will return information over a public key, such as a unique key ID, as well as a function that given a public key fingerprint would provide a memorable sketch.

Note that gnutls_pubkey_get_key_id calculates a SHA1 digest of the public key as a DER-formatted, subjectPublicKeyInfo object. Other implementations use different approaches, e.g., some use the “common method” described in section 4.2.1.2 of [RFC5280] which calculates a digest on a part of the subjectPublicKeyInfo object.

int gnutls_pubkey_get_pk_algorithm (gnutls_pubkey_t key, unsigned int * bits)

int gnutls_pubkey_get_preferred_hash_algorithm (gnutls_pubkey_t key, gnutls_digest_algorithm_t * hash, unsigned int * mand)

int gnutls_pubkey_get_key_id (gnutls_pubkey_t key, unsigned int flags, unsigned char * output_data, size_t * output_data_size)

int gnutls_random_art (gnutls_random_art_t type, const char * key_type, unsigned int key_size, void * fpr, size_t fpr_size, gnutls_datum_t * art)

To export the key-specific parameters, or obtain a unique key ID the following functions are provided.

int gnutls_pubkey_export_rsa_raw2 (gnutls_pubkey_t key, gnutls_datum_t * m, gnutls_datum_t * e, unsigned flags)

int gnutls_pubkey_export_dsa_raw2 (gnutls_pubkey_t key, gnutls_datum_t * p, gnutls_datum_t * q, gnutls_datum_t * g, gnutls_datum_t * y, unsigned flags)

int gnutls_pubkey_export_ecc_raw2 (gnutls_pubkey_t key, gnutls_ecc_curve_t * curve, gnutls_datum_t * x, gnutls_datum_t * y, unsigned int flags)

int gnutls_pubkey_export_ecc_x962 (gnutls_pubkey_t key, gnutls_datum_t * parameters, gnutls_datum_t * ecpoint)