Properties Implementation

Implementations for Properties API. More...

Namespaces
	alexaClientSDK::acsdkProperties
	Properties Implementation.
	alexaClientSDK::acsdkProperties::test
	Test cases for Properties Implementation.

Classes
class	alexaClientSDK::acsdkProperties::ErrorCallbackInterface
	Callback interface to handle errors. More...
class	alexaClientSDK::acsdkProperties::MiscStorageUriMapperInterface
	Interface to map properties config URI into component name and table name. More...
class	alexaClientSDK::acsdkProperties::SimpleMiscStorageUriMapper
	Generic URI mapper for MiscStorageInterface adapter. More...
struct	alexaClientSDK::acsdkProperties::Asn1Helper
	Helper for ASN.1 operations. More...
struct	alexaClientSDK::acsdkProperties::EncryptionInfo
	Data structure to produce and parse DER for encryption key property data. More...
struct	alexaClientSDK::acsdkProperties::EncryptionProperty
	Data structure to produce and parse DER for encryption key property data. More...
struct	alexaClientSDK::acsdkProperties::DataInfo
	Data structure to produce and parse DER for encrypted property data. More...
struct	alexaClientSDK::acsdkProperties::DataProperty
	Data structure to produce and parse DER for encrypted property data. More...
struct	alexaClientSDK::acsdkProperties::DataPropertyCodec
	ASN.1 Encoder/Decoder for encrypted property value. More...
class	alexaClientSDK::acsdkProperties::DataPropertyCodecState
	Helper state for holding ASN.1 structures of DER codec for encrypted property value. More...
class	alexaClientSDK::acsdkProperties::EncryptedProperties
	Properties adapter with field encryption. More...
struct	alexaClientSDK::acsdkProperties::EncryptionKeyPropertyCodec
	ASN.1 Codec API for Encryption Key Property Encoding. More...
class	alexaClientSDK::acsdkProperties::EncryptionKeyPropertyCodecState
	ASN.1 Codec state for encryption key property. More...
class	alexaClientSDK::acsdkProperties::MiscStorageProperties
	Properties for MiscStorageInterface. More...
class	alexaClientSDK::acsdkProperties::MiscStoragePropertiesFactory
	Properties factory for MiscStorageInterface. More...
class	alexaClientSDK::acsdkProperties::RetryExecutor
	Helper class to execute with retries. More...

Macros
#define	OPENSSL_VERSION_NUMBER_1_1_0   0x10100000L
	Macro for cutting off OpenSSL features introduced before 1.1.0 release. More...

Typedefs
typedef struct alexaClientSDK::acsdkProperties::EncryptionInfo	alexaClientSDK::acsdkProperties::ACSDK_ENC_INFO
	Data structure to produce and parse DER for encryption key property data. More...
typedef struct alexaClientSDK::acsdkProperties::EncryptionProperty	alexaClientSDK::acsdkProperties::ACSDK_ENC_PROP
	Data structure to produce and parse DER for encryption key property data. More...
typedef struct alexaClientSDK::acsdkProperties::DataInfo	alexaClientSDK::acsdkProperties::ACSDK_DATA_INFO
	Data structure to produce and parse DER for encrypted property data. More...
typedef struct alexaClientSDK::acsdkProperties::DataProperty	alexaClientSDK::acsdkProperties::ACSDK_DATA_PROP
	Data structure to produce and parse DER for encrypted property data. More...

Enumerations
enum	alexaClientSDK::acsdkProperties::StatusCode {   alexaClientSDK::acsdkProperties::StatusCode::SUCCESS = 1, alexaClientSDK::acsdkProperties::StatusCode::UNKNOWN_ERROR = 2, alexaClientSDK::acsdkProperties::StatusCode::HSM_ERROR = 3, alexaClientSDK::acsdkProperties::StatusCode::CRYPTO_ERROR = 4,   alexaClientSDK::acsdkProperties::StatusCode::DIGEST_ERROR = 5, alexaClientSDK::acsdkProperties::StatusCode::INNER_PROPERTIES_ERROR = 6 }
	Possible error causes. More...
enum	alexaClientSDK::acsdkProperties::Action { alexaClientSDK::acsdkProperties::Action::CONTINUE = 1, alexaClientSDK::acsdkProperties::Action::FAIL = 2, alexaClientSDK::acsdkProperties::Action::CLEAR_DATA = 3, alexaClientSDK::acsdkProperties::Action::RETRY = 4 }
	Error action. More...

Functions
std::shared_ptr< PropertiesFactoryInterface >	alexaClientSDK::acsdkProperties::createEncryptedPropertiesFactory (const std::shared_ptr< MiscStorageInterface > &innerStorage, const std::shared_ptr< MiscStorageUriMapperInterface > &uriMapper, const std::shared_ptr< CryptoFactoryInterface > &cryptoFactory, const std::shared_ptr< KeyStoreInterface > &keyStore) noexcept
	Creates properties factory with encryption support by wrapping a MiscStorageInterface. More...
bool	alexaClientSDK::acsdkProperties::setErrorCallback (const std::weak_ptr< ErrorCallbackInterface > &callback, uint32_t maxRetries=DEFAULT_MAX_RETRIES, std::weak_ptr< ErrorCallbackInterface > *previous=nullptr) noexcept
	Sets an error callback. More...
std::shared_ptr< PropertiesFactoryInterface >	alexaClientSDK::acsdkProperties::createPropertiesFactory (const std::shared_ptr< MiscStorageInterface > &innerStorage, const std::shared_ptr< MiscStorageUriMapperInterface > &nameMapper=SimpleMiscStorageUriMapper::create()) noexcept
	Creates PropertiesFactoryInterface from MiscStorageInterface. More...
	alexaClientSDK::acsdkProperties::DECLARE_ASN1_FUNCTIONS (ACSDK_ENC_INFO)
	alexaClientSDK::acsdkProperties::DECLARE_ASN1_FUNCTIONS (ACSDK_ENC_PROP)
	alexaClientSDK::acsdkProperties::DECLARE_ASN1_FUNCTIONS (ACSDK_DATA_INFO)
	alexaClientSDK::acsdkProperties::DECLARE_ASN1_FUNCTIONS (ACSDK_DATA_PROP)
static bool	alexaClientSDK::acsdkProperties::RetryExecutor::setErrorCallback (const std::weak_ptr< ErrorCallbackInterface > &callback, uint32_t maxRetries, std::weak_ptr< ErrorCallbackInterface > *previous=nullptr) noexcept
	Sets an error callback. More...

Variables
constexpr int64_t	alexaClientSDK::acsdkProperties::ACSDK_DATA_KEY_VER_V1 = 1
constexpr int64_t	alexaClientSDK::acsdkProperties::ACSDK_DATA_VER_V1 = 1
constexpr int64_t	alexaClientSDK::acsdkProperties::ACSDK_CIP_ALG_AES_256_GCM = 1
constexpr int64_t	alexaClientSDK::acsdkProperties::ACSDK_DIG_ALG_SHA_256 = 1

Detailed Description

Implementations for Properties API.

PropertiesIMPL enables users to use PropertiesAPI instead of lower level MiscStorageInterface and SQLiteDatabase. In addition, this module offers data at rest protection using hardware security module.

To use unencrypted adapter for alexaClientSDK::acsdkProperties::MiscStorageInterface:

#include <acsdkProperties/PropertiesFactories.h>
 
std::shared_ptr<MiscStorageInterface> miscStorage = ...;
auto factory = createPropertiesFactory(miscStorage);
auto properties = propertiesFactory->getProperties("componentName", "configNamespace");
properties->putString("propertyName", "stringValue");

The following example demonstrates how to use encrypted properties:

#include <acsdkProperties/EncryptedPropertiesFactories.h>
 
std::shared_ptr<MiscStorageInterface> miscStorage = ...;
std::shared_ptr<CryptoFactoryInterface> cryptoFactory = ...;
std::shared_ptr<KeyStoreInterface> keyStore = ...;
 
auto factory = createEncryptedPropertiesFactory(cryptoFactory, keyStore, miscStorage);
auto properties = propertiesFactory->getProperties("componentName", "configNamespace");
properties->putString("propertyName", "stringValue");

Encryption at rest requires that CryptoAPI support is available and the platform has correctly configured hardware security module.

See also

Cryptographic Functions Implementation how to obtain alexaClientSDK::acsdkCryptoInterfaces::CryptoFactoryInterface.

PKCS11IMPL how to obtain alexaClientSDK::acsdkCryptoInterfaces::KeyStoreInterface and configure HSM.

alexaClientSDK::acsdkProperties

alexaClientSDK::acsdkProperties::test

Macro Definition Documentation

OPENSSL_VERSION_NUMBER_1_1_0

#define OPENSSL_VERSION_NUMBER_1_1_0   0x10100000L

Macro for cutting off OpenSSL features introduced before 1.1.0 release.

Typedef Documentation

ACSDK_DATA_INFO

typedef struct alexaClientSDK::acsdkProperties::DataInfo alexaClientSDK::acsdkProperties::ACSDK_DATA_INFO

Data structure to produce and parse DER for encrypted property data.

ACSDK_DATA_PROP

typedef struct alexaClientSDK::acsdkProperties::DataProperty alexaClientSDK::acsdkProperties::ACSDK_DATA_PROP

Data structure to produce and parse DER for encrypted property data.

ACSDK_ENC_INFO

typedef struct alexaClientSDK::acsdkProperties::EncryptionInfo alexaClientSDK::acsdkProperties::ACSDK_ENC_INFO

Data structure to produce and parse DER for encryption key property data.

ACSDK_ENC_PROP

typedef struct alexaClientSDK::acsdkProperties::EncryptionProperty alexaClientSDK::acsdkProperties::ACSDK_ENC_PROP

Data structure to produce and parse DER for encryption key property data.

Enumeration Type Documentation

Action

enum alexaClientSDK::acsdkProperties::Action

strong

Error action.

This enumeration defines possible actions when properties framework encounters an error.

See also

ErrorCallbackInterface

Enumerator
CONTINUE	Continue with default behaviour.
FAIL	Fail operation. Do not delete data.
CLEAR_DATA	Continue operation, delete data.
RETRY	Retry operation.

StatusCode

enum alexaClientSDK::acsdkProperties::StatusCode

strong

Possible error causes.

This enumeration defines supported error reasons for properties open operation.

See also

ErrorCallbackInterface

Enumerator
SUCCESS	Status code indicating no error. For internal use only.
UNKNOWN_ERROR	Any error, that doesn't fit into other categories.
HSM_ERROR	HSM API Error.
CRYPTO_ERROR	Crypto API Error.
DIGEST_ERROR	Data corruption error.
INNER_PROPERTIES_ERROR	Underlying properties error.

Function Documentation

createEncryptedPropertiesFactory()

std::shared_ptr<PropertiesFactoryInterface> alexaClientSDK::acsdkProperties::createEncryptedPropertiesFactory ( const std::shared_ptr< MiscStorageInterface > &  innerStorage, const std::shared_ptr< MiscStorageUriMapperInterface > &  uriMapper, const std::shared_ptr< CryptoFactoryInterface > &  cryptoFactory, const std::shared_ptr< KeyStoreInterface > &  keyStore  )

noexcept

Creates properties factory with encryption support by wrapping a MiscStorageInterface.

Encrypted properties factory protects all values using AES-256 cipher. The data key is stored as one of the underlying properties with reserved name "$acsdkEncryption$" in encrypted form. Hardware security module is used for storing the main encryption key and wrapping/unwrapping data keys.

When client code accesses PropertiesInterface through encrypted PropertiesFactoryInterface, all existing data is automatically converted into encrypted form.

The method automatically creates database if it is not created. When user creates PropertiesInterface, the implementation automatically creates corresponding table.

As all encrypted property values are in binary form, the implementation uses base64 encoding to store values.

Parameters

[in]	innerStorage	Storage reference. This parameter must not be nullptr.
[in]	uriMapper	URI mapper reference.
[in]	cryptoFactory	Crypto factory reference. This parameter must not be nullptr.
[in]	keyStore	Key store factory reference. This parameter must not be nullptr.

Returns

Properties factory reference or nullptr on error.

createPropertiesFactory()

std::shared_ptr< PropertiesFactoryInterface > alexaClientSDK::acsdkProperties::createPropertiesFactory ( const std::shared_ptr< MiscStorageInterface > &  innerStorage, const std::shared_ptr< MiscStorageUriMapperInterface > &  nameMapper = SimpleMiscStorageUriMapper::create()  )

noexcept

Creates PropertiesFactoryInterface from MiscStorageInterface.

The method automatically creates database if it is not created. When user creates PropertiesInterface, the implementation automatically creates corresponding table.

Because underlying interface supports only string properties, the implementation uses base64 encoding to store all binary properties. This may cause side effects, as when content is decoded using base64, the result may contain additional padding 0 bytes, and client code must work correctly in this case.

Parameters

[in]	innerStorage	Storage reference. This parameter must not be nullptr.
[in]	nameMapper	Name mapper interface. This interface will be used to map configuration URI into table name and component name values when accessing MiscStorageInterface API.

Returns

Factory reference or nullptr on error.

DECLARE_ASN1_FUNCTIONS() [1/4]

alexaClientSDK::acsdkProperties::DECLARE_ASN1_FUNCTIONS

(

ACSDK_DATA_INFO

)

DECLARE_ASN1_FUNCTIONS() [2/4]

alexaClientSDK::acsdkProperties::DECLARE_ASN1_FUNCTIONS

(

ACSDK_DATA_PROP

)

DECLARE_ASN1_FUNCTIONS() [3/4]

alexaClientSDK::acsdkProperties::DECLARE_ASN1_FUNCTIONS

(

ACSDK_ENC_INFO

)

DECLARE_ASN1_FUNCTIONS() [4/4]

alexaClientSDK::acsdkProperties::DECLARE_ASN1_FUNCTIONS

(

ACSDK_ENC_PROP

)

setErrorCallback() [1/2]

bool alexaClientSDK::acsdkProperties::RetryExecutor::setErrorCallback ( const std::weak_ptr< ErrorCallbackInterface > &  callback, uint32_t  maxRetries, std::weak_ptr< ErrorCallbackInterface > *  previous = nullptr  )

staticnoexcept

Sets an error callback.

This method can both set a new callback or clear existing one if callback is nullptr. Changing callback affects error handling of Property API methods that are called after the callback is changed.

Parameters

[in]	callback	New callback reference or nullptr to remove callback.
[in]	maxRetries	Maximum number of retries to use with this callback. If implementation encounters more errors, than number of maxRetries plus one, the operation fails. If UNLIMITED_RETRIES value is specified, the implementation executes unlimited number of retries until operation succeeds or callback indicates that operation must stop.
[out]	previous	Optional pointer to store previous callback.

Returns

Boolean indicating operation success. On failure, contents of *previous is undefined and false is returned.

setErrorCallback() [2/2]

bool alexaClientSDK::acsdkProperties::setErrorCallback ( const std::weak_ptr< ErrorCallbackInterface > &  callback, uint32_t  maxRetries = DEFAULT_MAX_RETRIES, std::weak_ptr< ErrorCallbackInterface > *  previous = nullptr  )

noexcept

Sets an error callback.

This method can both set a new callback or clear existing one if callback is nullptr. Changing callback affects error handling of Property API methods that are called after the callback is changed.

Parameters

[in]	callback	New callback reference or nullptr to remove callback.
[in]	maxRetries	Maximum number of retries to use with this callback. If implementation encounters more errors, than number of maxRetries plus one, the operation fails. If UNLIMITED_RETRIES value is specified, the implementation executes unlimited number of retries until operation succeeds or callback indicates that operation must stop.
[out]	previous	Optional pointer to store previous callback.

Returns

Boolean indicating operation success. On failure, contents of *previous is undefined and false is returned.

Variable Documentation

ACSDK_CIP_ALG_AES_256_GCM

constexpr int64_t alexaClientSDK::acsdkProperties::ACSDK_CIP_ALG_AES_256_GCM = 1

constexpr

ACSDK_DATA_KEY_VER_V1

constexpr int64_t alexaClientSDK::acsdkProperties::ACSDK_DATA_KEY_VER_V1 = 1

constexpr

ACSDK_DATA_VER_V1

constexpr int64_t alexaClientSDK::acsdkProperties::ACSDK_DATA_VER_V1 = 1

constexpr

ACSDK_DIG_ALG_SHA_256

constexpr int64_t alexaClientSDK::acsdkProperties::ACSDK_DIG_ALG_SHA_256 = 1

constexpr