3 * Copyright (c) 2020 Project CHIP Authors
4 * Copyright (c) 2016-2017 Nest Labs, Inc.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 * This file defines classes and interfaces for deriving and
23 * managing CHIP constituent and application group keys.
27 #ifndef CHIPAPPLICATIONKEYS_H_
28 #define CHIPAPPLICATIONKEYS_H_
30 #include <core/CHIPCore.h>
33 * @namespace chip::Protocols::Security::AppKeys
36 * This namespace includes all interfaces within CHIP for the CHIP
37 * application keys library within the CHIP security profile.
47 * Key diversifier used for CHIP fabric root key derivation. This value represents
48 * first 4 bytes of the SHA-1 HASH of "Fabric Root Key" phrase.
50 extern const uint8_t kChipAppFabricRootKeyDiversifier[4];
54 * Key diversifier used for CHIP client root key derivation. This value represents
55 * first 4 bytes of the SHA-1 HASH of "Client Root Key" phrase.
57 extern const uint8_t kChipAppClientRootKeyDiversifier[4];
61 * Key diversifier used for CHIP intermediate key derivation. This value represents
62 * first 4 bytes of the SHA-1 HASH of "Intermediate Key" phrase.
64 extern const uint8_t kChipAppIntermediateKeyDiversifier[4];
68 * CHIP application keys protocol parameter definitions.
73 kChipAppGroupKeySize = 32, /**< CHIP constituent group key size. */
74 kChipAppRootKeySize = kChipAppGroupKeySize, /**< CHIP application root key size. */
75 kChipAppEpochKeySize = kChipAppGroupKeySize, /**< CHIP application epoch key size. */
76 kChipAppGroupMasterKeySize = kChipAppGroupKeySize, /**< CHIP application group master key size. */
77 kChipAppIntermediateKeySize = kChipAppGroupKeySize, /**< CHIP application intermediate key size. */
78 kChipFabricSecretSize = 36, /**< CHIP fabric secret size. */
80 // --- Key diversifiers sizes.
81 /** Fabric root key diversifier size. */
82 kChipAppFabricRootKeyDiversifierSize = sizeof(kChipAppFabricRootKeyDiversifier),
83 /** Client root key diversifier size. */
84 kChipAppClientRootKeyDiversifierSize = sizeof(kChipAppClientRootKeyDiversifier),
85 /** Intermediate key diversifier size. */
86 kChipAppIntermediateKeyDiversifierSize = sizeof(kChipAppIntermediateKeyDiversifier),
93 * Contains information about CHIP application group keys.
94 * Examples of keys that can be described by this class are: root key,
95 * epoch key, group master key, intermediate key, and fabric secret.
103 MaxKeySize = kChipFabricSecretSize
105 uint32_t KeyId; /**< The key ID. */
106 uint8_t KeyLen; /**< The key length. */
107 uint8_t Key[MaxKeySize]; /**< The secret key material. */
110 uint32_t StartTime; /**< The epoch key start time. */
111 uint32_t GlobalId; /**< The application group key global ID. */
116 * @class GroupKeyStoreBase
119 * The definition of the CHIP group key store class. Functions in
120 * this class are called to manage application group keys.
123 class DLL_EXPORT GroupKeyStoreBase
126 // Manage application group key material storage.
127 virtual CHIP_ERROR RetrieveGroupKey(uint32_t keyId, ChipGroupKey & key) = 0;
128 virtual CHIP_ERROR StoreGroupKey(const ChipGroupKey & key) = 0;
129 virtual CHIP_ERROR DeleteGroupKey(uint32_t keyId) = 0;
130 virtual CHIP_ERROR DeleteGroupKeysOfAType(uint32_t keyType) = 0;
131 virtual CHIP_ERROR EnumerateGroupKeys(uint32_t keyType, uint32_t * keyIds, uint8_t keyIdsArraySize, uint8_t & keyCount) = 0;
132 virtual CHIP_ERROR Clear() = 0;
134 // Get the current time.
135 virtual CHIP_ERROR GetCurrentUTCTime(uint32_t & utcTime);
137 // Get current application key Id.
138 CHIP_ERROR GetCurrentAppKeyId(uint32_t keyId, uint32_t & curKeyId);
140 // Get/Derive group key.
141 CHIP_ERROR GetGroupKey(uint32_t keyId, ChipGroupKey & groupKey);
143 // Derive application key.
144 CHIP_ERROR DeriveApplicationKey(uint32_t & appKeyId, const uint8_t * keySalt, uint8_t saltLen, const uint8_t * keyDiversifier,
145 uint8_t diversifierLen, uint8_t * appKey, uint8_t keyBufSize, uint8_t keyLen,
146 uint32_t & appGroupGlobalId);
149 uint32_t LastUsedEpochKeyId;
150 uint32_t NextEpochKeyStartTime;
153 void OnEpochKeysChange();
155 // Retrieve and Store LastUsedEpochKeyId value.
156 virtual CHIP_ERROR RetrieveLastUsedEpochKeyId() = 0;
157 virtual CHIP_ERROR StoreLastUsedEpochKeyId() = 0;
160 // Derive fabric/client root key.
161 CHIP_ERROR DeriveFabricOrClientRootKey(uint32_t rootKeyId, ChipGroupKey & rootKey);
163 // Derive intermediate key.
164 CHIP_ERROR DeriveIntermediateKey(uint32_t keyId, ChipGroupKey & intermediateKey);
167 extern CHIP_ERROR GetAppGroupMasterKeyId(uint32_t groupGlobalId, GroupKeyStoreBase * groupKeyStore, uint32_t & groupMasterKeyId);
169 extern CHIP_ERROR LogGroupKeys(GroupKeyStoreBase * groupKeyStore);
171 } // namespace AppKeys
172 } // namespace Security
173 } // namespace Protocols
176 #endif /* CHIPAPPLICATIONKEYS_H_ */