src/lib/core/CHIPKeyIds.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2016-2017 Nest Labs, Inc.
   5  *
   6  *    Licensed under the Apache License, Version 2.0 (the "License");
   7  *    you may not use this file except in compliance with the License.
   8  *    You may obtain a copy of the License at
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *    Unless required by applicable law or agreed to in writing, software
  13  *    distributed under the License is distributed on an "AS IS" BASIS,
  14  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *    See the License for the specific language governing permissions and
  16  *    limitations under the License.
  17  */
  18
  19 /**
  20  *    @file
  21  *      This file defines constant enumerations for all CHIP key types,
  22  *      key flags, key ID fields, and helper API functions.
  23  *
  24  */
  25
  26 #pragma once
  27
  28 #include <limits.h>
  29 #include <stdint.h>
  30
  31 namespace chip {
  32
  33 /**
  34  *  @class ChipKeyId
  35  *
  36  *  @brief
  37  *    The definition of the CHIP Key identifier. This class contains
  38  *    key types, key flags, key ID fields definition, and API functions.
  39  *
  40  */
  41 class ChipKeyId
  42 {
  43 private:
  44     /**
  45      * @brief
  46      *   Private CHIP key ID fields, flags, and types.
  47      */
  48     enum
  49     {
  50         kMask_KeyFlags         = 0xF0000000, /**< CHIP key flag field mask. */
  51         kMask_KeyType          = 0x0FFFF000, /**< CHIP key type field mask. */
  52         kMask_KeyNumber        = 0x00000FFF, /**< CHIP key number field mask. */
  53         kMask_RootKeyNumber    = 0x00000C00, /**< Application group root key number field mask. */
  54         kMask_EpochKeyNumber   = 0x00000380, /**< Application group epoch key number field mask. */
  55         kMask_GroupLocalNumber = 0x0000007F, /**< Application group local number field mask. */
  56
  57         kShift_RootKeyNumber    = 10, /**< Application group root key number field shift. */
  58         kShift_EpochKeyNumber   = 7,  /**< Application group epoch key number field shift. */
  59         kShift_GroupLocalNumber = 0,  /**< Application group local number field shift. */
  60
  61         kFlag_UseCurrentEpochKey = 0x80000000, /**< Used to indicate that the key is of logical current type. */
  62
  63         kTypeModifier_IncorporatesEpochKey = 0x00001000, /**< Used to indicate that the key incorporates group epoch key. */
  64     };
  65
  66 public:
  67     /**
  68      * @brief
  69      *   Public CHIP key ID fields, flags, and types.
  70      */
  71     enum
  72     {
  73         /**
  74          * @brief  CHIP key types used for CHIP message encryption.
  75          *
  76          * @note  16 (out of 32) most significant bits of the message encryption key
  77          *        type should be zero because only 16 least significant bits of the ID
  78          *        are encoded in the CHIP message.
  79          *  @{
  80          */
  81         kType_None         = 0x00000000, /**< CHIP message is unencrypted. */
  82         kType_General      = 0x00001000, /**< General key type. */
  83         kType_Session      = 0x00002000, /**< Session key type. */
  84         kType_AppStaticKey = 0x00004000, /**< Application static key type. */
  85         /** Application rotating key type. */
  86         kType_AppRotatingKey = kType_AppStaticKey | kTypeModifier_IncorporatesEpochKey,
  87         /** @} */
  88
  89         /**
  90          * @brief  CHIP key types (other than CHIP message encryption types).
  91          *
  92          * @note  16 (out of 32) most significant bits of these types cannot be all zeros,
  93          *        because these values are reserved for the CHIP message encryption keys only.
  94          *  @{
  95          */
  96
  97         /**
  98          * @brief  Constituent group key types.
  99          *  @{
 100          */
 101         /** Application group root key type. */
 102         kType_AppRootKey = 0x00010000,
 103         /** Application group epoch key type. */
 104         kType_AppEpochKey = 0x00020000 | kTypeModifier_IncorporatesEpochKey,
 105         /** Application group master key type. */
 106         kType_AppGroupMasterKey = 0x00030000,
 107         /** Application group intermediate key type. */
 108         kType_AppIntermediateKey = kType_AppRootKey | kTypeModifier_IncorporatesEpochKey,
 109         /** @} */
 110
 111         /**
 112          * @brief  CHIP global key IDs.
 113          *  @{
 114          */
 115         /** Unspecified CHIP key ID. */
 116         kNone = kType_None | 0x0000,
 117         /** CHIP fabric secret ID. */
 118         kFabricSecret = kType_General | 0x0001,
 119         /** Fabric root key ID. */
 120         kFabricRootKey = kType_AppRootKey | (0 << kShift_RootKeyNumber),
 121         /** Client root key ID. */
 122         kClientRootKey = kType_AppRootKey | (1 << kShift_RootKeyNumber),
 123         /** Service root key ID. */
 124         kServiceRootKey = kType_AppRootKey | (2 << kShift_RootKeyNumber),
 125         /** @} */
 126
 127         /**
 128          * @brief  Maximum values for key ID subfields.
 129          *  @{
 130          */
 131         kKeyNumber_Max        = kMask_KeyNumber,
 132         kRootKeyNumber_Max    = (kMask_RootKeyNumber >> kShift_RootKeyNumber),
 133         kEpochKeyNumber_Max   = (kMask_EpochKeyNumber >> kShift_EpochKeyNumber),
 134         kGroupLocalNumber_Max = (kMask_GroupLocalNumber >> kShift_GroupLocalNumber),
 135         /** @} */
 136     };
 137
 138     /**
 139      *  Get CHIP key type of the specified key ID.
 140      *
 141      *  @param[in]   keyId     CHIP key identifier.
 142      *  @return                type of the key ID.
 143      *
 144      */
 145     static uint32_t GetType(uint32_t keyId) { return keyId & kMask_KeyType; }
 146
 147     /**
 148      *  Determine whether the specified key ID is of a general type.
 149      *
 150      *  @param[in]   keyId     CHIP key identifier.
 151      *  @return      true      if the keyId has General type.
 152      *
 153      */
 154     static bool IsGeneralKey(uint32_t keyId) { return GetType(keyId) == kType_General; }
 155
 156     /**
 157      *  Determine whether the specified key ID is of a session type.
 158      *
 159      *  @param[in]   keyId     CHIP key identifier.
 160      *  @return      true      if the keyId of a session type.
 161      *
 162      */
 163     static bool IsSessionKey(uint32_t keyId) { return GetType(keyId) == kType_Session; }
 164
 165     /**
 166      *  Determine whether the specified key ID is of an application static type.
 167      *
 168      *  @param[in]   keyId     CHIP key identifier.
 169      *  @return      true      if the keyId of an application static type.
 170      *
 171      */
 172     static bool IsAppStaticKey(uint32_t keyId) { return GetType(keyId) == kType_AppStaticKey; }
 173
 174     /**
 175      *  Determine whether the specified key ID is of an application rotating type.
 176      *
 177      *  @param[in]   keyId     CHIP key identifier.
 178      *  @return      true      if the keyId of an application rotating type.
 179      *
 180      */
 181     static bool IsAppRotatingKey(uint32_t keyId) { return GetType(keyId) == kType_AppRotatingKey; }
 182
 183     static bool IsAppGroupKey(uint32_t keyId);
 184
 185     /**
 186      *  Determine whether the specified key ID is of an application root key type.
 187      *
 188      *  @param[in]   keyId     CHIP key identifier.
 189      *  @return      true      if the keyId of an application root key type.
 190      *
 191      */
 192     static bool IsAppRootKey(uint32_t keyId) { return GetType(keyId) == kType_AppRootKey; }
 193
 194     /**
 195      *  Determine whether the specified key ID is of an application epoch key type.
 196      *
 197      *  @param[in]   keyId     CHIP key identifier.
 198      *  @return      true      if the keyId of an application epoch key type.
 199      *
 200      */
 201     static bool IsAppEpochKey(uint32_t keyId) { return GetType(keyId) == kType_AppEpochKey; }
 202
 203     /**
 204      *  Determine whether the specified key ID is of an application group master key type.
 205      *
 206      *  @param[in]       keyId     CHIP key identifier.
 207      *  @return  true      if the keyId of an application group master key type.
 208      *
 209      */
 210     static bool IsAppGroupMasterKey(uint32_t keyId) { return GetType(keyId) == kType_AppGroupMasterKey; }
 211
 212     /**
 213      *  Construct session key ID given session key number.
 214      *
 215      *  @param[in]   sessionKeyNumber      Session key number.
 216      *  @return      session key ID.
 217      *
 218      */
 219     static uint16_t MakeSessionKeyId(uint16_t sessionKeyNumber)
 220     {
 221         static_assert(kType_Session <= UINT16_MAX, "We'll overflow");
 222         return static_cast<uint16_t>(kType_Session | (sessionKeyNumber & kMask_KeyNumber));
 223     }
 224
 225     /**
 226      *  Construct general key ID given general key number.
 227      *
 228      *  @param[in]   generalKeyNumber       General key number.
 229      *  @return      general key ID.
 230      *
 231      */
 232     static uint16_t MakeGeneralKeyId(uint16_t generalKeyNumber)
 233     {
 234         static_assert(kType_General <= UINT16_MAX, "We'll overflow");
 235         return static_cast<uint16_t>(kType_General | (generalKeyNumber & kMask_KeyNumber));
 236     }
 237
 238     /**
 239      *  Get application group root key ID that was used to derive specified application key.
 240      *
 241      *  @param[in]   keyId     CHIP application group key identifier.
 242      *  @return      root key ID.
 243      *
 244      */
 245     static uint32_t GetRootKeyId(uint32_t keyId) { return kType_AppRootKey | (keyId & kMask_RootKeyNumber); }
 246
 247     /**
 248      *  Get application group epoch key ID that was used to derive specified application key.
 249      *
 250      *  @param[in]   keyId     CHIP application group key identifier.
 251      *  @return      epoch key ID.
 252      *
 253      */
 254     static uint32_t GetEpochKeyId(uint32_t keyId) { return kType_AppEpochKey | (keyId & kMask_EpochKeyNumber); }
 255
 256     /**
 257      *  Get application group master key ID that was used to derive specified application key.
 258      *
 259      *  @param[in]   keyId     CHIP application group key identifier.
 260      *  @return      application group master key ID.
 261      *
 262      */
 263     static uint32_t GetAppGroupMasterKeyId(uint32_t keyId) { return kType_AppGroupMasterKey | (keyId & kMask_GroupLocalNumber); }
 264
 265     /**
 266      *  Get application group root key number that was used to derive specified application key.
 267      *
 268      *  @param[in]   keyId     CHIP application group key identifier.
 269      *  @return      root key number.
 270      *
 271      */
 272     static uint8_t GetRootKeyNumber(uint32_t keyId) { return (keyId & kMask_RootKeyNumber) >> kShift_RootKeyNumber; }
 273
 274     /**
 275      *  Get application group epoch key number that was used to derive specified application key.
 276      *
 277      *  @param[in]   keyId     CHIP application group key identifier.
 278      *  @return      epoch key number.
 279      *
 280      */
 281     static uint8_t GetEpochKeyNumber(uint32_t keyId) { return (keyId & kMask_EpochKeyNumber) >> kShift_EpochKeyNumber; }
 282
 283     /**
 284      *  Get application group local number that was used to derive specified application key.
 285      *
 286      *  @param[in]   keyId     CHIP application group key identifier.
 287      *  @return      application group local number.
 288      *
 289      */
 290     static uint8_t GetAppGroupLocalNumber(uint32_t keyId) { return (keyId & kMask_GroupLocalNumber) >> kShift_GroupLocalNumber; }
 291
 292     /**
 293      *  Construct application group root key ID given root key number.
 294      *
 295      *  @param[in]   rootKeyNumber         Root key number.
 296      *  @return      root key ID.
 297      *
 298      */
 299     static uint32_t MakeRootKeyId(uint8_t rootKeyNumber)
 300     {
 301         return static_cast<uint32_t>(kType_AppRootKey | (rootKeyNumber << kShift_RootKeyNumber));
 302     }
 303
 304     /**
 305      *  Construct application group root key ID given epoch key number.
 306      *
 307      *  @param[in]   epochKeyNumber        Epoch key number.
 308      *  @return      epoch key ID.
 309      *
 310      */
 311     static uint32_t MakeEpochKeyId(uint8_t epochKeyNumber)
 312     {
 313         return static_cast<uint32_t>(kType_AppEpochKey | (epochKeyNumber << kShift_EpochKeyNumber));
 314     }
 315
 316     /**
 317      *  Construct application group master key ID given application group local number.
 318      *
 319      *  @param[in]   appGroupLocalNumber   Application group local number.
 320      *  @return      application group master key ID.
 321      *
 322      */
 323     static uint32_t MakeAppGroupMasterKeyId(uint8_t appGroupLocalNumber)
 324     {
 325         return static_cast<uint32_t>(kType_AppGroupMasterKey | (appGroupLocalNumber << kShift_GroupLocalNumber));
 326     }
 327
 328     /**
 329      *  Convert application group key ID to application current key ID.
 330      *
 331      *  @param[in]   keyId                 Application key ID.
 332      *  @return      application current key ID.
 333      *
 334      */
 335     static uint32_t ConvertToCurrentAppKeyId(uint32_t keyId) { return (keyId & ~kMask_EpochKeyNumber) | kFlag_UseCurrentEpochKey; }
 336
 337     /**
 338      *  Determine whether the specified application group key ID incorporates epoch key.
 339      *
 340      *  @param[in]   keyId     CHIP application group key identifier.
 341      *  @return      true      if the keyId incorporates epoch key.
 342      *
 343      */
 344     static bool IncorporatesEpochKey(uint32_t keyId) { return (keyId & kTypeModifier_IncorporatesEpochKey) != 0; }
 345
 346     static bool UsesCurrentEpochKey(uint32_t keyId);
 347     static bool IncorporatesRootKey(uint32_t keyId);
 348     static bool IncorporatesAppGroupMasterKey(uint32_t keyId);
 349
 350     static uint32_t MakeAppKeyId(uint32_t keyType, uint32_t rootKeyId, uint32_t epochKeyId, uint32_t appGroupMasterKeyId,
 351                                  bool useCurrentEpochKey);
 352     static uint32_t MakeAppIntermediateKeyId(uint32_t rootKeyId, uint32_t epochKeyId, bool useCurrentEpochKey);
 353     static uint32_t MakeAppRotatingKeyId(uint32_t rootKeyId, uint32_t epochKeyId, uint32_t appGroupMasterKeyId,
 354                                          bool useCurrentEpochKey);
 355     static uint32_t MakeAppStaticKeyId(uint32_t rootKeyId, uint32_t appGroupMasterKeyId);
 356     static uint32_t ConvertToStaticAppKeyId(uint32_t keyId);
 357     static uint32_t UpdateEpochKeyId(uint32_t keyId, uint32_t epochKeyId);
 358
 359     static bool IsValidKeyId(uint32_t keyId);
 360     static bool IsMessageEncryptionKeyId(uint32_t keyId, bool allowLogicalKeys = true);
 361     static bool IsSameKeyOrGroup(uint32_t keyId1, uint32_t keyId2);
 362     static const char * DescribeKey(uint32_t keyId);
 363 };
 364
 365 } // namespace chip