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	pkcs11-helper-1.0/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.

References pkcs11h_addProvider().

Referenced by pkcs11h_addProvider().

◆ 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.

References pkcs11h_forkFixup().

Referenced by pkcs11h_forkFixup().

◆ pkcs11h_getFeatures()

unsigned int pkcs11h_getFeatures ( void )

Get features of library.

Returns: feature mask PKCS11H_FEATURE_MASK.

Examples: test-basic.c.

References pkcs11h_getFeatures().

Referenced by pkcs11h_getFeatures().

◆ pkcs11h_getLogLevel()

unsigned pkcs11h_getLogLevel ( void )

Get current log level.

Returns: Log level PKCS11H_LOG.

References pkcs11h_getLogLevel().

Referenced by pkcs11h_getLogLevel().

◆ 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.

References pkcs11h_getMessage().

Referenced by pkcs11h_getMessage().

◆ 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.

References pkcs11h_getProperty().

Referenced by pkcs11h_getProperty().

◆ pkcs11h_getVersion()

unsigned int pkcs11h_getVersion ( void )

Get version of library.

Returns: version identifier.

Examples: test-basic.c.

References pkcs11h_getVersion().

Referenced by pkcs11h_getVersion().

◆ 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.

References pkcs11h_initialize().

Referenced by pkcs11h_initialize().

◆ 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.

References pkcs11h_initializeProvider().

Referenced by pkcs11h_initializeProvider().

◆ pkcs11h_logout()

CK_RV pkcs11h_logout ( void )

Logout from all sessions.

Returns: CK_RV.

References pkcs11h_logout().

Referenced by pkcs11h_logout().

◆ 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.

References pkcs11h_plugAndPlay().

Referenced by pkcs11h_plugAndPlay().

◆ 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.

References pkcs11h_registerProvider().

Referenced by pkcs11h_registerProvider().

◆ 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.

References pkcs11h_removeProvider().

Referenced by pkcs11h_removeProvider().

◆ 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.

References pkcs11h_setForkMode().

Referenced by pkcs11h_setForkMode().

◆ 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.

References pkcs11h_setLogHook().

Referenced by pkcs11h_setLogHook().

◆ 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.

References pkcs11h_setLogLevel().

Referenced by pkcs11h_setLogLevel().

◆ 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.

References pkcs11h_setMaxLoginRetries().

Referenced by pkcs11h_setMaxLoginRetries().

◆ 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.

References pkcs11h_setPINCachePeriod().

Referenced by pkcs11h_setPINCachePeriod().

◆ 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.

References pkcs11h_setPINPromptHook().

Referenced by pkcs11h_setPINPromptHook().

◆ 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.

References pkcs11h_setProperty().

Referenced by pkcs11h_setProperty().

◆ 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.

References pkcs11h_setProtectedAuthentication().

Referenced by pkcs11h_setProtectedAuthentication().

◆ 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.

References pkcs11h_setProviderProperty().

Referenced by pkcs11h_setProviderProperty().

◆ 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.

References pkcs11h_setProviderPropertyByName().

Referenced by pkcs11h_setProviderPropertyByName().

◆ 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.

References pkcs11h_setSlotEventHook().

Referenced by pkcs11h_setSlotEventHook().

◆ 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.

References pkcs11h_setTokenPromptHook().

Referenced by pkcs11h_setTokenPromptHook().

◆ 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.

References pkcs11h_terminate().

Referenced by pkcs11h_terminate().

Topics

Files

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ PKCS11H_PIN_CACHE_INFINITE

Typedef Documentation

◆ pkcs11h_hook_key_prompt_t

◆ pkcs11h_hook_log_t

◆ pkcs11h_hook_pin_prompt_t

◆ pkcs11h_hook_slotevent_t

◆ pkcs11h_hook_token_prompt_t

Function Documentation

◆ pkcs11h_addProvider()

◆ pkcs11h_forkFixup()

◆ pkcs11h_getFeatures()

◆ pkcs11h_getLogLevel()

◆ pkcs11h_getMessage()

◆ pkcs11h_getProperty()

◆ pkcs11h_getVersion()

◆ pkcs11h_initialize()

◆ pkcs11h_initializeProvider()

◆ pkcs11h_logout()

◆ pkcs11h_plugAndPlay()

◆ pkcs11h_registerProvider()

◆ pkcs11h_removeProvider()

◆ pkcs11h_setForkMode()

◆ pkcs11h_setLogHook()

◆ pkcs11h_setLogLevel()

◆ pkcs11h_setMaxLoginRetries()

◆ pkcs11h_setPINCachePeriod()

◆ pkcs11h_setPINPromptHook()

◆ pkcs11h_setProperty()

◆ pkcs11h_setProtectedAuthentication()

◆ pkcs11h_setProviderProperty()

◆ pkcs11h_setProviderPropertyByName()

◆ pkcs11h_setSlotEventHook()

◆ pkcs11h_setTokenPromptHook()

◆ pkcs11h_terminate()