nl::Weave::WeaveKeyId

#include <src/lib/core/WeaveKeyIds.h>

The definition of the Weave Key identifier.

Summary

This class contains key types, key flags, key ID fields definition, and API functions.

Public types
@52{ kType_None = 0x00000000, kType_General = 0x00001000, kType_Session = 0x00002000, kType_AppStaticKey = 0x00004000, kType_AppRotatingKey = kType_AppStaticKey \| kTypeModifier_IncorporatesEpochKey, kType_AppRootKey = 0x00010000, kType_AppEpochKey = 0x00020000 \| kTypeModifier_IncorporatesEpochKey, kType_AppGroupMasterKey = 0x00030000, kType_AppIntermediateKey = kType_AppRootKey \| kTypeModifier_IncorporatesEpochKey, kNone = kType_None \| 0x0000, kFabricSecret = kType_General \| 0x0001, kFabricRootKey = kType_AppRootKey \| (0 << kShift_RootKeyNumber), kClientRootKey = kType_AppRootKey \| (1 << kShift_RootKeyNumber), kServiceRootKey = kType_AppRootKey \| (2 << kShift_RootKeyNumber), kKeyNumber_Max = kMask_KeyNumber }	enum Public Weave key ID fields, flags, and types.

Public types

@52{
  kType_None = 0x00000000,
  kType_General = 0x00001000,
  kType_Session = 0x00002000,
  kType_AppStaticKey = 0x00004000,
  kType_AppRotatingKey = kType_AppStaticKey | kTypeModifier_IncorporatesEpochKey,
  kType_AppRootKey = 0x00010000,
  kType_AppEpochKey = 0x00020000 | kTypeModifier_IncorporatesEpochKey,
  kType_AppGroupMasterKey = 0x00030000,
  kType_AppIntermediateKey = kType_AppRootKey | kTypeModifier_IncorporatesEpochKey,
  kNone = kType_None | 0x0000,
  kFabricSecret = kType_General | 0x0001,
  kFabricRootKey = kType_AppRootKey | (0 << kShift_RootKeyNumber),
  kClientRootKey = kType_AppRootKey | (1 << kShift_RootKeyNumber),
  kServiceRootKey = kType_AppRootKey | (2 << kShift_RootKeyNumber),
  kKeyNumber_Max = kMask_KeyNumber
}

enum

Public Weave key ID fields, flags, and types.

Public static functions
`ConvertToCurrentAppKeyId(uint32_t keyId)`	`uint32_t` Convert application group key ID to application current key ID.
`ConvertToStaticAppKeyId(uint32_t keyId)`	`uint32_t` Convert application key ID to application static key ID.
`DescribeKey(uint32_t keyId)`	`const char *` Decode a Weave key identifier with a descriptive string.
`GetAppGroupLocalNumber(uint32_t keyId)`	`uint8_t` Get application group local number that was used to derive specified application key.
`GetAppGroupMasterKeyId(uint32_t keyId)`	`uint32_t` Get application group master key ID that was used to derive specified application key.
`GetEpochKeyId(uint32_t keyId)`	`uint32_t` Get application group epoch key ID that was used to derive specified application key.
`GetEpochKeyNumber(uint32_t keyId)`	`uint8_t` Get application group epoch key number that was used to derive specified application key.
`GetRootKeyId(uint32_t keyId)`	`uint32_t` Get application group root key ID that was used to derive specified application key.
`GetRootKeyNumber(uint32_t keyId)`	`uint8_t` Get application group root key number that was used to derive specified application key.
`GetType(uint32_t keyId)`	`uint32_t` Get Weave key type of the specified key ID.
`IncorporatesAppGroupMasterKey(uint32_t keyId)`	`bool` Determine whether the specified application group key ID incorporates group master key.
`IncorporatesEpochKey(uint32_t keyId)`	`bool` Determine whether the specified application group key ID incorporates epoch key.
`IncorporatesRootKey(uint32_t keyId)`	`bool` Determine whether the specified application group key ID incorporates root key.
`IsAppEpochKey(uint32_t keyId)`	`bool` Determine whether the specified key ID is of an application epoch key type.
`IsAppGroupKey(uint32_t keyId)`	`bool` Determine whether the specified key ID belongs to one of the application group key types (static or rotating).
`IsAppGroupMasterKey(uint32_t keyId)`	`bool` Determine whether the specified key ID is of an application group master key type.
`IsAppRootKey(uint32_t keyId)`	`bool` Determine whether the specified key ID is of an application root key type.
`IsAppRotatingKey(uint32_t keyId)`	`bool` Determine whether the specified key ID is of an application rotating type.
`IsAppStaticKey(uint32_t keyId)`	`bool` Determine whether the specified key ID is of an application static type.
`IsGeneralKey(uint32_t keyId)`	`bool` Determine whether the specified key ID is of a general type.
`IsMessageEncryptionKeyId(uint32_t keyId, bool allowLogicalKeys)`	`bool` Determine whether a given key ID identifies a key that is suitable for Weave message encryption.
`IsSameKeyOrGroup(uint32_t keyId1, uint32_t keyId2)`	`bool` Determines whether two key IDs identify the same key, or in the case of rotating keys, the same group of keys independent of any particular epoch.
`IsSessionKey(uint32_t keyId)`	`bool` Determine whether the specified key ID is of a session type.
`IsValidKeyId(uint32_t keyId)`	`bool` Determine whether key identifier has valid (legal) value.
`MakeAppGroupMasterKeyId(uint8_t appGroupLocalNumber)`	`uint32_t` Construct application group master key ID given application group local number.
`MakeAppIntermediateKeyId(uint32_t rootKeyId, uint32_t epochKeyId, bool useCurrentEpochKey)`	`uint32_t` Construct application intermediate key ID given constituent key IDs.
`MakeAppKeyId(uint32_t keyType, uint32_t rootKeyId, uint32_t epochKeyId, uint32_t appGroupMasterKeyId, bool useCurrentEpochKey)`	`uint32_t` Construct application group key ID given constituent key IDs and other information.
`MakeAppRotatingKeyId(uint32_t rootKeyId, uint32_t epochKeyId, uint32_t appGroupMasterKeyId, bool useCurrentEpochKey)`	`uint32_t` Construct application rotating key ID given constituent key IDs and other information.
`MakeAppStaticKeyId(uint32_t rootKeyId, uint32_t appGroupMasterKeyId)`	`uint32_t` Construct application static key ID given constituent key IDs.
`MakeEpochKeyId(uint8_t epochKeyNumber)`	`uint32_t` Construct application group root key ID given epoch key number.
`MakeGeneralKeyId(uint16_t generalKeyNumber)`	`uint16_t` Construct general key ID given general key number.
`MakeRootKeyId(uint8_t rootKeyNumber)`	`uint32_t` Construct application group root key ID given root key number.
`MakeSessionKeyId(uint16_t sessionKeyNumber)`	`uint16_t` Construct session key ID given session key number.
`UpdateEpochKeyId(uint32_t keyId, uint32_t epochKeyId)`	`uint32_t` Update application group key ID with new epoch key number.
`UsesCurrentEpochKey(uint32_t keyId)`	`bool` Determine whether the specified application group key ID uses "current" epoch key.

Public types

@52

@52

Public Weave key ID fields, flags, and types.

Properties
`kClientRootKey`	Client root key ID.
`kFabricRootKey`	Fabric root key ID.
`kFabricSecret`	Weave fabric secret ID.
`kKeyNumber_Max`	Maximum values for key ID subfields.
`kNone`	Weave global key IDs. Unspecified Weave key ID.
`kServiceRootKey`	Service root key ID.
`kType_AppEpochKey`	Application group epoch key type.
`kType_AppGroupMasterKey`	Application group master key type.
`kType_AppIntermediateKey`	Application group intermediate key type.
`kType_AppRootKey`	Weave key types (other than Weave message encryption types). Note: 16 (out of 32) most significant bits of these types cannot be all zeros, because these values are reserved for the Weave message encryption keys only. Constituent group key types.Application group root key type.
`kType_AppRotatingKey`	Application rotating key type.
`kType_AppStaticKey`	Application static key type.
`kType_General`	General key type.
`kType_None`	Weave key types used for Weave message encryption. Note: 16 (out of 32) most significant bits of the message encryption key type should be zero because only 16 least significant bits of the ID are encoded in the Weave message.Weave message is unencrypted.
`kType_Session`	Session key type.

Public static functions

ConvertToCurrentAppKeyId

uint32_t ConvertToCurrentAppKeyId(
  uint32_t keyId
)

Convert application group key ID to application current key ID.

Details

Parameters

[in] keyId

Application key ID.

Returns

application current key ID.

ConvertToStaticAppKeyId

uint32_t ConvertToStaticAppKeyId(
  uint32_t keyId
)

Convert application key ID to application static key ID.

Details

Parameters

[in] keyId

Application key ID.

Returns

application static key ID.

DescribeKey

const char * DescribeKey(
  uint32_t keyId
)

Decode a Weave key identifier with a descriptive string.

Details

Parameters

[in] keyId

Weave key ID to decode and for which to return a descriptive string.

Returns

A pointer to a NULL-terminated string describing the specified key ID.

GetAppGroupLocalNumber

uint8_t GetAppGroupLocalNumber(
  uint32_t keyId
)

Get application group local number that was used to derive specified application key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

application group local number.

GetAppGroupMasterKeyId

uint32_t GetAppGroupMasterKeyId(
  uint32_t keyId
)

Get application group master key ID that was used to derive specified application key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

application group master key ID.

GetEpochKeyId

uint32_t GetEpochKeyId(
  uint32_t keyId
)

Get application group epoch key ID that was used to derive specified application key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

epoch key ID.

GetEpochKeyNumber

uint8_t GetEpochKeyNumber(
  uint32_t keyId
)

Get application group epoch key number that was used to derive specified application key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

epoch key number.

GetRootKeyId

uint32_t GetRootKeyId(
  uint32_t keyId
)

Get application group root key ID that was used to derive specified application key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

root key ID.

GetRootKeyNumber

uint8_t GetRootKeyNumber(
  uint32_t keyId
)

Get application group root key number that was used to derive specified application key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

root key number.

GetType

uint32_t GetType(
  uint32_t keyId
)

Get Weave key type of the specified key ID.

Details

Parameters

[in] keyId

Weave key identifier.

Returns

type of the key ID.

IncorporatesAppGroupMasterKey

bool IncorporatesAppGroupMasterKey(
  uint32_t keyId
)

Determine whether the specified application group key ID incorporates group master key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

true if the keyId incorporates group master key.

IncorporatesEpochKey

bool IncorporatesEpochKey(
  uint32_t keyId
)

Determine whether the specified application group key ID incorporates epoch key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

true if the keyId incorporates epoch key.

IncorporatesRootKey

bool IncorporatesRootKey(
  uint32_t keyId
)

Determine whether the specified application group key ID incorporates root key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

true if the keyId incorporates root key.

IsAppEpochKey

bool IsAppEpochKey(
  uint32_t keyId
)

Determine whether the specified key ID is of an application epoch key type.

Details

Parameters

[in] keyId

Weave key identifier.

Returns

true if the keyId of an application epoch key type.

IsAppGroupKey

bool IsAppGroupKey(
  uint32_t keyId
)

Determine whether the specified key ID belongs to one of the application group key types (static or rotating).

Details

Parameters

[in] keyId

Weave key identifier.

Returns

true if the keyId is of rotating or static key type.

IsAppGroupMasterKey

bool IsAppGroupMasterKey(
  uint32_t keyId
)

Determine whether the specified key ID is of an application group master key type.

Details

Parameters

[in] keyId

Weave key identifier.

Returns

true if the keyId of an application group master key type.

IsAppRootKey

bool IsAppRootKey(
  uint32_t keyId
)

Determine whether the specified key ID is of an application root key type.

Details

Parameters

[in] keyId

Weave key identifier.

Returns

true if the keyId of an application root key type.

IsAppRotatingKey

bool IsAppRotatingKey(
  uint32_t keyId
)

Determine whether the specified key ID is of an application rotating type.

Details

Parameters

[in] keyId

Weave key identifier.

Returns

true if the keyId of an application rotating type.

IsAppStaticKey

bool IsAppStaticKey(
  uint32_t keyId
)

Determine whether the specified key ID is of an application static type.

Details

Parameters

[in] keyId

Weave key identifier.

Returns

true if the keyId of an application static type.

IsGeneralKey

bool IsGeneralKey(
  uint32_t keyId
)

Determine whether the specified key ID is of a general type.

Details

Parameters

[in] keyId

Weave key identifier.

Returns

true if the keyId has General type.

IsMessageEncryptionKeyId

bool IsMessageEncryptionKeyId(
  uint32_t keyId,
  bool allowLogicalKeys
)

Determine whether a given key ID identifies a key that is suitable for Weave message encryption.

Details

Parameters

`[in] keyId`	Weave key ID.
`[in] allowLogicalKeys`	Specifies whether logical keys IDs (such as the "current" rotating key) should be considered suitable for message encryption.

Returns

true If the identified key can be used to encrypt Weave messages.

IsSameKeyOrGroup

bool IsSameKeyOrGroup(
  uint32_t keyId1,
  uint32_t keyId2
)

Determines whether two key IDs identify the same key, or in the case of rotating keys, the same group of keys independent of any particular epoch.

Details

Parameters

`[in] keyId1`	The first key ID to test.
`[in] keyId2`	The second key ID to test.

Returns

True if the keys IDs represent the same key.

IsSessionKey

bool IsSessionKey(
  uint32_t keyId
)

Determine whether the specified key ID is of a session type.

Details

Parameters

[in] keyId

Weave key identifier.

Returns

true if the keyId of a session type.

IsValidKeyId

bool IsValidKeyId(
  uint32_t keyId
)

Determine whether key identifier has valid (legal) value.

Details

Parameters

[in] keyId

Weave key ID.

Returns

true if key ID value is valid.

MakeAppGroupMasterKeyId

uint32_t MakeAppGroupMasterKeyId(
  uint8_t appGroupLocalNumber
)

Construct application group master key ID given application group local number.

Details

Parameters

[in] appGroupLocalNumber

Application group local number.

Returns

application group master key ID.

MakeAppIntermediateKeyId

uint32_t MakeAppIntermediateKeyId(
  uint32_t rootKeyId,
  uint32_t epochKeyId,
  bool useCurrentEpochKey
)

Construct application intermediate key ID given constituent key IDs.

Details

Parameters

`[in] rootKeyId`	Root key ID used to derive application intermediate key.
`[in] epochKeyId`	Epoch key ID used to derive application intermediate key.
`[in] useCurrentEpochKey`	A boolean flag that indicates if key should be derived using "current" epoch key.

Returns

application intermediate key ID.

MakeAppKeyId

uint32_t MakeAppKeyId(
  uint32_t keyType,
  uint32_t rootKeyId,
  uint32_t epochKeyId,
  uint32_t appGroupMasterKeyId,
  bool useCurrentEpochKey
)

Construct application group key ID given constituent key IDs and other information.

Details

Parameters

`[in] keyType`	Derived application group key type.
`[in] rootKeyId`	Root key ID used to derive application group key.
`[in] epochKeyId`	Epoch key ID used to derive application group key.
`[in] appGroupMasterKeyId`	Application group master key ID used to derive application group key.
`[in] useCurrentEpochKey`	A boolean flag that indicates if key should be derived using "current" epoch key.

Returns

application group key ID.

MakeAppRotatingKeyId

uint32_t MakeAppRotatingKeyId(
  uint32_t rootKeyId,
  uint32_t epochKeyId,
  uint32_t appGroupMasterKeyId,
  bool useCurrentEpochKey
)

Construct application rotating key ID given constituent key IDs and other information.

Details

Parameters

`[in] rootKeyId`	Root key ID used to derive application rotating key.
`[in] epochKeyId`	Epoch key ID used to derive application rotating key.
`[in] appGroupMasterKeyId`	Application group master key ID used to derive application rotating key.
`[in] useCurrentEpochKey`	A boolean flag that indicates if key should be derived using "current" epoch key.

Returns

application rotating key ID.

MakeAppStaticKeyId

uint32_t MakeAppStaticKeyId(
  uint32_t rootKeyId,
  uint32_t appGroupMasterKeyId
)

Construct application static key ID given constituent key IDs.

Details

Parameters

`[in] rootKeyId`	Root key ID used to derive application static key.
`[in] appGroupMasterKeyId`	Application group master key ID used to derive application static key.

Returns

application static key ID.

MakeEpochKeyId

uint32_t MakeEpochKeyId(
  uint8_t epochKeyNumber
)

Construct application group root key ID given epoch key number.

Details

Parameters

[in] epochKeyNumber

Epoch key number.

Returns

epoch key ID.

MakeGeneralKeyId

uint16_t MakeGeneralKeyId(
  uint16_t generalKeyNumber
)

Construct general key ID given general key number.

Details

Parameters

[in] generalKeyNumber

General key number.

Returns

general key ID.

MakeRootKeyId

uint32_t MakeRootKeyId(
  uint8_t rootKeyNumber
)

Construct application group root key ID given root key number.

Details

Parameters

[in] rootKeyNumber

Root key number.

Returns

root key ID.

MakeSessionKeyId

uint16_t MakeSessionKeyId(
  uint16_t sessionKeyNumber
)

Construct session key ID given session key number.

Details

Parameters

[in] sessionKeyNumber

Session key number.

Returns

session key ID.

UpdateEpochKeyId

uint32_t UpdateEpochKeyId(
  uint32_t keyId,
  uint32_t epochKeyId
)

Update application group key ID with new epoch key number.

Details

Parameters

`[in] keyId`	Application key ID.
`[in] epochKeyId`	Epoch key ID, which will be used in construction of the updated application key ID.

Returns

application key ID.

UsesCurrentEpochKey

bool UsesCurrentEpochKey(
  uint32_t keyId
)

Determine whether the specified application group key ID uses "current" epoch key.

Details

Parameters

[in] keyId

Weave application group key identifier.

Returns

true if the keyId indicates usage of the current epoch key.