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.

GNUTLS_PIN_USER

The PIN for the user.

GNUTLS_PIN_SO

The PIN for the security officer (admin).

GNUTLS_PIN_FINAL_TRY

This is the final try before blocking.

GNUTLS_PIN_COUNT_LOW

Few tries remain before token blocks.

GNUTLS_PIN_CONTEXT_SPECIFIC

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

GNUTLS_PIN_WRONG

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]