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

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)

This document was generated on May 31, 2014 using texi2html 5.0.