source-git / p11-kit

Clone
Source Code
GIT

Blame doc/manual/html/p11-kit-PIN-Callbacks.html

c8 c8s master
  1.   3749ba2733d07fc588d392a87a0d080ee1894801
  2.   doc
  3.   manual
  4.   html
  5.   p11-kit-PIN-Callbacks.html
Blob History Raw
Packit Service 3749ba
Packit Service 3749ba 
<html>
Packit Service 3749ba 
<head>
Packit Service 3749ba 
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
Packit Service 3749ba 
<title>PIN Callbacks: p11-kit</title>
Packit Service 3749ba 
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
Packit Service 3749ba 
<link rel="home" href="index.html" title="p11-kit">
Packit Service 3749ba 
<link rel="up" href="reference.html" title="API Reference">
Packit Service 3749ba 
<link rel="prev" href="p11-kit-URIs.html" title="URIs">
Packit Service 3749ba 
<link rel="next" href="p11-kit-Utilities.html" title="Utilities">
Packit Service 3749ba 
<meta name="generator" content="GTK-Doc V1.32 (XML mode)">
Packit Service 3749ba 
<link rel="stylesheet" href="style.css" type="text/css">
Packit Service 3749ba 
</head>
Packit Service 3749ba 
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Top  | 
Packit Service 3749ba 
                  Description
Packit Service 3749ba
Packit Service 3749ba 
Home
Packit Service 3749ba 
Up
Packit Service 3749ba 
Prev
Packit Service 3749ba 
Next
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
PIN Callbacks
Packit Service 3749ba 
PIN Callbacks — PIN Callbacks
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Functions
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_new ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_new_for_buffer ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_new_for_string ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
const unsigned char *
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_get_value ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
size_t
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_get_length ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_ref ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
void
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_unref ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
int
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_register_callback ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
void
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_unregister_callback ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
(*p11_kit_pin_callback) ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_request ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
void
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
(*p11_kit_pin_destroy_func) ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_file_callback ()
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Types and Values
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
typedef
Packit Service 3749ba 
P11KitPin
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
enum
Packit Service 3749ba 
P11KitPinFlags
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
#define
Packit Service 3749ba 
P11_KIT_PIN_FALLBACK
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Description
Packit Service 3749ba 
Applications can register a callback which will be called to provide a
Packit Service 3749ba 
password associated with a given pin source.
Packit Service 3749ba 
PKCS#11 URIs can contain a 'pin-source' attribute. The value of this attribute
Packit Service 3749ba 
is application dependent, but often references a file containing a PIN to
Packit Service 3749ba 
use.
Packit Service 3749ba 
Using these functions, an applications or libraries can register a
Packit Service 3749ba 
callback with p11_kit_pin_register_callback() to be called when a given
Packit Service 3749ba 
'pin-source' attribute value is requested. The application can then prompt
Packit Service 3749ba 
the user or retrieve a PIN for the given context. These registered
Packit Service 3749ba 
callbacks are only relevant and valid within the current process.
Packit Service 3749ba 
A fallback callback can be registered by passing the P11_KIT_PIN_FALLBACK
Packit Service 3749ba 
value to p11_kit_pin_register_callback(). This fallback callback will be
Packit Service 3749ba 
called for every 'pin-source' attribute request for which no callback has been
Packit Service 3749ba 
directly registered.
Packit Service 3749ba 
To request a PIN for a given 'pin-source' attribute, use the
Packit Service 3749ba 
p11_kit_pin_request() function. If this function returns NULL then either
Packit Service 3749ba 
no callbacks were registered or none of them could handle the request.
Packit Service 3749ba 
If multiple callbacks are registered for the same PIN source, then they are
Packit Service 3749ba 
called in last-registered-first-called order. They are called in turn until
Packit Service 3749ba 
one of them can handle the request. Fallback callbacks are not called if
Packit Service 3749ba 
a callback was registered specifically for a requested 'pin-source' attribute.
Packit Service 3749ba 
PINs themselves are handled inside of P11KitPin structures. These are thread
Packit Service 3749ba 
safe and allow the callback to specify how the PIN is stored in memory
Packit Service 3749ba 
and freed. A callback can use p11_kit_pin_new_for_string() or related
Packit Service 3749ba 
functions to create a PIN to be returned.
Packit Service 3749ba 
For example in order to handle the following PKCS#11 URI with a 'pin-source'
Packit Service 3749ba 
attribute
Packit Service 3749ba

Packit Service 3749ba 
     pkcs11:id=\%69\%95\%3e\%5c\%f4\%bd\%ec\%91;pin-source=my-application
Packit Service 3749ba 
an application could register a callback like this:
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
        
1
Packit Service 3749ba 
2
Packit Service 3749ba 
3
Packit Service 3749ba 
4
Packit Service 3749ba 
5
Packit Service 3749ba 
6
Packit Service 3749ba 
7
Packit Service 3749ba 
8
Packit Service 3749ba 
9
Packit Service 3749ba 
10
Packit Service 3749ba 
        
static P11KitPin*
Packit Service 3749ba 
my_application_pin_callback (const char *pin_source, P11KitUri *pin_uri,
Packit Service 3749ba 
                             const char *pin_description, P11KitPinFlags pin_flags,
Packit Service 3749ba 
                             void *callback_data)
Packit Service 3749ba 
{
Packit Service 3749ba 
    return p11_kit_pin_new_from_string ("pin-value");
Packit Service 3749ba 
}
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_register_callback ("my-application", my_application_pin_callback,
Packit Service 3749ba 
                               NULL, NULL);
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Functions
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_new ()
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba 
p11_kit_pin_new (const unsigned char *value,
Packit Service 3749ba 
                 size_t length);
Packit Service 3749ba 
Create a new P11KitPin with the given PIN value. This function is
Packit Service 3749ba 
usually used from within registered PIN callbacks.
Packit Service 3749ba 
Exactly length
Packit Service 3749ba 
 bytes from value
Packit Service 3749ba 
 are used. Null terminated strings,
Packit Service 3749ba 
or encodings are not considered. A copy of the value
Packit Service 3749ba 
 will be made.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
value
Packit Service 3749ba 
the value of the PIN
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
length
Packit Service 3749ba 
the length of value
Packit Service 3749ba
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 The newly allocated P11KitPin, which should be freed with
Packit Service 3749ba 
p11_kit_pin_unref() when no longer needed.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_new_for_buffer ()
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba 
p11_kit_pin_new_for_buffer (unsigned char *buffer,
Packit Service 3749ba 
                            size_t length,
Packit Service 3749ba 
                            p11_kit_pin_destroy_func destroy);
Packit Service 3749ba 
Create a new P11KitPin which will use buffer
Packit Service 3749ba 
 for the PIN value.
Packit Service 3749ba 
This function is usually used from within registered PIN callbacks.
Packit Service 3749ba 
The buffer will not be copied. String encodings and null characters
Packit Service 3749ba 
are not considered.
Packit Service 3749ba 
When the last reference to this PIN is lost, then the destroy
Packit Service 3749ba 
 callback
Packit Service 3749ba 
function will be called passing buffer
Packit Service 3749ba 
 as an argument. This allows the
Packit Service 3749ba 
caller to use a buffer as a PIN without copying it.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
        
1
Packit Service 3749ba 
2
Packit Service 3749ba 
3
Packit Service 3749ba 
4
Packit Service 3749ba 
        
char *buffer = malloc (128);
Packit Service 3749ba 
P11KitPin *pin;
Packit Service 3749ba 
 ....
Packit Service 3749ba 
pin = p11_kit_pin_new_for_buffer (buffer, 128, free);
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
buffer
Packit Service 3749ba 
the value of the PIN
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
length
Packit Service 3749ba 
the length of buffer
Packit Service 3749ba
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
destroy
Packit Service 3749ba 
if not NULL, then called when PIN is destroyed.
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 The newly allocated P11KitPin, which should be freed with
Packit Service 3749ba 
p11_kit_pin_unref() when no longer needed.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_new_for_string ()
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba 
p11_kit_pin_new_for_string (const char *value);
Packit Service 3749ba 
Create a new P11KitPin for the given null-terminated string, such as a
Packit Service 3749ba 
password. This function is usually used from within registered
Packit Service 3749ba 
PIN callbacks.
Packit Service 3749ba 
The PIN will consist of the string not including the null terminator.
Packit Service 3749ba 
String encoding is not considered. A copy of the value
Packit Service 3749ba 
 will be made.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
value
Packit Service 3749ba 
the value of the PIN
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 The newly allocated P11KitPin, which should be freed with
Packit Service 3749ba 
p11_kit_pin_unref() when no longer needed.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_get_value ()
Packit Service 3749ba 
const unsigned char *
Packit Service 3749ba 
p11_kit_pin_get_value (P11KitPin *pin,
Packit Service 3749ba 
                       size_t *length);
Packit Service 3749ba 
Get the PIN value from a P11KitPin. length
Packit Service 3749ba 
 will be set to the
Packit Service 3749ba 
length of the value.
Packit Service 3749ba 
The value returned is owned by the P11KitPin and should not be modified.
Packit Service 3749ba 
It remains valid as long as a reference to the PIN is held. The PIN value
Packit Service 3749ba 
will not contain an extra null-terminator character.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin
Packit Service 3749ba 
the P11KitPin
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
length
Packit Service 3749ba 
a location to return the value length
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 the value for the PIN.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_get_length ()
Packit Service 3749ba 
size_t
Packit Service 3749ba 
p11_kit_pin_get_length (P11KitPin *pin);
Packit Service 3749ba 
Get the length of the PIN value from a P11KitPin.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin
Packit Service 3749ba 
the P11KitPin
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 the length of the PIN value.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_ref ()
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba 
p11_kit_pin_ref (P11KitPin *pin);
Packit Service 3749ba 
Add a reference to a P11KitPin. This should be matched with a later call
Packit Service 3749ba 
to p11_kit_pin_unref(). As long as at least one reference is held, the PIN
Packit Service 3749ba 
will remain valid and in memory.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin
Packit Service 3749ba 
the P11KitPin
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 the pin
Packit Service 3749ba 
pointer, for convenience sake.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_unref ()
Packit Service 3749ba 
void
Packit Service 3749ba 
p11_kit_pin_unref (P11KitPin *pin);
Packit Service 3749ba 
Remove a reference from a P11KitPin. When all references have been removed
Packit Service 3749ba 
then the PIN will be freed and will no longer be in memory.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin
Packit Service 3749ba 
the P11KitPin
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_register_callback ()
Packit Service 3749ba 
int
Packit Service 3749ba 
p11_kit_pin_register_callback (const char *pin_source,
Packit Service 3749ba 
                               p11_kit_pin_callback callback,
Packit Service 3749ba 
                               void *callback_data,
Packit Service 3749ba 
                               p11_kit_pin_destroy_func callback_destroy);
Packit Service 3749ba 
Register a callback to handle PIN requests for a given 'pin-source' attribute.
Packit Service 3749ba 
If pin_source
Packit Service 3749ba 
 is set to P11_KIT_PIN_FALLBACK then this will be a fallback
Packit Service 3749ba 
callback and will be called for requests for which no other callback has
Packit Service 3749ba 
been specifically registered.
Packit Service 3749ba 
If multiple callbacks are registered for the same pin_source
Packit Service 3749ba 
 value, then
Packit Service 3749ba 
the last registered callback will be the first to be called.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_source
Packit Service 3749ba 
the 'pin-source' attribute this this callback is for
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
callback
Packit Service 3749ba 
the callback function
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
callback_data
Packit Service 3749ba 
data that will be passed to the callback
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
callback_destroy
Packit Service 3749ba 
a function that will be called with callback_data
Packit Service 3749ba 
when
Packit Service 3749ba 
the callback is unregistered.
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 Returns negative if registering fails.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_unregister_callback ()
Packit Service 3749ba 
void
Packit Service 3749ba 
p11_kit_pin_unregister_callback (const char *pin_source,
Packit Service 3749ba 
                                 p11_kit_pin_callback callback,
Packit Service 3749ba 
                                 void *callback_data);
Packit Service 3749ba 
Unregister a callback that was previously registered with the
Packit Service 3749ba 
p11_kit_pin_register_callback() function. If more than one registered
Packit Service 3749ba 
callback matches the given arguments, then only one of those will be
Packit Service 3749ba 
removed.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_source
Packit Service 3749ba 
the 'pin-source' attribute the callback was registered for
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
callback
Packit Service 3749ba 
the callback function that was registered
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
callback_data
Packit Service 3749ba 
data that was registered for the callback
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_callback ()
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba 
(*p11_kit_pin_callback) (const char *pin_source,
Packit Service 3749ba 
                         P11KitUri *pin_uri,
Packit Service 3749ba 
                         const char *pin_description,
Packit Service 3749ba 
                         P11KitPinFlags pin_flags,
Packit Service 3749ba 
                         void *callback_data);
Packit Service 3749ba 
Represents a PIN callback function.
Packit Service 3749ba 
The various arguments are the same as the ones passed to
Packit Service 3749ba 
p11_kit_pin_request(). The callback_data
Packit Service 3749ba 
 argument was the one passed to
Packit Service 3749ba 
p11_kit_pin_register_callback() when registering this callback.
Packit Service 3749ba 
The function should return NULL if it could not provide a PIN, either
Packit Service 3749ba 
because of an error or a user cancellation.
Packit Service 3749ba 
If a PIN is returned, it will be unreferenced by the caller. So it should be
Packit Service 3749ba 
either newly allocated, or referenced before returning.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_source
Packit Service 3749ba 
a 'pin-source' attribute string
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_uri
Packit Service 3749ba 
a PKCS#11 URI that the PIN is for, or NULL
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_description
Packit Service 3749ba 
a descrption of what the PIN is for
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_flags
Packit Service 3749ba 
flags describing the PIN request
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
callback_data
Packit Service 3749ba 
data that was provided when registering this callback
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 A PIN or NULL
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_request ()
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba 
p11_kit_pin_request (const char *pin_source,
Packit Service 3749ba 
                     P11KitUri *pin_uri,
Packit Service 3749ba 
                     const char *pin_description,
Packit Service 3749ba 
                     P11KitPinFlags pin_flags);
Packit Service 3749ba 
Request a PIN for a given 'pin-source' attribute. The result depends on the
Packit Service 3749ba 
registered callbacks.
Packit Service 3749ba 
If not NULL, then the pin_uri
Packit Service 3749ba 
 attribute should point to the thing that the
Packit Service 3749ba 
PIN is being requested for. In most use cases this should be a PKCS#11 URI
Packit Service 3749ba 
pointing to a token.
Packit Service 3749ba 
The pin_description
Packit Service 3749ba 
 should always be specified. It is a string describing
Packit Service 3749ba 
what the PIN is for. For example this would be the token label, if the PIN
Packit Service 3749ba 
is for a token.
Packit Service 3749ba 
If more than one callback is registered for the pin_source
Packit Service 3749ba 
, then the latest
Packit Service 3749ba 
registered one will be called first. If that callback does not return a
Packit Service 3749ba 
PIN, then the next will be called in turn.
Packit Service 3749ba 
If no callback is registered for pin_source
Packit Service 3749ba 
, then the fallback callbacks will
Packit Service 3749ba 
be invoked in the same way. The fallback callbacks will not be called if any
Packit Service 3749ba 
callback has been registered specifically for pin_source
Packit Service 3749ba 
.
Packit Service 3749ba 
The PIN returned should be released with p11_kit_pin_unref().
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_source
Packit Service 3749ba 
the 'pin-source' attribute that is being requested
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_uri
Packit Service 3749ba 
a PKCS#11 URI that the PIN is being requested for, optionally NULL.
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_description
Packit Service 3749ba 
a description of what the PIN is for, must not be NULL.
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_flags
Packit Service 3749ba 
various flags for this request
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 the PIN which should be released with p11_kit_pin_unref(), or NULL
Packit Service 3749ba 
if no callback was registered or could proivde a PIN
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_destroy_func ()
Packit Service 3749ba 
void
Packit Service 3749ba 
(*p11_kit_pin_destroy_func) (void *data);
Packit Service 3749ba 
A function called to free or cleanup data
Packit Service 3749ba 
.
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
data
Packit Service 3749ba 
the data to destroy
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
p11_kit_pin_file_callback ()
Packit Service 3749ba 
P11KitPin *
Packit Service 3749ba 
p11_kit_pin_file_callback (const char *pin_source,
Packit Service 3749ba 
                           P11KitUri *pin_uri,
Packit Service 3749ba 
                           const char *pin_description,
Packit Service 3749ba 
                           P11KitPinFlags pin_flags,
Packit Service 3749ba 
                           void *callback_data);
Packit Service 3749ba 
This is a PIN callback function that looks up the 'pin-source' attribute in
Packit Service 3749ba 
a file with that name. This can be used to enable the normal PKCS#11 URI
Packit Service 3749ba 
behavior described in the RFC.
Packit Service 3749ba 
If pin_flags
Packit Service 3749ba 
 contains the P11_KIT_PIN_FLAGS_RETRY flag, then this
Packit Service 3749ba 
callback will always return NULL. This is to prevent endless loops
Packit Service 3749ba 
where an application is expecting to interact with a prompter, but
Packit Service 3749ba 
instead is interacting with this callback reading a file over and over.
Packit Service 3749ba 
This callback fails on files larger than 4 Kilobytes.
Packit Service 3749ba 
This callback is not registered by default. It may have security
Packit Service 3749ba 
implications depending on the source of the PKCS#11 URI and the PKCS#11
Packit Service 3749ba 
in use. To register it, use code like the following:
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
        
1
Packit Service 3749ba 
2
Packit Service 3749ba 
        
p11_kit_pin_register_callback (P11_KIT_PIN_FALLBACK, p11_kit_pin_file_callback,
Packit Service 3749ba 
                               NULL, NULL);
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Parameters
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_source
Packit Service 3749ba 
a 'pin-source' attribute string
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_uri
Packit Service 3749ba 
a PKCS#11 URI that the PIN is for, or NULL
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_description
Packit Service 3749ba 
a descrption of what the PIN is for
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
pin_flags
Packit Service 3749ba 
flags describing the PIN request
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
callback_data
Packit Service 3749ba 
unused, should be NULL
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Returns
Packit Service 3749ba 
 a referenced PIN with the file contents, or NULL if the file
Packit Service 3749ba 
could not be read
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Types and Values
Packit Service 3749ba
Packit Service 3749ba 
P11KitPin
Packit Service 3749ba 
typedef struct p11_kit_pin P11KitPin;
Packit Service 3749ba
Packit Service 3749ba 
A structure representing a PKCS#11 PIN. There are no public fields
Packit Service 3749ba 
visible in this structure. Use the various accessor functions.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
enum P11KitPinFlags
Packit Service 3749ba 
Flags that are passed to p11_kit_pin_request() and registered callbacks.
Packit Service 3749ba
Packit Service 3749ba 
Members
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11_KIT_PIN_FLAGS_USER_LOGIN
Packit Service 3749ba
Packit Service 3749ba 
The PIN is for a PKCS#11 user type login.
Packit Service 3749ba
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11_KIT_PIN_FLAGS_SO_LOGIN
Packit Service 3749ba
Packit Service 3749ba 
The PIN is for a PKCS#11 security officer type login.
Packit Service 3749ba
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11_KIT_PIN_FLAGS_CONTEXT_LOGIN
Packit Service 3749ba
Packit Service 3749ba 
The PIN is for a PKCS#11 contect specific type login.
Packit Service 3749ba
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11_KIT_PIN_FLAGS_RETRY
Packit Service 3749ba
Packit Service 3749ba 
The PIN is being requested again, due to an invalid previous PIN.
Packit Service 3749ba
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11_KIT_PIN_FLAGS_MANY_TRIES
Packit Service 3749ba
Packit Service 3749ba 
The PIN has failed too many times, and few tries are left.
Packit Service 3749ba
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11_KIT_PIN_FLAGS_FINAL_TRY
Packit Service 3749ba
Packit Service 3749ba 
The PIN has failed too many times, and this is the last try.
Packit Service 3749ba
Packit Service 3749ba 
 
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
P11_KIT_PIN_FALLBACK
Packit Service 3749ba 
#define P11_KIT_PIN_FALLBACK ""
Packit Service 3749ba
Packit Service 3749ba 
Used with p11_kit_pin_register_callback() to register a fallback callback.
Packit Service 3749ba 
This callback will be called if no other callback is registered for a 'pin-source'.
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba
Packit Service 3749ba 
Generated by GTK-Doc V1.32
Packit Service 3749ba 
</body>
Packit Service 3749ba 
</html>

Powered by Pagure 5.14.1

SSH Hostkey/Fingerprint | Documentation