HSM functions for Cryptography API. More...

Namespaces
	alexaClientSDK::acsdkPkcs11
	HSM interface implementation.

	alexaClientSDK::acsdkPkcs11::test
	Test cases for Hardware Security Module Functions.

Classes
class	alexaClientSDK::acsdkPkcs11::PKCS11Functions
	PKCS11 API Wrapper. More...

class	alexaClientSDK::acsdkPkcs11::PKCS11Key
	PKCS11 key object wrapper. More...

class	alexaClientSDK::acsdkPkcs11::PKCS11KeyStore
	Key store implementation for PKCS11. More...

class	alexaClientSDK::acsdkPkcs11::PKCS11Session
	PKCS11 session wrapper. More...

class	alexaClientSDK::acsdkPkcs11::PKCS11Slot
	PKCS11 slot wrapper. 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
std::shared_ptr< alexaClientSDK::acsdkCryptoInterfaces::KeyStoreInterface >	alexaClientSDK::acsdkPkcs11::createKeyStore (const std::shared_ptr< MetricRecorderInterface > &metricRecorder=nullptr) noexcept
	Create instance of `KeyStoreInterface`. More...

Detailed Description

HSM functions for Cryptography API.

Hardware Security Module Functions implements a subset of Cryptography API for hardware security module operations. Module provides access to data encryption and decryption functions using HSM-managed secrets.

This module requires platform configuration that provides the following information:

Path to vendor-specific PKCS#11 interface library
Token name
User PIN for accessing key functions
Default main key alias.

Vendor-specific PKCS#11 library provides low-level access to HSM functions. In production environment the configuration access must be restricted to a service user account, and library path must point to vendor-specific interface library.

In test environment, a software emulation or interception library can be used for development and debugging, but this doesn't provide any additional security.

The library provides a single method:

#include <acsdkPkcs11/KeyStoreFactory.h>
 
auto metricRecorder = ...;
auto factory = createKeyStoreFactory(metricRecorder);

Metric recorder interface enables failure reporting in a form of metrics. The table summarizes activities:

Activity	Description
"PKCS11-ENCRYPT"	Data encryption operation.
"PKCS11-DECRYPT"	Data decryption operation.

The next table summarizes metric counters:

Counter	Description
"FAILURE"	General purpose failure counter. This counter is always present if a failure occurrs.
"DECRYPT_ERROR"	Decryption failure. This counter is present when decryption operation fails.
"ENCRYPT_ERROR"	Encryption failure. This counter is present when encryption operation fails.
"CHECKSUM_ERROR"	Checksum check error. This counter is present when supplied checksum doesn't match one in HSM. The failure indicates the key has been replaces.
"GET_KEY_ERROR"	Key access failure. This counter indicates the key is no longer accessible.
"GET_CHECKSUM_ERROR"	Checksum check error. This error indicates the checksum is not available.
"EXTRACTABLE_KEY"	This counters indicate the key may have been compromized.

See also: Cryptography API; alexaClientSDK::acsdkPkcs11; alexaClientSDK::acsdkPkcs11::test

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

◆ createKeyStore()

std::shared_ptr< alexaClientSDK::acsdkCryptoInterfaces::KeyStoreInterface > alexaClientSDK::acsdkPkcs11::createKeyStore ( const std::shared_ptr< MetricRecorderInterface > & metricRecorder = nullptr )

noexcept

Create instance of KeyStoreInterface.

Method creates key store factory instance backed by hardware security module. This method dynamically loads dependencies according to configuration.

Parameters

[in] metricRecorder Optional reference of MetricRecorderInterface for operational and error metrics.

Returns: Key store reference or nullptr on error.

See also: alexaClientSDK::acsdkCryptoInterfaces::KeyStoreInterface; alexaClientSDK::avsCommon::utils::metrics::MetricRecorderInterface

Namespaces

Classes

Macros

Functions