Next: , Previous: , Up: Smart cards and HSMs   [Contents][Index]

5.3.3 Accessing objects that require a PIN

Objects stored in token such as a private keys are typically protected from access by a PIN or password. This PIN may be required to either read the object (if allowed) or to perform operations with it. To allow obtaining the PIN when accessing a protected object, as well as probe the user to insert the token the following functions allow to set a callback.

void gnutls_pkcs11_set_token_function (gnutls_pkcs11_token_callback_t fn, void * userdata)
void gnutls_pkcs11_set_pin_function (gnutls_pin_callback_t fn, void * userdata)
int gnutls_pkcs11_add_provider (const char * name, const char * params)
gnutls_pin_callback_t gnutls_pkcs11_get_pin_function (void ** userdata)

The callback is of type gnutls_pin_callback_t and will have as input the provided userdata, the PIN attempt number, a URL describing the token, a label describing the object and flags. The PIN must be at most of pin_max size and must be copied to pin variable. The function must return 0 on success or a negative error code otherwise.

typedef int (*gnutls_pin_callback_t) (void *userdata, int attempt,
                                      const char *token_url,
                                      const char *token_label,
                                      unsigned int flags,
                                      char *pin, size_t pin_max);

The flags are of gnutls_pin_flag_t type and are explained below.


The PIN for the user.


The PIN for the security officer (admin).


This is the final try before blocking.


Few tries remain before token blocks.


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


Last given PIN was not correct.

Figure 5.2: The gnutls_pin_flag_t enumeration.

Note that due to limitations of PKCS #11 there are issues when multiple libraries are sharing a module. To avoid this problem GnuTLS uses p11-kit that provides a middleware to control access to resources over the multiple users.

To avoid conflicts with multiple registered callbacks for PIN functions, gnutls_pkcs11_get_pin_function may be used to check for any previously set functions. In addition context specific PIN functions are allowed, e.g., by using functions below.

void gnutls_certificate_set_pin_function (gnutls_certificate_credentials_t cred, gnutls_pin_callback_t fn, void * userdata)
void gnutls_pubkey_set_pin_function (gnutls_pubkey_t key, gnutls_pin_callback_t fn, void * userdata)
void gnutls_privkey_set_pin_function (gnutls_privkey_t key, gnutls_pin_callback_t fn, void * userdata)
void gnutls_pkcs11_obj_set_pin_function (gnutls_pkcs11_obj_t obj, gnutls_pin_callback_t fn, void * userdata)
void gnutls_x509_crt_set_pin_function (gnutls_x509_crt_t crt, gnutls_pin_callback_t fn, void * userdata)

Next: , Previous: , Up: Smart cards and HSMs   [Contents][Index]