Properties Implementation

Implementations for Properties API. More...

Namespaces
	alexaClientSDK::properties
	Properties Implementation.

Classes
class	alexaClientSDK::properties::ErrorCallbackInterface
	Callback interface to handle errors. More...
class	alexaClientSDK::properties::MiscStorageUriMapperInterface
	Interface to map properties config URI into component name and table name. More...
class	alexaClientSDK::properties::SimpleMiscStorageUriMapper
	Generic URI mapper for MiscStorageInterface adapter. More...

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

Functions
std::shared_ptr< PropertiesFactoryInterface >	alexaClientSDK::properties::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::properties::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::properties::createPropertiesFactory (const std::shared_ptr< MiscStorageInterface > &innerStorage, const std::shared_ptr< MiscStorageUriMapperInterface > &nameMapper=SimpleMiscStorageUriMapper::create()) noexcept
	Creates PropertiesFactoryInterface from MiscStorageInterface. More...

Detailed Description

Implementations for Properties API.

Lib_acsdkProperties enables users to use Lib_acsdkPropertiesInterfaces 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::properties::MiscStorageInterface:

#include <acsdk/Properties/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 <acsdk/Properties/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

CryptoIMPL how to obtain alexaClientSDK::cryptoInterfaces::CryptoFactoryInterface.

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

alexaClientSDK::properties

alexaClientSDK::properties::test

Enumeration Type Documentation

Action

enum alexaClientSDK::properties::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::properties::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::properties::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::properties::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.

setErrorCallback()

bool alexaClientSDK::properties::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.