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 <lib/core/CHIPError.h>
      21             : #include <lib/core/DataModelTypes.h>
      22             : #include <lib/support/Span.h>
      23             : 
      24             : namespace chip {
      25             : namespace Credentials {
      26             : 
      27             : class OperationalCertificateStore
      28             : {
      29             : public:
      30             :     enum class CertChainElement : uint8_t
      31             :     {
      32             :         kRcac = 0,
      33             :         kIcac = 1,
      34             :         kNoc  = 2
      35             :     };
      36             : 
      37           1 :     virtual ~OperationalCertificateStore() {}
      38             : 
      39             :     // ==== API designed for commisionables to support fail-safe (although can be used by controllers) ====
      40             : 
      41             :     /**
      42             :      * @brief Returns true if a pending root certificate exists and is active from a previous
      43             :      *        `AddNewTrustedRootCertForFabric`.
      44             :      */
      45             :     virtual bool HasPendingRootCert() const = 0;
      46             : 
      47             :     /**
      48             :      * @brief Returns true if a pending operational certificate chain exists and is active from a previous
      49             :      *        `AddNewOpCertsForFabric` or `UpdateOpCertsForFabric`.
      50             :      */
      51             :     virtual bool HasPendingNocChain() const = 0;
      52             : 
      53             :     /**
      54             :      * @brief Returns whether a usable operational certificates chain exists for the given fabric.
      55             :      *
      56             :      * Returns true even if the certificates are not persisted yet. Only returns true if a certificate
      57             :      * is presently usable such that `GetCertificate` would succeed for the fabric.
      58             :      *
      59             :      * @param fabricIndex - FabricIndex for which availability of certificate will be checked.
      60             :      * @param element - Element of the certificate chain whose presence needs to be checked
      61             :      * @return true if there an active obtainable operational certificate of the given type for the given FabricIndex,
      62             :      *         false otherwise.
      63             :      */
      64             :     virtual bool HasCertificateForFabric(FabricIndex fabricIndex, CertChainElement element) const = 0;
      65             : 
      66             :     /**
      67             :      * @brief Add and temporarily activate a new Trusted Root Certificate for the given fabric
      68             :      *
      69             :      * The certificate is temporary until committed or reverted.
      70             :      * The certificate is committed to storage only on `CommitOpCertsForFabric`.
      71             :      * The certificate is destroyed if `RevertPendingOpCerts` is called before `CommitOpCertsForFabric`.
      72             :      *
      73             :      * Only one pending trusted root certificate is supported at a time and it is illegal
      74             :      * to call this method if there is already a persisted root certificate for the given
      75             :      * fabric.
      76             :      *
      77             :      * Uniqueness constraints for roots (see AddTrustedRootCertificate command in spec) are not
      78             :      * enforced by this method and must be done as a more holistic check elsewhere. Cryptographic
      79             :      * signature verification or path validation are not enforced by this method.
      80             :      *
      81             :      * If `UpdateOpCertsForFabric` had been called before this method, this method will return
      82             :      * CHIP_ERROR_INCORRECT_STATE since it is illegal to update trusted roots when updating an
      83             :      * existing NOC chain.
      84             :      *
      85             :      * @param fabricIndex - FabricIndex for which a new trusted root certificate should be added
      86             :      * @param rcac - Buffer containing the root certificate to add.
      87             :      *
      88             :      * @retval CHIP_NO_ERROR on success
      89             :      * @retval CHIP_ERROR_NO_MEMORY if there is insufficient memory to maintain the temporary root cert
      90             :      * @retval CHIP_ERROR_INVALID_ARGUMENT if the certificate is empty or too large
      91             :      * @retval CHIP_ERROR_INCORRECT_STATE if the certificate store is not properly initialized, if this method
      92             :      *                                    is called after `UpdateOpCertsForFabric`, or if there was
      93             :      *                                    already a pending or persisted root certificate for the given `fabricIndex`.
      94             :      * @retval other CHIP_ERROR value on internal errors
      95             :      */
      96             :     virtual CHIP_ERROR AddNewTrustedRootCertForFabric(FabricIndex fabricIndex, const ByteSpan & rcac) = 0;
      97             : 
      98             :     /**
      99             :      * @brief Add and temporarily activate an operational certificate chain for the given fabric.
     100             :      *
     101             :      * The certificate chain is temporary until committed or reverted.
     102             :      * The certificate chain is committed to storage on `CommitOpCertsForFabric`.
     103             :      * The certificate chain is destroyed if `RevertPendingOpCerts` is called before `CommitOpCertsForFabric`.
     104             :      *
     105             :      * Only one pending operational certificate chain is supported at a time and it is illegal
     106             :      * to call this method if there is already a persisted certificate chain for the given
     107             :      * fabric.
     108             :      *
     109             :      * Cryptographic signature verification or path validation are not enforced by this method.
     110             :      *
     111             :      * If `UpdateOpCertsForFabric` had been called before this method, this method will return
     112             :      * CHIP_ERROR_INCORRECT_STATE since it is illegal to add a certificate chain after
     113             :      * updating an existing NOC and before committing or reverting the update.
     114             :      *
     115             :      * If `AddNewTrustedRootCertForFabric` had not been called before this method, this method will
     116             :      * return CHIP_ERROR_INCORRECT_STATE since it is illegal in this implementation to store an
     117             :      * NOC chain without associated root.
     118             :      *
     119             :      * NOTE: The Matter spec allows AddNOC without AddTrustedRootCertificate if the NOC
     120             :      * chains to an existing root, to support root reuse. In this implementation, we expect each
     121             :      * fabric to store the root with the rest of the chain. Because of this, callers must ensure
     122             :      * that if an AddNOC command is done and no trusted root was added, that the requisite existing
     123             :      * root be "copied over" to match.
     124             :      *
     125             :      * @param fabricIndex - FabricIndex for which to add a new operational certificate chain
     126             :      * @param noc - Buffer containing the NOC certificate to add
     127             :      * @param icac - Buffer containing the ICAC certificate to add. If no ICAC is needed, `icac.empty()` must be true.
     128             :      *
     129             :      * @retval CHIP_NO_ERROR on success
     130             :      * @retval CHIP_ERROR_NO_MEMORY if there is insufficient memory to maintain the temporary `noc` and `icac` cert copies
     131             :      * @retval CHIP_ERROR_INVALID_ARGUMENT if either the noc or icac are invalid sizes
     132             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if `fabricIndex` mismatches the one from a previous successful
     133             :      *                                         `AddNewTrustedRootCertForFabric`.
     134             :      * @retval CHIP_ERROR_INCORRECT_STATE if the certificate store is not properly initialized, if this method
     135             :      *                                    is called after `UpdateOpCertsForFabric`, or if there was
     136             :      *                                    already a pending or persisted operational cert chain for the given `fabricIndex`,
     137             :      *                                    or if AddNewTrustedRootCertForFabric had not yet been called for the given `fabricIndex`.
     138             :      * @retval other CHIP_ERROR value on internal errors
     139             :      */
     140             :     virtual CHIP_ERROR AddNewOpCertsForFabric(FabricIndex fabricIndex, const ByteSpan & noc, const ByteSpan & icac) = 0;
     141             : 
     142             :     /**
     143             :      * @brief Update and temporarily activate an existing operational certificate chain for the given fabric.
     144             :      *
     145             :      * The certificate chain is temporary until committed or reverted.
     146             :      * The certificate chain is committed to storage on `CommitOpCertsForFabric`.
     147             :      * The certificate chain is reverted to prior storage if `RevertPendingOpCerts` is called
     148             :      * before `CommitOpCertsForFabric`.
     149             :      *
     150             :      * Only one pending operational certificate chain is supported at a time and it is illegal
     151             :      * to call this method if there was not already a persisted certificate chain for the given
     152             :      * fabric.
     153             :      *
     154             :      * Cryptographic signature verification or path validation are not enforced by this method.
     155             :      *
     156             :      * If `AddNewOpCertsForFabric` had been called before this method, this method will return
     157             :      * CHIP_ERROR_INCORRECT_STATE since it is illegal to update a certificate chain after
     158             :      * adding an existing NOC and before committing or reverting the addition.
     159             :      *
     160             :      * If there is no existing persisted trusted root certificate and NOC chain for the given
     161             :      * fabricIndex, this method will return CHIP_ERROR_INCORRECT_STATE since it is
     162             :      * illegal in this implementation to store an NOC chain without associated root, and it is illegal
     163             :      * to update an opcert for a fabric not already configured.
     164             :      *
     165             :      * @param fabricIndex - FabricIndex for which to update the operational certificate chain
     166             :      * @param noc - Buffer containing the new NOC certificate to use
     167             :      * @param icac - Buffer containing the ICAC certificate to use. If no ICAC is needed, `icac.empty()` must be true.
     168             :      *
     169             :      * @retval CHIP_NO_ERROR on success
     170             :      * @retval CHIP_ERROR_NO_MEMORY if there is insufficient memory to maintain the temporary `noc` and `icac` cert copies
     171             :      * @retval CHIP_ERROR_INVALID_ARGUMENT if either the noc or icac are invalid sizes
     172             :      * @retval CHIP_ERROR_INCORRECT_STATE if the certificate store is not properly initialized, if this method
     173             :      *                                    is called after `AddNewOpCertsForFabric`, or if there was
     174             :      *                                    already a pending cert chain for the given `fabricIndex`, or if there are
     175             :      *                                    no associated persisted root and NOC chain for for the given `fabricIndex`.
     176             :      * @retval other CHIP_ERROR value on internal errors
     177             :      */
     178             :     virtual CHIP_ERROR UpdateOpCertsForFabric(FabricIndex fabricIndex, const ByteSpan & noc, const ByteSpan & icac) = 0;
     179             : 
     180             :     /**
     181             :      * @brief Permanently commit the certificate chain last configured via successful calls to
     182             :      *        legal combinations of `AddNewTrustedRootCertForFabric`, `AddNewOpCertsForFabric` or
     183             :      *        `UpdateOpCertsForFabric`, replacing previously committed data, if any.
     184             :      *
     185             :      * This is to be used when CommissioningComplete is successfully received
     186             :      *
     187             :      * @param fabricIndex - FabricIndex for which to commit the certificate chain, used for security cross-checking
     188             :      *
     189             :      * @retval CHIP_NO_ERROR on success
     190             :      * @retval CHIP_ERROR_INCORRECT_STATE if the certificate store is not properly initialized,
     191             :      *                                    or if no valid pending state is available.
     192             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if there is no pending certificate chain for `fabricIndex`
     193             :      * @retval other CHIP_ERROR value on internal storage errors
     194             :      */
     195             :     virtual CHIP_ERROR CommitOpCertsForFabric(FabricIndex fabricIndex) = 0;
     196             : 
     197             :     /**
     198             :      * @brief Permanently remove the certificate chain associated with a fabric.
     199             :      *
     200             :      * This is to be used for RemoveFabric. Removes both the pending operational cert chain
     201             :      * elements for the fabricIndex (if any) and the committed ones (if any).
     202             :      *
     203             :      * @param fabricIndex - FabricIndex for which to remove the operational cert chain
     204             :      *
     205             :      * @retval CHIP_NO_ERROR on success
     206             :      * @retval CHIP_ERROR_INCORRECT_STATE if the certificate store is not properly initialized.
     207             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if there was no operational certificate data at all for `fabricIndex`
     208             :      * @retval other CHIP_ERROR value on internal storage errors
     209             :      */
     210             :     virtual CHIP_ERROR RemoveOpCertsForFabric(FabricIndex fabricIndex) = 0;
     211             : 
     212             :     /**
     213             :      * @brief Permanently release the operational certificate chain made via successful calls to
     214             :      *        legal combinations of `AddNewTrustedRootCertForFabric`, `AddNewOpCertsForFabric` or
     215             :      *        `UpdateOpCertsForFabric`, if any.
     216             :      *
     217             :      * This is to be used when a fail-safe expires prior to CommissioningComplete.
     218             :      *
     219             :      * This method cannot error-out and must always succeed, even on a no-op. This should
     220             :      * be safe to do given that `CommitOpCertsForFabric` must succeed to make an operation
     221             :      * certificate chain usable.
     222             :      */
     223             :     virtual void RevertPendingOpCerts() = 0;
     224             : 
     225             :     /**
     226             :      * @brief Same as RevertPendingOpCerts(), but leaves pending Trusted Root certs if they had
     227             :      *        been added. This is is an operation to support the complex error handling of
     228             :      *        AddNOC, where we don't want to have "sticking" ICAC/NOC after validation
     229             :      *        problems, but don't want to lose the RCAC given in an AddTrustedRootCertificate
     230             :      *        command.
     231             :      */
     232             :     virtual void RevertPendingOpCertsExceptRoot() = 0;
     233             : 
     234             :     /**
     235             :      * @brief Get the operational certificate element requested, giving the pending data or committed
     236             :      *        data depending on prior `AddNewTrustedRootCertForFabric`, `AddNewOpCertsForFabric` or
     237             :      *        `UpdateOpCertsForFabric` calls.
     238             :      *
     239             :      * On success, the `outCertificate` span is resized to the size of the actual certificate read-back.
     240             :      *
     241             :      * @param fabricIndex - fabricIndex for which to get the certificate
     242             :      * @param element - which element of the cerficate chain to get
     243             :      * @param outCertificate - buffer to contain the certificate obtained from persistent or temporary storage
     244             :      *
     245             :      * @retval CHIP_NO_ERROR on success.
     246             :      * @retval CHIP_ERROR_BUFFER_TOO_SMALL if `outCertificate` is too small to fit the certificate found.
     247             :      * @retval CHIP_ERROR_INCORRECT_STATE if the certificate store is not properly initialized.
     248             :      * @retval CHIP_ERROR_NOT_FOUND if the element cannot be found.
     249             :      * @retval CHIP_ERROR_INVALID_FABRIC_INDEX if the fabricIndex is invalid.
     250             :      * @retval other CHIP_ERROR value on internal storage errors.
     251             :      */
     252             :     virtual CHIP_ERROR GetCertificate(FabricIndex fabricIndex, CertChainElement element,
     253             :                                       MutableByteSpan & outCertificate) const = 0;
     254             : };
     255             : 
     256             : /**
     257             :  * @brief RAII class to operate on an OperationalCertificateStore with auto-revert if not committed.
     258             :  *
     259             :  * Use as:
     260             :  *
     261             :  * CHIP_ERROR FunctionWillReturnWithPendingReverted(....)
     262             :  * {
     263             :  *     OpCertStoreTransaction transaction(opCertStore);
     264             :  *
     265             :  *     ReturnErrorOnFailure(transaction->AddNewTrustedRootCertForFabric(...));
     266             :  *     ReturnErrorOnFailure(transaction->AddNewOpCertsForFabric(...));
     267             :  *     ReturnErrorOnFailure(transaction->CommitOpCertsForFabric(...));
     268             :  *
     269             :  *     return CHIP_NO_ERROR;
     270             :  * }
     271             :  */
     272             : class OpCertStoreTransaction
     273             : {
     274             : public:
     275             :     explicit OpCertStoreTransaction(OperationalCertificateStore & store) : mStore(store) {}
     276             :     ~OpCertStoreTransaction()
     277             :     {
     278             :         // This is a no-op if CommitOpCertsForFabric had been called on the store
     279             :         mStore.RevertPendingOpCerts();
     280             :     }
     281             : 
     282             :     // Non-copyable
     283             :     OpCertStoreTransaction(OpCertStoreTransaction const &) = delete;
     284             :     void operator=(OpCertStoreTransaction const &)         = delete;
     285             : 
     286             :     OperationalCertificateStore * operator->() { return &mStore; }
     287             : 
     288             : private:
     289             :     OperationalCertificateStore & mStore;
     290             : };
     291             : 
     292             : } // namespace Credentials
     293             : } // namespace chip