pkcs11-helper
pkcs11-helper core interface

Topics

 PKCS11H_FEATURE_MASK
 pkcs11-helper features mask.
 PKCS11H_LOG
 pkcs11-helper log level.
 PKCS11H_PRIVATEMODE_MASK
 Signature mask selection. .
 PKCS11H_SLOTEVENT_METHOD
 Slotevent mode selection. .
 PKCS11H_PROMPT_MASK
 Prompt mask selection. .
 PKCS11H_ENUM_METHOD
 Enumeration mode selection. .
 PKCS11H_ENUM_PROPERTY
 Library properties. .
 PKCS11H_ENUM_PROVIDER_PROPERTY
 Provider properties. .

Files

file  pkcs11h-core.h
 pkcs11-helper core.

Classes

struct  pkcs11h_token_id_s
 Token identifier. More...

Macros

#define PKCS11H_PIN_CACHE_INFINITE   -1
#define PKCS11H_VERSION
 Library version.

Typedefs

typedef struct pkcs11h_token_id_spkcs11h_token_id_t
 Token identifier.
typedef void(* pkcs11h_hook_log_t) (IN void *const global_data, IN const unsigned flags, IN const char *const format, IN va_list args)
 Log hook.
typedef void(* pkcs11h_hook_slotevent_t) (IN void *const global_data)
 Slotevent hook.
typedef PKCS11H_BOOL(* pkcs11h_hook_token_prompt_t) (IN void *const global_data, IN void *const user_data, IN const pkcs11h_token_id_t token, IN const unsigned retry)
 Token prompt hook.
typedef PKCS11H_BOOL(* pkcs11h_hook_pin_prompt_t) (IN void *const global_data, IN void *const user_data, IN const pkcs11h_token_id_t token, IN const unsigned retry, OUT char *const pin, IN const size_t pin_max)
 PIN prompt hook.
typedef PKCS11H_BOOL(* pkcs11h_hook_key_prompt_t) (IN void *const global_data, IN void *const user_data, IN const pkcs11h_token_id_t token, IN const char *const label, IN const unsigned retry, OUT char *const pin, IN const size_t pin_max)
 Key prompt hook.

Functions

const char * pkcs11h_getMessage (IN const CK_RV rv)
 Get message by return value.
unsigned int pkcs11h_getVersion (void)
 Get version of library.
unsigned int pkcs11h_getFeatures (void)
 Get features of library.
CK_RV pkcs11h_initialize (void)
 Initialize helper interface.
CK_RV pkcs11h_terminate (void)
 Terminate helper interface.
CK_RV pkcs11h_getProperty (IN const unsigned property, OUT void *const value, IN OUT size_t *const value_size)
 Get library property.
CK_RV pkcs11h_setProperty (IN const unsigned property, IN const void *const value, IN const size_t value_size)
 Set library property.
void pkcs11h_setLogLevel (IN const unsigned flags)
 Set current log level of the helper.
unsigned pkcs11h_getLogLevel (void)
 Get current log level.
CK_RV pkcs11h_setForkMode (IN const PKCS11H_BOOL safe)
 How does the foked process bahaves after POSIX fork()
CK_RV pkcs11h_setLogHook (IN const pkcs11h_hook_log_t hook, IN void *const global_data)
 Set a log callback.
CK_RV pkcs11h_setSlotEventHook (IN const pkcs11h_hook_slotevent_t hook, IN void *const global_data)
 Set a slot event callback.
CK_RV pkcs11h_setTokenPromptHook (IN const pkcs11h_hook_token_prompt_t hook, IN void *const global_data)
 Set a token prompt callback.
CK_RV pkcs11h_setPINPromptHook (IN const pkcs11h_hook_pin_prompt_t hook, IN void *const global_data)
 Set a pin prompt callback.
CK_RV pkcs11h_setProtectedAuthentication (IN const PKCS11H_BOOL allow_protected_auth)
 Set global protected authentication mode.
CK_RV pkcs11h_setPINCachePeriod (IN const int pin_cache_period)
 Set global PIN cache timeout.
CK_RV pkcs11h_setMaxLoginRetries (IN const unsigned max_retries)
 Set global login retries attempts.
CK_RV pkcs11h_addProvider (IN const char *const reference, IN const char *const provider_location, IN const PKCS11H_BOOL allow_protected_auth, IN const unsigned mask_private_mode, IN const unsigned slot_event_method, IN const unsigned slot_poll_interval, IN const PKCS11H_BOOL cert_is_private)
 Register, configure and initialize a PKCS#11 provider.
CK_RV pkcs11h_registerProvider (IN const char *const reference)
 Register a PKCS#11 provider.
CK_RV pkcs11h_setProviderPropertyByName (IN const char *const reference, IN const char *const property_str, IN const char *const value_str)
 Set PKCS#11 provider property by name.
CK_RV pkcs11h_setProviderProperty (IN const char *const reference, IN const unsigned property, IN const void *value, IN const size_t value_size)
 Set PKCS#11 provider property.
CK_RV pkcs11h_initializeProvider (IN const char *const reference)
 Initialize a PKCS#11 provider.
CK_RV pkcs11h_removeProvider (IN const char *const reference)
 Delete a PKCS#11 provider.
CK_RV pkcs11h_forkFixup (void)
 Handle special case of POSIX fork()
CK_RV pkcs11h_plugAndPlay (void)
 Handle slot rescan.
CK_RV pkcs11h_logout (void)
 Logout from all sessions.

Detailed Description

Core functionality.

Core functionality.

Macro Definition Documentation

◆ PKCS11H_PIN_CACHE_INFINITE

#define PKCS11H_PIN_CACHE_INFINITE   -1

Infinite session limit

Examples
test-certificate.c.

Typedef Documentation

◆ pkcs11h_hook_key_prompt_t

typedef PKCS11H_BOOL(* pkcs11h_hook_key_prompt_t) (IN void *const global_data, IN void *const user_data, IN const pkcs11h_token_id_t token, IN const char *const label, IN const unsigned retry, OUT char *const pin, IN const size_t pin_max)

Key prompt hook.

Parameters
global_dataHook data.
user_dataLocal data.
tokenToken.
labelKey label
retryRetry counter.
pinPIN buffer.
pin_maxPIN buffer size.
Returns
TRUE success.

◆ pkcs11h_hook_log_t

typedef void(* pkcs11h_hook_log_t) (IN void *const global_data, IN const unsigned flags, IN const char *const format, IN va_list args)

Log hook.

Parameters
global_dataHook data.
flagsLog flags.
formatprintf style format.
argsstdargs

◆ pkcs11h_hook_pin_prompt_t

typedef PKCS11H_BOOL(* pkcs11h_hook_pin_prompt_t) (IN void *const global_data, IN void *const user_data, IN const pkcs11h_token_id_t token, IN const unsigned retry, OUT char *const pin, IN const size_t pin_max)

PIN prompt hook.

Parameters
global_dataHook data.
user_dataLocal data.
tokenToken.
retryRetry counter.
pinPIN buffer.
pin_maxPIN buffer size.
Returns
TRUE success.

◆ pkcs11h_hook_slotevent_t

typedef void(* pkcs11h_hook_slotevent_t) (IN void *const global_data)

Slotevent hook.

Parameters
global_dataHook data.

◆ pkcs11h_hook_token_prompt_t

typedef PKCS11H_BOOL(* pkcs11h_hook_token_prompt_t) (IN void *const global_data, IN void *const user_data, IN const pkcs11h_token_id_t token, IN const unsigned retry)

Token prompt hook.

Parameters
global_dataHook data.
user_dataLocal data.
tokenToken.
retryRetry counter.
Returns
TRUE success.

Function Documentation

◆ pkcs11h_addProvider()

CK_RV pkcs11h_addProvider ( IN const char *const reference,
IN const char *const provider_location,
IN const PKCS11H_BOOL allow_protected_auth,
IN const unsigned mask_private_mode,
IN const unsigned slot_event_method,
IN const unsigned slot_poll_interval,
IN const PKCS11H_BOOL cert_is_private )

Register, configure and initialize a PKCS#11 provider.

Parameters
referenceReference name for this provider.
provider_locationProvider library location.
allow_protected_authAllow this provider to use protected authentication.
mask_private_modeProvider private mode PKCS11H_PRIVATEMODE_MASK override.
slot_event_methodProvider slot event PKCS11H_SLOTEVENT_METHOD method.
slot_poll_intervalSlot event poll interval (If in polling mode), specify 0 for default.
cert_is_privateProvider's certificate access should be done after login.
Returns
CK_RV.
Attention
This function must be called from the main thread.
Note
The global allow_protected_auth must be enabled in order to allow provider specific.
Examples
test-basic.c, test-certificate.c, and test-slotevent.c.

◆ pkcs11h_forkFixup()

CK_RV pkcs11h_forkFixup ( void )

Handle special case of POSIX fork()

Returns
CK_RV.
Attention
This function must be called once from the main thread of child process. It must be called before any pkcs11-helper calls. In case you do not want to use PKCS#11 at child, call this function and then pkcs11h_terminate.
This function should be called after fork is called. This is required due to a limitation of the PKCS#11 standard.
Note
The helper library handles fork automatically if PKCS11H_FEATURE_MASK_THREADING is set by use of pthread_atfork. When PKCS11H_FEATURE_MASK_THREADING is enabled this function does nothing.

◆ pkcs11h_getFeatures()

unsigned int pkcs11h_getFeatures ( void )

Get features of library.

Returns
feature mask PKCS11H_FEATURE_MASK.
Examples
test-basic.c.

◆ pkcs11h_getLogLevel()

unsigned pkcs11h_getLogLevel ( void )

Get current log level.

Returns
Log level PKCS11H_LOG.

◆ pkcs11h_getMessage()

const char * pkcs11h_getMessage ( IN const CK_RV rv)

Get message by return value.

Parameters
rvReturn value.
Returns
CK_RV.
Examples
test-basic.c, test-certificate.c, and test-slotevent.c.

◆ pkcs11h_getProperty()

CK_RV pkcs11h_getProperty ( IN const unsigned property,
OUT void *const value,
IN OUT size_t *const value_size )

Get library property.

Parameters
propertyProperty kind.
valueProperty value.
value_sizesize of dereferenced property value.
Returns
CK_RV.
Note
Referenced type has to satisfy PKCS11H_ENUM_PROPERTY.

◆ pkcs11h_getVersion()

unsigned int pkcs11h_getVersion ( void )

Get version of library.

Returns
version identifier.
Examples
test-basic.c.

◆ pkcs11h_initialize()

CK_RV pkcs11h_initialize ( void )

Initialize helper interface.

Returns
CK_RV.
See also
pkcs11h_terminate().
Attention
This function must be called from the main thread.
Examples
test-basic.c, test-certificate.c, and test-slotevent.c.

◆ pkcs11h_initializeProvider()

CK_RV pkcs11h_initializeProvider ( IN const char *const reference)

Initialize a PKCS#11 provider.

Parameters
referenceReference name for this provider.
Attention
This function must be called from the main thread.
Note
The global allow_protected_auth must be enabled in order to allow provider specific.
Returns
CK_RV.

◆ pkcs11h_logout()

CK_RV pkcs11h_logout ( void )

Logout from all sessions.

Returns
CK_RV.

◆ pkcs11h_plugAndPlay()

CK_RV pkcs11h_plugAndPlay ( void )

Handle slot rescan.

Returns
CK_RV.
Attention
This function must be called from the main thread.
Remarks
PKCS#11 providers do not allow plug&play, plug&play can be established by finalizing all providers and initializing them again.
The cost of this process is invalidating all sessions, and require user login at the next access.

◆ pkcs11h_registerProvider()

CK_RV pkcs11h_registerProvider ( IN const char *const reference)

Register a PKCS#11 provider.

Parameters
referenceReference name for this provider.
Returns
CK_RV.

◆ pkcs11h_removeProvider()

CK_RV pkcs11h_removeProvider ( IN const char *const reference)

Delete a PKCS#11 provider.

Parameters
referenceReference name for this provider.
Returns
CK_RV.
Attention
This function must be called from the main thread.
Examples
test-slotevent.c.

◆ pkcs11h_setForkMode()

CK_RV pkcs11h_setForkMode ( IN const PKCS11H_BOOL safe)

How does the foked process bahaves after POSIX fork()

Parameters
safeSafe mode, default is false.
Returns
CK_RV.
Attention
This function should be called after pkcs11h_initialize()
Note
This function is relevant if PKCS11H_FEATURE_MASK_THREADING is set. If safe mode is on, the child process can use the loaded PKCS#11 providers but it cannot use fork(), while it is in one of the hooks functions, since locked mutexes cannot be released.

◆ pkcs11h_setLogHook()

CK_RV pkcs11h_setLogHook ( IN const pkcs11h_hook_log_t hook,
IN void *const global_data )

Set a log callback.

Parameters
hookCallback.
global_dataData to send to callback.
Returns
CK_RV.
Examples
test-basic.c, test-certificate.c, and test-slotevent.c.

◆ pkcs11h_setLogLevel()

void pkcs11h_setLogLevel ( IN const unsigned flags)

Set current log level of the helper.

Parameters
flagsCurrent log level PKCS11H_LOG.
Examples
test-basic.c, test-certificate.c, and test-slotevent.c.

◆ pkcs11h_setMaxLoginRetries()

CK_RV pkcs11h_setMaxLoginRetries ( IN const unsigned max_retries)

Set global login retries attempts.

Parameters
max_retriesLogin retries handled by the helper.
Returns
CK_RV.
Note
Default is 3.

◆ pkcs11h_setPINCachePeriod()

CK_RV pkcs11h_setPINCachePeriod ( IN const int pin_cache_period)

Set global PIN cache timeout.

Parameters
pin_cache_periodCache period in seconds, or PKCS11H_PIN_CACHE_INFINITE.
Returns
CK_RV.
Note
Default is infinite.

◆ pkcs11h_setPINPromptHook()

CK_RV pkcs11h_setPINPromptHook ( IN const pkcs11h_hook_pin_prompt_t hook,
IN void *const global_data )

Set a pin prompt callback.

Parameters
hookCallback.
global_dataData to send to callback.
Returns
CK_RV.
Attention
If pkcs11h_setForkMode() is true, you cannot fork while in hook.
Examples
test-certificate.c.

◆ pkcs11h_setProperty()

CK_RV pkcs11h_setProperty ( IN const unsigned property,
IN const void *const value,
IN const size_t value_size )

Set library property.

Parameters
propertyProperty kind.
valueProperty value.
value_sizesize of dereferenced property value.
Returns
CK_RV.
Note
Referenced type has to satisfy PKCS11H_ENUM_PROPERTY.

◆ pkcs11h_setProtectedAuthentication()

CK_RV pkcs11h_setProtectedAuthentication ( IN const PKCS11H_BOOL allow_protected_auth)

Set global protected authentication mode.

Parameters
allow_protected_authAllow protected authentication if enabled by token.
Returns
CK_RV.
Note
Default is on.

◆ pkcs11h_setProviderProperty()

CK_RV pkcs11h_setProviderProperty ( IN const char *const reference,
IN const unsigned property,
IN const void * value,
IN const size_t value_size )

Set PKCS#11 provider property.

Parameters
referenceReference name for this provider.
propertyProperty kind.
valueProperty value.
value_sizesize of dereferenced property value.
Returns
CK_RV.
Note
Referenced type has to satisfy PKCS11H_ENUM_PROVIDER_PROPERTY.

◆ pkcs11h_setProviderPropertyByName()

CK_RV pkcs11h_setProviderPropertyByName ( IN const char *const reference,
IN const char *const property_str,
IN const char *const value_str )

Set PKCS#11 provider property by name.

Parameters
referenceReference name for this provider.
property_strProperty kind.
value_strProperty value.

◆ pkcs11h_setSlotEventHook()

CK_RV pkcs11h_setSlotEventHook ( IN const pkcs11h_hook_slotevent_t hook,
IN void *const global_data )

Set a slot event callback.

Parameters
hookCallback.
global_dataData to send to callback.
Returns
CK_RV.
See also
pkcs11h_terminate().
Attention
Calling this function initialize slot event notifications, these notifications can be started, but never terminate due to PKCS#11 limitation.
Note
In order to use slot events you must have threading PKCS11H_FEATURE_MASK_THREADING enabled.
Examples
test-slotevent.c.

◆ pkcs11h_setTokenPromptHook()

CK_RV pkcs11h_setTokenPromptHook ( IN const pkcs11h_hook_token_prompt_t hook,
IN void *const global_data )

Set a token prompt callback.

Parameters
hookCallback.
global_dataData to send to callback.
Returns
CK_RV.
Attention
If pkcs11h_setForkMode() is true, you cannot fork while in hook.
Examples
test-certificate.c.

◆ pkcs11h_terminate()

CK_RV pkcs11h_terminate ( void )

Terminate helper interface.

Returns
CK_RV.
Attention
This function must be called from the main thread.
Examples
test-basic.c, test-certificate.c, and test-slotevent.c.

pkcs11-helper, Copyright (C) Alon Bar-Lev <alon.barlev@gmail.com>OpenSC-Project.org Logo