5.2 System and application-specific keys

5.2.1 System-specific keys

In several systems there are keystores which allow to read, store and use certificates and private keys. For these systems GnuTLS provides the system-key API in gnutls/system-keys.h. That API provides the ability to iterate through all stored keys, add and delete keys as well as use these keys using a URL which starts with "system:". The format of the URLs is system-specific. The systemkey tool is also provided to assist in listing keys and debugging.

The systems supported via this API are the following.

• Windows Cryptography API (CNG)

Function: int gnutls_system_key_iter_get_info (gnutls_system_key_iter_t * iter, unsigned cert_type, char ** cert_url, char ** key_url, char ** label, gnutls_datum_t * der, unsigned int flags)

iter: an iterator of the system keys (must be set to NULL initially)

cert_type: A value of gnutls_certificate_type_t which indicates the type of certificate to look for

cert_url: The certificate URL of the pair (may be NULL )

key_url: The key URL of the pair (may be NULL )

label: The friendly name (if any) of the pair (may be NULL )

der: if non-NULL the DER data of the certificate

flags: should be zero

This function will return on each call a certificate and key pair URLs, as well as a label associated with them, and the DER-encoded certificate. When the iteration is complete it will return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE .

Typically cert_type should be GNUTLS_CRT_X509 .

All values set are allocated and must be cleared using gnutls_free() ,

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

Since: 3.4.0

void gnutls_system_key_iter_deinit (gnutls_system_key_iter_t iter)

int gnutls_system_key_add_x509 (gnutls_x509_crt_t crt, gnutls_x509_privkey_t privkey, const char * label, char ** cert_url, char ** key_url)

int gnutls_system_key_delete (const char * cert_url, const char * key_url)

5.2.2 Application-specific keys

For systems where GnuTLS doesn’t provide a system specific store, it may often be desirable to define a custom class of keys that are identified via URLs and available to GnuTLS calls such as gnutls_certificate_set_x509_key_file2. Such keys can be registered using the API in gnutls/urls.h. The function which registers such keys is gnutls_register_custom_url.

Function: int gnutls_register_custom_url (const gnutls_custom_url_st * st)

st: A gnutls_custom_url_st structure

Register a custom URL. This will affect the following functions: gnutls_url_is_supported() , gnutls_privkey_import_url() , gnutls_pubkey_import_url, gnutls_x509_crt_import_url() and all functions that depend on them, e.g., gnutls_certificate_set_x509_key_file2() .

The provided structure and callback functions must be valid throughout the lifetime of the process. The registration of an existing URL type will fail with GNUTLS_E_INVALID_REQUEST . Since GnuTLS 3.5.0 this function can be used to override the builtin URLs.

This function is not thread safe.

Returns: returns zero if the given structure was imported or a negative value otherwise.

Since: 3.4.0

The input to this function are three callback functions as well as the prefix of the URL, (e.g., "mypkcs11:") and the length of the prefix. The types of the callbacks are shown below, and are expected to use the exported gnutls functions to import the keys and certificates. E.g., a typical import_key callback should use gnutls_privkey_import_ext4.

typedef int (*gnutls_privkey_import_url_func)(gnutls_privkey_t pkey,
                                              const char *url,
                                              unsigned flags);

typedef int (*gnutls_x509_crt_import_url_func)(gnutls_x509_crt_t pkey,
                                               const char *url,
                                               unsigned flags);

/* The following callbacks are optional */

/* This is to enable gnutls_pubkey_import_url() */
typedef int (*gnutls_pubkey_import_url_func)(gnutls_pubkey_t pkey,
					     const char *url, unsigned flags);

/* This is to allow constructing a certificate chain. It will be provided
 * the initial certificate URL and the certificate to find its issuer, and must
 * return zero and the DER encoding of the issuer's certificate. If not available,
 * it should return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE. */
typedef int (*gnutls_get_raw_issuer_func)(const char *url, gnutls_x509_crt_t crt,
					  gnutls_datum_t *issuer_der, unsigned flags);

typedef struct custom_url_st {
        const char *name;
        unsigned name_size;
        gnutls_privkey_import_url_func import_key;
        gnutls_x509_crt_import_url_func import_crt;
        gnutls_pubkey_import_url_func import_pubkey;
	gnutls_get_raw_issuer_func get_issuer;
} gnutls_custom_url_st;