Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2021-2022 Project CHIP Authors
       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             : /**
      19             :  * @brief Defines a table of fabrics that have provisioned the device.
      20             :  */
      21             : 
      22             : #pragma once
      23             : 
      24             : #include <lib/core/CHIPPersistentStorageDelegate.h>
      25             : #include <lib/core/Optional.h>
      26             : #include <lib/core/TLV.h>
      27             : #include <system/SystemClock.h>
      28             : 
      29             : namespace chip {
      30             : 
      31             : class LastKnownGoodTime
      32             : {
      33             : public:
      34           0 :     LastKnownGoodTime() {}
      35             : 
      36             :     /**
      37             :      * Initialize Last Known Good Time to the later of firmware build time or
      38             :      * last known good time persisted in storage.  Persist the selected value
      39             :      * if this differs from the value in storage or no value is yet persisted.
      40             :      *
      41             :      * @param storage storage delegate to persist Last Known Good Time
      42             :      * @return CHIP_NO_ERROR on success, else an appropriate CHIP_ERROR
      43             :      */
      44             :     CHIP_ERROR Init(PersistentStorageDelegate * storage);
      45             : 
      46             :     /**
      47             :      * Get the current Last Known Good Time.
      48             :      *
      49             :      * @param lastKnownGoodChipEpochTime (out) the current last known good time, if any is known
      50             :      * &return CHIP_NO_ERROR on success, else an appropriate CHIP_ERROR
      51             :      */
      52           0 :     CHIP_ERROR GetLastKnownGoodChipEpochTime(System::Clock::Seconds32 & lastKnownGoodChipEpochTime) const
      53             :     {
      54           0 :         VerifyOrReturnError(mLastKnownGoodChipEpochTime.HasValue(), CHIP_ERROR_INCORRECT_STATE);
      55           0 :         lastKnownGoodChipEpochTime = mLastKnownGoodChipEpochTime.Value();
      56           0 :         return CHIP_NO_ERROR;
      57             :     }
      58             : 
      59             :     /**
      60             :      * Validate that the passed Last Known Good Time is within bounds and then
      61             :      * store this and write back to storage.  Legal values are those which are
      62             :      * not earlier than firmware build time or any of our stored certificates'
      63             :      * NotBefore times:
      64             :      *
      65             :      *    3.5.6.1. Last Known Good UTC Time
      66             :      *
      67             :      *    A Node MAY adjust the Last Known Good UTC Time backwards if it
      68             :      *    believes the current Last Known Good UTC Time is incorrect and it has
      69             :      *    a good time value from a trusted source. The Node SHOULD NOT adjust
      70             :      *    the Last Known Good UTC to a time before the later of:
      71             :      *      • The build timestamp of its currently running software image
      72             :      *      • The not-before timestamp of any of its operational certificates
      73             :      *
      74             :      * @param lastKnownGoodChipEpochTime Last Known Good Time in seconds since CHIP epoch
      75             :      * @param notBefore the latest NotBefore time of all installed certificates
      76             :      * @return CHIP_NO_ERROR on success, else an appopriate CHIP_ERROR
      77             :      */
      78             :     CHIP_ERROR SetLastKnownGoodChipEpochTime(System::Clock::Seconds32 lastKnownGoodChipEpochTime,
      79             :                                              System::Clock::Seconds32 notBefore);
      80             : 
      81             :     /**
      82             :      * Update the Last Known Good Time to the later of the current value and
      83             :      * the passed value and store in RAM.  This does not persist the value.
      84             :      * Persist only happens if CommitPendingLastKnownGoodChipEpochTime is
      85             :      * called.
      86             :      *
      87             :      * @param lastKnownGoodChipEpochTime Last Known Good Time in seconds since CHIP epoch
      88             :      * @return CHIP_NO_ERROR on success, else an appopriate CHIP_ERROR
      89             :      */
      90             :     CHIP_ERROR UpdatePendingLastKnownGoodChipEpochTime(System::Clock::Seconds32 lastKnownGoodChipEpochTime);
      91             : 
      92             :     /*
      93             :      * Commit the pending Last Known Good Time in RAM to storage.
      94             :      *
      95             :      * @return CHIP_NO_ERROR on success, else an appopriate CHIP_ERROR
      96             :      */
      97             :     CHIP_ERROR CommitPendingLastKnownGoodChipEpochTime();
      98             : 
      99             :     /*
     100             :      * Revert the Last Known Good Time to the fail-safe backup value in
     101             :      * persistence if any exists.
     102             :      *
     103             :      * @return CHIP_NO_ERROR on success, else an appopriate CHIP_ERROR
     104             :      */
     105             :     CHIP_ERROR RevertPendingLastKnownGoodChipEpochTime();
     106             : 
     107             : private:
     108             :     static constexpr size_t LastKnownGoodTimeTLVMaxSize()
     109             :     {
     110             :         // We have Last Known Good Time and, optionally, a previous Last known
     111             :         // good time for fail safe cleanup.
     112             :         return TLV::EstimateStructOverhead(sizeof(uint32_t), sizeof(uint32_t));
     113             :     }
     114             : 
     115             :     /**
     116             :      * Log the message, appending the passed CHIP epoch time in ISO8601 format.
     117             :      *
     118             :      * @param msg message to log with ISO8601 time appended
     119             :      * @param chipEpochTime time in seconds from the CHIP epoch
     120             :      */
     121             :     void LogTime(const char * msg, System::Clock::Seconds32 chipEpochTime);
     122             : 
     123             :     /**
     124             :      * Load the Last Known Good Time from storage.
     125             :      *
     126             :      * @param lastKnownGoodChipEpochTime (out) Last Known Good Time as seconds from CHIP epoch
     127             :      * @return CHIP_NO_ERROR on success, else an appropriate CHIP_ERROR
     128             :      */
     129             :     CHIP_ERROR LoadLastKnownGoodChipEpochTime(System::Clock::Seconds32 & lastKnownGoodChipEpochTime) const;
     130             : 
     131             :     /**
     132             :      * Store the Last Known Good Time to storage.
     133             :      *
     134             :      * @param lastKnownGoodChipEpochTime Last Known Good Time as seconds from CHIP epoch
     135             :      * @return CHIP_NO_ERROR on success, else an appropriate CHIP_ERROR
     136             :      */
     137             :     CHIP_ERROR StoreLastKnownGoodChipEpochTime(System::Clock::Seconds32 lastKnownGoodChipEpochTime) const;
     138             : 
     139             :     PersistentStorageDelegate * mStorage = nullptr;
     140             :     Optional<System::Clock::Seconds32> mLastKnownGoodChipEpochTime;
     141             : };
     142             : 
     143             : } // namespace chip