Line data    Source code

       1             : /*
       2             :  *    Copyright (c) 2022 Project CHIP Authors
       3             :  *    All rights reserved.
       4             :  *
       5             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       6             :  *    you may not use this file except in compliance with the License.
       7             :  *    You may obtain a copy of the License at
       8             :  *
       9             :  *        http://www.apache.org/licenses/LICENSE-2.0
      10             :  *
      11             :  *    Unless required by applicable law or agreed to in writing, software
      12             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      13             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      14             :  *    See the License for the specific language governing permissions and
      15             :  *    limitations under the License.
      16             :  */
      17             : 
      18             : #pragma once
      19             : 
      20             : #include <crypto/CHIPCryptoPAL.h>
      21             : #include <lib/core/CHIPError.h>
      22             : #include <lib/core/DataModelTypes.h>
      23             : #include <lib/support/Span.h>
      24             : 
      25             : namespace chip {
      26             : namespace Crypto {
      27             : 
      28             : class OperationalKeystore
      29             : {
      30             : public:
      31           1 :     virtual ~OperationalKeystore() {}
      32             : 
      33             :     // ==== API designed for commisionables to support fail-safe (although can be used by controllers) ====
      34             : 
      35             :     /**
      36             :      * @brief Returns true if a pending operational key exists from a previous
      37             :      *        `NewOpKeypairForFabric` before any `CommitOpKeypairForFabric` or
      38             :      *        `RevertOpKeypairForFabric`. This returns true even if the key is
      39             :      *        NOT ACTIVE (i.e after `NewOpKeypairForFabric` but before
      40             :      *        `ActivateOpKeypairForFabric`).
      41             :      */
      42             :     virtual bool HasPendingOpKeypair() const = 0;
      43             : 
      44             :     /**
      45             :      * @brief Returns whether a usable operational key exists for the given fabric.
      46             :      *
      47             :      * Returns true even if the key is not persisted, such as if `ActivateOpKeypairForFabric`
      48             :      * had been successfully called for a given fabric. Only returns true if a key
      49             :      * is presently usable such that `SignWithOpKeypair` would succeed for the fabric. Therefore
      50             :      * if there was no previously persisted key and `NewOpKeypairForFabric` had been called
      51             :      * but not `ActivateOpKeypairForFabric`, there is only an inactive key, and this would return false.
      52             :      *
      53             :      * @param fabricIndex - FabricIndex for which availability of keypair will be checked.
      54             :      * @return true if there an active operational keypair for the given FabricIndex, false otherwise.
      55             :      */
      56             :     virtual bool HasOpKeypairForFabric(FabricIndex fabricIndex) const = 0;
      57             : 
      58             :     /**
      59             :      * @brief This initializes a new keypair for the given fabric and generates a CSR for it,
      60             :      *        so that it can be passed in a CSRResponse.
      61             :      *
      62             :      * The keypair is temporary and becomes usable for `SignWithOpKeypair` only after either
      63             :      * `ActivateOpKeypairForFabric` is called. It is destroyed if
      64             :      * `RevertPendingKeypair` is called before `CommitOpKeypairForFabric`.
      65             :      *  If a pending keypair already existed for the given `fabricIndex`, it is replaced by this call.
      66             :      *
      67             :      *  Only one pending operational keypair is supported at a time.
      68             :      *
      69             :      * @param fabricIndex - FabricIndex for which a new keypair must be made available
      70             :      * @param outCertificateSigningRequest - Buffer to contain the CSR. Must have size at least `kMIN_CSR_Buffer_Size`.
      71             :      *
      72             :      * @retval CHIP_NO_ERROR on success
      73             :      * @retval CHIP_ERROR_BUFFER_TOO_SMALL if `outCertificateSigningRequest` buffer is too small
      74             :      * @retval CHIP_ERROR_INCORRECT_STATE if the key store is not properly initialized.
      75             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if there is already a pending keypair for another `fabricIndex` value
      76             :      *                                         or if fabricIndex is an invalid value.
      77             :      * @retval CHIP_ERROR_NOT_IMPLEMENTED if only `SignWithOpKeypair` is supported
      78             :      * @retval other CHIP_ERROR value on internal crypto engine errors
      79             :      */
      80             :     virtual CHIP_ERROR NewOpKeypairForFabric(FabricIndex fabricIndex, MutableByteSpan & outCertificateSigningRequest) = 0;
      81             : 
      82             :     /**
      83             :      * @brief Temporarily activates the operational keypair last generated with `NewOpKeypairForFabric`, so
      84             :      *        that `SignWithOpKeypair` starts using it, but only if it matches the public key associated
      85             :      *        with the last NewOpKeypairForFabric.
      86             :      *
      87             :      * This is to be used by AddNOC and UpdateNOC so that a prior key generated by NewOpKeypairForFabric
      88             :      * can be used for CASE while not committing it yet to permanent storage to remain after fail-safe.
      89             :      *
      90             :      * @param fabricIndex - FabricIndex for which to activate the keypair, used for security cross-checking
      91             :      * @param nocPublicKey - Subject public key associated with an incoming NOC
      92             :      *
      93             :      * @retval CHIP_NO_ERROR on success
      94             :      * @retval CHIP_ERROR_INCORRECT_STATE if the key store is not properly initialized.
      95             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if there is no operational keypair for `fabricIndex` from a previous
      96             :      *                                         matching `NewOpKeypairForFabric`.
      97             :      * @retval CHIP_ERROR_INVALID_PUBLIC_KEY if `nocPublicKey` does not match the public key associated with the
      98             :      *                                       key pair from last `NewOpKeypairForFabric`.
      99             :      * @retval CHIP_ERROR_NOT_IMPLEMENTED if only `SignWithOpKeypair` is supported
     100             :      * @retval other CHIP_ERROR value on internal storage or crypto engine errors
     101             :      */
     102             :     virtual CHIP_ERROR ActivateOpKeypairForFabric(FabricIndex fabricIndex, const Crypto::P256PublicKey & nocPublicKey) = 0;
     103             : 
     104             :     /**
     105             :      * @brief Permanently commit the operational keypair last generated with `NewOpKeypairForFabric`,
     106             :      *        replacing a prior one previously committed, if any, so that `SignWithOpKeypair` for the
     107             :      *        given `FabricIndex` permanently uses the key that was pending.
     108             :      *
     109             :      * This is to be used when CommissioningComplete is successfully received
     110             :      *
     111             :      * @param fabricIndex - FabricIndex for which to commit the keypair, used for security cross-checking
     112             :      *
     113             :      * @retval CHIP_NO_ERROR on success
     114             :      * @retval CHIP_ERROR_INCORRECT_STATE if the key store is not properly initialized,
     115             :      *                                    or ActivateOpKeypairForFabric not yet called
     116             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if there is no pending operational keypair for `fabricIndex`
     117             :      * @retval CHIP_ERROR_NOT_IMPLEMENTED if only `SignWithOpKeypair` is supported
     118             :      * @retval other CHIP_ERROR value on internal storage or crypto engine errors
     119             :      */
     120             :     virtual CHIP_ERROR CommitOpKeypairForFabric(FabricIndex fabricIndex) = 0;
     121             : 
     122             :     /**
     123             :      * @brief Try to read out the permanently committed operational keypair and save it to the buffer.
     124             :      *
     125             :      * @param fabricIndex - FabricIndex from which the keypair will be exported
     126             :      * @param outKeypair - a reference to P256SerializedKeypair object to store the exported key.
     127             :      * @retval CHIP_ERROR on success.
     128             :      * @retval CHIP_ERROR_UNSUPPORTED_CHIP_FEATURE if the key cannot be exported due to security restrictions.
     129             :      * @retval CHIP_ERROR_NOT_IMPLEMENTED if the exporting is not implemented for the cryptography backend.
     130             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if provided wrong value of `fabricIndex`.
     131             :      * @retval CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND if there is no keypair found for `fabricIndex`.
     132             :      * @retval CHIP_ERROR_BUFFER_TOO_SMALL if `outKeyPair` buffer is too small to store the read out keypair.
     133             :      * @retval other CHIP_ERROR value on internal storage or cryptography backend errors.
     134             :      */
     135           0 :     virtual CHIP_ERROR ExportOpKeypairForFabric(FabricIndex fabricIndex, Crypto::P256SerializedKeypair & outKeypair)
     136             :     {
     137           0 :         return CHIP_ERROR_NOT_IMPLEMENTED;
     138             :     };
     139             : 
     140             :     /**
     141             :      * @brief Migrate the operational keypair from another Operational keystore (`operationalKeystore`) implementation to this one.
     142             :      *
     143             :      * This method assumes that the operational key for given `fabricIndex` exists in the `operationalKeystore` storage or it has
     144             :      * been already migrated to the new Operational Storage. If a key for the given `fabricIndex` does not exist in any of those
     145             :      * keystores, then the method retuns CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND.
     146             :      *
     147             :      * @param fabricIndex - FabricIndex for which to migrate the operational key
     148             :      * @param operationalKeystore - a reference to the operationalKeystore implementation that may contain saved operational key
     149             :      * for Fabric
     150             :      * @retval CHIP_ERROR on success
     151             :      * @retval CHIP_ERROR_UNSUPPORTED_CHIP_FEATURE if the key cannot be exported due to security restrictions.
     152             :      * @retval CHIP_ERROR_NOT_IMPLEMENTED if the exporting is not implemented for the cryptography backend.
     153             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if there is no keypair found for `fabricIndex`.
     154             :      * @retval CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND if there is no keypair found for `fabricIndex`.
     155             :      * @retval other CHIP_ERROR value on internal storage or crypto engine errors.
     156             :      */
     157           0 :     virtual CHIP_ERROR MigrateOpKeypairForFabric(FabricIndex fabricIndex, OperationalKeystore & operationalKeystore) const
     158             :     {
     159           0 :         return CHIP_ERROR_NOT_IMPLEMENTED;
     160             :     };
     161             : 
     162             :     /**
     163             :      * @brief Permanently remove the keypair associated with a fabric
     164             :      *
     165             :      * This is to be used for fail-safe handling and RemoveFabric.  Removes both the
     166             :      * pending operational keypair for the fabricIndex (if any) and the committed one (if any).
     167             :      *
     168             :      * @param fabricIndex - FabricIndex for which to remove the keypair
     169             :      *
     170             :      * @retval CHIP_NO_ERROR on success
     171             :      * @retval CHIP_ERROR_INCORRECT_STATE if the key store is not properly initialized.
     172             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if there is no operational keypair for `fabricIndex`
     173             :      * @retval CHIP_ERROR_NOT_IMPLEMENTED if only `SignWithOpKeypair` is supported
     174             :      * @retval other CHIP_ERROR value on internal storage errors
     175             :      */
     176             :     virtual CHIP_ERROR RemoveOpKeypairForFabric(FabricIndex fabricIndex) = 0;
     177             : 
     178             :     /**
     179             :      * @brief Permanently release the operational keypair last generated with `NewOpKeypairForFabric`,
     180             :      *        such that `SignWithOpKeypair` uses the previously committed key (if one existed).
     181             :      *
     182             :      * This is to be used when a fail-safe expires prior to CommissioningComplete.
     183             :      *
     184             :      * This method cannot error-out and must always succeed, even on a no-op. This should
     185             :      * be safe to do given that `CommitOpKeypairForFabric` must succeed to make a new operational
     186             :      * keypair usable.
     187             :      */
     188             :     virtual void RevertPendingKeypair() = 0;
     189             : 
     190             :     // ==== Primary operation required: signature
     191             :     /**
     192             :      * @brief Whether `SignWithOpKeypair` may be performed in the background.
     193             :      *
     194             :      * If true, `CASESession` may attempt to perform `SignWithOpKeypair` in the
     195             :      * background. In this case, `OperationalKeystore` should protect itself,
     196             :      * e.g. with a mutex, as the signing could occur at any time during session
     197             :      * establishment.
     198             :      *
     199             :      * @retval true if `SignWithOpKeypair` may be performed in the background
     200             :      * @retval false if `SignWithOpKeypair` may NOT be performed in the background
     201             :      */
     202           0 :     virtual bool SupportsSignWithOpKeypairInBackground() const { return false; }
     203             : 
     204             :     /**
     205             :      * @brief Sign a message with a fabric's currently-active operational keypair.
     206             :      *
     207             :      * If a Keypair was successfully made temporarily active for the given `fabricIndex` with `ActivateOpKeypairForFabric`,
     208             :      * then that is the keypair whose private key is used. Otherwise, the last committed private key
     209             :      * is used, if one exists
     210             :      *
     211             :      * @param fabricIndex - FabricIndex whose operational keypair will be used to sign the `message`
     212             :      * @param message - Message to sign with the currently active operational keypair
     213             :      * @param outSignature - Buffer to contain the signature
     214             :      *
     215             :      * @retval CHIP_NO_ERROR on success
     216             :      * @retval CHIP_ERROR_INCORRECT_STATE if the key store is not properly initialized.
     217             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if no active key is found for the given `fabricIndex` or if
     218             :      *                                         `fabricIndex` is invalid.
     219             :      * @retval other CHIP_ERROR value on internal crypto engine errors
     220             :      */
     221             :     virtual CHIP_ERROR SignWithOpKeypair(FabricIndex fabricIndex, const ByteSpan & message,
     222             :                                          Crypto::P256ECDSASignature & outSignature) const = 0;
     223             : 
     224             :     /**
     225             :      * @brief Create an ephemeral keypair for use in session establishment.
     226             :      *
     227             :      * The caller must Initialize() the P256Keypair if needed. It is not done by this method.
     228             :      *
     229             :      * This method MUST ONLY be used for CASESession ephemeral keys.
     230             :      *
     231             :      * NOTE: The stack will allocate as many of these as there are CASE sessions which
     232             :      *       can be concurrently in the process of establishment. Implementations must
     233             :      *       support more than one such keypair, or be implemented to match the limitations
     234             :      *       enforced by a given product on its concurrent CASE session establishment limits.
     235             :      *
     236             :      * WARNING: The return value MUST be released by `ReleaseEphemeralKeypair`. This is because
     237             :      *          Matter CHIPMem.h does not properly support UniquePtr in a way that would
     238             :      *          safely allow classes derived from Crypto::P256Keypair to be released properly.
     239             :      *
     240             :      * @return a pointer to a P256Keypair (or derived class thereof), which may evaluate to nullptr
     241             :      *         if running out of memory.
     242             :      */
     243             :     virtual Crypto::P256Keypair * AllocateEphemeralKeypairForCASE() = 0;
     244             : 
     245             :     /**
     246             :      * @brief Release an ephemeral keypair previously provided by `AllocateEphemeralKeypairForCASE()`
     247             :      */
     248             :     virtual void ReleaseEphemeralKeypair(Crypto::P256Keypair * keypair) = 0;
     249             : };
     250             : 
     251             : } // namespace Crypto
     252             : } // namespace chip