Test Stubs for PKCS#11 Library

HSM function stubs for CryptoAPI. More...

Classes
struct	SessionStub
	Session state object. More...

Macros
#define	LX(event)   alexaClientSDK::avsCommon::utils::logger::LogEntry(TAG, event)
#define	CK_PTR   *
#define	CK_DECLARE_FUNCTION(returnType, name)   returnType name
#define	CK_DECLARE_FUNCTION_POINTER(returnType, name)   returnType(*name)
#define	CK_CALLBACK_FUNCTION(returnType, name)   returnType(*name)
#define	NULL_PTR   nullptr

Functions
static std::shared_ptr< SessionStub >	findSession (CK_SESSION_HANDLE sessionHandle)
	Helper to find session by handle. More...
CK_RV	C_GetFunctionList (CK_FUNCTION_LIST_PTR_PTR result)
	Provides function table. More...
static void	initializeKey (AlgorithmType type, CryptoCodecInterface::Key &key, DigestInterface::DataBlock &checksum)
CK_RV	C_Initialize (CK_VOID_PTR reserved)
	Initializes module. More...
CK_RV	C_Finalize (CK_VOID_PTR reserved)
	Releases module data. More...
CK_RV	C_GetSlotList (CK_BBOOL tokenPresent, CK_SLOT_ID_PTR slotList, CK_ULONG_PTR slotListSize)
	Provides slot list. More...
CK_RV	C_GetTokenInfo (CK_SLOT_ID slotID, CK_TOKEN_INFO_PTR tokenInfo)
	Provide token info. More...
CK_RV	C_OpenSession (CK_SLOT_ID slotID, CK_FLAGS flags, CK_VOID_PTR application, CK_NOTIFY notify, CK_SESSION_HANDLE_PTR sessionHandle)
	Opens a new session. More...
CK_RV	C_CloseSession (CK_SESSION_HANDLE sessionHandle)
	Terminates session. More...
CK_RV	C_Login (CK_SESSION_HANDLE sessionHandle, CK_USER_TYPE type, CK_UTF8CHAR_PTR pin, CK_ULONG pinLen)
	Performs login. More...
CK_RV	C_Logout (CK_SESSION_HANDLE sessionHandle)
CK_RV	C_GetAttributeValue (CK_SESSION_HANDLE sessionHandle, CK_OBJECT_HANDLE objectHandle, CK_ATTRIBUTE_PTR attributes, CK_ULONG attributeCount)
CK_RV	C_FindObjectsInit (CK_SESSION_HANDLE sessionHandle, CK_ATTRIBUTE_PTR attributes, CK_ULONG attributeCount)
	Initializes object search. More...
CK_RV	C_FindObjects (CK_SESSION_HANDLE sessionHandle, CK_OBJECT_HANDLE_PTR objectHandles, CK_ULONG maxObjectCount, CK_ULONG_PTR objectCount)
	Finds objects matching search criteria. More...
CK_RV	C_FindObjectsFinal (CK_SESSION_HANDLE sessionHandle)
	Finishes object search. More...
CK_RV	C_EncryptInit (CK_SESSION_HANDLE sessionHandle, CK_MECHANISM_PTR mechanism, CK_OBJECT_HANDLE keyHandle)
	Initializes encryption operation. More...
CK_RV	C_Encrypt (CK_SESSION_HANDLE sessionHandle, CK_BYTE_PTR plaintext, CK_ULONG plaintextLen, CK_BYTE_PTR ciphertext, CK_ULONG_PTR ciphertextLen)
	Performs encryption. More...
CK_RV	C_DecryptInit (CK_SESSION_HANDLE sessionHandle, CK_MECHANISM_PTR mechanism, CK_OBJECT_HANDLE keyHandle)
	Initializes decryption operation. More...
CK_RV	C_Decrypt (CK_SESSION_HANDLE sessionHandle, CK_BYTE_PTR ciphertext, CK_ULONG ciphertextLen, CK_BYTE_PTR plaintext, CK_ULONG_PTR plaintextLen)
	Performs decryption. More...

Variables
static CK_FUNCTION_LIST	FUNCTION_LIST
	PKCS11 function list table. More...
static constexpr CK_OBJECT_CLASS	UNSPECIFIED_OBJECT_CLASS = (CK_OBJECT_CLASS)-1
	Constant to indicate unspecified value for object class attribute. More...
static constexpr CK_KEY_TYPE	UNSPECIFIED_KEY_TYPE = (CK_KEY_TYPE)-1
	Constant to indicate unspecified value for key type attribute. More...
static constexpr CK_ULONG	UNSPECIFIED_VALUE_LEN = (CK_ULONG)-1
	Constant to indicate unspecified value for value length attribute. More...
static constexpr CK_SLOT_ID	DEFAULT_SLOT_ID = 1
	Default slot id. More...
static constexpr CK_OBJECT_HANDLE	AES256_KEY_OBJECT_HANDLE = 2
	AES256 key object handle. More...
static constexpr CK_OBJECT_HANDLE	AES128_KEY_OBJECT_HANDLE = 3
	AES128 key object handle. More...
static constexpr CK_ULONG	AES_BLOCK_SIZE = 16
	AES block size in bytes. More...
static constexpr int	AES_GCM_TAG_SIZE = 16
	AES GCM tag size in bytes. More...
static constexpr CK_ULONG	AES256_KEY_SIZE = 32
	Key size in bytes for AES 256. More...
static constexpr CK_ULONG	AES128_KEY_SIZE = 16
	Key size in bytes for AES 128. More...
static std::shared_ptr< CryptoFactoryInterface >	c_cryptoFactory
	Crypto factory to HSM function simulations. More...
static KeyFactoryInterface::Key	c_aes256Key
	AES 256 key value. This stub generates key value on initialization. More...
static KeyFactoryInterface::Key	c_aes128Key
	AES 128 key value. This stub generates key value on initialization. More...
static DigestInterface::DataBlock	c_aes256Checksum
static DigestInterface::DataBlock	c_aes128Checksum
	AES 128 key checksum. More...
static CK_ULONG	c_sessionCounter
	Counter to generate unique session handle values. More...
static std::unordered_map< CK_ULONG, std::shared_ptr< SessionStub > >	c_sessions
	Session map. More...
static std::mutex	c_sessionsMutex
	Session map mutex. More...

Detailed Description

HSM function stubs for CryptoAPI.

This module provide bare-bone stub functionality subset from PKCS#11 specification. Only few functions are implemented, and code can expect the following:

• There is only one hardcoded slot with ACSDK token name.
• User PIN is hardcoded to 1234 value.
• There are two object that corresponds to AES-256 and AES-128 keys with TEST_KEY name.
• Code supports AES encryption and decryption operations using Cryptographic Functions Implementation.

This is a test support module, and must not be used either for integration tests or in production.

See also

Cryptography API

Hardware Security Module Functions

Cryptographic Functions Implementation

Macro Definition Documentation

CK_CALLBACK_FUNCTION

#define CK_CALLBACK_FUNCTION	(		returnType,
			name
	)		returnType(*name)

CK_DECLARE_FUNCTION

#define CK_DECLARE_FUNCTION	(		returnType,
			name
	)		returnType name

CK_DECLARE_FUNCTION_POINTER

#define CK_DECLARE_FUNCTION_POINTER	(		returnType,
			name
	)		returnType(*name)

CK_PTR

#define CK_PTR   *

LX

#define LX

(

event

)

alexaClientSDK::avsCommon::utils::logger::LogEntry(TAG, event)

Create a LogEntry using this file's TAG and the specified event string.

Parameters

event

The event string for this LogEntry.

NULL_PTR

#define NULL_PTR   nullptr

Function Documentation

C_CloseSession()

CK_RV C_CloseSession

(

CK_SESSION_HANDLE

sessionHandle

)

Terminates session.

Parameters

[in]

sessionHandle

Session handle.

Returns

CKR_OK on success, or error code on failure.

C_Decrypt()

CK_RV C_Decrypt	(	CK_SESSION_HANDLE	sessionHandle,
		CK_BYTE_PTR	ciphertext,
		CK_ULONG	ciphertextLen,
		CK_BYTE_PTR	plaintext,
		CK_ULONG_PTR	plaintextLen
	)

Performs decryption.

Method decrypts data block or signal an error. Any result except CKR_BUFFER_TOO_SMALL terminates decryption operation.

Parameters

[in]	sessionHandle	Session handle.
[in]	ciphertext	Optional ciphertext output.
[in]	ciphertextLen	Size of ciphertext buffer on input, and required size on output.
[out]	plaintext	Plaintext data.
[in,out]	plaintextLen	Size of plaintext.

Returns

CKR_OK on success, or error code on failure.

Return values

CKR_BUFFER_TOO_SMALL

Indicates the plaintextLen was too small.

C_DecryptInit()

CK_RV C_DecryptInit	(	CK_SESSION_HANDLE	sessionHandle,
		CK_MECHANISM_PTR	mechanism,
		CK_OBJECT_HANDLE	keyHandle
	)

Initializes decryption operation.

Parameters

[in]	sessionHandle	Session handle.
[in]	mechanism	Encryption parameters.
[in]	keyHandle	Key handle.

Returns

CKR_OK on success, or error code on failure.

C_Encrypt()

CK_RV C_Encrypt	(	CK_SESSION_HANDLE	sessionHandle,
		CK_BYTE_PTR	plaintext,
		CK_ULONG	plaintextLen,
		CK_BYTE_PTR	ciphertext,
		CK_ULONG_PTR	ciphertextLen
	)

Performs encryption.

Method encrypts data block or signal an error. Any result except CKR_BUFFER_TOO_SMALL terminates encryption operation.

Parameters

[in]	sessionHandle	Session handle.
[in]	plaintext	Plaintext data.
[in]	plaintextLen	Size of plaintext.
[out]	ciphertext	Optional ciphertext output.
[in,out]	ciphertextLen	Size of ciphertext buffer on input, and required size on output.

Returns

CKR_OK on success, or error code on failure.

Return values

CKR_BUFFER_TOO_SMALL

Indicates the ciphertextLen was too small.

C_EncryptInit()

CK_RV C_EncryptInit	(	CK_SESSION_HANDLE	sessionHandle,
		CK_MECHANISM_PTR	mechanism,
		CK_OBJECT_HANDLE	keyHandle
	)

Initializes encryption operation.

Parameters

[in]	sessionHandle	Session handle.
[in]	mechanism	Encryption parameters.
[in]	keyHandle	Key handle.

Returns

CKR_OK on success, or error code on failure.

C_Finalize()

CK_RV C_Finalize

(

CK_VOID_PTR

reserved

)

Releases module data.

Parameters

reserved

Unused parameter. The value must be nullptr.

Returns

CKR_OK on success, error code on failure.

C_FindObjects()

CK_RV C_FindObjects	(	CK_SESSION_HANDLE	sessionHandle,
		CK_OBJECT_HANDLE_PTR	objectHandles,
		CK_ULONG	maxObjectCount,
		CK_ULONG_PTR	objectCount
	)

Finds objects matching search criteria.

This method provides object handles that match search criteria.

Parameters

[in]	sessionHandle	Session handle.
[out]	objectHandles	Discovered object handles.
[in]	maxObjectCount	Maximum number of objects to locate.
[out]	objectCount	Number of objects located.

Returns

CKR_OK on success, or error code on failure.

C_FindObjectsFinal()

CK_RV C_FindObjectsFinal

(

CK_SESSION_HANDLE

sessionHandle

)

Finishes object search.

Parameters

[in]

sessionHandle

Session handle.

Returns

CKR_OK on success, or error code on failure.

C_FindObjectsInit()

CK_RV C_FindObjectsInit	(	CK_SESSION_HANDLE	sessionHandle,
		CK_ATTRIBUTE_PTR	attributes,
		CK_ULONG	attributeCount
	)

Initializes object search.

This method configures object search parametrs.

Parameters

[in]	sessionHandle	Session handle.
[in]	attributes	Attributes to match.
[in]	attributeCount	Number of attributes to query.

Returns

CKR_OK on success, or error code on failure.

C_GetAttributeValue()

CK_RV C_GetAttributeValue	(	CK_SESSION_HANDLE	sessionHandle,
		CK_OBJECT_HANDLE	objectHandle,
		CK_ATTRIBUTE_PTR	attributes,
		CK_ULONG	attributeCount
	)

Method returns object attributes. This implementation supports only subset of attributes.

Parameters

[in]	sessionHandle	Session handle.
[in]	objectHandle	Object handle.
[in,out]	attributes	Attributes to query.
[in]	attributeCount	Number of attributes to query.

Returns

CKR_OK on success, or error code on failure.

C_GetFunctionList()

CK_RV C_GetFunctionList

(

CK_FUNCTION_LIST_PTR_PTR

result

)

Provides function table.

This method provides function table for PKCS#11 interface.

Parameters

[out]

result

Pointer to store function table.

Returns

CRK_OK on success.

C_GetSlotList()

CK_RV C_GetSlotList	(	CK_BBOOL	tokenPresent,
		CK_SLOT_ID_PTR	slotList,
		CK_ULONG_PTR	slotListSize
	)

Provides slot list.

This method returns a single hardcoded slot id.

Parameters

	tokenPresent	Flag if the slot must have token.
[out]	slotList	Optional pointer for slot ids with at least slotListSize elements
[in,out]	slotListSize	Number of elements in slotList.

Returns

CKR_OK on success, or error code on failure.

C_GetTokenInfo()

CK_RV C_GetTokenInfo	(	CK_SLOT_ID	slotID,
		CK_TOKEN_INFO_PTR	tokenInfo
	)

Provide token info.

Provides token info for supported slot.

Parameters

[in]	slotID	Slot id.
[out]	tokenInfo	Token information.

Returns

CKR_OK on success, or error code on failure.

C_Initialize()

CK_RV C_Initialize

(

CK_VOID_PTR

reserved

)

Initializes module.

This method generates a new unique key and computes key signature.

Parameters

reserved

Unused parameter.

Returns

CKR_OK on success, error code on failure.

C_Login()

CK_RV C_Login	(	CK_SESSION_HANDLE	sessionHandle,
		CK_USER_TYPE	type,
		CK_UTF8CHAR_PTR	pin,
		CK_ULONG	pinLen
	)

Performs login.

Parameters

[in]	sessionHandle	Session handle.
[in]	type	Login type.
[in]	pin	User pin.
[in]	pinLen	Length of user pin.

Returns

CKR_OK on success, or error code on failure.

C_Logout()

CK_RV C_Logout

(

CK_SESSION_HANDLE

sessionHandle

)

Performs logout.

Parameters

[in]

sessionHandle

Session handle.

Returns

CKR_OK on success, or error code on failure.

C_OpenSession()

CK_RV C_OpenSession	(	CK_SLOT_ID	slotID,
		CK_FLAGS	flags,
		CK_VOID_PTR	application,
		CK_NOTIFY	notify,
		CK_SESSION_HANDLE_PTR	sessionHandle
	)

Opens a new session.

Method allocates and registers new session object and provides session handle.

Parameters

[in]	slotID	Slot id.
[in]	flags	Session flags.
[in]	application	Optional application-specific pointer for callbacks.
[in]	notify	Optional callback function.
[out]	sessionHandle	Session handle.

Returns

CKR_OK on success, or error code on failure.

findSession()

static std::shared_ptr<SessionStub> findSession ( CK_SESSION_HANDLE  sessionHandle )

static

Helper to find session by handle.

This method looks up session object in session map.

Parameters

sessionHandle

Session handle.

Returns

Session pointer or nullptr on error.

initializeKey()

static void initializeKey ( AlgorithmType  type, CryptoCodecInterface::Key &  key, DigestInterface::DataBlock &  checksum  )

static

Variable Documentation

AES128_KEY_OBJECT_HANDLE

constexpr CK_OBJECT_HANDLE AES128_KEY_OBJECT_HANDLE = 3

staticconstexpr

AES128 key object handle.

AES128_KEY_SIZE

constexpr CK_ULONG AES128_KEY_SIZE = 16

staticconstexpr

Key size in bytes for AES 128.

AES256_KEY_OBJECT_HANDLE

constexpr CK_OBJECT_HANDLE AES256_KEY_OBJECT_HANDLE = 2

staticconstexpr

AES256 key object handle.

AES256_KEY_SIZE

constexpr CK_ULONG AES256_KEY_SIZE = 32

staticconstexpr

Key size in bytes for AES 256.

AES_BLOCK_SIZE

constexpr CK_ULONG AES_BLOCK_SIZE = 16

staticconstexpr

AES block size in bytes.

AES_GCM_TAG_SIZE

constexpr int AES_GCM_TAG_SIZE = 16

staticconstexpr

AES GCM tag size in bytes.

c_aes128Checksum

DigestInterface::DataBlock c_aes128Checksum

static

AES 128 key checksum.

c_aes128Key

KeyFactoryInterface::Key c_aes128Key

static

AES 128 key value. This stub generates key value on initialization.

c_aes256Checksum

DigestInterface::DataBlock c_aes256Checksum

static

AES 256 key checksum. It is three bytes, that correspond to c_mainKey data. Unlike PKCS#11 spec, we use SHA-256 algorithm to produce checksum instead of SHA-1.

c_aes256Key

KeyFactoryInterface::Key c_aes256Key

static

AES 256 key value. This stub generates key value on initialization.

c_cryptoFactory

std::shared_ptr<CryptoFactoryInterface> c_cryptoFactory

static

Crypto factory to HSM function simulations.

c_sessionCounter

CK_ULONG c_sessionCounter

static

Counter to generate unique session handle values.

c_sessions

std::unordered_map<CK_ULONG, std::shared_ptr<SessionStub> > c_sessions

static

Session map.

c_sessionsMutex

std::mutex c_sessionsMutex

static

Session map mutex.

DEFAULT_SLOT_ID

constexpr CK_SLOT_ID DEFAULT_SLOT_ID = 1

staticconstexpr

Default slot id.

FUNCTION_LIST

CK_FUNCTION_LIST FUNCTION_LIST

static

PKCS11 function list table.

This table is returned to PKCS11 client from C_Initialize call.

UNSPECIFIED_KEY_TYPE

constexpr CK_KEY_TYPE UNSPECIFIED_KEY_TYPE = (CK_KEY_TYPE)-1

staticconstexpr

Constant to indicate unspecified value for key type attribute.

UNSPECIFIED_OBJECT_CLASS

constexpr CK_OBJECT_CLASS UNSPECIFIED_OBJECT_CLASS = (CK_OBJECT_CLASS)-1

staticconstexpr

Constant to indicate unspecified value for object class attribute.

UNSPECIFIED_VALUE_LEN

constexpr CK_ULONG UNSPECIFIED_VALUE_LEN = (CK_ULONG)-1

staticconstexpr

Constant to indicate unspecified value for value length attribute.