pkcs11-helper core interface

## Modules

| 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_s * | pkcs11h_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.

## 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_data | Hook data.
  user_data | Local data.
  token | Token.
  label | Key label
  retry | Retry counter.
  pin | PIN buffer.
  pin_max | PIN 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_data | Hook data.
  flags | Log flags.
  format | printf style format.
  args | stdargs

## 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_data | Hook data.
  user_data | Local data.
  token | Token.
  retry | Retry counter.
  pin | PIN buffer.
  pin_max | PIN buffer size.

Returns
  TRUE success.

## pkcs11h_hook_slotevent_t

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

Slotevent hook.

Parameters

  global_data | Hook 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_data | Hook data.
  user_data | Local data.
  token | Token.
  retry | Retry 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

  reference | Reference name for this provider.
  provider_location | Provider library location.
  allow_protected_auth | Allow this provider to use protected authentication.
  mask_private_mode | Provider private mode PKCS11H_PRIVATEMODE_MASK override.
  slot_event_method | Provider slot event PKCS11H_SLOTEVENT_METHOD method.
  slot_poll_interval | Slot event poll interval (If in polling mode), specify 0 for default.
  cert_is_private | Provider'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

  rv | Return 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

  property | Property kind.
  value | Property value.
  value_size | size 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

  reference | Reference 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

  reference | Reference name for this provider.

Returns
  CK_RV.

## pkcs11h_removeProvider()

CK_RV pkcs11h_removeProvider | ( | IN const char *const | reference | ) |

Delete a PKCS#11 provider.

Parameters

  reference | Reference 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

  safe | Safe 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

  hook | Callback.
  global_data | Data 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

  flags | Current 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_retries | Login 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_period | Cache 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

  hook | Callback.
  global_data | Data 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

  property | Property kind.
  value | Property value.
  value_size | size 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_auth | Allow 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

  reference | Reference name for this provider.
  property | Property kind.
  value | Property value.
  value_size | size 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

  reference | Reference name for this provider.
  property_str | Property kind.
  value_str | Property 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

  hook | Callback.
  global_data | Data 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

  hook | Callback.
  global_data | Data 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> |