nl::Weave::Profiles::Security::Passcodes

This namespace includes all interfaces within Weave for the Weave passcodes library within the Weave security profile.

Summary

Enumerations
@278{
  kPasscode_Config1_TEST_ONLY = 0x01,
  kPasscode_Config2 = 0x02,
  kPasscodeConfig1_KeyId = WeaveKeyId::kNone
} 		enum
Weave passcode encryption configuration types.
@279{
  kPasscodeEncryptionKeyLen = Platform::Security::AES128BlockCipher::kKeyLength,
  kPasscodeAuthenticationKeyLen = Platform::Security::SHA1::kHashLength,
  kPasscodeFingerprintKeyLen = Platform::Security::SHA1::kHashLength,
  kPasscodeTotalDerivedKeyLen = kPasscodeEncryptionKeyLen + kPasscodeAuthenticationKeyLen,
  kPasscodePaddedLen = Platform::Security::AES128BlockCipher::kBlockLength,
  kPasscodeAuthenticatorLen = 8,
  kPasscodeFingerprintLen = 8,
  kPasscodeMaxEncryptedLen = sizeof(uint8_t) + 2 * sizeof(uint32_t) + kPasscodePaddedLen + kPasscodeAuthenticatorLen + kPasscodeFingerprintLen,
  kPasscodeMaxLen = kPasscodePaddedLen,
  kPasscodeEncKeyDiversifierSize = sizeof(kPasscodeEncKeyDiversifier) + sizeof(uint8_t),
  kPasscodeFingerprintKeyDiversifierSize = sizeof(kPasscodeFingerprintKeyDiversifier)
} 		enum
Weave passcode encryption protocol parameter sizes.

Variables
kPasscodeEncKeyDiversifier = { 0x1A, 0x65, 0x5D, 0x96 }[]
const uint8_t
Key diversifier used for Weave passcode encryption key derivation.
kPasscodeFingerprintKeyDiversifier = { 0xD1, 0xA1, 0xD9, 0x6C }[]
const uint8_t
Key diversifier used for Weave passcode encryption key derivation.

Functions
DecryptPasscode(const uint8_t *encPasscode, size_t encPasscodeLen, uint8_t *passcodeBuf, size_t passcodeBufSize, size_t & passcodeLen, GroupKeyStoreBase *groupKeyStore)
Decrypt a passcode that was encrypted using the Nest Passcode Encryption scheme.
DecryptPasscode(const uint8_t *encPasscode, size_t encPasscodeLen, const uint8_t *encKey, const uint8_t *authKey, const uint8_t *fingerprintKey, uint8_t *passcodeBuf, size_t passcodeBufSize, size_t & passcodeLen)
Decrypt a passcode that was encrypted using the Nest Passcode Encryption scheme.
EncryptPasscode(uint8_t config, uint32_t keyId, uint32_t nonce, const uint8_t *passcode, size_t passcodeLen, uint8_t *encPasscode, size_t encPasscodeBufSize, size_t & encPasscodeLen, GroupKeyStoreBase *groupKeyStore)
Encrypt a passcode using the Nest Passcode Encryption scheme.
EncryptPasscode(uint8_t config, uint32_t keyId, uint32_t nonce, const uint8_t *passcode, size_t passcodeLen, const uint8_t *encKey, const uint8_t *authKey, const uint8_t *fingerprintKey, uint8_t *encPasscode, size_t encPasscodeBufSize, size_t & encPasscodeLen)
Encrypt a passcode using the Nest Passcode Encryption scheme.
GetEncryptedPasscodeConfig(const uint8_t *encPasscode, size_t encPasscodeLen, uint8_t & config)
Get the configuration type of an encrypted passcode.
GetEncryptedPasscodeFingerprint(const uint8_t *encPasscode, size_t encPasscodeLen, uint8_t *fingerprintBuf, size_t fingerprintBufSize, size_t & fingerprintLen)
Get the fingerprint value associated with an encrypted passcode.
GetEncryptedPasscodeKeyId(const uint8_t *encPasscode, size_t encPasscodeLen, uint32_t & keyId)
Get the id of the key used to encrypt an encrypted passcode.
GetEncryptedPasscodeNonce(const uint8_t *encPasscode, size_t encPasscodeLen, uint32_t & nonce)
Get the nonce value associated with an encrypted passcode.
IsSupportedPasscodeEncryptionConfig(uint8_t config)
bool
Returns true if the supplied passcode encryption configuration is supported by the passcode encryption/decryption APIs.

Structs
nl::Weave::Profiles::Security::Passcodes::EncryptedPasscodeStruct

Enumerations

@278

 @278

Weave passcode encryption configuration types.

Properties
kPasscodeConfig1_KeyId

Dummy key id used for test passcode configuration #1.

kPasscode_Config1_TEST_ONLY

Passcode encryption configuration #1 is not using encryption and secret keys to authenticate and fingerprint passcode.

This configuration SHOULD be used for TEST purposes only.

kPasscode_Config2

Passcode encryption configuration #2 is using AES-128-ECB encryption with 8 byte HMAC-SHA-1 integrity and 8 byte HMAC-SHA-1 fingerprint.

@279

 @279

Weave passcode encryption protocol parameter sizes.

Properties
kPasscodeAuthenticationKeyLen

Passcode authentication (SHA-1) key length.

kPasscodeAuthenticatorLen

Passcode authenticator length.

kPasscodeEncKeyDiversifierSize

Passcode encryption application key diversifier size.

kPasscodeEncryptionKeyLen

Passcode encryption (AES-128) key length.

kPasscodeFingerprintKeyDiversifierSize

Passcode fingerprint key diversifier size.

kPasscodeFingerprintKeyLen

Passcode fingerprint (SHA-1) key length.

kPasscodeFingerprintLen

Passcode fingerprint length.

kPasscodeMaxEncryptedLen

Max encrypted passcode length.

kPasscodeMaxLen

Max unencrytped passcode length.

kPasscodePaddedLen

Passcode length (padded to the AES-128 block length).

kPasscodeTotalDerivedKeyLen

Passcode total (encryption & integrity) key length.

Variables

kPasscodeEncKeyDiversifier

const uint8_t kPasscodeEncKeyDiversifier[] = { 0x1A, 0x65, 0x5D, 0x96 }

Key diversifier used for Weave passcode encryption key derivation.

This value represents first 4 bytes of the SHA-1 HASH of "Nest Passcode EK and AK" phrase.

kPasscodeFingerprintKeyDiversifier

const uint8_t kPasscodeFingerprintKeyDiversifier[] = { 0xD1, 0xA1, 0xD9, 0x6C }

Key diversifier used for Weave passcode encryption key derivation.

This value represents first 4 bytes of the SHA-1 HASH of "Nest Passcode EK and AK" phrase.

Functions

DecryptPasscode

WEAVE_ERROR DecryptPasscode(
  const uint8_t *encPasscode,
  size_t encPasscodeLen,
  uint8_t *passcodeBuf,
  size_t passcodeBufSize,
  size_t & passcodeLen,
  GroupKeyStoreBase *groupKeyStore
)

Decrypt a passcode that was encrypted using the Nest Passcode Encryption scheme.

Details
Parameters
[in] encPasscode
A pointer to the encrypted passcode buffer.
[in] encPasscodeLen
The encrypted passcode length.
[in] passcodeBuf
A pointer to a buffer to receive the decrypted passcode.
[in] passcodeBufSize
The size of the buffer pointed at by passcodeBuf.
[out] passcodeLen
Set to the length of the decrypted passcode.
[in] groupKeyStore
A pointer to the group key store object.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_UNSUPPORTED_PASSCODE_CONFIG
If specified passcode configuration is not supported.
WEAVE_ERROR_PASSCODE_AUTHENTICATION_FAILED
If passcode authentication fails.
WEAVE_ERROR_PASSCODE_FINGERPRINT_FAILED
If passcode fingerprint check fail-es.
WEAVE_ERROR_INVALID_KEY_ID
If the requested key has invalid key Id.
WEAVE_ERROR_BUFFER_TOO_SMALL
If the supplied passcode buffer is too small.
WEAVE_ERROR_INVALID_ARGUMENT
If the encrytped passcode is too short or too long; Or if pointer to the group key store is not provided or platform key store returns invalid key parameters.
other
Other platform-specific errors returned by the platform key store APIs.

DecryptPasscode

WEAVE_ERROR DecryptPasscode(
  const uint8_t *encPasscode,
  size_t encPasscodeLen,
  const uint8_t *encKey,
  const uint8_t *authKey,
  const uint8_t *fingerprintKey,
  uint8_t *passcodeBuf,
  size_t passcodeBufSize,
  size_t & passcodeLen
)

Decrypt a passcode that was encrypted using the Nest Passcode Encryption scheme.

Details
Parameters
[in] encPasscode
A pointer to the encrypted passcode buffer.
[in] encPasscodeLen
The encrypted passcode length.
[in] encKey
A pointer to the key to be used to encrypt the passcode. The length of the key must match the encryption algorithm associated with the specified configuration.
[in] authKey
A pointer to the key to be used to authenticate the passcode. The length of the key must match the authentication algorithm associated with the specified configuration.
[in] fingerprintKey
A pointer to the key to be used to generate the passcode fingerprint. The length of the key must match the fingerprint algorithm associated with the specified configuration.
[in] passcodeBuf
A pointer to a buffer to receive the decrypted passcode.
[in] passcodeBufSize
The size of the buffer pointed at by passcodeBuf.
[out] passcodeLen
Set to the length of the decrypted passcode.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_UNSUPPORTED_PASSCODE_CONFIG
If specified passcode configuration is not supported.
WEAVE_ERROR_PASSCODE_AUTHENTICATION_FAILED
If passcode authentication fails.
WEAVE_ERROR_PASSCODE_FINGERPRINT_FAILED
If passcode fingerprint check fail-es.
WEAVE_ERROR_BUFFER_TOO_SMALL
If the supplied passcode buffer is too small.
WEAVE_ERROR_INVALID_ARGUMENT
If the encrytped passcode is too short or too long.

EncryptPasscode

WEAVE_ERROR EncryptPasscode(
  uint8_t config,
  uint32_t keyId,
  uint32_t nonce,
  const uint8_t *passcode,
  size_t passcodeLen,
  uint8_t *encPasscode,
  size_t encPasscodeBufSize,
  size_t & encPasscodeLen,
  GroupKeyStoreBase *groupKeyStore
)

Encrypt a passcode using the Nest Passcode Encryption scheme.

Details
Parameters
[in] config
The passcode encryption configuration to be used.
[in] keyId
The requested passcode encryption key Id.
[in] nonce
An unique value assigned to the encrypted passcode.
[in] passcode
A pointer to the passcode to be encrypted.
[in] passcodeLen
The passcode length.
[out] encPasscode
A pointer to the buffer to store encrypted passcode.
[in] encPasscodeBufSize
The size of the buffer for encrypted passcode storage.
[out] encPasscodeLen
The encrypted passcode length.
[in] groupKeyStore
A pointer to the group key store object.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_UNSUPPORTED_PASSCODE_CONFIG
If specified passcode configuration is not supported.
WEAVE_ERROR_BUFFER_TOO_SMALL
If provided output buffer is too small for encrypted passcode.
WEAVE_ERROR_INVALID_KEY_ID
If the requested key has invalid key Id.
WEAVE_ERROR_INVALID_ARGUMENT
If the supplied passcode is too short or too long; Or if pointer to the group key store is not provided or platform key store returns invalid key parameters.
other
Other platform-specific errors returned by the platform key store APIs.

EncryptPasscode

WEAVE_ERROR EncryptPasscode(
  uint8_t config,
  uint32_t keyId,
  uint32_t nonce,
  const uint8_t *passcode,
  size_t passcodeLen,
  const uint8_t *encKey,
  const uint8_t *authKey,
  const uint8_t *fingerprintKey,
  uint8_t *encPasscode,
  size_t encPasscodeBufSize,
  size_t & encPasscodeLen
)

Encrypt a passcode using the Nest Passcode Encryption scheme.

Details
Parameters
[in] config
The Weave passcode encryption configuration to be used.
[in] keyId
The requested passcode encryption key Id.
[in] nonce
An unique value assigned to the passcode.
[in] passcode
A pointer to the passcode to be encrypted.
[in] passcodeLen
The passcode length.
[in] encKey
A pointer to the key to be used to encrypt the passcode. The length of the key must match the encryption algorithm associated with the specified configuration.
[in] authKey
A pointer to the key to be used to authenticate the passcode. The length of the key must match the authentication algorithm associated with the specified configuration.
[in] fingerprintKey
A pointer to the key to be used to generate the passcode fingerprint. The length of the key must match the fingerprint algorithm associated with the specified configuration.
[out] encPasscode
A pointer to a buffer into which the encrypted passcode will be stored. This buffer must be at least kPasscodeMaxEncryptedLen in size.
[in] encPasscodeBufSize
The size of the buffer pointed to by encPasscode.
[out] encPasscodeLen
The encrypted passcode length.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_UNSUPPORTED_PASSCODE_CONFIG
If specified passcode configuration is not supported.
WEAVE_ERROR_BUFFER_TOO_SMALL
If provided output buffer is too small for encrypted passcode.
WEAVE_ERROR_INVALID_ARGUMENT
If the supplied passcode is too short or too long.

GetEncryptedPasscodeConfig

WEAVE_ERROR GetEncryptedPasscodeConfig(
  const uint8_t *encPasscode,
  size_t encPasscodeLen,
  uint8_t & config
)

Get the configuration type of an encrypted passcode.

Details
Parameters
[in] encPasscode
Pointer to a buffer containing the encrypted passcode.
[in] encPasscodeLen
Length of the encrypted passcode.
[out] config
The Weave passcode encryption configuration used by the encrypted passcode.

GetEncryptedPasscodeFingerprint

WEAVE_ERROR GetEncryptedPasscodeFingerprint(
  const uint8_t *encPasscode,
  size_t encPasscodeLen,
  uint8_t *fingerprintBuf,
  size_t fingerprintBufSize,
  size_t & fingerprintLen
)

Get the fingerprint value associated with an encrypted passcode.

Details
Parameters
[in] encPasscode
Pointer to a buffer containing the encrypted passcode.
[in] encPasscodeLen
Length of the encrypted passcode.
[in] fingerprintBuf
A buffer to receive the fingerprint value.
[in] fingerprintBufSize
The size of the buffer pointed at by fingerprintBuf.
[out] fingerprintLen
The length of the returned fingerprint value.

GetEncryptedPasscodeKeyId

WEAVE_ERROR GetEncryptedPasscodeKeyId(
  const uint8_t *encPasscode,
  size_t encPasscodeLen,
  uint32_t & keyId
)

Get the id of the key used to encrypt an encrypted passcode.

Details
Parameters
[in] encPasscode
Pointer to a buffer containing the encrypted passcode.
[in] encPasscodeLen
Length of the encrypted passcode.
[out] keyId
The id of the key used to encrypt the encrypted passcode.

GetEncryptedPasscodeNonce

WEAVE_ERROR GetEncryptedPasscodeNonce(
  const uint8_t *encPasscode,
  size_t encPasscodeLen,
  uint32_t & nonce
)

Get the nonce value associated with an encrypted passcode.

Details
Parameters
[in] encPasscode
Pointer to a buffer containing the encrypted passcode.
[in] encPasscodeLen
Length of the encrypted passcode.
[out] nonce
The nonce value associated with an encrypted passcode.

IsSupportedPasscodeEncryptionConfig

bool IsSupportedPasscodeEncryptionConfig(
  uint8_t config
)

Returns true if the supplied passcode encryption configuration is supported by the passcode encryption/decryption APIs.