pkcs11

## pkcs11 pkcs11 |

## Functions

#define | GNUTLS_PKCS11_OBJ_FLAG_LOGIN
#define | GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO
#define | GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_PRIVATE
#define | GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE
#define | GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE
#define | GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED
int | gnutls_pkcs11_add_provider ()
int | gnutls_pkcs11_copy_secret_key ()
int | gnutls_pkcs11_copy_x509_crt ()
int | gnutls_pkcs11_copy_x509_privkey ()
void | gnutls_pkcs11_deinit ()
int | gnutls_pkcs11_delete_url ()
gnutls_pin_callback_t | gnutls_pkcs11_get_pin_function ()
int | gnutls_pkcs11_init ()
void | gnutls_pkcs11_obj_deinit ()
int | gnutls_pkcs11_obj_export ()
int | gnutls_pkcs11_obj_export2 ()
int | gnutls_pkcs11_obj_export_url ()
int | gnutls_pkcs11_obj_get_info ()
int | gnutls_pkcs11_obj_import_url ()
int | gnutls_pkcs11_obj_init ()
int | gnutls_pkcs11_obj_list_import_url ()
int | gnutls_pkcs11_obj_list_import_url2 ()
void | gnutls_pkcs11_obj_set_pin_function ()
void | gnutls_pkcs11_privkey_deinit ()
int | gnutls_pkcs11_privkey_export_url ()
int | gnutls_pkcs11_privkey_generate ()
int | gnutls_pkcs11_privkey_generate2 ()
int | gnutls_pkcs11_privkey_get_info ()
int | gnutls_pkcs11_privkey_get_pk_algorithm ()
int | gnutls_pkcs11_privkey_import_url ()
int | gnutls_pkcs11_privkey_init ()
void | gnutls_pkcs11_privkey_set_pin_function ()
int | gnutls_pkcs11_privkey_status ()
int | gnutls_pkcs11_reinit ()
void | gnutls_pkcs11_set_pin_function ()
void | gnutls_pkcs11_set_token_function ()
int | (*gnutls_pkcs11_token_callback_t) ()
int | gnutls_pkcs11_token_get_flags ()
int | gnutls_pkcs11_token_get_info ()
int | gnutls_pkcs11_token_get_mechanism ()
int | gnutls_pkcs11_token_get_url ()
int | gnutls_pkcs11_token_init ()
int | gnutls_pkcs11_token_set_pin ()
const char * | gnutls_pkcs11_type_get_name ()
int | gnutls_x509_crt_import_pkcs11 ()
int | gnutls_x509_crt_import_pkcs11_url ()
int | gnutls_x509_crt_list_import_pkcs11 ()

## Types and Values

#define | GNUTLS_PKCS11_FLAG_AUTO
#define | GNUTLS_PKCS11_FLAG_MANUAL
#define | GNUTLS_PKCS11_MAX_PIN_LEN
#define | GNUTLS_PKCS11_TOKEN_HW
enum | gnutls_pkcs11_obj_attr_t
enum | gnutls_pkcs11_obj_info_t
struct | gnutls_pkcs11_obj_st
typedef | gnutls_pkcs11_obj_t
enum | gnutls_pkcs11_obj_type_t
enum | gnutls_pkcs11_token_info_t
enum | gnutls_pkcs11_url_type_t

## Description

## Functions

### GNUTLS_PKCS11_OBJ_FLAG_LOGIN

    #define GNUTLS_PKCS11_OBJ_FLAG_LOGIN (1<<0) /* force login in the token for the operation */

### GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO

    #define GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO (1<<3) /* force login as a security officer in the token for the operation */

### GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_PRIVATE

    #define GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_PRIVATE (1<<5) /* marked as not private */

### GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE

    #define GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE (1<<4) /* marked as private (requires PIN to access) */

### GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE

    #define GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE (1<<2) /* object marked as sensitive (unexportable) */

### GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED

    #define GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED (1<<1) /* object marked as trusted */

### 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.

#### Parameters

name | The filename of the module |
params | should be NULL |

#### Returns

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

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.

#### Parameters

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_* |

#### Returns

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

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.

#### Parameters

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_* |

#### Returns

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

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.

#### Parameters

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 |

#### Returns

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

Since 2.12.0

### gnutls_pkcs11_deinit ()

    void
    gnutls_pkcs11_deinit (void);

This function will deinitialize the PKCS 11 subsystem in gnutls.

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.

#### Parameters

object_url | The URL of the object to delete. |
flags | One of GNUTLS_PKCS11_OBJ_* flags |

#### Returns

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

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

#### Parameters

userdata | data to be supplied to callback |

#### Returns

The function set or NULL otherwise.

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.

Normally you don't need to call this function since it is being called by `gnutls_global_init()` using the `GNUTLS_PKCS11_FLAG_AUTO`. If other option is required then it must be called before it.

#### Parameters

flags | `GNUTLS_PKCS11_FLAG_MANUAL` or `GNUTLS_PKCS11_FLAG_AUTO` |
deprecated_config_file | either NULL or the location of a deprecated configuration file |

#### Returns

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

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.

#### Parameters

obj | The structure to be initialized |

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.

#### Parameters

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

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

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

#### Parameters

obj | Holds the object |
out | will contain the object data |

#### 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_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 certificate.

#### Parameters

obj | Holds the PKCS 11 certificate |
detailed | non zero if a detailed URL is required |
url | will contain an allocated url |

#### Returns

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

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.

#### Parameters

crt | 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 |

#### Returns

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

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

#### Parameters

obj | The structure to store the object |
url | a PKCS 11 url identifying the key |
flags | One of GNUTLS_PKCS11_OBJ_* flags |

#### Returns

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

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.

#### Parameters

obj | The structure to be initialized |

#### Returns

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

Since 2.12.0

### gnutls_pkcs11_obj_list_import_url ()

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

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

#### Parameters

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

#### Returns

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

Since 2.12.0

### gnutls_pkcs11_obj_list_import_url2 ()

    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);

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.

#### Parameters

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

#### Returns

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

Since 3.1.0

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

#### Parameters

obj | The object structure |
fn | the callback |
userdata | data associated with the callback |

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.

#### Parameters

key | The structure to be initialized |

### 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.

#### Parameters

key | Holds the PKCS 11 key |
detailed | non zero if a detailed URL is required |
url | will contain an allocated url |

#### Returns

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

### 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.

#### Parameters

url | a token URL |
pk | the public key algorithm |
bits | the security bits |
label | a label |
flags | should be zero |

#### Returns

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

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.

#### Parameters

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 | should be zero |

#### Returns

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

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.

#### Parameters

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 |

#### Returns

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

### 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.

#### Parameters

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 |

#### Returns

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

### 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 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.

#### Parameters

pkey | The structure to store the parsed key |
url | a PKCS 11 url identifying the key |
flags | sequence of GNUTLS_PKCS_PRIVKEY_* |

#### Returns

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

### gnutls_pkcs11_privkey_init ()

    int
    gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t *key);

This function will initialize an private key structure.

#### Parameters

key | The structure to be initialized |

#### Returns

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

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

#### Parameters

key | The private key |
fn | the callback |
userdata | data associated with the callback |

Since 3.1.0

### gnutls_pkcs11_privkey_status ()

    int
    gnutls_pkcs11_privkey_status (gnutls_pkcs11_privkey_t key);

Checks the status of the private key token.

#### Parameters

key | Holds the key |

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

    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.

#### Returns

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

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.

#### Parameters

fn | The PIN callback, a `gnutls_pin_callback_t()` function. |
userdata | data to be supplied to callback |

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.

#### Parameters

fn | The token callback |
userdata | data to be supplied to callback |

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.

#### Parameters

userdata | user-controlled data from `gnutls_pkcs11_set_token_function()`. |
label | token label. |
retry | retry counter, initially 0. |

#### Returns

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

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`.

#### Parameters

url | should contain a PKCS 11 URL |
flags | The output flags (GNUTLS_PKCS11_TOKEN_*) |

#### Returns

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

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.

#### Parameters

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 |

#### Returns

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

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.

#### Parameters

url | should contain a PKCS 11 URL |
idx | The index of the mechanism |
mechanism | The PKCS 11 mechanism ID |

#### Returns

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

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

#### Parameters

seq | sequence number starting from 0 |
detailed | non zero if a detailed URL is required |
url | will contain an allocated url |

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

    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.

#### Parameters

token_url | A PKCS 11 URL specifying a token |
so_pin | Security Officer's PIN |
label | A name to be used for the token |

#### Returns

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

### 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.

#### Parameters

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

#### Returns

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

### 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.

#### Parameters

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

#### Returns

human readable string labeling the PKCS11 object type `type` .

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.

#### Parameters

crt | A certificate of type gnutls_x509_crt_t |
pkcs11_crt | A PKCS 11 object that contains a certificate |

#### Returns

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

Since 2.12.0

### gnutls_x509_crt_import_pkcs11_url ()

    int
    gnutls_x509_crt_import_pkcs11_url (gnutls_x509_crt_t crt,
                                       const char *url,
                                       unsigned int 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.

#### Parameters

crt | A certificate of type gnutls_x509_crt_t |
url | A PKCS 11 url |
flags | One of GNUTLS_PKCS11_OBJ_* flags |

#### Returns

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

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 structure. These must not be initialized.

#### Parameters

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 |

#### Returns

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

Since 2.12.0

## Types and Values

### 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

### enum gnutls_pkcs11_obj_attr_t

Enumeration of several attributes for object enumeration.

#### Members

GNUTLS_PKCS11_OBJ_ATTR_CRT_ALL | Specify all certificates. |
GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED | Specify all certificates marked as trusted. |
GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY | Specify all certificates with a corresponding private key. |
GNUTLS_PKCS11_OBJ_ATTR_PUBKEY | Specify all public keys. |
GNUTLS_PKCS11_OBJ_ATTR_PRIVKEY | Specify all private keys. |
GNUTLS_PKCS11_OBJ_ATTR_ALL | Specify all objects. |
GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED_CA | Specify all certificates marked as trusted and are CAs. |

### enum gnutls_pkcs11_obj_info_t

Enumeration of several object information types.

#### Members

GNUTLS_PKCS11_OBJ_ID_HEX | The object ID in hex. |
GNUTLS_PKCS11_OBJ_LABEL | The object label. |
GNUTLS_PKCS11_OBJ_TOKEN_LABEL | The token's label. |
GNUTLS_PKCS11_OBJ_TOKEN_SERIAL | The token's serial number. |
GNUTLS_PKCS11_OBJ_TOKEN_MANUFACTURER | The token's manufacturer. |
GNUTLS_PKCS11_OBJ_TOKEN_MODEL | The token's model. |
GNUTLS_PKCS11_OBJ_ID | The object ID. |
GNUTLS_PKCS11_OBJ_LIBRARY_VERSION | The library's used to access the object version. |
GNUTLS_PKCS11_OBJ_LIBRARY_DESCRIPTION | The library's used to access the object description (name). |
GNUTLS_PKCS11_OBJ_LIBRARY_MANUFACTURER | The library's used to access the object manufacturer name. |

### struct gnutls_pkcs11_obj_st

    struct gnutls_pkcs11_obj_st {
    	gnutls_datum_t raw;
    	gnutls_pkcs11_obj_type_t type;
    	struct p11_kit_uri *info;

    	/* only when pubkey */
    	gnutls_datum_t pubkey[MAX_PUBLIC_PARAMS_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.

#### Members

GNUTLS_PKCS11_OBJ_UNKNOWN | Unknown PKCS11 object. |
GNUTLS_PKCS11_OBJ_X509_CRT | X.509 certificate. |
GNUTLS_PKCS11_OBJ_PUBKEY | Public key. |
GNUTLS_PKCS11_OBJ_PRIVKEY | Private key. |
GNUTLS_PKCS11_OBJ_SECRET_KEY | Secret key. |
GNUTLS_PKCS11_OBJ_DATA | Data object. |

### enum gnutls_pkcs11_token_info_t

Enumeration of types for retrieving token information.

#### Members

GNUTLS_PKCS11_TOKEN_LABEL | The token's label (string) |
GNUTLS_PKCS11_TOKEN_SERIAL | The token's serial number (string) |
GNUTLS_PKCS11_TOKEN_MANUFACTURER | The token's manufacturer (string) |
GNUTLS_PKCS11_TOKEN_MODEL | The token's model (string) |

### enum gnutls_pkcs11_url_type_t

Enumeration of different URL extraction flags.

#### Members

GNUTLS_PKCS11_URL_GENERIC | A generic-purpose URL. |
GNUTLS_PKCS11_URL_LIB | A URL that specifies the library used as well. |
GNUTLS_PKCS11_URL_LIB_VERSION | A URL that specifies the library and its version. |