GnuTLS 3.3.10: PKCS 11 API

E.7 Hardware token via PKCS 11 API

The following functions are to be used for PKCS 11 handling. Their prototypes lie in gnutls/pkcs11.h.

gnutls_pkcs11_add_provider

Function: int gnutls_pkcs11_add_provider (const char * name, const char * params)

name: The filename of the module

params: should be NULL

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.

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

Since: 2.12.0

gnutls_pkcs11_copy_secret_key

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

token_url: A PKCS 11 URL specifying a token

key: The raw key

label: A name to be used for the stored data

key_usage: One of GNUTLS_KEY_*

flags: One of GNUTLS_PKCS11_OBJ_FLAG_*

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.

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

Since: 2.12.0

gnutls_pkcs11_copy_x509_crt

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

token_url: A PKCS 11 URL specifying a token

crt: A certificate

label: A name to be used for the stored data

flags: One of GNUTLS_PKCS11_OBJ_FLAG_*

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

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

Since: 2.12.0

gnutls_pkcs11_copy_x509_privkey

Function: 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)

token_url: A PKCS 11 URL specifying a token

key: A private key

label: A name to be used for the stored data

key_usage: One of GNUTLS_KEY_*

flags: One of GNUTLS_PKCS11_OBJ_* 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.

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

Since: 2.12.0

gnutls_pkcs11_crt_is_known

Function: int gnutls_pkcs11_crt_is_known (const char * url, gnutls_x509_crt_t cert, unsigned int flags)

url: A PKCS 11 url identifying a token

cert: is the certificate to find issuer for

flags: Use zero or flags from GNUTLS_PKCS11_OBJ_FLAG .

This function will check whether the provided certificate is stored in the specified token. This is useful in combination with GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_TRUSTED or GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED , to check whether a CA is present or a certificate is blacklisted in a trust PKCS 11 module.

This function can be used with a url of "pkcs11:", and in that case all modules will be searched. To restrict the modules to the marked as trusted in p11-kit use the GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE flag.

Note that the flag GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED is specific to p11-kit trust modules.

Returns: If the certificate exists non-zero is returned, otherwise zero.

Since: 3.3.0

gnutls_pkcs11_deinit

Function: 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

Function: int gnutls_pkcs11_delete_url (const char * object_url, unsigned int flags)

object_url: The URL of the object to delete.

flags: One of GNUTLS_PKCS11_OBJ_* flags

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

Returns: On success, the number of objects deleted is returned, otherwise a negative error value.

Since: 2.12.0

gnutls_pkcs11_get_pin_function

Function: gnutls_pin_callback_t gnutls_pkcs11_get_pin_function (void ** userdata)

userdata: data to be supplied to callback

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

Returns: The function set or NULL otherwise.

Since: 3.1.0

gnutls_pkcs11_get_raw_issuer

Function: int gnutls_pkcs11_get_raw_issuer (const char * url, gnutls_x509_crt_t cert, gnutls_datum_t * issuer, gnutls_x509_crt_fmt_t fmt, unsigned int flags)

url: A PKCS 11 url identifying a token

cert: is the certificate to find issuer for

issuer: Will hold the issuer if any in an allocated buffer.

fmt: The format of the exported issuer.

flags: Use zero or flags from GNUTLS_PKCS11_OBJ_FLAG .

This function will return the issuer of a given certificate, if it is stored in the token. By default only marked as trusted issuers are retuned. If any issuer should be returned specify GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY in flags .

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

Since: 3.2.7

gnutls_pkcs11_init

Function: int gnutls_pkcs11_init (unsigned int flags, const char * deprecated_config_file)

flags: An ORed sequence of GNUTLS_PKCS11_FLAG_ *

deprecated_config_file: either NULL or the location of a deprecated configuration 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.

Normally you don’t need to call this function since it is being called when the first PKCS 11 operation is requested using the GNUTLS_PKCS11_FLAG_AUTO flag. If another flags are required then it must be called independently prior to any PKCS 11 operation.

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

Since: 2.12.0

gnutls_pkcs11_obj_deinit

Function: void gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t obj)

obj: The structure to be initialized

This function will deinitialize a certificate structure.

Since: 2.12.0

gnutls_pkcs11_obj_export

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

obj: Holds the object

output_data: will contain the object data

output_data_size: holds the size of output_data (and will be replaced by the actual size of parameters)

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.

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

Since: 2.12.0

gnutls_pkcs11_obj_export2

Function: int gnutls_pkcs11_obj_export2 (gnutls_pkcs11_obj_t obj, gnutls_datum_t * out)

obj: Holds the object

out: will contain the object data

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() .

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

Since: 3.1.3

gnutls_pkcs11_obj_export3

Function: int gnutls_pkcs11_obj_export3 (gnutls_pkcs11_obj_t obj, gnutls_x509_crt_fmt_t fmt, gnutls_datum_t * out)

obj: Holds the object

fmt: The format of the exported data

out: will contain the object data

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() .

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

Since: 3.2.7

gnutls_pkcs11_obj_export_url

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

obj: Holds the PKCS 11 certificate

detailed: non zero if a detailed URL is required

url: will contain an allocated url

This function will export a URL identifying the given certificate.

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

Since: 2.12.0

gnutls_pkcs11_obj_flags_get_str

Function: char * gnutls_pkcs11_obj_flags_get_str (unsigned int flags)

flags: holds the flags

This function given an or-sequence of GNUTLS_PKCS11_OBJ_FLAG_MARK , will return an allocated string with its description. The string needs to be deallocated using gnutls_free() .

Returns: If flags is zero NULL is returned, otherwise an allocated string.

Since: 3.3.7

gnutls_pkcs11_obj_get_exts

Function: int gnutls_pkcs11_obj_get_exts (gnutls_pkcs11_obj_t obj, gnutls_x509_ext_st ** exts, unsigned int * exts_size, unsigned int flags)

obj: should contain a gnutls_pkcs11_obj_t structure

exts: an allocated list of pointers to gnutls_x509_ext_st

exts_size: the number of exts

flags: Or sequence of GNUTLS_PKCS11_OBJ_ * flags

This function will return information about attached extensions that associate to the provided object (which should be a certificate). The extensions are the attached p11-kit trust module extensions.

Returns: GNUTLS_E_SUCCESS (0) on success or a negative error code on error.

Since: 3.3.8

gnutls_pkcs11_obj_get_flags

Function: int gnutls_pkcs11_obj_get_flags (gnutls_pkcs11_obj_t obj, unsigned int * oflags)

obj: The structure that holds the object

oflags: Will hold the output flags

This function will return the flags of the object being stored in the structure. The oflags are the GNUTLS_PKCS11_OBJ_FLAG_MARK flags.

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

Since: 3.3.7

gnutls_pkcs11_obj_get_info

Function: int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t obj, gnutls_pkcs11_obj_info_t itype, void * output, size_t * output_size)

obj: should contain a gnutls_pkcs11_obj_t structure

itype: Denotes the type of information requested

output: where output will be stored

output_size: contains the maximum size of the output and will be overwritten with actual

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.

Returns: GNUTLS_E_SUCCESS (0) on success or a negative error code on error.

Since: 2.12.0

gnutls_pkcs11_obj_get_type

Function: gnutls_pkcs11_obj_type_t gnutls_pkcs11_obj_get_type (gnutls_pkcs11_obj_t obj)

obj: Holds the PKCS 11 object

This function will return the type of the object being stored in the structure.

Returns: The type of the object

Since: 2.12.0

gnutls_pkcs11_obj_import_url

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

obj: The structure to store the object

url: a PKCS 11 url identifying the key

flags: Or sequence of GNUTLS_PKCS11_OBJ_* flags

This function will "import" a PKCS 11 URL identifying an object (e.g. certificate) to the gnutls_pkcs11_obj_t structure. 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.

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

Since: 2.12.0

gnutls_pkcs11_obj_init

Function: int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t * obj)

obj: The structure to be initialized

This function will initialize a pkcs11 certificate structure.

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

Since: 2.12.0

gnutls_pkcs11_obj_list_import_url

Function: int gnutls_pkcs11_obj_list_import_url (gnutls_pkcs11_obj_t * p_list, unsigned int * n_list, const char * url, gnutls_pkcs11_obj_attr_t attrs, unsigned int flags)

p_list: An uninitialized object list (may be NULL)

n_list: initially should hold the maximum size of the list. Will contain the actual size.

url: A PKCS 11 url identifying a set of objects

attrs: Attributes of type gnutls_pkcs11_obj_attr_t that can be used to limit output

flags: Or sequence of GNUTLS_PKCS11_OBJ_* flags

This function will initialize and set values to an object list by using all objects identified by a PKCS 11 URL.

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

Since: 2.12.0

gnutls_pkcs11_obj_list_import_url2

Function: int gnutls_pkcs11_obj_list_import_url2 (gnutls_pkcs11_obj_t ** p_list, unsigned int * n_list, const char * url, gnutls_pkcs11_obj_attr_t attrs, unsigned int flags)

p_list: An uninitialized object list (may be NULL)

n_list: It will contain the size of the list.

url: A PKCS 11 url identifying a set of objects

attrs: Attributes of type gnutls_pkcs11_obj_attr_t that can be used to limit output

flags: Or sequence of GNUTLS_PKCS11_OBJ_* flags

This function will initialize and set values to an object list by using all objects identified by the PKCS 11 URL. The output is stored in p_list , which will be initialized.

All returned objects must be deinitialized using gnutls_pkcs11_obj_deinit() , and p_list must be free’d using gnutls_free() .

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

Since: 3.1.0

gnutls_pkcs11_obj_set_pin_function

Function: void gnutls_pkcs11_obj_set_pin_function (gnutls_pkcs11_obj_t obj, gnutls_pin_callback_t fn, void * userdata)

obj: The object structure

fn: the callback

userdata: data associated with the callback

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

Function: void gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t key)

key: The structure to be initialized

This function will deinitialize a private key structure.

gnutls_pkcs11_privkey_export_pubkey

Function: int gnutls_pkcs11_privkey_export_pubkey (gnutls_pkcs11_privkey_t pkey, gnutls_x509_crt_fmt_t fmt, gnutls_datum_t * data, unsigned int flags)

pkey: The private key

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

data: will hold the public key

flags: should be zero

This function will extract the public key (modulus and public exponent) from the private key specified by the url private key. This public key will be stored in pubkey in the format specified by fmt . pubkey should be deinitialized using gnutls_free() .

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

Since: 3.3.7

gnutls_pkcs11_privkey_export_url

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

key: Holds the PKCS 11 key

detailed: non zero if a detailed URL is required

url: will contain an allocated url

This function will export a URL identifying the given key.

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

gnutls_pkcs11_privkey_generate

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

url: a token URL

pk: the public key algorithm

bits: the security bits

label: a label

flags: should be zero

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.

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

Since: 3.0

gnutls_pkcs11_privkey_generate2

Function: 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)

url: a token URL

pk: the public key algorithm

bits: the security bits

label: a label

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

pubkey: will hold the public key (may be NULL )

flags: zero or an OR’ed sequence of GNUTLS_PKCS11_OBJ_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.

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

Since: 3.1.5

gnutls_pkcs11_privkey_get_info

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

pkey: should contain a gnutls_pkcs11_privkey_t structure

itype: Denotes the type of information requested

output: where output will be stored

output_size: contains the maximum size of the output and will be overwritten with actual

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.

Returns: GNUTLS_E_SUCCESS (0) on success or a negative error code on error.

gnutls_pkcs11_privkey_get_pk_algorithm

Function: int gnutls_pkcs11_privkey_get_pk_algorithm (gnutls_pkcs11_privkey_t key, unsigned int * bits)

key: should contain a gnutls_pkcs11_privkey_t structure

bits: if bits is non null it will hold the size of the parameters’ in bits

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

Returns: a member of the gnutls_pk_algorithm_t enumeration on success, or a negative error code on error.

gnutls_pkcs11_privkey_import_url

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

pkey: The structure to store the parsed key

url: a PKCS 11 url identifying the key

flags: Or sequence of GNUTLS_PKCS11_OBJ_* flags

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

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

gnutls_pkcs11_privkey_init

Function: int gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t * key)

key: The structure to be initialized

This function will initialize an private key structure.

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

gnutls_pkcs11_privkey_set_pin_function

Function: void gnutls_pkcs11_privkey_set_pin_function (gnutls_pkcs11_privkey_t key, gnutls_pin_callback_t fn, void * userdata)

key: The private key

fn: the callback

userdata: data associated with the callback

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_status

Function: int gnutls_pkcs11_privkey_status (gnutls_pkcs11_privkey_t key)

key: Holds the key

Checks the status of the private key token.

Returns: this function will return non-zero if the token holding the private key is still available (inserted), and zero otherwise.

Since: 3.1.9

gnutls_pkcs11_reinit

Function: 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.

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

Since: 3.0

gnutls_pkcs11_set_pin_function

Function: void gnutls_pkcs11_set_pin_function (gnutls_pin_callback_t fn, void * userdata)

fn: The PIN callback, a gnutls_pin_callback_t() function.

userdata: data to be supplied to callback

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

Function: void gnutls_pkcs11_set_token_function (gnutls_pkcs11_token_callback_t fn, void * userdata)

fn: The token callback

userdata: data to be supplied to callback

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_get_flags

Function: int gnutls_pkcs11_token_get_flags (const char * url, unsigned int * flags)

url: should contain a PKCS 11 URL

flags: The output flags (GNUTLS_PKCS11_TOKEN_*)

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

The supported flags are: GNUTLS_PKCS11_TOKEN_HW and GNUTLS_PKCS11_TOKEN_TRUSTED .

Returns: GNUTLS_E_SUCCESS (0) on success or a negative error code on error.

Since: 2.12.0

gnutls_pkcs11_token_get_info

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

url: should contain a PKCS 11 URL

ttype: Denotes the type of information requested

output: where output will be stored

output_size: contains the maximum size of the output and will be overwritten with actual

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

Returns: GNUTLS_E_SUCCESS (0) on success or a negative error code on error.

Since: 2.12.0

gnutls_pkcs11_token_get_mechanism

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

url: should contain a PKCS 11 URL

idx: The index of the mechanism

mechanism: The PKCS 11 mechanism ID

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.

Returns: GNUTLS_E_SUCCESS (0) on success or a negative error code on error.

Since: 2.12.0

gnutls_pkcs11_token_get_random

Function: int gnutls_pkcs11_token_get_random (const char * token_url, void * rnddata, size_t len)

token_url: A PKCS 11 URL specifying a token

rnddata: A pointer to the memory area to be filled with random data

len: The number of bytes of randomness to request

This function will get random data from the given token. It will store rnddata and fill the memory pointed to by rnddata with len random bytes from the token.

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

gnutls_pkcs11_token_get_url

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

seq: sequence number starting from 0

detailed: non zero if a detailed URL is required

url: will contain an allocated url

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

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE if the sequence number exceeds the available tokens, otherwise a negative error value.

Since: 2.12.0

gnutls_pkcs11_token_init

Function: int gnutls_pkcs11_token_init (const char * token_url, const char * so_pin, const char * label)

token_url: A PKCS 11 URL specifying a token

so_pin: Security Officer’s PIN

label: A name to be used for the token

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.

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

gnutls_pkcs11_token_set_pin

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

token_url: A PKCS 11 URL specifying a token

oldpin: old user’s PIN

newpin: new user’s PIN

flags: one of gnutls_pin_flag_t .

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.

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

gnutls_pkcs11_type_get_name

Function: const char * gnutls_pkcs11_type_get_name (gnutls_pkcs11_obj_type_t type)

type: Holds the PKCS 11 object type, a gnutls_pkcs11_obj_type_t .

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

Returns: human readable string labeling the PKCS11 object type type .

Since: 2.12.0

gnutls_x509_crt_import_pkcs11

Function: int gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t crt, gnutls_pkcs11_obj_t pkcs11_crt)

crt: A certificate of type gnutls_x509_crt_t

pkcs11_crt: A PKCS 11 object that contains a certificate

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

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

Since: 2.12.0

gnutls_x509_crt_import_pkcs11_url

Function: int gnutls_x509_crt_import_pkcs11_url (gnutls_x509_crt_t crt, const char * url, unsigned int flags)

crt: A certificate of type gnutls_x509_crt_t

url: A PKCS 11 url

flags: One of GNUTLS_PKCS11_OBJ_* flags

This function will import a PKCS 11 certificate directly from a token without involving the gnutls_pkcs11_obj_t structure. This function will fail if the certificate stored is not of X.509 type.

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

Since: 2.12.0

gnutls_x509_crt_list_import_pkcs11

Function: 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)

certs: A list of certificates of type gnutls_x509_crt_t

cert_max: The maximum size of the list

objs: A list of PKCS 11 objects

flags: 0 for now

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

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

Since: 2.12.0