pkcs11

pkcs11

Synopsis

#define             GNUTLS_PKCS11_MAX_PIN_LEN
int                 (*gnutls_pkcs11_token_callback_t)   (void *const global_data,
                                                         const char *const label,
                                                         const unsigned retry Param3);
enum                gnutls_pkcs11_pin_flag_t;
int                 (*gnutls_pkcs11_pin_callback_t)     (void *userdata,
                                                         int attempt,
                                                         const char *token_url,
                                                         const char *token_label,
                                                         unsigned int flags);
struct              gnutls_pkcs11_obj_st;
typedef             gnutls_pkcs11_obj_t;
#define             GNUTLS_PKCS11_FLAG_MANUAL
#define             GNUTLS_PKCS11_FLAG_AUTO
int                 gnutls_pkcs11_init                  (unsigned int flags,
                                                         const char *deprecated_config_file);
void                gnutls_pkcs11_deinit                (void);
void                gnutls_pkcs11_set_token_function    (gnutls_pkcs11_token_callback_t fn,
                                                         void *userdata);
void                gnutls_pkcs11_set_pin_function      (gnutls_pkcs11_pin_callback_t fn,
                                                         void *userdata);
int                 gnutls_pkcs11_add_provider          (const char *name,
                                                         const char *params);
int                 gnutls_pkcs11_obj_init              (gnutls_pkcs11_obj_t *obj);
#define             GNUTLS_PKCS11_OBJ_FLAG_LOGIN
#define             GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED
#define             GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE
enum                gnutls_pkcs11_url_type_t;
int                 gnutls_pkcs11_obj_import_url        (gnutls_pkcs11_obj_t Param1,
                                                         const char *url,
                                                         unsigned int flags);
int                 gnutls_pkcs11_obj_export_url        (gnutls_pkcs11_obj_t obj,
                                                         gnutls_pkcs11_url_type_t detailed,
                                                         char **url);
void                gnutls_pkcs11_obj_deinit            (gnutls_pkcs11_obj_t obj);
int                 gnutls_pkcs11_obj_export            (gnutls_pkcs11_obj_t obj,
                                                         void *output_data,
                                                         size_t *output_data_size);
int                 gnutls_pkcs11_copy_x509_crt         (const char *token_url,
                                                         gnutls_x509_crt_t crt,
                                                         const char *label,
                                                         unsigned int flags);
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);
int                 gnutls_pkcs11_delete_url            (const char *object_url,
                                                         unsigned int flags);
int                 gnutls_pkcs11_copy_secret_key       (const char *token_url,
                                                         gnutls_datum_t *key,
                                                         const char *label,
                                                         unsigned int key_usage,
                                                         unsigned int flags);
enum                gnutls_pkcs11_obj_info_t;
int                 gnutls_pkcs11_obj_get_info          (gnutls_pkcs11_obj_t crt,
                                                         gnutls_pkcs11_obj_info_t itype,
                                                         void *output,
                                                         size_t *output_size);
enum                gnutls_pkcs11_obj_attr_t;
enum                gnutls_pkcs11_token_info_t;
enum                gnutls_pkcs11_obj_type_t;
int                 gnutls_pkcs11_token_init            (const char *token_url,
                                                         const char *so_pin,
                                                         const char *label);
int                 gnutls_pkcs11_token_get_mechanism   (const char *url,
                                                         int idx,
                                                         unsigned long *mechanism);
int                 gnutls_pkcs11_token_set_pin         (const char *token_url,
                                                         const char *oldpin,
                                                         const char *newpin,
                                                         unsigned int flags);
int                 gnutls_pkcs11_token_get_url         (unsigned int seq,
                                                         gnutls_pkcs11_url_type_t detailed,
                                                         char **url);
int                 gnutls_pkcs11_token_get_info        (const char *url,
                                                         gnutls_pkcs11_token_info_t ttype,
                                                         void *output,
                                                         size_t *output_size);
#define             GNUTLS_PKCS11_TOKEN_HW
int                 gnutls_pkcs11_token_get_flags       (const char *url,
                                                         unsigned int *flags);
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);
int                 gnutls_x509_crt_import_pkcs11       (gnutls_x509_crt_t crt,
                                                         gnutls_pkcs11_obj_t pkcs11_crt);
int                 gnutls_x509_crt_import_pkcs11_url   (gnutls_x509_crt_t crt,
                                                         const char *url,
                                                         unsigned int flags);
gnutls_pkcs11_obj_type_t  gnutls_pkcs11_obj_get_type    (gnutls_pkcs11_obj_t certificate);
const char *        gnutls_pkcs11_type_get_name         (gnutls_pkcs11_obj_type_t Param1);
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);
int                 gnutls_pkcs11_privkey_init          (gnutls_pkcs11_privkey_t *key);
void                gnutls_pkcs11_privkey_deinit        (gnutls_pkcs11_privkey_t key);
int                 gnutls_pkcs11_privkey_get_pk_algorithm
                                                        (gnutls_pkcs11_privkey_t key,
                                                         unsigned int *bits);
int                 gnutls_pkcs11_privkey_get_info      (gnutls_pkcs11_privkey_t pkey,
                                                         gnutls_pkcs11_obj_info_t itype,
                                                         void *output,
                                                         size_t *output_size);
int                 gnutls_pkcs11_privkey_import_url    (gnutls_pkcs11_privkey_t pkey,
                                                         const char *url,
                                                         unsigned int flags);
int                 gnutls_pkcs11_privkey_export_url    (gnutls_pkcs11_privkey_t key,
                                                         gnutls_pkcs11_url_type_t detailed,
                                                         char **url);

Description

Details

GNUTLS_PKCS11_MAX_PIN_LEN

#define GNUTLS_PKCS11_MAX_PIN_LEN 32


gnutls_pkcs11_token_callback_t ()

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


enum gnutls_pkcs11_pin_flag_t

typedef enum
  {
    GNUTLS_PKCS11_PIN_USER = (1 << 0),
    GNUTLS_PKCS11_PIN_SO = (1 << 1),
    GNUTLS_PKCS11_PIN_FINAL_TRY = (1 << 2),
    GNUTLS_PKCS11_PIN_COUNT_LOW = (1 << 3),
    GNUTLS_PKCS11_PIN_CONTEXT_SPECIFIC = (1 << 4),
    GNUTLS_PKCS11_PIN_WRONG = (1 << 5),
  } gnutls_pkcs11_pin_flag_t;

Enumeration of different PIN flags.

GNUTLS_PKCS11_PIN_USER

The PIN for the user.

GNUTLS_PKCS11_PIN_SO

The PIN for the security officer.

GNUTLS_PKCS11_PIN_FINAL_TRY

This is the final try before blocking.

GNUTLS_PKCS11_PIN_COUNT_LOW

Few tries remain before token blocks.

GNUTLS_PKCS11_PIN_CONTEXT_SPECIFIC

The PIN is for a specific action and key like signing.

GNUTLS_PKCS11_PIN_WRONG

Last given PIN was not correct.

gnutls_pkcs11_pin_callback_t ()

int                 (*gnutls_pkcs11_pin_callback_t)     (void *userdata,
                                                         int attempt,
                                                         const char *token_url,
                                                         const char *token_label,
                                                         unsigned int flags);

Callback function type for PKCS11 PIN entry. It is set by gnutls_pkcs11_set_pin_function().

The callback should provides the PIN code to unlock the token with label token_label, specified by the URL token_url.

The PIN code, as a NUL-terminated ASCII string, should be copied into the pin buffer (of maximum size pin_max), and return 0 to indicate success. Alternatively, the callback may return a negative gnutls error code to indicate failure and cancel PIN entry (in which case, the contents of the pin parameter are ignored).

When a PIN is required, the callback will be invoked repeatedly (and indefinitely) until either the returned PIN code is correct, the callback returns failure, or the token refuses login (e.g. when the token is locked due to too many incorrect PINs!). For the first such invocation, the attempt counter will have value zero; it will increase by one for each subsequent attempt.

userdata :

user-controlled data from gnutls_pkcs11_set_pin_function().

attempt :

pin-attempt counter, initially 0.

token_url :

PKCS11 URL.

token_label :

label of PKCS11 token.

flags :

a gnutls_pkcs11_pin_flag_t flag.

Returns :

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

Since 2.12.0


struct gnutls_pkcs11_obj_st

struct gnutls_pkcs11_obj_st;


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 1       /* Automatically load libraries by reading /etc/gnutls/pkcs11.conf */


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.

Using a custom configfile is deprecated and will not be supported in future versions of gnutls.

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 you need to call this function, you must call it before gnutls_global_init().

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 is returned, otherwise a negative error value.

gnutls_pkcs11_deinit ()

void                gnutls_pkcs11_deinit                (void);

This function will deinitialize the PKCS 11 subsystem in gnutls.


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.

fn :

The token callback

userdata :

data to be supplied to callback

gnutls_pkcs11_set_pin_function ()

void                gnutls_pkcs11_set_pin_function      (gnutls_pkcs11_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.

Callback for PKCS11 PIN entry. The callback provides the PIN code to unlock the token with label 'token_label', specified by the URL 'token_url'.

The PIN code, as a NUL-terminated ASCII string, should be copied into the 'pin' buffer (of maximum size pin_max), and return 0 to indicate success. Alternatively, the callback may return a negative gnutls error code to indicate failure and cancel PIN entry (in which case, the contents of the 'pin' parameter are ignored).

When a PIN is required, the callback will be invoked repeatedly (and indefinitely) until either the returned PIN code is correct, the callback returns failure, or the token refuses login (e.g. when the token is locked due to too many incorrect PINs!). For the first such invocation, the 'attempt' counter will have value zero; it will increase by one for each subsequent attempt.

fn :

The PIN callback

userdata :

data to be supplied to callback

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.

name :

The filename of the module

params :

should be NULL

Returns :

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

gnutls_pkcs11_obj_init ()

int                 gnutls_pkcs11_obj_init              (gnutls_pkcs11_obj_t *obj);

This function will initialize a pkcs11 certificate structure.

obj :

The structure to be initialized

Returns :

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

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_MARK_TRUSTED

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


GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE

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


enum gnutls_pkcs11_url_type_t

typedef enum
{
  GNUTLS_PKCS11_URL_GENERIC,    /* URL specifies the object on token level */
  GNUTLS_PKCS11_URL_LIB,        /* URL specifies the object on module level */
  GNUTLS_PKCS11_URL_LIB_VERSION /* URL specifies the object on module and version level */
} gnutls_pkcs11_url_type_t;

Enumeration of different URL extraction flags.

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.

gnutls_pkcs11_obj_import_url ()

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


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.

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 is returned, otherwise a negative error value.

gnutls_pkcs11_obj_deinit ()

void                gnutls_pkcs11_obj_deinit            (gnutls_pkcs11_obj_t obj);

This function will deinitialize a certificate structure.

obj :

The structure to be initialized

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

If the structure is PEM encoded, it will have a header of "BEGIN CERTIFICATE".

obj :

Holds the object

output_data :

will contain a certificate PEM or DER encoded

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 value will be returned, and 0 on success.

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.

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 is returned, otherwise a negative error value.

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.

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 is returned, otherwise a negative error value.

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.

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.

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.

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 is returned, otherwise a negative error value.

enum gnutls_pkcs11_obj_info_t

typedef enum
{
  GNUTLS_PKCS11_OBJ_ID_HEX = 1,
  GNUTLS_PKCS11_OBJ_LABEL,
  GNUTLS_PKCS11_OBJ_TOKEN_LABEL,
  GNUTLS_PKCS11_OBJ_TOKEN_SERIAL,
  GNUTLS_PKCS11_OBJ_TOKEN_MANUFACTURER,
  GNUTLS_PKCS11_OBJ_TOKEN_MODEL,
  GNUTLS_PKCS11_OBJ_ID,
  /* the pkcs11 provider library info  */
  GNUTLS_PKCS11_OBJ_LIBRARY_VERSION,
  GNUTLS_PKCS11_OBJ_LIBRARY_DESCRIPTION,
  GNUTLS_PKCS11_OBJ_LIBRARY_MANUFACTURER
} gnutls_pkcs11_obj_info_t;

Enumeration of several object information types.

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.

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 PKCS 11 certificatesuch 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.

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 :

zero on success or a negative value on error.

enum gnutls_pkcs11_obj_attr_t

typedef enum
{
  GNUTLS_PKCS11_OBJ_ATTR_CRT_ALL = 1,   /* all certificates */
  GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED,   /* certificates marked as trusted */
  GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY,      /* certificates with corresponding private key */
  GNUTLS_PKCS11_OBJ_ATTR_PUBKEY,        /* public keys */
  GNUTLS_PKCS11_OBJ_ATTR_PRIVKEY,       /* private keys */
  GNUTLS_PKCS11_OBJ_ATTR_ALL    /* everything! */
} gnutls_pkcs11_obj_attr_t;

Enumeration of several attributes for object enumeration.

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.

enum gnutls_pkcs11_token_info_t

typedef enum
{
  GNUTLS_PKCS11_TOKEN_LABEL,
  GNUTLS_PKCS11_TOKEN_SERIAL,
  GNUTLS_PKCS11_TOKEN_MANUFACTURER,
  GNUTLS_PKCS11_TOKEN_MODEL
} gnutls_pkcs11_token_info_t;

Enumeration of types for retrieving token information.

GNUTLS_PKCS11_TOKEN_LABEL

The token's label

GNUTLS_PKCS11_TOKEN_SERIAL

The token's serial number

GNUTLS_PKCS11_TOKEN_MANUFACTURER

The token's manufacturer

GNUTLS_PKCS11_TOKEN_MODEL

The token's model

enum gnutls_pkcs11_obj_type_t

typedef enum
{
  GNUTLS_PKCS11_OBJ_UNKNOWN,
  GNUTLS_PKCS11_OBJ_X509_CRT,
  GNUTLS_PKCS11_OBJ_PUBKEY,
  GNUTLS_PKCS11_OBJ_PRIVKEY,
  GNUTLS_PKCS11_OBJ_SECRET_KEY,
  GNUTLS_PKCS11_OBJ_DATA
} gnutls_pkcs11_obj_type_t;

Enumeration of object types.

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

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 is returned, otherwise a negative error value.

gnutls_pkcs11_token_get_mechanism ()

int                 gnutls_pkcs11_token_get_mechanism   (const char *url,
                                                         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.

url :

should contain a PKCS 11 URL

idx :

The index of the mechanism

mechanism :

The PKCS 11 mechanism ID

Returns :

zero on success or a negative value on error.

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.

token_url :

A PKCS 11 URL specifying a token

oldpin :

old user's PIN

newpin :

new user's PIN

flags :

one of gnutls_pkcs11_pin_flag_t

Returns :

On success, GNUTLS_E_SUCCESS 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()

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 is returned, GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE if the sequence number exceeds the available tokens, otherwise a negative error value.

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 as well as token information where the key is stored.

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 :

zero on success or a negative value on error.

GNUTLS_PKCS11_TOKEN_HW

#define GNUTLS_PKCS11_TOKEN_HW 1


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.

url :

should contain a PKCS 11 URL

flags :

The output flags (GNUTLS_PKCS11_TOKEN_*)

Returns :

zero on success or a negative value on error.

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.

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 is returned, otherwise a negative error value.

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.

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 is returned, otherwise a negative error value.

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.

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 is returned, otherwise a negative error value.

gnutls_pkcs11_obj_get_type ()

gnutls_pkcs11_obj_type_t  gnutls_pkcs11_obj_get_type    (gnutls_pkcs11_obj_t certificate);

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

certificate :

Holds the PKCS 11 certificate

Returns :

The type of the certificate.

gnutls_pkcs11_type_get_name ()

const char *        gnutls_pkcs11_type_get_name         (gnutls_pkcs11_obj_type_t Param1);


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.

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

key :

The structure to be initialized

Returns :

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

gnutls_pkcs11_privkey_deinit ()

void                gnutls_pkcs11_privkey_deinit        (gnutls_pkcs11_privkey_t key);

This function will deinitialize a private key structure.

key :

The structure to be initialized

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.

key :

should contain a gnutls_pkcs11_privkey_t structure

Returns :

a member of the gnutls_pk_algorithm_t enumeration on success, or a negative value 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.

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 :

zero on success or a negative value 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 certificate key 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.

url :

a PKCS 11 url identifying the key

flags :

One of GNUTLS_PKCS11_OBJ_* flags

Returns :

On success, GNUTLS_E_SUCCESS 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.

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 is returned, otherwise a negative error value.