Hardware Security Module Functions

HSM functions for Cryptography API. More...

Namespaces
	alexaClientSDK::pkcs11
	HSM interface implementation.
	alexaClientSDK::pkcs11::test
	Test cases for Hardware Security Module Functions.

Functions
std::shared_ptr< alexaClientSDK::cryptoInterfaces::KeyStoreInterface >	alexaClientSDK::pkcs11::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 <acsdk/Pkcs11/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::pkcs11

alexaClientSDK::pkcs11::test

Function Documentation

createKeyStore()

std::shared_ptr<alexaClientSDK::cryptoInterfaces::KeyStoreInterface> alexaClientSDK::pkcs11::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::cryptoInterfaces::KeyStoreInterface

alexaClientSDK::avsCommon::utils::metrics::MetricRecorderInterface