src/lib/protocols/security/CHIPApplicationKeys.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2016-2017 Nest Labs, Inc.
   5  *    All rights reserved.
   6  *
   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
  10  *
  11  *        http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  */
  19
  20 /**
  21  *    @file
  22  *      This file defines classes and interfaces for deriving and
  23  *      managing CHIP constituent and application group keys.
  24  *
  25  */
  26
  27 #ifndef CHIPAPPLICATIONKEYS_H_
  28 #define CHIPAPPLICATIONKEYS_H_
  29
  30 #include <core/CHIPCore.h>
  31
  32 /**
  33  *   @namespace chip::Protocols::Security::AppKeys
  34  *
  35  *   @brief
  36  *     This namespace includes all interfaces within CHIP for the CHIP
  37  *     application keys library within the CHIP security profile.
  38  */
  39
  40 namespace chip {
  41 namespace Protocols {
  42 namespace Security {
  43 namespace AppKeys {
  44
  45 /**
  46  * @brief
  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.
  49  */
  50 extern const uint8_t kChipAppFabricRootKeyDiversifier[4];
  51
  52 /**
  53  * @brief
  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.
  56  */
  57 extern const uint8_t kChipAppClientRootKeyDiversifier[4];
  58
  59 /**
  60  * @brief
  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.
  63  */
  64 extern const uint8_t kChipAppIntermediateKeyDiversifier[4];
  65
  66 /**
  67  * @brief
  68  *   CHIP application keys protocol parameter definitions.
  69  */
  70 enum
  71 {
  72     // --- Key sizes.
  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. */
  79
  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),
  87 };
  88
  89 /**
  90  *  @class ChipGroupKey
  91  *
  92  *  @brief
  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.
  96  *
  97  */
  98 class ChipGroupKey
  99 {
 100 public:
 101     enum
 102     {
 103         MaxKeySize = kChipFabricSecretSize
 104     };
 105     uint32_t KeyId;          /**< The key ID. */
 106     uint8_t KeyLen;          /**< The key length. */
 107     uint8_t Key[MaxKeySize]; /**< The secret key material. */
 108     union
 109     {
 110         uint32_t StartTime; /**< The epoch key start time. */
 111         uint32_t GlobalId;  /**< The application group key global ID. */
 112     };
 113 };
 114
 115 /**
 116  *  @class GroupKeyStoreBase
 117  *
 118  *  @brief
 119  *    The definition of the CHIP group key store class. Functions in
 120  *    this class are called to manage application group keys.
 121  *
 122  */
 123 class DLL_EXPORT GroupKeyStoreBase
 124 {
 125 public:
 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;
 133
 134     // Get the current time.
 135     virtual CHIP_ERROR GetCurrentUTCTime(uint32_t & utcTime);
 136
 137     // Get current application key Id.
 138     CHIP_ERROR GetCurrentAppKeyId(uint32_t keyId, uint32_t & curKeyId);
 139
 140     // Get/Derive group key.
 141     CHIP_ERROR GetGroupKey(uint32_t keyId, ChipGroupKey & groupKey);
 142
 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);
 147
 148 protected:
 149     uint32_t LastUsedEpochKeyId;
 150     uint32_t NextEpochKeyStartTime;
 151
 152     void Init();
 153     void OnEpochKeysChange();
 154
 155     // Retrieve and Store LastUsedEpochKeyId value.
 156     virtual CHIP_ERROR RetrieveLastUsedEpochKeyId() = 0;
 157     virtual CHIP_ERROR StoreLastUsedEpochKeyId()    = 0;
 158
 159 private:
 160     // Derive fabric/client root key.
 161     CHIP_ERROR DeriveFabricOrClientRootKey(uint32_t rootKeyId, ChipGroupKey & rootKey);
 162
 163     // Derive intermediate key.
 164     CHIP_ERROR DeriveIntermediateKey(uint32_t keyId, ChipGroupKey & intermediateKey);
 165 };
 166
 167 extern CHIP_ERROR GetAppGroupMasterKeyId(uint32_t groupGlobalId, GroupKeyStoreBase * groupKeyStore, uint32_t & groupMasterKeyId);
 168
 169 extern CHIP_ERROR LogGroupKeys(GroupKeyStoreBase * groupKeyStore);
 170
 171 } // namespace AppKeys
 172 } // namespace Security
 173 } // namespace Protocols
 174 } // namespace chip
 175
 176 #endif /* CHIPAPPLICATIONKEYS_H_ */