Line data    Source code

       1              : /*
       2              :  *
       3              :  *    Copyright (c) 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              : #pragma once
      19              : 
      20              : #include <lib/core/CHIPError.h>
      21              : #include <lib/core/Optional.h>
      22              : #include <lib/support/ScopedBuffer.h>
      23              : #include <lib/support/Span.h>
      24              : 
      25              : #include <cstdint>
      26              : 
      27              : namespace chip {
      28              : 
      29              : /// File signature (aka magic number) of a valid Matter OTA image
      30              : inline constexpr uint32_t kOTAImageFileIdentifier = 0x1BEEF11E;
      31              : 
      32              : enum class OTAImageDigestType : uint8_t
      33              : {
      34              :     kSha256     = 1,
      35              :     kSha256_128 = 2,
      36              :     kSha256_120 = 3,
      37              :     kSha256_96  = 4,
      38              :     kSha256_64  = 5,
      39              :     kSha256_32  = 6,
      40              :     kSha384     = 7,
      41              :     kSha512     = 8,
      42              :     kSha3_224   = 9,
      43              :     kSha3_256   = 10,
      44              :     kSha3_384   = 11,
      45              :     kSha3_512   = 12,
      46              : };
      47              : 
      48              : struct OTAImageHeader
      49              : {
      50              :     uint16_t mVendorId;
      51              :     uint16_t mProductId;
      52              :     uint32_t mSoftwareVersion;
      53              :     CharSpan mSoftwareVersionString;
      54              :     uint64_t mPayloadSize;
      55              :     Optional<uint32_t> mMinApplicableVersion;
      56              :     Optional<uint32_t> mMaxApplicableVersion;
      57              :     CharSpan mReleaseNotesURL;
      58              :     OTAImageDigestType mImageDigestType;
      59              :     ByteSpan mImageDigest;
      60              : };
      61              : 
      62              : class OTAImageHeaderParser
      63              : {
      64              : public:
      65              :     /**
      66              :      * @brief Prepare the parser for accepting Matter OTA image chunks.
      67              :      *
      68              :      * The method can be called many times to reset the parser state.
      69              :      */
      70              :     void Init();
      71              : 
      72              :     /**
      73              :      * @brief Clear all resources associated with the parser.
      74              :      */
      75              :     void Clear();
      76              : 
      77              :     /**
      78              :      * @brief Returns if the parser is ready to accept subsequent Matter OTA image chunks.
      79              :      */
      80            8 :     bool IsInitialized() const { return mState != State::kNotInitialized; }
      81              : 
      82              :     /**
      83              :      * @brief Decode Matter OTA image header
      84              :      *
      85              :      * The method takes subsequent chunks of the Matter OTA image file and decodes the header when
      86              :      * enough data has been provided. If more image chunks are needed, CHIP_ERROR_BUFFER_TOO_SMALL
      87              :      * error is returned. Other error codes indicate that the header is invalid.
      88              :      *
      89              :      * @param buffer Byte span containing a subsequent Matter OTA image chunk. When the method
      90              :      *               returns CHIP_NO_ERROR, the byte span is used to return a remaining part
      91              :      *               of the chunk, not used by the header.
      92              :      * @param header Structure to store results of the operation. Note that the results must not be
      93              :      *               referenced after the parser is cleared since string members of the structure
      94              :      *               are only shallow-copied by the method.
      95              :      *
      96              :      * @retval CHIP_NO_ERROR                        Header has been decoded successfully.
      97              :      * @retval CHIP_ERROR_BUFFER_TOO_SMALL          Provided buffers are insufficient to decode the
      98              :      *                                              header. A user is expected call the method again
      99              :      *                                              when the next image chunk is available.
     100              :      * @retval CHIP_ERROR_INVALID_FILE_IDENTIFIER   Not a Matter OTA image file.
     101              :      * @retval Error code                           Encoded header is invalid.
     102              :      */
     103              :     CHIP_ERROR AccumulateAndDecode(ByteSpan & buffer, OTAImageHeader & header);
     104              : 
     105              : private:
     106              :     enum State
     107              :     {
     108              :         kNotInitialized,
     109              :         kInitialized,
     110              :         kTlv
     111              :     };
     112              : 
     113              :     void Append(ByteSpan & buffer, uint32_t numBytes);
     114              :     CHIP_ERROR DecodeFixed();
     115              :     CHIP_ERROR DecodeTlv(OTAImageHeader & header);
     116              : 
     117              :     State mState;
     118              :     uint32_t mHeaderTlvSize;
     119              :     uint32_t mBufferOffset;
     120              :     Platform::ScopedMemoryBuffer<uint8_t> mBuffer;
     121              : };
     122              : 
     123              : } // namespace chip