Logo Search packages:      
Sourcecode: p11-kit version File versions  Download package

Public Attributes

_PinCallback Struct Reference

Collaboration diagram for _PinCallback:
Collaboration graph

List of all members.

Public Attributes

p11_kit_pin_destroy_func destroy
p11_kit_pin_callback func
int refs
void * user_data

Detailed Description

SECTION:p11-kit-pin : PIN Callbacks : PIN Callbacks

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

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

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

an application could register a callback like this:

<informalexample><programlisting> static P11KitPin* my_application_pin_callback (const char *pin_source, P11KitUri *pin_uri, const char *pin_description, P11KitPinFlags pin_flags, void *callback_data) { return p11_kit_pin_new_from_string ("pin-value"); }

p11_kit_pin_register_callback ("my-application", my_application_pin_callback, NULL, NULL); </programlisting></informalexample> P11KitPinFlags: : The PIN is for a PKCS#11 user type login. : The PIN is for a PKCS#11 security officer type login. : The PIN is for a PKCS#11 contect specific type login. : The PIN is being requested again, due to an invalid previous PIN. : The PIN has failed too many times, and few tries are left. : The PIN has failed too many times, and this is the last try.

Flags that are passed to p11_kit_pin_request() and registered callbacks. P11_KIT_PIN_FALLBACK:

Used with p11_kit_pin_register_callback() to register a fallback callback. This callback will be called if no other String of URI scheme for PKCS#11 URIs.

Definition at line 134 of file pin.c.

The documentation for this struct was generated from the following file:

Generated by  Doxygen 1.6.0   Back to index