Next: Reading objects, Previous: PKCS11 Manual Initialization, Up: Smart cards and HSMs [Contents][Index]
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_USERThe PIN for the user.
GNUTLS_PIN_SOThe PIN for the security officer (admin).
GNUTLS_PIN_FINAL_TRYThis is the final try before blocking.
GNUTLS_PIN_COUNT_LOWFew tries remain before token blocks.
GNUTLS_PIN_CONTEXT_SPECIFICThe PIN is for a specific action and key like signing.
GNUTLS_PIN_WRONGLast 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: Reading objects, Previous: PKCS11 Manual Initialization, Up: Smart cards and HSMs [Contents][Index]