gnutls_pkcs11_add_provider ()

int
gnutls_pkcs11_add_provider (const char *name,
                            const char *params);

This function will load and add a PKCS 11 module to the module list used in gnutls. After this function is called the module will be used for PKCS 11 operations.

When loading a module to be used for certificate verification, use the string 'trusted' as params .

Note that this function is not thread safe.

Since: 2.12.0

gnutls_pkcs11_copy_secret_key ()

int
gnutls_pkcs11_copy_secret_key (const char *token_url,
                               gnutls_datum_t *key,
                               const char *label,
                               unsigned int key_usage,
                               unsigned int flags);

This function will copy a raw secret (symmetric) key into a PKCS 11 token specified by a URL. The key can be marked as sensitive or not.

Since: 2.12.0

gnutls_pkcs11_copy_x509_crt ()

int
gnutls_pkcs11_copy_x509_crt (const char *token_url,
                             gnutls_x509_crt_t crt,
                             const char *label,
                             unsigned int flags);

This function will copy a certificate into a PKCS 11 token specified by a URL. The certificate can be marked as trusted or not.

Since: 2.12.0

gnutls_pkcs11_copy_x509_privkey ()

int
gnutls_pkcs11_copy_x509_privkey (const char *token_url,
                                 gnutls_x509_privkey_t key,
                                 const char *label,
                                 unsigned int key_usage,
                                 unsigned int flags);

This function will copy a private key into a PKCS 11 token specified by a URL. It is highly recommended flags to contain GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE unless there is a strong reason not to.

Since: 2.12.0

gnutls_pkcs11_deinit ()

void
gnutls_pkcs11_deinit (void);

This function will deinitialize the PKCS 11 subsystem in gnutls. This function is only needed if you need to deinitialize the subsystem without calling gnutls_global_deinit().

Since: 2.12.0

gnutls_pkcs11_delete_url ()

int
gnutls_pkcs11_delete_url (const char *object_url,
                          unsigned int flags);

This function will delete objects matching the given URL. Note that not all tokens support the delete operation.

Since: 2.12.0

gnutls_pkcs11_get_pin_function ()

gnutls_pin_callback_t
gnutls_pkcs11_get_pin_function (void **userdata);

This function will return the callback function set using gnutls_pkcs11_set_pin_function().

Since: 3.1.0

gnutls_pkcs11_init ()

int
gnutls_pkcs11_init (unsigned int flags,
                    const char *deprecated_config_file);

This function will initialize the PKCS 11 subsystem in gnutls. It will read configuration files if GNUTLS_PKCS11_FLAG_AUTO is used or allow you to independently load PKCS 11 modules using gnutls_pkcs11_add_provider() if GNUTLS_PKCS11_FLAG_MANUAL is specified.

You don't need to call this function since GnuTLS 3.3.0 because it is being called during the first request PKCS 11 operation. That call will assume the GNUTLS_PKCS11_FLAG_AUTO flag. If another flags are required then it must be called independently prior to any PKCS 11 operation.

Since: 2.12.0

gnutls_pkcs11_obj_deinit ()

void
gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t obj);

This function will deinitialize a certificate structure.

Since: 2.12.0

gnutls_pkcs11_obj_export ()

int
gnutls_pkcs11_obj_export (gnutls_pkcs11_obj_t obj,
                          void *output_data,
                          size_t *output_data_size);

This function will export the PKCS11 object data. It is normal for data to be inaccesible and in that case GNUTLS_E_INVALID_REQUEST will be returned.

If the buffer provided is not long enough to hold the output, then *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.

Since: 2.12.0

gnutls_pkcs11_obj_export2 ()

int
gnutls_pkcs11_obj_export2 (gnutls_pkcs11_obj_t obj,
                           gnutls_datum_t *out);

This function will export the PKCS11 object data. It is normal for data to be inaccesible and in that case GNUTLS_E_INVALID_REQUEST will be returned.

The output buffer is allocated using gnutls_malloc().

Since: 3.1.3

gnutls_pkcs11_obj_export_url ()

int
gnutls_pkcs11_obj_export_url (gnutls_pkcs11_obj_t obj,
                              gnutls_pkcs11_url_type_t detailed,
                              char **url);

This function will export a URL identifying the given object.

Since: 2.12.0

gnutls_pkcs11_obj_get_info ()

int
gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t crt,
                            gnutls_pkcs11_obj_info_t itype,
                            void *output,
                            size_t *output_size);

This function will return information about the PKCS11 certificate such as the label, id as well as token information where the key is stored. When output is text it returns null terminated string although output_size contains the size of the actual data only.

Since: 2.12.0

gnutls_pkcs11_obj_import_url ()

int
gnutls_pkcs11_obj_import_url (gnutls_pkcs11_obj_t obj,
                              const char *url,
                              unsigned int flags);

This function will "import" a PKCS 11 URL identifying an object (e.g. certificate) to the gnutls_pkcs11_obj_t type. This does not involve any parsing (such as X.509 or OpenPGP) since the gnutls_pkcs11_obj_t is format agnostic. Only data are transferred.

If the flag GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT is specified any certificate read, will have its extensions overwritten by any stapled extensions in the trust module.

Since: 2.12.0

gnutls_pkcs11_obj_init ()

int
gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t *obj);

This function will initialize a pkcs11 certificate structure.

Since: 2.12.0

gnutls_pkcs11_obj_list_import_url()

#define gnutls_pkcs11_obj_list_import_url(p_list, n_list, url, attrs, flags) gnutls_pkcs11_obj_list_import_url3(p_list, n_list, url, attrs|flags)

gnutls_pkcs11_obj_list_import_url2()

#define gnutls_pkcs11_obj_list_import_url2(p_list, n_list, url, attrs, flags) gnutls_pkcs11_obj_list_import_url4(p_list, n_list, url, attrs|flags)

gnutls_pkcs11_obj_set_pin_function ()

void
gnutls_pkcs11_obj_set_pin_function (gnutls_pkcs11_obj_t obj,
                                    gnutls_pin_callback_t fn,
                                    void *userdata);

This function will set a callback function to be used when required to access the object. This function overrides the global set using gnutls_pkcs11_set_pin_function().

Since: 3.1.0

gnutls_pkcs11_privkey_deinit ()

void
gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t key);

This function will deinitialize a private key structure.

gnutls_pkcs11_privkey_export_url ()

int
gnutls_pkcs11_privkey_export_url (gnutls_pkcs11_privkey_t key,
                                  gnutls_pkcs11_url_type_t detailed,
                                  char **url);

This function will export a URL identifying the given key.

gnutls_pkcs11_privkey_generate ()

int
gnutls_pkcs11_privkey_generate (const char *url,
                                gnutls_pk_algorithm_t pk,
                                unsigned int bits,
                                const char *label,
                                unsigned int flags);

This function will generate a private key in the specified by the url token. The private key will be generate within the token and will not be exportable.

Since: 3.0

gnutls_pkcs11_privkey_generate2 ()

int
gnutls_pkcs11_privkey_generate2 (const char *url,
                                 gnutls_pk_algorithm_t pk,
                                 unsigned int bits,
                                 const char *label,
                                 gnutls_x509_crt_fmt_t fmt,
                                 gnutls_datum_t *pubkey,
                                 unsigned int flags);

This function will generate a private key in the specified by the url token. The private key will be generate within the token and will not be exportable. This function will store the DER-encoded public key in the SubjectPublicKeyInfo format in pubkey . The pubkey should be deinitialized using gnutls_free().

Note that when generating an elliptic curve key, the curve can be substituted in the place of the bits parameter using the GNUTLS_CURVE_TO_BITS() macro.

Since: 3.1.5

gnutls_pkcs11_privkey_get_info ()

int
gnutls_pkcs11_privkey_get_info (gnutls_pkcs11_privkey_t pkey,
                                gnutls_pkcs11_obj_info_t itype,
                                void *output,
                                size_t *output_size);

This function will return information about the PKCS 11 private key such as the label, id as well as token information where the key is stored. When output is text it returns null terminated string although output_size contains the size of the actual data only.

gnutls_pkcs11_privkey_get_pk_algorithm ()

int
gnutls_pkcs11_privkey_get_pk_algorithm
                               (gnutls_pkcs11_privkey_t key,
                                unsigned int *bits);

This function will return the public key algorithm of a private key.

gnutls_pkcs11_privkey_import_url ()

int
gnutls_pkcs11_privkey_import_url (gnutls_pkcs11_privkey_t pkey,
                                  const char *url,
                                  unsigned int flags);

This function will "import" a PKCS 11 URL identifying a private key to the gnutls_pkcs11_privkey_t type. In reality since in most cases keys cannot be exported, the private key structure is being associated with the available operations on the token.

gnutls_pkcs11_privkey_init ()

int
gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t *key);

This function will initialize an private key structure. This structure can be used for accessing an underlying PKCS11 object.

In versions of GnuTLS later than 3.5.11 the object is protected using locks and a single gnutls_pkcs11_privkey_t can be re-used by many threads. However, for performance it is recommended to utilize one object per key per thread.

gnutls_pkcs11_privkey_set_pin_function ()

void
gnutls_pkcs11_privkey_set_pin_function
                               (gnutls_pkcs11_privkey_t key,
                                gnutls_pin_callback_t fn,
                                void *userdata);

This function will set a callback function to be used when required to access the object. This function overrides the global set using gnutls_pkcs11_set_pin_function().

Since: 3.1.0

gnutls_pkcs11_reinit ()

int
gnutls_pkcs11_reinit (void);

This function will reinitialize the PKCS 11 subsystem in gnutls. This is required by PKCS 11 when an application uses fork(). The reinitialization function must be called on the child.

Note that since GnuTLS 3.3.0, the reinitialization of the PKCS 11 subsystem occurs automatically after fork.

Since: 3.0

gnutls_pkcs11_set_pin_function ()

void
gnutls_pkcs11_set_pin_function (gnutls_pin_callback_t fn,
                                void *userdata);

This function will set a callback function to be used when a PIN is required for PKCS 11 operations. See gnutls_pin_callback_t() on how the callback should behave.

Since: 2.12.0

gnutls_pkcs11_set_token_function ()

void
gnutls_pkcs11_set_token_function (gnutls_pkcs11_token_callback_t fn,
                                  void *userdata);

This function will set a callback function to be used when a token needs to be inserted to continue PKCS 11 operations.

Since: 2.12.0

gnutls_pkcs11_token_callback_t ()

int
(*gnutls_pkcs11_token_callback_t) (void *const userdata,
                                   const char *const label,
                                   unsigned  retry);

Token callback function. The callback will be used to ask the user to re-insert the token with given (null terminated) label. The callback should return zero if token has been inserted by user and a negative error code otherwise. It might be called multiple times if the token is not detected and the retry counter will be increased.

Since: 2.12.0

gnutls_pkcs11_token_get_flags ()

int
gnutls_pkcs11_token_get_flags (const char *url,
                               unsigned int *flags);

This function will return information about the PKCS 11 token flags.

The supported flags are: GNUTLS_PKCS11_TOKEN_HW and GNUTLS_PKCS11_TOKEN_TRUSTED.

Since: 2.12.0

gnutls_pkcs11_token_get_info ()

int
gnutls_pkcs11_token_get_info (const char *url,
                              gnutls_pkcs11_token_info_t ttype,
                              void *output,
                              size_t *output_size);

This function will return information about the PKCS 11 token such as the label, id, etc.

Since: 2.12.0

gnutls_pkcs11_token_get_mechanism ()

int
gnutls_pkcs11_token_get_mechanism (const char *url,
                                   unsigned int idx,
                                   unsigned long *mechanism);

This function will return the names of the supported mechanisms by the token. It should be called with an increasing index until it return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE.

Since: 2.12.0

gnutls_pkcs11_token_get_url ()

int
gnutls_pkcs11_token_get_url (unsigned int seq,
                             gnutls_pkcs11_url_type_t detailed,
                             char **url);

This function will return the URL for each token available in system. The url has to be released using gnutls_free()

Since: 2.12.0

gnutls_pkcs11_token_init ()

int
gnutls_pkcs11_token_init (const char *token_url,
                          const char *so_pin,
                          const char *label);

This function will initialize (format) a token. If the token is at a factory defaults state the security officer's PIN given will be set to be the default. Otherwise it should match the officer's PIN.

gnutls_pkcs11_token_set_pin ()

int
gnutls_pkcs11_token_set_pin (const char *token_url,
                             const char *oldpin,
                             const char *newpin,
                             unsigned int flags);

This function will modify or set a user's PIN for the given token. If it is called to set a user pin for first time the oldpin must be NULL.

gnutls_pkcs11_type_get_name ()

const char *
gnutls_pkcs11_type_get_name (gnutls_pkcs11_obj_type_t type);

This function will return a human readable description of the PKCS11 object type obj . It will return "Unknown" for unknown types.

Since: 2.12.0

gnutls_x509_crt_import_pkcs11 ()

int
gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t crt,
                               gnutls_pkcs11_obj_t pkcs11_crt);

This function will import a PKCS 11 certificate to a gnutls_x509_crt_t structure.

Since: 2.12.0

gnutls_x509_crt_list_import_pkcs11 ()

int
gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t *certs,
                                    unsigned int cert_max,
                                    gnutls_pkcs11_obj_t * const objs,
                                    unsigned int flags);

This function will import a PKCS 11 certificate list to a list of gnutls_x509_crt_t type. These must not be initialized.

Since: 2.12.0

GNUTLS_PKCS11_FLAG_AUTO

#define GNUTLS_PKCS11_FLAG_AUTO 1 /* Automatically load libraries by reading /etc/gnutls/pkcs11.conf */

GNUTLS_PKCS11_FLAG_MANUAL

#define GNUTLS_PKCS11_FLAG_MANUAL 0 /* Manual loading of libraries */

GNUTLS_PKCS11_MAX_PIN_LEN

#define GNUTLS_PKCS11_MAX_PIN_LEN 32

GNUTLS_PKCS11_TOKEN_HW

#define GNUTLS_PKCS11_TOKEN_HW 1

gnutls_pkcs11_obj_attr_t

#define gnutls_pkcs11_obj_attr_t gnutls_pkcs11_obj_flags

enum gnutls_pkcs11_obj_info_t

Enumeration of several object information types.

struct gnutls_pkcs11_obj_st

struct gnutls_pkcs11_obj_st {
	gnutls_datum_t raw;
	gnutls_pkcs11_obj_type_t type;
	ck_object_class_t class;

	unsigned int flags;
	struct p11_kit_uri *info;

	/* only when pubkey */
	gnutls_datum_t pubkey[MAX_PUBLIC_PARAMS_SIZE];
	unsigned pubkey_size;
	gnutls_pk_algorithm_t pk_algorithm;
	unsigned int key_usage;

	struct pin_info_st pin;
};

gnutls_pkcs11_obj_t

typedef struct gnutls_pkcs11_obj_st *gnutls_pkcs11_obj_t;

enum gnutls_pkcs11_obj_type_t

Enumeration of object types.

enum gnutls_pkcs11_token_info_t

Enumeration of types for retrieving token information.

enum gnutls_pkcs11_url_type_t

Enumeration of different URL extraction flags.

gnutls_x509_crt_import_pkcs11_url

#define gnutls_x509_crt_import_pkcs11_url gnutls_x509_crt_import_url