#include <KeyStoreInterface.h>

Inheritance diagram for alexaClientSDK::cryptoInterfaces::KeyStoreInterface:

Public Types
typedef std::vector< unsigned char >	DataBlock
	Data type for data block (encrypted or unencrypted). More...

typedef std::vector< unsigned char >	IV
	Data type for initialization vector data. More...

typedef std::vector< unsigned char >	KeyChecksum
	Data type for key checksum. More...

typedef std::vector< unsigned char >	Tag
	Data type for tag. Tag (known as Message Authentication Code) is used with AEAD mode of operation like with Galois/Counter mode. More...

Public Member Functions
virtual	~KeyStoreInterface () noexcept=default
	Default destructor. More...

virtual bool	encrypt (const std::string &keyAlias, AlgorithmType type, const IV &iv, const DataBlock &plaintext, KeyChecksum &checksum, DataBlock &ciphertext) noexcept=0
	Encrypts data block. More...

virtual bool	encryptAE (const std::string &keyAlias, AlgorithmType type, const IV &iv, const DataBlock &aad, const DataBlock &plaintext, KeyChecksum &checksum, DataBlock &ciphertext, Tag &tag) noexcept=0
	Encrypts data block using authenticated encryption algorithm. More...

virtual bool	decrypt (const std::string &keyAlias, AlgorithmType type, const KeyChecksum &checksum, const IV &iv, const DataBlock &ciphertext, DataBlock &plaintext) noexcept=0
	Decrypts data block. More...

virtual bool	decryptAD (const std::string &keyAlias, AlgorithmType type, const KeyChecksum &checksum, const IV &iv, const DataBlock &aad, const DataBlock &ciphertext, const Tag &tag, DataBlock &plaintext) noexcept=0
	Decrypts data block using authenticated decryption algorithm. More...

virtual bool	getDefaultKeyAlias (std::string &keyAlias) noexcept=0
	Returns default key alias. More...

Detailed Description

Key Store Interface.

Interface provides integration with platform-specific key storage and operations. The vendor can choose how to implement this interface for a best security.

This interface enables data encryption and decryption without accessing encryption key data. Keys must be provided by device manufacturer (vendor), and cryptography functions access those keys through key aliases.

ACSDK provides a reference implementation of this interface to integrate with Hardware Security Module through PKCS#11 API.

Thread Safety

This interface is thread safe and can be used concurrently by different threads.

See also: Hardware Security Module Functions

Member Typedef Documentation

◆ DataBlock

typedef std::vector<unsigned char> alexaClientSDK::cryptoInterfaces::KeyStoreInterface::DataBlock

Data type for data block (encrypted or unencrypted).

◆ IV

typedef std::vector<unsigned char> alexaClientSDK::cryptoInterfaces::KeyStoreInterface::IV

Data type for initialization vector data.

◆ KeyChecksum

typedef std::vector<unsigned char> alexaClientSDK::cryptoInterfaces::KeyStoreInterface::KeyChecksum

Data type for key checksum.

◆ Tag

typedef std::vector<unsigned char> alexaClientSDK::cryptoInterfaces::KeyStoreInterface::Tag

Data type for tag. Tag (known as Message Authentication Code) is used with AEAD mode of operation like with Galois/Counter mode.

Constructor & Destructor Documentation

◆ ~KeyStoreInterface()

virtual alexaClientSDK::cryptoInterfaces::KeyStoreInterface::~KeyStoreInterface ( )

virtualdefaultnoexcept

Default destructor.

Member Function Documentation

◆ decrypt()

virtual bool alexaClientSDK::cryptoInterfaces::KeyStoreInterface::decrypt	(	const std::string &	keyAlias,
		AlgorithmType	type,
		const KeyChecksum &	checksum,
		const IV &	iv,
		const DataBlock &	ciphertext,
		DataBlock &	plaintext
	)

pure virtualnoexcept

Decrypts data block.

Method decrypts data block. The method locates the key, checks if key type supports requested algorithm and has matching checksum (if checksum is supported), and performs decryption.

Parameters

[in]	keyAlias	Key alias.
[in]	type	Algorithm type to use. The method will fail, if type is AEAD algorithm like AES-GCM.
[in]	checksum	Key checksum if available. If implementation doesn't support checksum, the value of this parameter is ignored. The system checks checksum against checksum of a currently available key before decrypting data to ensure we don't try to use a different key, then the one, that has been used during encryption.
[in]	iv	Initialization vector. This vector must match have the same value, as the one used when encrypting data.
[in]	ciphertext	Data to decrypt.
[out]	plaintext	Decrypted data. This method appends data to plaintext.

Returns: Boolean indicating operation success. If operation fails, the contents of plaintext is undefined.

◆ decryptAD()

virtual bool alexaClientSDK::cryptoInterfaces::KeyStoreInterface::decryptAD	(	const std::string &	keyAlias,
		AlgorithmType	type,
		const KeyChecksum &	checksum,
		const IV &	iv,
		const DataBlock &	aad,
		const DataBlock &	ciphertext,
		const Tag &	tag,
		DataBlock &	plaintext
	)

pure virtualnoexcept

Decrypts data block using authenticated decryption algorithm.

Method decrypts data block using additional authenticated data and authentication tag (also known as Message Authentication Code/MAC). This method locates the key, checks if key type supports requested algorithm and has matching checksum (if checksum is supported), and performs decryption.

Parameters

[in]	keyAlias	Key alias.
[in]	type	Algorithm type to use. The method will fail, if type is not AEAD algorithm like AES-GCM.
[in]	checksum	Key checksum if available. If implementation doesn't support checksum, the value of this parameter is ignored. The system checks checksum against checksum of a currently available key before decrypting data to ensure we don't try to use a different key, then the one, that has been used during encryption.
[in]	iv	Initialization vector. This vector must match have the same value, as the one used when encrypting data.
[in]	aad	Additional authenticated data. This data must match AAD used when encrypting the content. Decryption will fail if the data doesn't match.
[in]	ciphertext	Data to decrypt.
[in]	tag	Authentication tag (also known as MAC). The algorithm uses tag from encryption algorithm to check if the data has been tampered.
[in]	plaintext	Decrypted data. This method appends data to plaintext.

Returns: Boolean indicating operation success. If operation fails, the contents of plaintext is undefined.

See also: encryptAE()

◆ encrypt()

virtual bool alexaClientSDK::cryptoInterfaces::KeyStoreInterface::encrypt	(	const std::string &	keyAlias,
		AlgorithmType	type,
		const IV &	iv,
		const DataBlock &	plaintext,
		KeyChecksum &	checksum,
		DataBlock &	ciphertext
	)

pure virtualnoexcept

Encrypts data block.

This method encrypts data block. The method locates the key, checks if the key type supports the algorithm, and performs encryption using provided initialization vector. As a result, the method provides key checksum (if supported), and encrypted content.

Parameters

[in]	keyAlias	Key alias.
[in]	type	Algorithm type to use. The method will fail, if type is AEAD algorithm like AES-GCM.
[in]	iv	Initialization vector.
[in]	plaintext	Data to encrypt.
[out]	checksum	Key checksum. The method appends data to checksum if this attribute is supported by implementation.
[out]	ciphertext	Encrypted data. The method appends data to ciphertext container.

Returns: Boolean indicating operation success. If operation fails, the contents of checksum and ciphertext are undefined.

◆ encryptAE()

virtual bool alexaClientSDK::cryptoInterfaces::KeyStoreInterface::encryptAE	(	const std::string &	keyAlias,
		AlgorithmType	type,
		const IV &	iv,
		const DataBlock &	aad,
		const DataBlock &	plaintext,
		KeyChecksum &	checksum,
		DataBlock &	ciphertext,
		Tag &	tag
	)

pure virtualnoexcept

Encrypts data block using authenticated encryption algorithm.

Method encrypts data block using authenticated encryption. The method locates the key, checks if the key type supports the algorithm, and performs encryption using provided initialization vector and additional authenticated data. As a result, the method provides key checksum (if supported), authentication tag (also known as Message Authentication Code/MAC), and encrypted content.

Parameters

[in]	keyAlias	Key alias.
[in]	type	Algorithm type to use. The method will fail, if type is not AEAD algorithm like AES-GCM.
[in]	iv	Initialization vector.
[in]	aad	Additional authenticated data. This data works as an input to encryption function to ensure that the resulting ciphertext can be decrypted only with the same AAD.
[in]	plaintext	Data to encrypt.
[out]	checksum	Key checksum. The method appends data to checksum if this attribute is supported by implementation.
[out]	ciphertext	Encrypted data. The method appends data to ciphertext container.
[out]	tag	Authentication tag (also known as MAC). Authentication tag must be provided to decryption function to prevent data tampering. The method appends data to tag container.

Returns: Boolean indicating operation success. If operation fails, the contents of checksum, ciphertext, and tag are undefined.

See also: decryptAD()

◆ getDefaultKeyAlias()

virtual bool alexaClientSDK::cryptoInterfaces::KeyStoreInterface::getDefaultKeyAlias ( std::string & keyAlias )

pure virtualnoexcept

Returns default key alias.

Get default key alias. Any component can have component-specific configuration or use default configuration.

Default key alias is a platform configuration parameter, and may change over time. When the alias changes, implementation must use new alias to encrypt new data, and must use old alias to decrypt existing data as long as the old key exists.

Parameters

[out] keyAlias Reference to key alias. The method replaces contents of keyAlias.

Returns: Returns true if main key alias is stored into keyAlias. Returns false on error.

The documentation for this class was generated from the following file:

/workplace/avs-device-sdk/core/Crypto/CryptoInterfaces/include/acsdk/CryptoInterfaces/KeyStoreInterface.h

Public Types

Public Member Functions

Detailed Description

Thread Safety

Member Typedef Documentation

◆ DataBlock

◆ IV

◆ KeyChecksum

◆ Tag

Constructor & Destructor Documentation

◆ ~KeyStoreInterface()

Member Function Documentation

◆ decrypt()

◆ decryptAD()

◆ encrypt()

◆ encryptAE()

◆ getDefaultKeyAlias()