nl::Weave::Profiles::Security::AppKeys::GroupKeyStoreBase

This is an abstract class.

#include <src/lib/profiles/security/WeaveApplicationKeys.h>

The definition of the Weave group key store class.

Summary

Functions in this class are called to manage application group keys.

Inheritance

Direct Known Subclasses:
nl::Weave::DeviceLayer::Internal::GroupKeyStoreImpl
nl::Weave::DeviceLayer::Internal::GroupKeyStoreImpl
nl::Weave::DeviceLayer::Internal::GroupKeyStoreImpl
nl::Weave::Profiles::Security::AppKeys::DummyGroupKeyStore

Protected attributes
`LastUsedEpochKeyId`	`uint32_t`
`NextEpochKeyStartTime`	`uint32_t`

Public functions
`Clear(void)=0`	`virtual WEAVE_ERROR`
`DeleteGroupKey(uint32_t keyId)=0`	`virtual WEAVE_ERROR`
`DeleteGroupKeysOfAType(uint32_t keyType)=0`	`virtual WEAVE_ERROR`
`DeriveApplicationKey(uint32_t & appKeyId, const uint8_t keySalt, uint8_t saltLen, const uint8_t keyDiversifier, uint8_t diversifierLen, uint8_t *appKey, uint8_t keyBufSize, uint8_t keyLen, uint32_t & appGroupGlobalId)`	`WEAVE_ERROR` Derives application key.
`EnumerateGroupKeys(uint32_t keyType, uint32_t *keyIds, uint8_t keyIdsArraySize, uint8_t & keyCount)=0`	`virtual WEAVE_ERROR`
`GetCurrentAppKeyId(uint32_t keyId, uint32_t & curKeyId)`	`WEAVE_ERROR` Returns current key ID.
`GetCurrentUTCTime(uint32_t & utcTime)`	`virtual WEAVE_ERROR` Get current platform UTC time in seconds.
`GetGroupKey(uint32_t keyId, WeaveGroupKey & groupKey)`	`WEAVE_ERROR` Get application group key.
`RetrieveGroupKey(uint32_t keyId, WeaveGroupKey & key)=0`	`virtual WEAVE_ERROR`
`StoreGroupKey(const WeaveGroupKey & key)=0`	`virtual WEAVE_ERROR`

Protected functions
`Init(void)`	`void` Initialize local group key store parameters.
`OnEpochKeysChange(void)`	`void` Returns current key ID.
`RetrieveLastUsedEpochKeyId(void)=0`	`virtual WEAVE_ERROR`
`StoreLastUsedEpochKeyId(void)=0`	`virtual WEAVE_ERROR`

Protected attributes

LastUsedEpochKeyId

uint32_t LastUsedEpochKeyId

NextEpochKeyStartTime

uint32_t NextEpochKeyStartTime

Public functions

Clear

virtual WEAVE_ERROR Clear(
  void
)=0

DeleteGroupKey

virtual WEAVE_ERROR DeleteGroupKey(
  uint32_t keyId
)=0

DeleteGroupKeysOfAType

virtual WEAVE_ERROR DeleteGroupKeysOfAType(
  uint32_t keyType
)=0

DeriveApplicationKey

WEAVE_ERROR DeriveApplicationKey(
  uint32_t & appKeyId,
  const uint8_t *keySalt,
  uint8_t saltLen,
  const uint8_t *keyDiversifier,
  uint8_t diversifierLen,
  uint8_t *appKey,
  uint8_t keyBufSize,
  uint8_t keyLen,
  uint32_t & appGroupGlobalId
)

Derives application key.

Three types of application keys are supported: current application key, rotating application key and static application key. When current application key is requested the function finds and uses the current epoch key based on the current system time and the start time parameter of each epoch key.

Details

Parameters

`[in,out] keyId`	A reference to the requested key ID. When current application key is requested this field is updated to reflect the new type (rotating application key) and the actual epoch key ID that was used to generate application key.
`[in] keySalt`	A pointer to a buffer with application key salt value.
`[in] saltLen`	The length of the application key salt.
`[in] keyDiversifier`	A pointer to a buffer with application key diversifier value.
`[in] diversifierLen`	The length of the application key diversifier.
`[out] appKey`	A pointer to a buffer where the derived key will be written.
`[in] keyBufSize`	The length of the supplied key buffer.
`[in] keyLen`	The length of the requested key material.
`[out] appGroupGlobalId`	The application group global ID of the associated key.

Return Values

`WEAVE_NO_ERROR`	On success.
`WEAVE_ERROR_BUFFER_TOO_SMALL`	If the provided key buffer size is not sufficient.
`WEAVE_ERROR_INVALID_KEY_ID`	If the requested key has invalid key ID.
`WEAVE_ERROR_INVALID_ARGUMENT`	If the platform key store returns invalid key parameters or key identifier has invalid value.
`other`	Other platform-specific errors returned by the platform key store APIs.

EnumerateGroupKeys

virtual WEAVE_ERROR EnumerateGroupKeys(
  uint32_t keyType,
  uint32_t *keyIds,
  uint8_t keyIdsArraySize,
  uint8_t & keyCount
)=0

GetCurrentAppKeyId

WEAVE_ERROR GetCurrentAppKeyId(
  uint32_t keyId,
  uint32_t & curKeyId
)

Returns current key ID.

Finds current epoch key based on the current system time and the start time parameter of each epoch key. If system doesn't have valid, accurate time then last-used epoch key ID is returned.

Details

Parameters

`[in] keyId`	The application key ID.
`[out] curKeyId`	The application current key ID.

Return Values

`WEAVE_NO_ERROR`	On success.
`WEAVE_ERROR_INVALID_KEY_ID`	If the input key ID had an invalid value.
`WEAVE_ERROR_KEY_NOT_FOUND`	If epoch keys are not found in the platform key store.
`other`	Other platform-specific errors returned by the platform key store APIs.

GetCurrentUTCTime

virtual WEAVE_ERROR GetCurrentUTCTime(
  uint32_t & utcTime
)

Get current platform UTC time in seconds.

Details

Parameters

[out] utcTime

A reference to the time value.

Return Values

`WEAVE_NO_ERROR`	On success.
`#WEAVE_SYSTEM_ERROR_NOT_SUPPORTED`	If platform does not support a real time clock.
`#WEAVE_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED`	If the system's real time clock is not synchronized to an accurate time source.
`other`	Other Weave or platform error codes.

GetGroupKey

WEAVE_ERROR GetGroupKey(
  uint32_t keyId,
  WeaveGroupKey & groupKey
)

Get application group key.

This function derives or retrieves application group keys. Key types supported by this function are: fabric secret, root key, epoch key, group master key, and intermediate key.

Details

Parameters

`[in] keyId`	The group key ID.
`[out] groupKey`	A reference to the group key object.

Return Values

`WEAVE_NO_ERROR`	On success.
`WEAVE_ERROR_INVALID_KEY_ID`	If the requested key has invalid key ID.
`WEAVE_ERROR_INVALID_ARGUMENT`	If the platform key store returns invalid key parameters.
`other`	Other platform-specific errors returned by the platform key store APIs.

RetrieveGroupKey

virtual WEAVE_ERROR RetrieveGroupKey(
  uint32_t keyId,
  WeaveGroupKey & key
)=0

StoreGroupKey

virtual WEAVE_ERROR StoreGroupKey(
  const WeaveGroupKey & key
)=0

Protected functions

Init

void Init(
  void
)

Initialize local group key store parameters.

OnEpochKeysChange

void OnEpochKeysChange(
  void
)

Returns current key ID.

Sets member variables associated with epoch keys to the default values when any change (delete or store) happens to the set of application epoch keys. It is the responsibility of the subclass that implements StoreGroupKey(), DeleteGroupKey(), and DeleteGroupKeysOfAType() functions to call this method.

RetrieveLastUsedEpochKeyId

virtual WEAVE_ERROR RetrieveLastUsedEpochKeyId(
  void
)=0

StoreLastUsedEpochKeyId

virtual WEAVE_ERROR StoreLastUsedEpochKeyId(
  void
)=0