pkcs11

pkcs11

Functions

int (*gnutls_pkcs11_token_callback_t) ()
int gnutls_pkcs11_init ()
int gnutls_pkcs11_reinit ()
void gnutls_pkcs11_deinit ()
void gnutls_pkcs11_set_token_function ()
void gnutls_pkcs11_set_pin_function ()
gnutls_pin_callback_t gnutls_pkcs11_get_pin_function ()
int gnutls_pkcs11_add_provider ()
int gnutls_pkcs11_obj_init ()
void gnutls_pkcs11_obj_set_pin_function ()
int gnutls_pkcs11_obj_import_url ()
int gnutls_pkcs11_obj_export_url ()
void gnutls_pkcs11_obj_deinit ()
int gnutls_pkcs11_obj_export ()
int gnutls_pkcs11_obj_export2 ()
int gnutls_pkcs11_obj_export3 ()
int gnutls_pkcs11_get_raw_issuer ()
int gnutls_pkcs11_get_raw_issuer_by_dn ()
int gnutls_pkcs11_get_raw_issuer_by_subject_key_id ()
unsigned gnutls_pkcs11_crt_is_known ()
int gnutls_pkcs11_copy_x509_crt ()
int gnutls_pkcs11_copy_x509_privkey ()
int gnutls_pkcs11_privkey_generate2 ()
int gnutls_pkcs11_privkey_generate ()
int gnutls_pkcs11_copy_pubkey ()
int gnutls_pkcs11_copy_x509_crt2 ()
int gnutls_pkcs11_copy_x509_privkey2 ()
int gnutls_pkcs11_delete_url ()
int gnutls_pkcs11_copy_secret_key ()
int gnutls_pkcs11_obj_get_ptr ()
int gnutls_pkcs11_obj_get_info ()
int gnutls_pkcs11_obj_set_info ()
int gnutls_pkcs11_token_init ()
int gnutls_pkcs11_token_get_ptr ()
int gnutls_pkcs11_token_get_mechanism ()
unsigned gnutls_pkcs11_token_check_mechanism ()
int gnutls_pkcs11_token_set_pin ()
int gnutls_pkcs11_token_get_url ()
int gnutls_pkcs11_token_get_info ()
int gnutls_pkcs11_token_get_flags ()
#define gnutls_pkcs11_obj_list_import_url()
#define gnutls_pkcs11_obj_list_import_url2()
int gnutls_pkcs11_obj_list_import_url3 ()
int gnutls_pkcs11_obj_list_import_url4 ()
int gnutls_x509_crt_import_pkcs11 ()
const char * gnutls_pkcs11_type_get_name ()
int gnutls_pkcs11_obj_get_exts ()
int gnutls_pkcs11_obj_get_flags ()
char * gnutls_pkcs11_obj_flags_get_str ()
int gnutls_x509_crt_list_import_pkcs11 ()
int gnutls_pkcs11_privkey_init ()
int gnutls_pkcs11_privkey_cpy ()
void gnutls_pkcs11_privkey_set_pin_function ()
void gnutls_pkcs11_privkey_deinit ()
int gnutls_pkcs11_privkey_get_pk_algorithm ()
int gnutls_pkcs11_privkey_get_info ()
int gnutls_pkcs11_privkey_import_url ()
int gnutls_pkcs11_privkey_export_url ()
unsigned gnutls_pkcs11_privkey_status ()
int gnutls_pkcs11_privkey_generate3 ()
int gnutls_pkcs11_privkey_export_pubkey ()
int gnutls_pkcs11_token_get_random ()
int gnutls_pkcs11_copy_attached_extension ()

Types and Values

Description

Functions

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

Parameters

flags

An ORed sequence of GNUTLS_PKCS11_FLAG_*

 

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

Returns

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

Since: 3.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_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_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_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_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.

Parameters

name

The filename of the module

 

params

should be NULL or a known string (see description)

 

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

A pointer to the type to be initialized

 

Returns

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

Since: 2.12.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_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.

Parameters

obj

The structure to store the object

 

url

a PKCS 11 url identifying the key

 

flags

Or sequence 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_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.

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

void
gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t obj);

This function will deinitialize a certificate structure.

Parameters

obj

The type to be deinitialized

 

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 inaccessible 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 inaccessible 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_export3 ()

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

This function will export the PKCS11 object data. It is normal for data to be inaccessible 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

 

fmt

The format of the exported data

 

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

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

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 returned. If any issuer should be returned specify GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY in flags .

Parameters

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.

 

Returns

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

Since: 3.2.7


gnutls_pkcs11_get_raw_issuer_by_dn ()

int
gnutls_pkcs11_get_raw_issuer_by_dn (const char *url,
                                    const gnutls_datum_t *dn,
                                    gnutls_datum_t *issuer,
                                    gnutls_x509_crt_fmt_t fmt,
                                    unsigned int flags);

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

The name of the function includes issuer because it can be used to discover issuers of certificates.

Parameters

url

A PKCS 11 url identifying a token

 

dn

is the DN to search 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.

 

Returns

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

Since: 3.4.0


gnutls_pkcs11_get_raw_issuer_by_subject_key_id ()

int
gnutls_pkcs11_get_raw_issuer_by_subject_key_id
                               (const char *url,
                                const gnutls_datum_t *dn,
                                const gnutls_datum_t *spki,
                                gnutls_datum_t *issuer,
                                gnutls_x509_crt_fmt_t fmt,
                                unsigned int flags);

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

The name of the function includes issuer because it can be used to discover issuers of certificates.

Parameters

url

A PKCS 11 url identifying a token

 

dn

is the DN to search for (may be NULL)

 

spki

is the subject key ID to search 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.

 

Returns

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

Since: 3.4.2


gnutls_pkcs11_crt_is_known ()

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

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

Parameters

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.

 

Returns

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

Since: 3.3.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.

Since 3.6.3 the objects are marked as sensitive by default unless GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE is specified.

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

zero or an OR'ed sequence of GNUTLS_PKCS11_OBJ_FLAGs

 

Returns

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

Since: 3.1.5


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

int
gnutls_pkcs11_copy_pubkey (const char *token_url,
                           gnutls_pubkey_t crt,
                           const char *label,
                           const gnutls_datum_t *cid,
                           unsigned int key_usage,
                           unsigned int flags);

This function will copy a public key object into a PKCS 11 token specified by a URL. Valid flags to mark the key: GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED, GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE, GNUTLS_PKCS11_OBJ_FLAG_MARK_CA, GNUTLS_PKCS11_OBJ_FLAG_MARK_ALWAYS_AUTH.

Parameters

token_url

A PKCS 11 URL specifying a token

 

pubkey

The public key to copy

 

label

The name to be used for the stored data

 

cid

The CKA_ID to set for the object -if NULL, the ID will be derived from the public key

 

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


gnutls_pkcs11_copy_x509_crt2 ()

int
gnutls_pkcs11_copy_x509_crt2 (const char *token_url,
                              gnutls_x509_crt_t crt,
                              const char *label,
                              const gnutls_datum_t *id,
                              unsigned int flags);

This function will copy a certificate into a PKCS 11 token specified by a URL. Valid flags to mark the certificate: GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED, GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE, GNUTLS_PKCS11_OBJ_FLAG_MARK_CA, GNUTLS_PKCS11_OBJ_FLAG_MARK_ALWAYS_AUTH.

Parameters

token_url

A PKCS 11 URL specifying a token

 

crt

The certificate to copy

 

label

The name to be used for the stored data

 

cid

The CKA_ID to set for the object -if NULL, the ID will be derived from the public key

 

flags

One of GNUTLS_PKCS11_OBJ_FLAG_*

 

Returns

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

Since: 3.4.0


gnutls_pkcs11_copy_x509_privkey2 ()

int
gnutls_pkcs11_copy_x509_privkey2 (const char *token_url,
                                  gnutls_x509_privkey_t key,
                                  const char *label,
                                  const gnutls_datum_t *cid,
                                  unsigned int key_usage,
                                  unsigned int flags);

This function will copy a private key into a PKCS 11 token specified by a URL.

Since 3.6.3 the objects are marked as sensitive by default unless GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE is specified.

Parameters

token_url

A PKCS 11 URL specifying a token

 

key

A private key

 

label

A name to be used for the stored data

 

cid

The CKA_ID to set for the object -if NULL, the ID will be derived from the public key

 

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: 3.4.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_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_obj_get_ptr ()

int
gnutls_pkcs11_obj_get_ptr (gnutls_pkcs11_obj_t obj,
                           void **ptr,
                           void **session,
                           void **ohandle,
                           unsigned long *slot_id,
                           unsigned int flags);

Obtains the PKCS11 session handles of an object. session and ohandle must be deinitialized by the caller. The returned pointers are independent of the obj lifetime.

Parameters

obj

should contain a gnutls_pkcs11_obj_t type

 

ptr

will contain the CK_FUNCTION_LIST_PTR pointer (may be NULL)

 

session

will contain the CK_SESSION_HANDLE of the object

 

ohandle

will contain the CK_OBJECT_HANDLE of the object

 

slot_id

the identifier of the slot (may be NULL)

 

flags

Or sequence of GNUTLS_PKCS11_OBJ_* flags

 

Returns

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

Since: 3.6.3


gnutls_pkcs11_obj_get_info ()

int
gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t obj,
                            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, a null terminated string is written to output and its string length is written to output_size (without null terminator). If the buffer is too small, output_size will contain the expected buffer size (with null terminator for text) and return GNUTLS_E_SHORT_MEMORY_BUFFER.

In versions previously to 3.6.0 this function included the null terminator to output_size . After 3.6.0 the output size doesn't include the terminator character.

Parameters

obj

should contain a gnutls_pkcs11_obj_t type

 

itype

Denotes the type of information requested

 

output

where output will be stored

 

output_size

contains the maximum size of the output buffer and will be overwritten with the actual size.

 

Returns

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

Since: 2.12.0


gnutls_pkcs11_obj_set_info ()

int
gnutls_pkcs11_obj_set_info (gnutls_pkcs11_obj_t obj,
                            gnutls_pkcs11_obj_info_t itype,
                            const void *data,
                            size_t data_size,
                            unsigned  flags);

This function will set attributes on the provided object. Available options for itype are GNUTLS_PKCS11_OBJ_LABEL, GNUTLS_PKCS11_OBJ_ID_HEX, and GNUTLS_PKCS11_OBJ_ID.

Parameters

obj

should contain a gnutls_pkcs11_obj_t type

 

itype

Denotes the type of information to be set

 

data

the data to set

 

data_size

the size of data

 

flags

Or sequence of GNUTLS_PKCS11_OBJ_* flags

 

Returns

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

Since: 3.4.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_get_ptr ()

int
gnutls_pkcs11_token_get_ptr (const char *url,
                             void **ptr,
                             unsigned long *slot_id,
                             unsigned int flags);

This function will return the function pointer of the specified token by the URL. The returned pointers are valid until gnutls is deinitialized, c.f. _global_deinit().

Parameters

url

should contain a PKCS11 URL identifying a token

 

ptr

will contain the CK_FUNCTION_LIST_PTR pointer

 

slot_id

will contain the slot_id (may be NULL)

 

flags

should be zero

 

Returns

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

Since: 3.6.3


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

unsigned
gnutls_pkcs11_token_check_mechanism (const char *url,
                                     unsigned long  mechanism,
                                     void *ptr,
                                     unsigned  psize,
                                     unsigned  flags);

This function will return whether a mechanism is supported by the given token. If the mechanism is supported and ptr is set, it will be updated with the token information.

Parameters

url

should contain a PKCS 11 URL

 

mechanism

The PKCS 11 mechanism ID

 

ptr

if set it should point to a CK_MECHANISM_INFO struct

 

psize

the size of CK_MECHANISM_INFO struct (for safety)

 

flags

must be zero

 

Returns

Non-zero if the mechanism is supported or zero otherwise.

Since: 3.6.0


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 or administrator's PIN for the given token. If it is called to set a PIN for first time the oldpin must be NULL. When setting the admin's PIN with the GNUTLS_PIN_SO flag, the oldpin value must be provided (this requirement is relaxed after GnuTLS 3.6.5 since which the PIN will be requested if missing).

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

When output is text, a null terminated string is written to output and its string length is written to output_size (without null terminator). If the buffer is too small, output_size will contain the expected buffer size (with null terminator for text) and return GNUTLS_E_SHORT_MEMORY_BUFFER.

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 buffer and will be overwritten with the actual size.

 

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

#define             gnutls_pkcs11_obj_list_import_url(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_url3 ()

int
gnutls_pkcs11_obj_list_import_url3 (gnutls_pkcs11_obj_t *p_list,
                                    unsigned int *const n_list,
                                    const char *url,
                                    unsigned int flags);

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

This function will enumerate all the objects specified by the PKCS11 URL provided. It expects an already allocated p_list which has *n_list elements, and that value will be updated to the actual number of present objects. The p_list objects will be initialized and set by this function. To obtain a list of all available objects use a url of 'pkcs11:'.

All returned objects must be deinitialized using gnutls_pkcs11_obj_deinit().

The supported in this function flags are GNUTLS_PKCS11_OBJ_FLAG_LOGIN, GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO, GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE, GNUTLS_PKCS11_OBJ_FLAG_CRT, GNUTLS_PKCS11_OBJ_FLAG_PUBKEY, GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY, GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY, GNUTLS_PKCS11_OBJ_FLAG_MARK_CA, GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED, and since 3.5.1 the GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT.

On versions of GnuTLS prior to 3.4.0 the equivalent function was gnutls_pkcs11_obj_list_import_url(). That is also available on this version as a macro which maps to this function.

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

 

flags

Or sequence of GNUTLS_PKCS11_OBJ_* flags

 

Returns

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

Since: 3.4.0


gnutls_pkcs11_obj_list_import_url4 ()

int
gnutls_pkcs11_obj_list_import_url4 (gnutls_pkcs11_obj_t **p_list,
                                    unsigned int *n_list,
                                    const char *url,
                                    unsigned int flags);

This function will enumerate all the objects specified by the PKCS11 URL provided. It will initialize and set values to the object pointer list (p_list ) provided. To obtain a list of all available objects use a url of 'pkcs11:'.

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

The supported in this function flags are GNUTLS_PKCS11_OBJ_FLAG_LOGIN, GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO, GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE, GNUTLS_PKCS11_OBJ_FLAG_CRT, GNUTLS_PKCS11_OBJ_FLAG_PUBKEY, GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY, GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY, GNUTLS_PKCS11_OBJ_FLAG_MARK_CA, GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED, and since 3.5.1 the GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT.

On versions of GnuTLS prior to 3.4.0 the equivalent function was gnutls_pkcs11_obj_list_import_url2(). That is also available on this version as a macro which maps to this function.

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

 

flags

Or sequence of GNUTLS_PKCS11_OBJ_* flags

 

Returns

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

Since: 3.4.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_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_pkcs11_obj_get_exts ()

int
gnutls_pkcs11_obj_get_exts (gnutls_pkcs11_obj_t obj,
                            struct gnutls_x509_ext_st **exts,
                            unsigned int *exts_size,
                            unsigned int 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.

Each element of exts must be deinitialized using gnutls_x509_ext_deinit() while exts should be deallocated using gnutls_free().

Parameters

obj

should contain a gnutls_pkcs11_obj_t type

 

exts

a pointer to a gnutls_x509_ext_st pointer

 

exts_size

will be updated with the number of exts

 

flags

Or sequence of GNUTLS_PKCS11_OBJ_* flags

 

Returns

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

Since: 3.3.8


gnutls_pkcs11_obj_get_flags ()

int
gnutls_pkcs11_obj_get_flags (gnutls_pkcs11_obj_t obj,
                             unsigned int *oflags);

This function will return the flags of the object. The oflags will be flags from gnutls_pkcs11_obj_flags. That is, the GNUTLS_PKCS11_OBJ_FLAG_MARK_* flags.

Parameters

obj

The pkcs11 object

 

oflags

Will hold the output flags

 

Returns

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

Since: 3.3.7


gnutls_pkcs11_obj_flags_get_str ()

char *
gnutls_pkcs11_obj_flags_get_str (unsigned int 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().

Parameters

flags

holds the flags

 

Returns

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

Since: 3.3.7


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.

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


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.

Parameters

key

A pointer to the type to be initialized

 

Returns

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


gnutls_pkcs11_privkey_cpy ()

int
gnutls_pkcs11_privkey_cpy (gnutls_pkcs11_privkey_t dst,
                           gnutls_pkcs11_privkey_t src);

This function will copy a private key from source to destination key. Destination has to be initialized.

Parameters

dst

The destination key, which should be initialized.

 

src

The source key

 

Returns

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

Since: 3.4.0


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

void
gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t key);

This function will deinitialize a private key structure.

Parameters

key

the key to be deinitialized

 

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 type

 

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

 

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

Parameters

pkey

The private key

 

url

a PKCS 11 url identifying the key

 

flags

Or sequence of GNUTLS_PKCS11_OBJ_* flags

 

Returns

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


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

unsigned
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_privkey_generate3 ()

int
gnutls_pkcs11_privkey_generate3 (const char *url,
                                 gnutls_pk_algorithm_t pk,
                                 unsigned int bits,
                                 const char *label,
                                 const gnutls_datum_t *cid,
                                 gnutls_x509_crt_fmt_t fmt,
                                 gnutls_datum_t *pubkey,
                                 unsigned int key_usage,
                                 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.6.3 the objects are marked as sensitive by default unless GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE is specified.

Parameters

url

a token URL

 

pk

the public key algorithm

 

bits

the security bits

 

label

a label

 

cid

The CKA_ID to use for the new object

 

fmt

the format of output params. PEM or DER

 

pubkey

will hold the public key (may be NULL)

 

key_usage

One of GNUTLS_KEY_*

 

flags

zero or an OR'ed sequence of GNUTLS_PKCS11_OBJ_FLAGs

 

Returns

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

Since: 3.4.0


gnutls_pkcs11_privkey_export_pubkey ()

int
gnutls_pkcs11_privkey_export_pubkey (gnutls_pkcs11_privkey_t pkey,
                                     gnutls_x509_crt_fmt_t fmt,
                                     gnutls_datum_t *pubkey,
                                     unsigned int flags);

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

Parameters

pkey

The private key

 

fmt

the format of output params. PEM or DER.

 

data

will hold the public key

 

flags

should be zero

 

Returns

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

Since: 3.3.7


gnutls_pkcs11_token_get_random ()

int
gnutls_pkcs11_token_get_random (const char *token_url,
                                void *data,
                                size_t len);

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.

Parameters

token_url

A PKCS 11 URL specifying a token

 

len

The number of bytes of randomness to request

 

rnddata

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

 

Returns

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


gnutls_pkcs11_copy_attached_extension ()

int
gnutls_pkcs11_copy_attached_extension (const char *token_url,
                                       gnutls_x509_crt_t crt,
                                       gnutls_datum_t *data,
                                       const char *label,
                                       unsigned int flags);

This function will copy an the attached extension in data for the certificate provided in crt in the PKCS 11 token specified by the URL (typically a trust module). The extension must be in RFC5280 Extension format.

Parameters

token_url

A PKCS 11 URL specifying a token

 

crt

An X.509 certificate object

 

data

the attached extension

 

label

A name to be used for the attached extension (may be NULL)

 

flags

One of GNUTLS_PKCS11_OBJ_FLAG_*

 

Returns

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

Since: 3.3.8

Types and Values

GNUTLS_PKCS11_MAX_PIN_LEN

#define GNUTLS_PKCS11_MAX_PIN_LEN 256

gnutls_pkcs11_obj_t

typedef struct gnutls_pkcs11_obj_st *gnutls_pkcs11_obj_t;

GNUTLS_PKCS11_FLAG_MANUAL

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

GNUTLS_PKCS11_FLAG_AUTO

#define             GNUTLS_PKCS11_FLAG_AUTO

GNUTLS_PKCS11_FLAG_AUTO_TRUSTED

#define             GNUTLS_PKCS11_FLAG_AUTO_TRUSTED

enum gnutls_pkcs11_obj_flags

Enumeration of different PKCS 11 object flags. Some flags are used to mark objects when storing, while others are also used while seeking or retrieving objects.

Members

GNUTLS_PKCS11_OBJ_FLAG_LOGIN

Force login in the token for the operation (seek+store).

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED

object marked as trusted (seek+store).

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE

object is explicitly marked as sensitive -unexportable (store).

 

GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO

force login as a security officer in the token for the operation (seek+store).

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE

marked as private -requires PIN to access (store).

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_PRIVATE

marked as not private (store).

 

GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY

When retrieving an object, do not set any requirements (store).

 

GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_TRUSTED

When retrieving an object, only retrieve the marked as trusted (alias to GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED). In gnutls_pkcs11_crt_is_known() it implies GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_COMPARE if GNUTLS_PKCS11_OBJ_FLAG_COMPARE_KEY is not given.

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_DISTRUSTED

When writing an object, mark it as distrusted (store).

 

GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED

When retrieving an object, only retrieve the marked as distrusted (seek).

 

GNUTLS_PKCS11_OBJ_FLAG_COMPARE

When checking an object's presence, fully compare it before returning any result (seek).

 

GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE

The object must be present in a marked as trusted module (seek).

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_CA

Mark the object as a CA (seek+store).

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_KEY_WRAP

Mark the generated key pair as wrapping and unwrapping keys (store).

 

GNUTLS_PKCS11_OBJ_FLAG_COMPARE_KEY

When checking an object's presence, compare the key before returning any result (seek).

 

GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT

When an issuer is requested, override its extensions with the ones present in the trust module (seek).

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_ALWAYS_AUTH

Mark the key pair as requiring authentication (pin entry) before every operation (seek+store).

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_EXTRACTABLE

Mark the key pair as being extractable (store).

 

GNUTLS_PKCS11_OBJ_FLAG_NEVER_EXTRACTABLE

If set, the object was never marked as extractable (store).

 

GNUTLS_PKCS11_OBJ_FLAG_CRT

When searching, restrict to certificates only (seek).

 

GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY

   

GNUTLS_PKCS11_OBJ_FLAG_PUBKEY

When searching, restrict to public key objects only (seek).

 

GNUTLS_PKCS11_OBJ_FLAG_NO_STORE_PUBKEY

When generating a keypair don't store the public key (store).

 

GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY

When searching, restrict to private key objects only (seek).

 

GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE

object marked as not sensitive -exportable (store).

 

gnutls_pkcs11_obj_attr_t

#define gnutls_pkcs11_obj_attr_t gnutls_pkcs11_obj_flags

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.

 

enum gnutls_pkcs11_obj_info_t

Enumeration of several object information types.

Members

GNUTLS_PKCS11_OBJ_ID_HEX

The object ID in hex. Null-terminated text.

 

GNUTLS_PKCS11_OBJ_LABEL

The object label. Null-terminated text.

 

GNUTLS_PKCS11_OBJ_TOKEN_LABEL

The token's label. Null-terminated text.

 

GNUTLS_PKCS11_OBJ_TOKEN_SERIAL

The token's serial number. Null-terminated text.

 

GNUTLS_PKCS11_OBJ_TOKEN_MANUFACTURER

The token's manufacturer. Null-terminated text.

 

GNUTLS_PKCS11_OBJ_TOKEN_MODEL

The token's model. Null-terminated text.

 

GNUTLS_PKCS11_OBJ_ID

The object ID. Raw bytes.

 

GNUTLS_PKCS11_OBJ_LIBRARY_VERSION

The library's version. Null-terminated text.

 

GNUTLS_PKCS11_OBJ_LIBRARY_DESCRIPTION

The library's description. Null-terminated text.

 

GNUTLS_PKCS11_OBJ_LIBRARY_MANUFACTURER

The library's manufacturer name. Null-terminated text.

 

GNUTLS_PKCS11_OBJ_ATTR_CRT_ALL

#define GNUTLS_PKCS11_OBJ_ATTR_CRT_ALL GNUTLS_PKCS11_OBJ_FLAG_CRT

GNUTLS_PKCS11_OBJ_ATTR_MATCH

#define GNUTLS_PKCS11_OBJ_ATTR_MATCH 0 /* always match the given URL */

GNUTLS_PKCS11_OBJ_ATTR_ALL

#define GNUTLS_PKCS11_OBJ_ATTR_ALL 0 /* match everything! */

GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED

#define             GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED

GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY

#define             GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY

GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED_CA

#define             GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED_CA

GNUTLS_PKCS11_OBJ_ATTR_PUBKEY

#define GNUTLS_PKCS11_OBJ_ATTR_PUBKEY GNUTLS_PKCS11_OBJ_FLAG_PUBKEY

GNUTLS_PKCS11_OBJ_ATTR_PRIVKEY

#define GNUTLS_PKCS11_OBJ_ATTR_PRIVKEY GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY

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)

 

GNUTLS_PKCS11_TOKEN_MODNAME

The token's module name (string - since 3.4.3). This value is unavailable for providers which were manually loaded.

 

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.

 

GNUTLS_PKCS11_OBJ_X509_CRT_EXTENSION

X.509 certificate extension (supported by p11-kit trust module only).

 

GNUTLS_PKCS11_TOKEN_HW

#define GNUTLS_PKCS11_TOKEN_HW 1

GNUTLS_PKCS11_TOKEN_TRUSTED

#define GNUTLS_PKCS11_TOKEN_TRUSTED (1 << 1) /* p11-kit trusted */

GNUTLS_PKCS11_TOKEN_RNG

#define GNUTLS_PKCS11_TOKEN_RNG (1 << 2) /* CKF_RNG */

GNUTLS_PKCS11_TOKEN_LOGIN_REQUIRED

#define GNUTLS_PKCS11_TOKEN_LOGIN_REQUIRED (1 << 3) /* CKF_LOGIN_REQUIRED */

GNUTLS_PKCS11_TOKEN_PROTECTED_AUTHENTICATION_PATH

#define             GNUTLS_PKCS11_TOKEN_PROTECTED_AUTHENTICATION_PATH

GNUTLS_PKCS11_TOKEN_INITIALIZED

#define GNUTLS_PKCS11_TOKEN_INITIALIZED (1 << 5) /* CKF_TOKEN_INITIALIZED */

GNUTLS_PKCS11_TOKEN_USER_PIN_COUNT_LOW

#define             GNUTLS_PKCS11_TOKEN_USER_PIN_COUNT_LOW

GNUTLS_PKCS11_TOKEN_USER_PIN_FINAL_TRY

#define             GNUTLS_PKCS11_TOKEN_USER_PIN_FINAL_TRY

GNUTLS_PKCS11_TOKEN_USER_PIN_LOCKED

#define GNUTLS_PKCS11_TOKEN_USER_PIN_LOCKED (1 << 8) /* CKF_USER_PIN_LOCKED */

GNUTLS_PKCS11_TOKEN_SO_PIN_COUNT_LOW

#define GNUTLS_PKCS11_TOKEN_SO_PIN_COUNT_LOW (1 << 9) /* CKF_SO_PIN_COUNT_LOW */

GNUTLS_PKCS11_TOKEN_SO_PIN_FINAL_TRY

#define             GNUTLS_PKCS11_TOKEN_SO_PIN_FINAL_TRY

GNUTLS_PKCS11_TOKEN_SO_PIN_LOCKED

#define GNUTLS_PKCS11_TOKEN_SO_PIN_LOCKED (1 << 11) /* CKF_SO_PIN_LOCKED */

GNUTLS_PKCS11_TOKEN_USER_PIN_INITIALIZED

#define             GNUTLS_PKCS11_TOKEN_USER_PIN_INITIALIZED

GNUTLS_PKCS11_TOKEN_ERROR_STATE

#define GNUTLS_PKCS11_TOKEN_ERROR_STATE (1 << 13) /* CKF_ERROR_STATE */

gnutls_x509_crt_import_pkcs11_url

#define gnutls_x509_crt_import_pkcs11_url gnutls_x509_crt_import_url

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