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::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)
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)
Returns current key ID.
GetCurrentUTCTime(uint32_t & utcTime)=0
virtual WEAVE_ERROR
Get current platform UTC time in seconds.
GetGroupKey(uint32_t keyId, WeaveGroupKey & groupKey)
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
)=0

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_ERROR_UNSUPPORTED_CLOCK
If platform does not support time functions.
WEAVE_ERROR_TIME_NOT_SYNCED_YET
If platform does not have an accurate time yet.
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