PIN Callbacks

PIN Callbacks — PIN Callbacks

Synopsis

typedef             P11KitPin;
P11KitPin *         p11_kit_pin_new                     (const unsigned char *value,
                                                         size_t length);
P11KitPin *         p11_kit_pin_new_for_buffer          (unsigned char *buffer,
                                                         size_t length,
                                                         p11_kit_pin_destroy_func destroy);
P11KitPin *         p11_kit_pin_new_for_string          (const char *value);
const unsigned char * p11_kit_pin_get_value             (P11KitPin *pin,
                                                         size_t *length);
size_t              p11_kit_pin_get_length              (P11KitPin *pin);
P11KitPin *         p11_kit_pin_ref                     (P11KitPin *pin);
void                p11_kit_pin_unref                   (P11KitPin *pin);
enum                P11KitPinFlags;
#define             P11_KIT_PIN_FALLBACK
int                 p11_kit_pin_register_callback       (const char *pin_source,
                                                         p11_kit_pin_callback callback,
                                                         void *callback_data,
                                                         p11_kit_pin_destroy_func callback_destroy);
void                p11_kit_pin_unregister_callback     (const char *pin_source,
                                                         p11_kit_pin_callback callback,
                                                         void *callback_data);
P11KitPin *         (*p11_kit_pin_callback)             (const char *pin_source,
                                                         P11KitUri *pin_uri,
                                                         const char *pin_description,
                                                         P11KitPinFlags pin_flags,
                                                         void *callback_data);
P11KitPin *         p11_kit_pin_request                 (const char *pin_source,
                                                         P11KitUri *pin_uri,
                                                         const char *pin_description,
                                                         P11KitPinFlags pin_flags);
void                (*p11_kit_pin_destroy_func)         (void *data);
P11KitPin *         p11_kit_pin_file_callback           (const char *pin_source,
                                                         P11KitUri *pin_uri,
                                                         const char *pin_description,
                                                         P11KitPinFlags pin_flags,
                                                         void *callback_data);

Description

Applications can register a callback which will be called to provide a password associated with a given pin source.

PKCS#11 URIs can contain a 'pin-source' attribute. The value of this attribute is application dependent, but often references a file containing a PIN to use.

Using these functions, an applications or libraries can register a callback with p11_kit_pin_register_callback() to be called when a given 'pin-source' attribute value is requested. The application can then prompt the user or retrieve a PIN for the given context. These registered callbacks are only relevant and valid within the current process.

A fallback callback can be registered by passing the P11_KIT_PIN_FALLBACK value to p11_kit_pin_register_callback(). This fallback callback will be called for every 'pin-source' attribute request for which no callback has been directly registered.

To request a PIN for a given 'pin-source' attribute, use the p11_kit_pin_request() function. If this function returns NULL then either no callbacks were registered or none of them could handle the request.

If multiple callbacks are registered for the same PIN source, then they are called in last-registered-first-called order. They are called in turn until one of them can handle the request. Fallback callbacks are not called if a callback was registered specifically for a requested 'pin-source' attribute.

PINs themselves are handled inside of P11KitPin structures. These are thread safe and allow the callback to specify how the PIN is stored in memory and freed. A callback can use p11_kit_pin_new_for_string() or related functions to create a PIN to be returned.

For example in order to handle the following PKCS#11 URI with a 'pin-source' attribute


     pkcs11:id=%69%95%3e%5c%f4%bd%ec%91;pin-source=my-application

an application could register a callback like this:

1
2
3
4
5
6
7
8
9
10
11
12
13