Matter SDK Coverage Report
Current view: top level - crypto - CHIPCryptoPAL.h (source / functions) Coverage Total Hit
Test: SHA:41c719200fc7796f8cebc1c631a46003859b1b19 Lines: 87.8 % 90 79
Test Date: 2025-06-27 07:08:42 Functions: 85.7 % 98 84

            Line data    Source code
       1              : /*
       2              :  *
       3              :  *    Copyright (c) 2020-2023 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              :  *    @file
      20              :  *      Header that exposes the platform agnostic CHIP crypto primitives
      21              :  */
      22              : 
      23              : #pragma once
      24              : 
      25              : #if CHIP_HAVE_CONFIG_H
      26              : #include <crypto/CryptoBuildConfig.h>
      27              : #endif // CHIP_HAVE_CONFIG_H
      28              : 
      29              : #include <system/SystemConfig.h>
      30              : 
      31              : #include <lib/core/CHIPError.h>
      32              : #include <lib/core/CHIPVendorIdentifiers.hpp>
      33              : #include <lib/core/DataModelTypes.h>
      34              : #include <lib/core/Optional.h>
      35              : #include <lib/support/Base64.h>
      36              : #include <lib/support/BufferReader.h>
      37              : #include <lib/support/CodeUtils.h>
      38              : #include <lib/support/SafePointerCast.h>
      39              : #include <lib/support/Span.h>
      40              : #include <lib/support/StringBuilder.h>
      41              : 
      42              : #include <stddef.h>
      43              : #include <string.h>
      44              : 
      45              : namespace chip {
      46              : namespace Crypto {
      47              : 
      48              : inline constexpr size_t kMax_x509_Certificate_Length = 600;
      49              : 
      50              : inline constexpr size_t kP256_FE_Length                        = 32;
      51              : inline constexpr size_t kP256_ECDSA_Signature_Length_Raw       = (2 * kP256_FE_Length);
      52              : inline constexpr size_t kP256_Point_Length                     = (2 * kP256_FE_Length + 1);
      53              : inline constexpr size_t kSHA256_Hash_Length                    = 32;
      54              : inline constexpr size_t kSHA1_Hash_Length                      = 20;
      55              : inline constexpr size_t kSubjectKeyIdentifierLength            = kSHA1_Hash_Length;
      56              : inline constexpr size_t kAuthorityKeyIdentifierLength          = kSHA1_Hash_Length;
      57              : inline constexpr size_t kMaxCertificateSerialNumberLength      = 20;
      58              : inline constexpr size_t kMaxCertificateDistinguishedNameLength = 200;
      59              : inline constexpr size_t kMaxCRLDistributionPointURLLength      = 100;
      60              : 
      61              : inline constexpr char kValidCDPURIHttpPrefix[]  = "http://";
      62              : inline constexpr char kValidCDPURIHttpsPrefix[] = "https://";
      63              : 
      64              : inline constexpr size_t CHIP_CRYPTO_GROUP_SIZE_BYTES      = kP256_FE_Length;
      65              : inline constexpr size_t CHIP_CRYPTO_PUBLIC_KEY_SIZE_BYTES = kP256_Point_Length;
      66              : 
      67              : inline constexpr size_t CHIP_CRYPTO_AEAD_MIC_LENGTH_BYTES      = 16;
      68              : inline constexpr size_t CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES = 16;
      69              : 
      70              : inline constexpr size_t kMax_ECDH_Secret_Length     = kP256_FE_Length;
      71              : inline constexpr size_t kMax_ECDSA_Signature_Length = kP256_ECDSA_Signature_Length_Raw;
      72              : inline constexpr size_t kMAX_FE_Length              = kP256_FE_Length;
      73              : inline constexpr size_t kMAX_Point_Length           = kP256_Point_Length;
      74              : inline constexpr size_t kMAX_Hash_Length            = kSHA256_Hash_Length;
      75              : 
      76              : // Minimum required CSR length buffer length is relatively small since it's a single
      77              : // P256 key and no metadata/extensions are expected to be honored by the CA.
      78              : inline constexpr size_t kMIN_CSR_Buffer_Size = 255;
      79              : 
      80              : [[deprecated("This constant is no longer used by common code and should be replaced by kMIN_CSR_Buffer_Size. Checks that a CSR is "
      81              :              "<= kMAX_CSR_Buffer_size must be updated. This remains to keep valid buffers working from previous public API "
      82              :              "usage.")]] constexpr size_t kMAX_CSR_Buffer_Size = 255;
      83              : 
      84              : inline constexpr size_t CHIP_CRYPTO_HASH_LEN_BYTES = kSHA256_Hash_Length;
      85              : 
      86              : inline constexpr size_t kSpake2p_Min_PBKDF_Salt_Length  = 16;
      87              : inline constexpr size_t kSpake2p_Max_PBKDF_Salt_Length  = 32;
      88              : inline constexpr uint32_t kSpake2p_Min_PBKDF_Iterations = 1000;
      89              : inline constexpr uint32_t kSpake2p_Max_PBKDF_Iterations = 100000;
      90              : 
      91              : inline constexpr size_t kP256_PrivateKey_Length = CHIP_CRYPTO_GROUP_SIZE_BYTES;
      92              : inline constexpr size_t kP256_PublicKey_Length  = CHIP_CRYPTO_PUBLIC_KEY_SIZE_BYTES;
      93              : 
      94              : inline constexpr size_t kAES_CCM128_Key_Length   = 128u / 8u;
      95              : inline constexpr size_t kAES_CCM128_Block_Length = kAES_CCM128_Key_Length;
      96              : inline constexpr size_t kAES_CCM128_Nonce_Length = 13;
      97              : inline constexpr size_t kAES_CCM128_Tag_Length   = 16;
      98              : inline constexpr size_t kHMAC_CCM128_Key_Length  = 128u / 8u;
      99              : 
     100              : inline constexpr size_t CHIP_CRYPTO_AEAD_NONCE_LENGTH_BYTES = kAES_CCM128_Nonce_Length;
     101              : 
     102              : /* These sizes are hardcoded here to remove header dependency on underlying crypto library
     103              :  * in a public interface file. The validity of these sizes is verified by static_assert in
     104              :  * the implementation files.
     105              :  */
     106              : inline constexpr size_t kMAX_Spake2p_Context_Size     = 1024;
     107              : inline constexpr size_t kMAX_P256Keypair_Context_Size = 512;
     108              : 
     109              : inline constexpr size_t kEmitDerIntegerWithoutTagOverhead = 1; // 1 sign stuffer
     110              : inline constexpr size_t kEmitDerIntegerOverhead           = 3; // Tag + Length byte + 1 sign stuffer
     111              : 
     112              : inline constexpr size_t kMAX_Hash_SHA256_Context_Size = CHIP_CONFIG_SHA256_CONTEXT_SIZE;
     113              : 
     114              : inline constexpr size_t kSpake2p_WS_Length                 = kP256_FE_Length + 8;
     115              : inline constexpr size_t kSpake2p_VerifierSerialized_Length = kP256_FE_Length + kP256_Point_Length;
     116              : 
     117              : inline constexpr char kVIDPrefixForCNEncoding[]    = "Mvid:";
     118              : inline constexpr char kPIDPrefixForCNEncoding[]    = "Mpid:";
     119              : inline constexpr size_t kVIDandPIDHexLength        = sizeof(uint16_t) * 2;
     120              : inline constexpr size_t kMax_CommonNameAttr_Length = 64;
     121              : 
     122              : enum class FabricBindingVersion : uint8_t
     123              : {
     124              :     kVersion1 = 0x01 // Initial version using version 1.0 of the Matter Cryptographic Primitives.
     125              : };
     126              : 
     127              : // VidVerificationStatementVersion is on purpose different and non-overlapping with FabricBindingVersion.
     128              : enum class VidVerificationStatementVersion : uint8_t
     129              : {
     130              :     kVersion1 = 0x21 // Initial version using version 1.0 of the Matter Cryptographic Primitives.
     131              : };
     132              : 
     133              : inline constexpr uint8_t kFabricBindingVersionV1 = 1u;
     134              : 
     135              : inline constexpr size_t kVendorIdVerificationClientChallengeSize = 32u;
     136              : 
     137              : // VIDVerificationStatement := statement_version || vid_verification_signer_skid || vid_verification_statement_signature
     138              : inline constexpr size_t kVendorIdVerificationStatementV1Size =
     139              :     sizeof(uint8_t) + kSubjectKeyIdentifierLength + kP256_ECDSA_Signature_Length_Raw;
     140              : static_assert(
     141              :     kVendorIdVerificationStatementV1Size == 85,
     142              :     "Expected size of VendorIdVerificationStatement version 1 was computed incorrectly due to changes of fundamental constants");
     143              : 
     144              : // vendor_fabric_binding_message := fabric_binding_version (1 byte) || root_public_key || fabric_id || vendor_id
     145              : inline constexpr size_t kVendorFabricBindingMessageV1Size =
     146              :     sizeof(uint8_t) + CHIP_CRYPTO_PUBLIC_KEY_SIZE_BYTES + sizeof(uint64_t) + sizeof(uint16_t);
     147              : static_assert(
     148              :     kVendorFabricBindingMessageV1Size == 76,
     149              :     "Expected size of VendorFabricBindingMessage version 1 was computed incorrectly due to changes of fundamental constants");
     150              : 
     151              : // vendor_id_verification_tbs := fabric_binding_version || client_challenge || attestation_challenge || fabric_index ||
     152              : // vendor_fabric_binding_message || <vid_verification_statement>
     153              : inline constexpr size_t kVendorIdVerificationTbsV1MaxSize = sizeof(uint8_t) + kVendorIdVerificationClientChallengeSize +
     154              :     CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES + sizeof(uint8_t) + kVendorFabricBindingMessageV1Size +
     155              :     kVendorIdVerificationStatementV1Size;
     156              : 
     157              : /*
     158              :  * Overhead to encode a raw ECDSA signature in X9.62 format in ASN.1 DER
     159              :  *
     160              :  * Ecdsa-Sig-Value ::= SEQUENCE {
     161              :  *     r       INTEGER,
     162              :  *     s       INTEGER
     163              :  * }
     164              :  *
     165              :  * --> SEQUENCE, universal constructed tag (0x30), length over 2 bytes, up to 255 (to support future larger sizes up to 512 bits)
     166              :  *   -> SEQ_OVERHEAD = 3 bytes
     167              :  * --> INTEGER, universal primitive tag (0x02), length over 1 byte, one extra byte worst case
     168              :  *     over max for 0x00 when MSB is set.
     169              :  *       -> INT_OVERHEAD = 3 bytes
     170              :  *
     171              :  * There is 1 sequence of 2 integers. Overhead is SEQ_OVERHEAD + (2 * INT_OVERHEAD) = 3 + (2 * 3) = 9.
     172              :  */
     173              : inline constexpr size_t kMax_ECDSA_X9Dot62_Asn1_Overhead = 9;
     174              : inline constexpr size_t kMax_ECDSA_Signature_Length_Der  = kMax_ECDSA_Signature_Length + kMax_ECDSA_X9Dot62_Asn1_Overhead;
     175              : 
     176              : static_assert(kMax_ECDH_Secret_Length >= kP256_FE_Length, "ECDH shared secret is too short for crypto suite");
     177              : static_assert(kMax_ECDSA_Signature_Length >= kP256_ECDSA_Signature_Length_Raw,
     178              :               "ECDSA signature buffer length is too short for crypto suite");
     179              : 
     180              : inline constexpr size_t kCompressedFabricIdentifierSize = 8;
     181              : 
     182              : /**
     183              :  * Spake2+ parameters for P256
     184              :  * Defined in https://www.ietf.org/id/draft-bar-cfrg-spake2plus-01.html#name-ciphersuites
     185              :  */
     186              : const uint8_t spake2p_M_p256[] = {
     187              :     0x04, 0x88, 0x6e, 0x2f, 0x97, 0xac, 0xe4, 0x6e, 0x55, 0xba, 0x9d, 0xd7, 0x24, 0x25, 0x79, 0xf2, 0x99,
     188              :     0x3b, 0x64, 0xe1, 0x6e, 0xf3, 0xdc, 0xab, 0x95, 0xaf, 0xd4, 0x97, 0x33, 0x3d, 0x8f, 0xa1, 0x2f, 0x5f,
     189              :     0xf3, 0x55, 0x16, 0x3e, 0x43, 0xce, 0x22, 0x4e, 0x0b, 0x0e, 0x65, 0xff, 0x02, 0xac, 0x8e, 0x5c, 0x7b,
     190              :     0xe0, 0x94, 0x19, 0xc7, 0x85, 0xe0, 0xca, 0x54, 0x7d, 0x55, 0xa1, 0x2e, 0x2d, 0x20,
     191              : };
     192              : const uint8_t spake2p_N_p256[] = {
     193              :     0x04, 0xd8, 0xbb, 0xd6, 0xc6, 0x39, 0xc6, 0x29, 0x37, 0xb0, 0x4d, 0x99, 0x7f, 0x38, 0xc3, 0x77, 0x07,
     194              :     0x19, 0xc6, 0x29, 0xd7, 0x01, 0x4d, 0x49, 0xa2, 0x4b, 0x4f, 0x98, 0xba, 0xa1, 0x29, 0x2b, 0x49, 0x07,
     195              :     0xd6, 0x0a, 0xa6, 0xbf, 0xad, 0xe4, 0x50, 0x08, 0xa6, 0x36, 0x33, 0x7f, 0x51, 0x68, 0xc6, 0x4d, 0x9b,
     196              :     0xd3, 0x60, 0x34, 0x80, 0x8c, 0xd5, 0x64, 0x49, 0x0b, 0x1e, 0x65, 0x6e, 0xdb, 0xe7,
     197              : };
     198              : 
     199              : /**
     200              :  * Spake2+ state machine to ensure proper execution of the protocol.
     201              :  */
     202              : enum class CHIP_SPAKE2P_STATE : uint8_t
     203              : {
     204              :     PREINIT = 0, // Before any initialization
     205              :     INIT,        // First initialization
     206              :     STARTED,     // Prover & Verifier starts
     207              :     R1,          // Round one complete
     208              :     R2,          // Round two complete
     209              :     KC,          // Key confirmation complete
     210              : };
     211              : 
     212              : /**
     213              :  * Spake2+ role.
     214              :  */
     215              : enum class CHIP_SPAKE2P_ROLE : uint8_t
     216              : {
     217              :     VERIFIER = 0, // Accessory
     218              :     PROVER   = 1, // Commissioner
     219              : };
     220              : 
     221              : enum class SupportedECPKeyTypes : uint8_t
     222              : {
     223              :     ECP256R1 = 0,
     224              : };
     225              : 
     226              : enum class ECPKeyTarget : uint8_t
     227              : {
     228              :     ECDH  = 0,
     229              :     ECDSA = 1,
     230              : };
     231              : 
     232              : /** @brief Safely clears the first `len` bytes of memory area `buf`.
     233              :  * @param buf Pointer to a memory buffer holding secret data that must be cleared.
     234              :  * @param len Specifies secret data size in bytes.
     235              :  **/
     236              : void ClearSecretData(uint8_t * buf, size_t len);
     237              : 
     238              : /**
     239              :  * Helper for clearing a C array which auto-deduces the size.
     240              :  */
     241              : template <size_t N>
     242       413666 : void ClearSecretData(uint8_t (&buf)[N])
     243              : {
     244       413666 :     ClearSecretData(buf, N);
     245       413666 : }
     246              : 
     247              : /**
     248              :  * @brief Constant-time buffer comparison
     249              :  *
     250              :  * This function implements constant time memcmp. It's good practice
     251              :  * to use constant time functions for cryptographic functions.
     252              :  *
     253              :  * @param a Pointer to first buffer
     254              :  * @param b Pointer to Second buffer
     255              :  * @param n Number of bytes to compare
     256              :  * @return true if `n` first bytes of both buffers are equal, false otherwise
     257              :  */
     258              : bool IsBufferContentEqualConstantTime(const void * a, const void * b, size_t n);
     259              : 
     260              : template <typename Sig>
     261              : class ECPKey
     262              : {
     263              : protected:
     264              :     // This base type can't be copied / assigned directly.
     265              :     // Sub-types should be either uncopyable or final.
     266           90 :     ECPKey()                           = default;
     267              :     ECPKey(const ECPKey &)             = default;
     268         1628 :     ECPKey & operator=(const ECPKey &) = default;
     269              : 
     270              : public:
     271          910 :     virtual ~ECPKey() = default;
     272              : 
     273              :     virtual SupportedECPKeyTypes Type() const  = 0;
     274              :     virtual size_t Length() const              = 0;
     275              :     virtual bool IsUncompressed() const        = 0;
     276              :     virtual operator const uint8_t *() const   = 0;
     277              :     virtual operator uint8_t *()               = 0;
     278              :     virtual const uint8_t * ConstBytes() const = 0;
     279              :     virtual uint8_t * Bytes()                  = 0;
     280              : 
     281            0 :     virtual bool Matches(const ECPKey<Sig> & other) const
     282              :     {
     283            0 :         return (this->Length() == other.Length()) &&
     284            0 :             IsBufferContentEqualConstantTime(this->ConstBytes(), other.ConstBytes(), this->Length());
     285              :     }
     286              : 
     287              :     virtual CHIP_ERROR ECDSA_validate_msg_signature(const uint8_t * msg, const size_t msg_length, const Sig & signature) const = 0;
     288              :     virtual CHIP_ERROR ECDSA_validate_hash_signature(const uint8_t * hash, const size_t hash_length,
     289              :                                                      const Sig & signature) const                                              = 0;
     290              : };
     291              : 
     292              : /**
     293              :  * @brief Helper class for holding sensitive data that should be erased from memory after use.
     294              :  *
     295              :  * The sensitive data buffer is a variable-length, fixed-capacity buffer class that securely erases
     296              :  * the contents of a buffer when the buffer is destroyed.
     297              :  */
     298              : template <size_t kCapacity>
     299              : class SensitiveDataBuffer
     300              : {
     301              : public:
     302         3693 :     ~SensitiveDataBuffer()
     303              :     {
     304              :         // Sanitize after use
     305         3693 :         ClearSecretData(mBytes);
     306         3693 :     }
     307         3692 :     SensitiveDataBuffer() {}
     308            1 :     SensitiveDataBuffer(const SensitiveDataBuffer & other) { *this = other; }
     309            1 :     SensitiveDataBuffer & operator=(const SensitiveDataBuffer & other)
     310              :     {
     311              :         // Guard self assignment
     312            1 :         if (this == &other)
     313            0 :             return *this;
     314              : 
     315            1 :         ClearSecretData(mBytes);
     316            1 :         SetLength(other.Length());
     317            1 :         ::memcpy(Bytes(), other.ConstBytes(), other.Length());
     318            1 :         return *this;
     319              :     }
     320              : 
     321              :     /**
     322              :      * @brief Set current length of the buffer
     323              :      * @return Error if new length is exceeds capacity of the buffer
     324              :      */
     325         3565 :     CHIP_ERROR SetLength(size_t length)
     326              :     {
     327         3565 :         VerifyOrReturnError(length <= kCapacity, CHIP_ERROR_INVALID_ARGUMENT);
     328         3565 :         mLength = length;
     329         3565 :         return CHIP_NO_ERROR;
     330              :     }
     331              : 
     332              :     /**
     333              :      * @brief Returns current length of the buffer
     334              :      */
     335         3769 :     size_t Length() const { return mLength; }
     336              : 
     337              :     /**
     338              :      * @brief Returns non-const pointer to start of the underlying buffer
     339              :      */
     340         3956 :     uint8_t * Bytes() { return &mBytes[0]; }
     341              : 
     342              :     /**
     343              :      * @brief Returns const pointer to start of the underlying buffer
     344              :      */
     345         6302 :     const uint8_t * ConstBytes() const { return &mBytes[0]; }
     346              : 
     347              :     /**
     348              :      * @brief Constructs span from the underlying buffer
     349              :      */
     350           21 :     ByteSpan Span() const { return ByteSpan(ConstBytes(), Length()); }
     351              : 
     352              :     /**
     353              :      * @brief Returns capacity of the buffer
     354              :      */
     355         1489 :     static constexpr size_t Capacity() { return kCapacity; }
     356              : 
     357              : private:
     358              :     uint8_t mBytes[kCapacity];
     359              :     size_t mLength = 0;
     360              : };
     361              : 
     362              : /**
     363              :  * @brief Helper class for holding fixed-sized sensitive data that should be erased from memory after use.
     364              :  *
     365              :  * The sensitive data buffer is a fixed-length, fixed-capacity buffer class that securely erases
     366              :  * the contents of a buffer when the buffer is destroyed.
     367              :  */
     368              : template <size_t kCapacity>
     369              : class SensitiveDataFixedBuffer
     370              : {
     371              : public:
     372              :     SensitiveDataFixedBuffer() = default;
     373              : 
     374              :     constexpr explicit SensitiveDataFixedBuffer(const uint8_t (&rawValue)[kCapacity])
     375              :     {
     376              :         memcpy(&mBytes[0], &rawValue[0], kCapacity);
     377              :     }
     378              : 
     379            0 :     constexpr explicit SensitiveDataFixedBuffer(const FixedByteSpan<kCapacity> & value)
     380              :     {
     381            0 :         memcpy(&mBytes[0], value.data(), kCapacity);
     382            0 :     }
     383              : 
     384       135355 :     ~SensitiveDataFixedBuffer()
     385              :     {
     386              :         // Sanitize after use
     387       135355 :         ClearSecretData(mBytes);
     388       135355 :     }
     389              : 
     390              :     /**
     391              :      * @brief Returns fixed length of the buffer
     392              :      */
     393              :     constexpr size_t Length() const { return kCapacity; }
     394              : 
     395              :     /**
     396              :      * @brief Returns non-const pointer to start of the underlying buffer
     397              :      */
     398         1573 :     uint8_t * Bytes() { return &mBytes[0]; }
     399              : 
     400              :     /**
     401              :      * @brief Returns const pointer to start of the underlying buffer
     402              :      */
     403              :     const uint8_t * ConstBytes() const { return &mBytes[0]; }
     404              : 
     405              :     /**
     406              :      * @brief Constructs fixed span from the underlying buffer
     407              :      */
     408            0 :     FixedByteSpan<kCapacity> Span() const { return FixedByteSpan<kCapacity>(mBytes); }
     409              : 
     410              :     /**
     411              :      * @brief Returns capacity of the buffer
     412              :      */
     413         1558 :     static constexpr size_t Capacity() { return kCapacity; }
     414              : 
     415              : private:
     416              :     uint8_t mBytes[kCapacity];
     417              : };
     418              : 
     419              : using P256ECDSASignature    = SensitiveDataBuffer<kMax_ECDSA_Signature_Length>;
     420              : using P256ECDHDerivedSecret = SensitiveDataBuffer<kMax_ECDH_Secret_Length>;
     421              : 
     422              : using IdentityProtectionKey     = SensitiveDataFixedBuffer<CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES>;
     423              : using IdentityProtectionKeySpan = FixedByteSpan<Crypto::CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES>;
     424              : 
     425              : using AttestationChallenge = SensitiveDataFixedBuffer<CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES>;
     426              : 
     427              : class P256PublicKey final // final due to being copyable
     428              :     : public ECPKey<P256ECDSASignature>
     429              : {
     430              : public:
     431           90 :     P256PublicKey() = default;
     432              : 
     433              :     template <size_t N>
     434              :     constexpr P256PublicKey(const uint8_t (&raw_value)[N])
     435              :     {
     436              :         static_assert(N == kP256_PublicKey_Length, "Can only array-initialize from proper bounds");
     437              :         memcpy(&bytes[0], &raw_value[0], N);
     438              :     }
     439              : 
     440              :     template <size_t N>
     441          744 :     constexpr P256PublicKey(const FixedByteSpan<N> & value)
     442          744 :     {
     443              :         static_assert(N == kP256_PublicKey_Length, "Can only initialize from proper sized byte span");
     444          744 :         memcpy(&bytes[0], value.data(), N);
     445          744 :     }
     446              : 
     447              :     template <size_t N>
     448          946 :     P256PublicKey & operator=(const FixedByteSpan<N> & value)
     449              :     {
     450              :         static_assert(N == kP256_PublicKey_Length, "Can only initialize from proper sized byte span");
     451          946 :         memcpy(&bytes[0], value.data(), N);
     452          946 :         return *this;
     453              :     }
     454              : 
     455         4267 :     SupportedECPKeyTypes Type() const override { return SupportedECPKeyTypes::ECP256R1; }
     456        14552 :     size_t Length() const override { return kP256_PublicKey_Length; }
     457         6354 :     operator uint8_t *() override { return bytes; }
     458         2674 :     operator const uint8_t *() const override { return bytes; }
     459         3210 :     const uint8_t * ConstBytes() const override { return &bytes[0]; }
     460           20 :     uint8_t * Bytes() override { return &bytes[0]; }
     461          814 :     bool IsUncompressed() const override
     462              :     {
     463          814 :         constexpr uint8_t kUncompressedPointMarker = 0x04;
     464              :         // SEC1 definition of an uncompressed point is (0x04 || X || Y) where X and Y are
     465              :         // raw zero-padded big-endian large integers of the group size.
     466          814 :         return (Length() == ((kP256_FE_Length * 2) + 1)) && (ConstBytes()[0] == kUncompressedPointMarker);
     467              :     }
     468              : 
     469              :     CHIP_ERROR ECDSA_validate_msg_signature(const uint8_t * msg, size_t msg_length,
     470              :                                             const P256ECDSASignature & signature) const override;
     471              :     CHIP_ERROR ECDSA_validate_hash_signature(const uint8_t * hash, size_t hash_length,
     472              :                                              const P256ECDSASignature & signature) const override;
     473              : 
     474              : private:
     475              :     uint8_t bytes[kP256_PublicKey_Length];
     476              : };
     477              : 
     478              : template <typename PK, typename Secret, typename Sig>
     479              : class ECPKeypair
     480              : {
     481              : protected:
     482              :     // This base type can't be copied / assigned directly.
     483              :     // Sub-types should be either uncopyable or final.
     484         1429 :     ECPKeypair()                               = default;
     485              :     ECPKeypair(const ECPKeypair &)             = default;
     486              :     ECPKeypair & operator=(const ECPKeypair &) = default;
     487              : 
     488              : public:
     489         1770 :     virtual ~ECPKeypair() = default;
     490              : 
     491              :     /** @brief Generate a new Certificate Signing Request (CSR).
     492              :      * @param csr Newly generated CSR in DER format
     493              :      * @param csr_length The caller provides the length of input buffer (csr). The function returns the actual length of generated
     494              :      *CSR.
     495              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     496              :      **/
     497              :     virtual CHIP_ERROR NewCertificateSigningRequest(uint8_t * csr, size_t & csr_length) const = 0;
     498              : 
     499              :     /**
     500              :      * @brief A function to sign a msg using ECDSA
     501              :      * @param msg Message that needs to be signed
     502              :      * @param msg_length Length of message
     503              :      * @param out_signature Buffer that will hold the output signature. The signature consists of: 2 EC elements (r and s),
     504              :      * in raw <r,s> point form (see SEC1).
     505              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     506              :      **/
     507              :     virtual CHIP_ERROR ECDSA_sign_msg(const uint8_t * msg, size_t msg_length, Sig & out_signature) const = 0;
     508              : 
     509              :     /** @brief A function to derive a shared secret using ECDH
     510              :      * @param remote_public_key Public key of remote peer with which we are trying to establish secure channel. remote_public_key is
     511              :      * ASN.1 DER encoded as padded big-endian field elements as described in SEC 1: Elliptic Curve Cryptography
     512              :      * [https://www.secg.org/sec1-v2.pdf]
     513              :      * @param out_secret Buffer to write out secret into. This is a byte array representing the x coordinate of the shared secret.
     514              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     515              :      **/
     516              :     virtual CHIP_ERROR ECDH_derive_secret(const PK & remote_public_key, Secret & out_secret) const = 0;
     517              : 
     518              :     virtual const PK & Pubkey() const = 0;
     519              : };
     520              : 
     521              : struct alignas(size_t) P256KeypairContext
     522              : {
     523              :     uint8_t mBytes[kMAX_P256Keypair_Context_Size];
     524              : };
     525              : 
     526              : /**
     527              :  * A serialized P256 key pair is the concatenation of the public and private keys, in that order.
     528              :  */
     529              : using P256SerializedKeypair = SensitiveDataBuffer<kP256_PublicKey_Length + kP256_PrivateKey_Length>;
     530              : 
     531              : class P256KeypairBase : public ECPKeypair<P256PublicKey, P256ECDHDerivedSecret, P256ECDSASignature>
     532              : {
     533              : protected:
     534              :     // This base type can't be copied / assigned directly.
     535              :     // Sub-types should be either uncopyable or final.
     536         1429 :     P256KeypairBase()                                    = default;
     537              :     P256KeypairBase(const P256KeypairBase &)             = default;
     538              :     P256KeypairBase & operator=(const P256KeypairBase &) = default;
     539              : 
     540              : public:
     541              :     /**
     542              :      * @brief Initialize the keypair.
     543              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     544              :      **/
     545              :     virtual CHIP_ERROR Initialize(ECPKeyTarget key_target) = 0;
     546              : 
     547              :     /**
     548              :      * @brief Serialize the keypair.
     549              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     550              :      **/
     551              :     virtual CHIP_ERROR Serialize(P256SerializedKeypair & output) const = 0;
     552              : 
     553              :     /**
     554              :      * @brief Deserialize the keypair.
     555              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     556              :      **/
     557              :     virtual CHIP_ERROR Deserialize(P256SerializedKeypair & input) = 0;
     558              : };
     559              : 
     560              : class P256Keypair : public P256KeypairBase
     561              : {
     562              : public:
     563         1429 :     P256Keypair() = default;
     564              :     ~P256Keypair() override;
     565              : 
     566              :     // P256Keypair can't be copied / assigned.
     567              :     P256Keypair(const P256Keypair &)             = delete;
     568              :     P256Keypair & operator=(const P256Keypair &) = delete;
     569              : 
     570              :     /**
     571              :      * @brief Initialize the keypair.
     572              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     573              :      **/
     574              :     CHIP_ERROR Initialize(ECPKeyTarget key_target) override;
     575              : 
     576              :     /**
     577              :      * @brief Serialize the keypair.
     578              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     579              :      **/
     580              :     CHIP_ERROR Serialize(P256SerializedKeypair & output) const override;
     581              : 
     582              :     /**
     583              :      * @brief Deserialize the keypair.
     584              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     585              :      **/
     586              :     CHIP_ERROR Deserialize(P256SerializedKeypair & input) override;
     587              : 
     588              :     /**
     589              :      * @brief Generate a new Certificate Signing Request (CSR).
     590              :      * @param csr Newly generated CSR in DER format
     591              :      * @param csr_length The caller provides the length of input buffer (csr). The function returns the actual length of generated
     592              :      *CSR.
     593              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     594              :      **/
     595              :     CHIP_ERROR NewCertificateSigningRequest(uint8_t * csr, size_t & csr_length) const override;
     596              : 
     597              :     /**
     598              :      * @brief A function to sign a msg using ECDSA
     599              :      * @param msg Message that needs to be signed
     600              :      * @param msg_length Length of message
     601              :      * @param out_signature Buffer that will hold the output signature. The signature consists of: 2 EC elements (r and s),
     602              :      * in raw <r,s> point form (see SEC1).
     603              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     604              :      **/
     605              :     CHIP_ERROR ECDSA_sign_msg(const uint8_t * msg, size_t msg_length, P256ECDSASignature & out_signature) const override;
     606              : 
     607              :     /**
     608              :      * @brief A function to derive a shared secret using ECDH
     609              :      *
     610              :      * This implements the CHIP_Crypto_ECDH(PrivateKey myPrivateKey, PublicKey theirPublicKey) cryptographic primitive
     611              :      * from the specification, using this class's private key from `mKeypair` as `myPrivateKey` and the remote
     612              :      * public key from `remote_public_key` as `theirPublicKey`.
     613              :      *
     614              :      * @param remote_public_key Public key of remote peer with which we are trying to establish secure channel. remote_public_key is
     615              :      * ASN.1 DER encoded as padded big-endian field elements as described in SEC 1: Elliptic Curve Cryptography
     616              :      * [https://www.secg.org/sec1-v2.pdf]
     617              :      * @param out_secret Buffer to write out secret into. This is a byte array representing the x coordinate of the shared secret.
     618              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     619              :      **/
     620              :     CHIP_ERROR ECDH_derive_secret(const P256PublicKey & remote_public_key, P256ECDHDerivedSecret & out_secret) const override;
     621              : 
     622              :     /** @brief Return public key for the keypair.
     623              :      **/
     624          822 :     const P256PublicKey & Pubkey() const override { return mPublicKey; }
     625              : 
     626              : #if CHIP_WITH_NLFAULTINJECTION
     627            0 :     P256PublicKey & TestOnlyMutablePubkey() { return mPublicKey; }
     628              : #endif
     629              : 
     630              :     /** Release resources associated with this key pair */
     631              :     void Clear();
     632              : 
     633              : protected:
     634              : #if CHIP_WITH_NLFAULTINJECTION
     635              :     mutable P256PublicKey mPublicKey;
     636              : #else
     637              :     P256PublicKey mPublicKey;
     638              : #endif
     639              :     // P256PublicKey mPublicKey;
     640              :     mutable P256KeypairContext mKeypair;
     641              :     bool mInitialized = false;
     642              : };
     643              : 
     644              : /**
     645              :  * @brief Platform-specific symmetric key handle
     646              :  *
     647              :  * The class represents a key used by the Matter stack either in the form of raw key material or key
     648              :  * reference, depending on the platform. To achieve that, it contains an opaque context that can be
     649              :  * cast to a concrete representation used by the given platform.
     650              :  *
     651              :  * @note SymmetricKeyHandle is an abstract class to force child classes for each key handle type.
     652              :  *       SymmetricKeyHandle class implements all the necessary components for handles.
     653              :  */
     654              : template <size_t ContextSize>
     655              : class SymmetricKeyHandle
     656              : {
     657              : public:
     658              :     SymmetricKeyHandle(const SymmetricKeyHandle &) = delete;
     659              :     SymmetricKeyHandle(SymmetricKeyHandle &&)      = delete;
     660              :     void operator=(const SymmetricKeyHandle &)     = delete;
     661              :     void operator=(SymmetricKeyHandle &&)          = delete;
     662              : 
     663              :     /**
     664              :      * @brief Get internal context cast to the desired key representation
     665              :      */
     666              :     template <class T>
     667        30432 :     const T & As() const
     668              :     {
     669        30432 :         return *SafePointerCast<const T *>(&mContext);
     670              :     }
     671              : 
     672              :     /**
     673              :      * @brief Get internal context cast to the desired, mutable key representation
     674              :      */
     675              :     template <class T>
     676         7466 :     T & AsMutable()
     677              :     {
     678         7466 :         return *SafePointerCast<T *>(&mContext);
     679              :     }
     680              : 
     681              : protected:
     682       271234 :     SymmetricKeyHandle() = default;
     683       271234 :     ~SymmetricKeyHandle() { ClearSecretData(mContext.mOpaque); }
     684              : 
     685              : private:
     686              :     struct alignas(uintptr_t) OpaqueContext
     687              :     {
     688              :         uint8_t mOpaque[ContextSize] = {};
     689              :     } mContext;
     690              : };
     691              : 
     692              : using Symmetric128BitsKeyByteArray = uint8_t[CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES];
     693              : 
     694              : /**
     695              :  * @brief Platform-specific 128-bit symmetric key handle
     696              :  */
     697              : class Symmetric128BitsKeyHandle : public SymmetricKeyHandle<CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES>
     698              : {
     699              : };
     700              : 
     701              : /**
     702              :  * @brief Platform-specific 128-bit AES key handle
     703              :  */
     704              : class Aes128KeyHandle final : public Symmetric128BitsKeyHandle
     705              : {
     706              : };
     707              : 
     708              : /**
     709              :  * @brief Platform-specific 128-bit HMAC key handle
     710              :  */
     711              : class Hmac128KeyHandle final : public Symmetric128BitsKeyHandle
     712              : {
     713              : };
     714              : 
     715              : /**
     716              :  * @brief Platform-specific HKDF key handle
     717              :  */
     718              : class HkdfKeyHandle final : public SymmetricKeyHandle<CHIP_CONFIG_HKDF_KEY_HANDLE_CONTEXT_SIZE>
     719              : {
     720              : };
     721              : 
     722              : /**
     723              :  * @brief Convert a raw ECDSA signature to ASN.1 signature (per X9.62) as used by TLS libraries.
     724              :  *
     725              :  * Errors are:
     726              :  *   - CHIP_ERROR_INVALID_ARGUMENT on any argument being invalid (e.g. nullptr), wrong sizes,
     727              :  *     wrong or unsupported format,
     728              :  *   - CHIP_ERROR_BUFFER_TOO_SMALL on running out of space at runtime.
     729              :  *   - CHIP_ERROR_INTERNAL on any unexpected processing error.
     730              :  *
     731              :  * @param[in] fe_length_bytes Field Element length in bytes (e.g. 32 for P256 curve)
     732              :  * @param[in] raw_sig Raw signature of <r,s> concatenated
     733              :  * @param[out] out_asn1_sig ASN.1 DER signature format output buffer. Size must have space for at least
     734              :  * kMax_ECDSA_X9Dot62_Asn1_Overhead. On CHIP_NO_ERROR, the out_asn1_sig buffer will be re-assigned
     735              :  * to have the correct size based on variable-length output.
     736              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     737              :  */
     738              : CHIP_ERROR EcdsaRawSignatureToAsn1(size_t fe_length_bytes, const ByteSpan & raw_sig, MutableByteSpan & out_asn1_sig);
     739              : 
     740              : /**
     741              :  * @brief Convert an ASN.1 DER signature (per X9.62) as used by TLS libraries to SEC1 raw format
     742              :  *
     743              :  * Errors are:
     744              :  *   - CHIP_ERROR_INVALID_ARGUMENT on any argument being invalid (e.g. nullptr), wrong sizes,
     745              :  *     wrong or unsupported format,
     746              :  *   - CHIP_ERROR_BUFFER_TOO_SMALL on running out of space at runtime.
     747              :  *   - CHIP_ERROR_INTERNAL on any unexpected processing error.
     748              :  *
     749              :  * @param[in] fe_length_bytes Field Element length in bytes (e.g. 32 for P256 curve)
     750              :  * @param[in] asn1_sig ASN.1 DER signature input
     751              :  * @param[out] out_raw_sig Raw signature of <r,s> concatenated format output buffer. Size must be at
     752              :  * least >= `2 * fe_length_bytes`. On CHIP_NO_ERROR, the out_raw_sig buffer will be re-assigned
     753              :  * to have the correct size (2 * fe_length_bytes).
     754              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     755              :  */
     756              : CHIP_ERROR EcdsaAsn1SignatureToRaw(size_t fe_length_bytes, const ByteSpan & asn1_sig, MutableByteSpan & out_raw_sig);
     757              : 
     758              : /**
     759              :  * @brief Utility to read a length field after a tag in a DER-encoded stream.
     760              :  * @param[in] reader Reader instance from which the input will be read
     761              :  * @param[out] length Length of the following element read from the stream
     762              :  * @return CHIP_ERROR_INVALID_ARGUMENT or CHIP_ERROR_BUFFER_TOO_SMALL on error, CHIP_NO_ERROR otherwise
     763              :  */
     764              : CHIP_ERROR ReadDerLength(chip::Encoding::LittleEndian::Reader & reader, size_t & length);
     765              : 
     766              : /**
     767              :  * @brief Utility to emit a DER-encoded INTEGER given a raw unsigned large integer
     768              :  *        in big-endian order. The `out_der_integer` span is updated to reflect the final
     769              :  *        variable length, including tag and length, and must have at least `kEmitDerIntegerOverhead`
     770              :  *        extra space in addition to the `raw_integer.size()`.
     771              :  * @param[in] raw_integer Bytes of a large unsigned integer in big-endian, possibly including leading zeroes
     772              :  * @param[out] out_der_integer Buffer to receive the DER-encoded integer
     773              :  * @return Returns CHIP_ERROR_INVALID_ARGUMENT or CHIP_ERROR_BUFFER_TOO_SMALL on error, CHIP_NO_ERROR otherwise.
     774              :  */
     775              : CHIP_ERROR ConvertIntegerRawToDer(const ByteSpan & raw_integer, MutableByteSpan & out_der_integer);
     776              : 
     777              : /**
     778              :  * @brief Utility to emit a DER-encoded INTEGER given a raw unsigned large integer
     779              :  *        in big-endian order. The `out_der_integer` span is updated to reflect the final
     780              :  *        variable length, excluding tag and length, and must have at least `kEmitDerIntegerWithoutTagOverhead`
     781              :  *        extra space in addition to the `raw_integer.size()`.
     782              :  * @param[in] raw_integer Bytes of a large unsigned integer in big-endian, possibly including leading zeroes
     783              :  * @param[out] out_der_integer Buffer to receive the DER-encoded integer
     784              :  * @return Returns CHIP_ERROR_INVALID_ARGUMENT or CHIP_ERROR_BUFFER_TOO_SMALL on error, CHIP_NO_ERROR otherwise.
     785              :  */
     786              : CHIP_ERROR ConvertIntegerRawToDerWithoutTag(const ByteSpan & raw_integer, MutableByteSpan & out_der_integer);
     787              : 
     788              : /**
     789              :  * @brief A function that implements AES-CCM encryption
     790              :  *
     791              :  * This implements the CHIP_Crypto_AEAD_GenerateEncrypt() cryptographic primitive
     792              :  * from the specification. For an empty plaintext, the user of the API can provide
     793              :  * an empty string, or a nullptr, and provide plaintext_length as 0. The output buffer,
     794              :  * ciphertext can also be an empty string, or a nullptr for this case.
     795              :  *
     796              :  * @param plaintext Plaintext to encrypt
     797              :  * @param plaintext_length Length of plain_text
     798              :  * @param aad Additional authentication data
     799              :  * @param aad_length Length of additional authentication data
     800              :  * @param key Encryption key
     801              :  * @param nonce Encryption nonce
     802              :  * @param nonce_length Length of encryption nonce
     803              :  * @param ciphertext Buffer to write ciphertext into. Caller must ensure this is large enough to hold the ciphertext
     804              :  * @param tag Buffer to write tag into. Caller must ensure this is large enough to hold the tag
     805              :  * @param tag_length Expected length of tag
     806              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     807              :  * */
     808              : CHIP_ERROR AES_CCM_encrypt(const uint8_t * plaintext, size_t plaintext_length, const uint8_t * aad, size_t aad_length,
     809              :                            const Aes128KeyHandle & key, const uint8_t * nonce, size_t nonce_length, uint8_t * ciphertext,
     810              :                            uint8_t * tag, size_t tag_length);
     811              : 
     812              : /**
     813              :  * @brief A function that implements AES-CCM decryption
     814              :  *
     815              :  * This implements the CHIP_Crypto_AEAD_DecryptVerify() cryptographic primitive
     816              :  * from the specification. For an empty ciphertext, the user of the API can provide
     817              :  * an empty string, or a nullptr, and provide ciphertext_length as 0. The output buffer,
     818              :  * plaintext can also be an empty string, or a nullptr for this case.
     819              :  *
     820              :  * @param ciphertext Ciphertext to decrypt
     821              :  * @param ciphertext_length Length of ciphertext
     822              :  * @param aad Additional authentical data.
     823              :  * @param aad_length Length of additional authentication data
     824              :  * @param tag Tag to use to decrypt
     825              :  * @param tag_length Length of tag
     826              :  * @param key Decryption key
     827              :  * @param nonce Encryption nonce
     828              :  * @param nonce_length Length of encryption nonce
     829              :  * @param plaintext Buffer to write plaintext into
     830              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     831              :  **/
     832              : CHIP_ERROR AES_CCM_decrypt(const uint8_t * ciphertext, size_t ciphertext_length, const uint8_t * aad, size_t aad_length,
     833              :                            const uint8_t * tag, size_t tag_length, const Aes128KeyHandle & key, const uint8_t * nonce,
     834              :                            size_t nonce_length, uint8_t * plaintext);
     835              : 
     836              : /**
     837              :  * @brief A function that implements AES-CTR encryption/decryption
     838              :  *
     839              :  * This implements the AES-CTR-Encrypt/Decrypt() cryptographic primitives per sections
     840              :  * 3.7.1 and 3.7.2 of the specification. For an empty input, the user of the API
     841              :  * can provide an empty string, or a nullptr, and provide input as 0.
     842              :  * The output buffer can also be an empty string, or a nullptr for this case.
     843              :  *
     844              :  * @param input Input text to encrypt/decrypt
     845              :  * @param input_length Length of ciphertext
     846              :  * @param key Decryption key
     847              :  * @param nonce Encryption nonce
     848              :  * @param nonce_length Length of encryption nonce
     849              :  * @param output Buffer to write output into
     850              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     851              :  **/
     852              : CHIP_ERROR AES_CTR_crypt(const uint8_t * input, size_t input_length, const Aes128KeyHandle & key, const uint8_t * nonce,
     853              :                          size_t nonce_length, uint8_t * output);
     854              : 
     855              : /**
     856              :  * @brief Generate a PKCS#10 CSR, usable for Matter, from a P256Keypair.
     857              :  *
     858              :  * This uses first principles ASN.1 encoding to avoid relying on the CHIPCryptoPAL backend
     859              :  * itself, other than to provide an implementation of a P256Keypair * that supports
     860              :  * at least `::Pubkey()` and `::ECDSA_sign_msg`. This allows using it with
     861              :  * OS/Platform-bridged private key handling, without requiring a specific
     862              :  * implementation of other bits like ASN.1.
     863              :  *
     864              :  * The CSR will have subject OU set to `CSA`. This is needed since omiting
     865              :  * subject altogether often trips CSR parsing code. The profile at the CA can
     866              :  * be configured to ignore CSR requested subject.
     867              :  *
     868              :  * @param keypair The key pair for which a CSR should be generated. Must not be null.
     869              :  * @param csr_span Span to hold the resulting CSR. Must have size at least kMIN_CSR_Buffer_Size.
     870              :  *                 Otherwise returns CHIP_ERROR_BUFFER_TOO_SMALL. It will get resized to
     871              :  *                 actual size needed on success.
     872              : 
     873              :  * @return Returns a CHIP_ERROR from P256Keypair or ASN.1 backend on error, CHIP_NO_ERROR otherwise
     874              :  **/
     875              : CHIP_ERROR GenerateCertificateSigningRequest(const P256Keypair * keypair, MutableByteSpan & csr_span);
     876              : 
     877              : /**
     878              :  * @brief Common code to validate ASN.1 format/size of a CSR, used by VerifyCertificateSigningRequest.
     879              :  *
     880              :  * Ensures it's not obviously malformed and doesn't have trailing garbage.
     881              :  *
     882              :  * @param csr CSR in DER format
     883              :  * @param csr_length The length of the CSR buffer
     884              :  * @return CHIP_ERROR_UNSUPPORTED_CERT_FORMAT on invalid format, CHIP_NO_ERROR otherwise.
     885              :  */
     886              : CHIP_ERROR VerifyCertificateSigningRequestFormat(const uint8_t * csr, size_t csr_length);
     887              : 
     888              : /**
     889              :  * @brief Verify the Certificate Signing Request (CSR). If successfully verified, it outputs the public key from the CSR.
     890              :  *
     891              :  * The CSR is valid if the format is correct, the signature validates with the embedded public
     892              :  * key, and there is no trailing garbage data.
     893              :  *
     894              :  * @param csr CSR in DER format
     895              :  * @param csr_length The length of the CSR
     896              :  * @param pubkey The public key from the verified CSR
     897              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     898              :  **/
     899              : CHIP_ERROR VerifyCertificateSigningRequest(const uint8_t * csr, size_t csr_length, P256PublicKey & pubkey);
     900              : 
     901              : /**
     902              :  * @brief A function that implements SHA-256 hash
     903              :  *
     904              :  * This implements the CHIP_Crypto_Hash() cryptographic primitive
     905              :  * in the the specification.
     906              :  *
     907              :  * @param data The data to hash
     908              :  * @param data_length Length of the data
     909              :  * @param out_buffer Pointer to buffer to write output into
     910              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     911              :  **/
     912              : 
     913              : CHIP_ERROR Hash_SHA256(const uint8_t * data, size_t data_length, uint8_t * out_buffer);
     914              : 
     915              : /**
     916              :  * @brief A function that implements SHA-1 hash
     917              :  * @param data The data to hash
     918              :  * @param data_length Length of the data
     919              :  * @param out_buffer Pointer to buffer to write output into
     920              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
     921              :  **/
     922              : 
     923              : CHIP_ERROR Hash_SHA1(const uint8_t * data, size_t data_length, uint8_t * out_buffer);
     924              : 
     925              : /**
     926              :  * @brief A class that defines stream based implementation of SHA-256 hash
     927              :  *        It's expected that the object of this class can be safely copied.
     928              :  *        All implementations must check for std::is_trivially_copyable.
     929              :  **/
     930              : 
     931              : struct alignas(CHIP_CONFIG_SHA256_CONTEXT_ALIGN) HashSHA256OpaqueContext
     932              : {
     933              :     uint8_t mOpaque[kMAX_Hash_SHA256_Context_Size];
     934              : };
     935              : 
     936              : class Hash_SHA256_stream
     937              : {
     938              : public:
     939              :     Hash_SHA256_stream();
     940              :     ~Hash_SHA256_stream();
     941              : 
     942              :     /**
     943              :      * @brief Re-initialize digest computation to an empty context.
     944              :      *
     945              :      * @return CHIP_ERROR_INTERNAL on failure to initialize the context,
     946              :      *         CHIP_NO_ERROR otherwise.
     947              :      */
     948              :     CHIP_ERROR Begin();
     949              : 
     950              :     /**
     951              :      * @brief Add some data to the digest computation, updating internal state.
     952              :      *
     953              :      * @param[in] data The span of bytes to include in the digest update process.
     954              :      *
     955              :      * @return CHIP_ERROR_INTERNAL on failure to ingest the data, CHIP_NO_ERROR otherwise.
     956              :      */
     957              :     CHIP_ERROR AddData(const ByteSpan data);
     958              : 
     959              :     /**
     960              :      * @brief Get the intermediate padded digest for the current state of the stream.
     961              :      *
     962              :      * More data can be added before finish is called.
     963              :      *
     964              :      * @param[in,out] out_buffer Output buffer to receive the digest. `out_buffer` must
     965              :      * be at least `kSHA256_Hash_Length` bytes long. The `out_buffer` size
     966              :      * will be set to `kSHA256_Hash_Length` on success.
     967              :      *
     968              :      * @return CHIP_ERROR_INTERNAL on failure to compute the digest, CHIP_ERROR_BUFFER_TOO_SMALL
     969              :      *         if out_buffer is too small, CHIP_NO_ERROR otherwise.
     970              :      */
     971              :     CHIP_ERROR GetDigest(MutableByteSpan & out_buffer);
     972              : 
     973              :     /**
     974              :      * @brief Finalize the stream digest computation, getting the final digest.
     975              :      *
     976              :      * @param[in,out] out_buffer Output buffer to receive the digest. `out_buffer` must
     977              :      * be at least `kSHA256_Hash_Length` bytes long. The `out_buffer` size
     978              :      * will be set to `kSHA256_Hash_Length` on success.
     979              :      *
     980              :      * @return CHIP_ERROR_INTERNAL on failure to compute the digest, CHIP_ERROR_BUFFER_TOO_SMALL
     981              :      *         if out_buffer is too small, CHIP_NO_ERROR otherwise.
     982              :      */
     983              :     CHIP_ERROR Finish(MutableByteSpan & out_buffer);
     984              : 
     985              :     /**
     986              :      * @brief Clear-out internal digest data to avoid lingering the state.
     987              :      */
     988              :     void Clear();
     989              : 
     990              : private:
     991              :     // Check if the digest computation has been initialized; implement this if your backend needs it.
     992              :     bool IsInitialized();
     993              : 
     994              :     HashSHA256OpaqueContext mContext;
     995              : };
     996              : 
     997              : class HKDF_sha
     998              : {
     999              : public:
    1000              :     HKDF_sha()          = default;
    1001         3895 :     virtual ~HKDF_sha() = default;
    1002              : 
    1003              :     /**
    1004              :      * @brief A function that implements SHA-256 based HKDF
    1005              :      *
    1006              :      * This implements the CHIP_Crypto_KDF() cryptographic primitive
    1007              :      * in the the specification.
    1008              :      *
    1009              :      *  Error values are:
    1010              :      *   - CHIP_ERROR_INVALID_ARGUMENT: for any bad arguments or nullptr input on
    1011              :      *     any pointer.
    1012              :      *   - CHIP_ERROR_INTERNAL: for any unexpected error arising in the underlying
    1013              :      *     cryptographic layers.
    1014              :      *
    1015              :      * @param secret The secret to use as the key to the HKDF
    1016              :      * @param secret_length Length of the secret
    1017              :      * @param salt Optional salt to use as input to the HKDF
    1018              :      * @param salt_length Length of the salt
    1019              :      * @param info Optional info to use as input to the HKDF
    1020              :      * @param info_length Length of the info
    1021              :      * @param out_buffer Pointer to buffer to write output into.
    1022              :      * @param out_length Size of the underlying out_buffer. That length of output key material will be generated in out_buffer.
    1023              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1024              :      **/
    1025              : 
    1026              :     virtual CHIP_ERROR HKDF_SHA256(const uint8_t * secret, size_t secret_length, const uint8_t * salt, size_t salt_length,
    1027              :                                    const uint8_t * info, size_t info_length, uint8_t * out_buffer, size_t out_length);
    1028              : };
    1029              : 
    1030              : class HMAC_sha
    1031              : {
    1032              : public:
    1033              :     HMAC_sha()          = default;
    1034           96 :     virtual ~HMAC_sha() = default;
    1035              : 
    1036              :     /**
    1037              :      * @brief A function that implements SHA-256 based HMAC per FIPS1981.
    1038              :      *
    1039              :      * This implements the CHIP_Crypto_HMAC() cryptographic primitive
    1040              :      * in the the specification.
    1041              :      *
    1042              :      * The `out_length` must be at least kSHA256_Hash_Length, and only
    1043              :      * kSHA256_Hash_Length bytes are written to out_buffer.
    1044              :      *
    1045              :      * Error values are:
    1046              :      *   - CHIP_ERROR_INVALID_ARGUMENT: for any bad arguments or nullptr input on
    1047              :      *     any pointer.
    1048              :      *   - CHIP_ERROR_INTERNAL: for any unexpected error arising in the underlying
    1049              :      *     cryptographic layers.
    1050              :      *
    1051              :      * @param key The key to use for the HMAC operation
    1052              :      * @param key_length Length of the key
    1053              :      * @param message Message over which to compute the HMAC
    1054              :      * @param message_length Length of the message over which to compute the HMAC
    1055              :      * @param out_buffer Pointer to buffer into which to write the output.
    1056              :      * @param out_length Underlying size of the `out_buffer`.
    1057              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1058              :      **/
    1059              : 
    1060              :     virtual CHIP_ERROR HMAC_SHA256(const uint8_t * key, size_t key_length, const uint8_t * message, size_t message_length,
    1061              :                                    uint8_t * out_buffer, size_t out_length);
    1062              : 
    1063              :     /**
    1064              :      * @brief A function that implements SHA-256 based HMAC per FIPS1981.
    1065              :      *
    1066              :      * This implements the CHIP_Crypto_HMAC() cryptographic primitive
    1067              :      * in the the specification.
    1068              :      *
    1069              :      * The `out_length` must be at least kSHA256_Hash_Length, and only
    1070              :      * kSHA256_Hash_Length bytes are written to out_buffer.
    1071              :      *
    1072              :      * Error values are:
    1073              :      *   - CHIP_ERROR_INVALID_ARGUMENT: for any bad arguments or nullptr input on
    1074              :      *     any pointer.
    1075              :      *   - CHIP_ERROR_INTERNAL: for any unexpected error arising in the underlying
    1076              :      *     cryptographic layers.
    1077              :      *
    1078              :      * @param key The HMAC Key handle to use for the HMAC operation
    1079              :      * @param message Message over which to compute the HMAC
    1080              :      * @param message_length Length of the message over which to compute the HMAC
    1081              :      * @param out_buffer Pointer to buffer into which to write the output.
    1082              :      * @param out_length Underlying size of the `out_buffer`.
    1083              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1084              :      **/
    1085              :     virtual CHIP_ERROR HMAC_SHA256(const Hmac128KeyHandle & key, const uint8_t * message, size_t message_length,
    1086              :                                    uint8_t * out_buffer, size_t out_length);
    1087              : };
    1088              : 
    1089              : /**
    1090              :  * @brief A cryptographically secure random number generator based on NIST SP800-90A
    1091              :  * @param out_buffer Buffer into which to write random bytes
    1092              :  * @param out_length Number of random bytes to generate
    1093              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1094              :  **/
    1095              : CHIP_ERROR DRBG_get_bytes(uint8_t * out_buffer, size_t out_length);
    1096              : 
    1097              : /** @brief Entropy callback function
    1098              :  * @param data Callback-specific data pointer
    1099              :  * @param output Output data to fill
    1100              :  * @param len Length of output buffer
    1101              :  * @param olen The actual amount of data that was written to output buffer
    1102              :  * @return 0 if success
    1103              :  */
    1104              : typedef int (*entropy_source)(void * data, uint8_t * output, size_t len, size_t * olen);
    1105              : 
    1106              : /** @brief A function to add entropy sources to crypto library
    1107              :  *
    1108              :  * This function can be called multiple times to add multiple entropy sources. However,
    1109              :  * once the entropy source is added, it cannot be removed. Please make sure that the
    1110              :  * entropy source is valid for the lifetime of the application. Also, make sure that the
    1111              :  * same entropy source is not added multiple times, e.g.: by calling this function
    1112              :  * in class constructor or initialization function.
    1113              :  *
    1114              :  * @param fn_source Function pointer to the entropy source
    1115              :  * @param p_source  Data that should be provided when fn_source is called
    1116              :  * @param threshold Minimum required from source before entropy is released
    1117              :  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1118              :  **/
    1119              : CHIP_ERROR add_entropy_source(entropy_source fn_source, void * p_source, size_t threshold);
    1120              : 
    1121              : class PBKDF2_sha256
    1122              : {
    1123              : public:
    1124              :     PBKDF2_sha256()          = default;
    1125            9 :     virtual ~PBKDF2_sha256() = default;
    1126              : 
    1127              :     /** @brief Function to derive key using password. SHA256 hashing algorithm is used for calculating hmac.
    1128              :      * @param password password used for key derivation
    1129              :      * @param plen length of buffer containing password
    1130              :      * @param salt salt to use as input to the KDF
    1131              :      * @param slen length of salt
    1132              :      * @param iteration_count number of iterations to run
    1133              :      * @param key_length length of output key
    1134              :      * @param output output buffer where the key will be written
    1135              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1136              :      **/
    1137              :     virtual CHIP_ERROR pbkdf2_sha256(const uint8_t * password, size_t plen, const uint8_t * salt, size_t slen,
    1138              :                                      unsigned int iteration_count, uint32_t key_length, uint8_t * output);
    1139              : };
    1140              : 
    1141              : // TODO: Extract Spake2p to a separate header and replace the forward declaration with #include SessionKeystore.h
    1142              : class SessionKeystore;
    1143              : 
    1144              : /**
    1145              :  * The below class implements the draft 01 version of the Spake2+ protocol as
    1146              :  * defined in https://www.ietf.org/id/draft-bar-cfrg-spake2plus-01.html.
    1147              :  *
    1148              :  * The following describes the protocol flows:
    1149              :  *
    1150              :  *     Commissioner                     Accessory
    1151              :  *     ------------                     ---------
    1152              :  *
    1153              :  *     Init
    1154              :  *     BeginProver
    1155              :  *     ComputeRoundOne  ------------->
    1156              :  *                                      Init
    1157              :  *                                      BeginVerifier
    1158              :  *                                  /-  ComputeRoundOne
    1159              :  *                      <-------------  ComputeRoundTwo
    1160              :  *     ComputeRoundTwo  ------------->
    1161              :  *     KeyConfirm                       KeyConfirm
    1162              :  *     GetKeys                          GetKeys
    1163              :  *
    1164              :  **/
    1165              : class Spake2p
    1166              : {
    1167              : public:
    1168              :     Spake2p(size_t fe_size, size_t point_size, size_t hash_size);
    1169           25 :     virtual ~Spake2p() = default;
    1170              : 
    1171              :     /**
    1172              :      * @brief Initialize Spake2+ with some context specific information.
    1173              :      *
    1174              :      * @param context     The context is arbitrary but should include information about the
    1175              :      *                    protocol being run, contain the transcript for negotiation, include
    1176              :      *                    the PKBDF parameters, etc.
    1177              :      * @param context_len The length of the context.
    1178              :      *
    1179              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1180              :      **/
    1181              :     virtual CHIP_ERROR Init(const uint8_t * context, size_t context_len);
    1182              : 
    1183              :     /**
    1184              :      * @brief Free Spake2+ underlying objects.
    1185              :      **/
    1186              :     virtual void Clear() = 0;
    1187              : 
    1188              :     /**
    1189              :      * @brief Start the Spake2+ process as a verifier (i.e. an accessory being provisioned).
    1190              :      *
    1191              :      * @param my_identity       The verifier identity. May be NULL if identities are not established.
    1192              :      * @param my_identity_len   The verifier identity length.
    1193              :      * @param peer_identity     The peer identity. May be NULL if identities are not established.
    1194              :      * @param peer_identity_len The peer identity length.
    1195              :      * @param w0in              The input w0 (a parameter baked into the device or computed with ComputeW0).
    1196              :      * @param w0in_len          The input w0 length.
    1197              :      * @param Lin               The input L (a parameter baked into the device or computed with ComputeL).
    1198              :      * @param Lin_len           The input L length.
    1199              :      *
    1200              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1201              :      **/
    1202              :     virtual CHIP_ERROR BeginVerifier(const uint8_t * my_identity, size_t my_identity_len, const uint8_t * peer_identity,
    1203              :                                      size_t peer_identity_len, const uint8_t * w0in, size_t w0in_len, const uint8_t * Lin,
    1204              :                                      size_t Lin_len);
    1205              : 
    1206              :     /**
    1207              :      * @brief Start the Spake2+ process as a prover (i.e. a commissioner).
    1208              :      *
    1209              :      * @param my_identity       The prover identity. May be NULL if identities are not established.
    1210              :      * @param my_identity_len   The prover identity length.
    1211              :      * @param peer_identity     The peer identity. May be NULL if identities are not established.
    1212              :      * @param peer_identity_len The peer identity length.
    1213              :      * @param w0sin             The input w0s (an output from the PBKDF).
    1214              :      * @param w0sin_len         The input w0s length.
    1215              :      * @param w1sin             The input w1s (an output from the PBKDF).
    1216              :      * @param w1sin_len         The input w1s length.
    1217              :      *
    1218              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1219              :      **/
    1220              :     virtual CHIP_ERROR BeginProver(const uint8_t * my_identity, size_t my_identity_len, const uint8_t * peer_identity,
    1221              :                                    size_t peer_identity_len, const uint8_t * w0sin, size_t w0sin_len, const uint8_t * w1sin,
    1222              :                                    size_t w1sin_len);
    1223              : 
    1224              :     /**
    1225              :      * @brief Compute the first round of the protocol.
    1226              :      *
    1227              :      * @param pab      X value from commissioner.
    1228              :      * @param pab_len  X length.
    1229              :      * @param out     The output first round Spake2+ contribution.
    1230              :      * @param out_len The output first round Spake2+ contribution length.
    1231              :      *
    1232              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1233              :      **/
    1234              :     virtual CHIP_ERROR ComputeRoundOne(const uint8_t * pab, size_t pab_len, uint8_t * out, size_t * out_len);
    1235              : 
    1236              :     /**
    1237              :      * @brief Compute the second round of the protocol.
    1238              :      *
    1239              :      * @param in      The peer first round Spake2+ contribution.
    1240              :      * @param in_len  The peer first round Spake2+ contribution length.
    1241              :      * @param out     The output second round Spake2+ contribution.
    1242              :      * @param out_len The output second round Spake2+ contribution length.
    1243              :      *
    1244              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1245              :      **/
    1246              :     virtual CHIP_ERROR ComputeRoundTwo(const uint8_t * in, size_t in_len, uint8_t * out, size_t * out_len);
    1247              : 
    1248              :     /**
    1249              :      * @brief Confirm that each party computed the same keys.
    1250              :      *
    1251              :      * @param in     The peer second round Spake2+ contribution.
    1252              :      * @param in_len The peer second round Spake2+ contribution length.
    1253              :      *
    1254              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1255              :      **/
    1256              :     virtual CHIP_ERROR KeyConfirm(const uint8_t * in, size_t in_len);
    1257              : 
    1258              :     /**
    1259              :      * @brief Return the shared HKDF key.
    1260              :      *
    1261              :      * Returns the shared key established during the Spake2+ process, which can be used
    1262              :      * to derive application-specific keys using HKDF.
    1263              :      *
    1264              :      * @param keystore The session keystore for managing the HKDF key lifetime.
    1265              :      * @param key The output HKDF key.
    1266              :      *
    1267              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1268              :      **/
    1269              :     CHIP_ERROR GetKeys(SessionKeystore & keystore, HkdfKeyHandle & key);
    1270              : 
    1271              :     CHIP_ERROR InternalHash(const uint8_t * in, size_t in_len);
    1272              :     CHIP_ERROR WriteMN();
    1273              :     CHIP_ERROR GenerateKeys();
    1274              : 
    1275              :     /**
    1276              :      * @brief Load a field element.
    1277              :      *
    1278              :      *  @param in     The input big endian field element.
    1279              :      *  @param in_len The size of the input buffer in bytes.
    1280              :      *  @param fe     A pointer to an initialized implementation dependant field element.
    1281              :      *
    1282              :      *  @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1283              :      **/
    1284              :     virtual CHIP_ERROR FELoad(const uint8_t * in, size_t in_len, void * fe) = 0;
    1285              : 
    1286              :     /**
    1287              :      * @brief Write a field element in big-endian format.
    1288              :      *
    1289              :      *  @param fe      The field element to write.
    1290              :      *  @param out     The output buffer.
    1291              :      *  @param out_len The length of the output buffer.
    1292              :      *
    1293              :      *  @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1294              :      **/
    1295              :     virtual CHIP_ERROR FEWrite(const void * fe, uint8_t * out, size_t out_len) = 0;
    1296              : 
    1297              :     /**
    1298              :      * @brief Generate a field element.
    1299              :      *
    1300              :      *  @param fe  A pointer to an initialized implementation dependant field element.
    1301              :      *
    1302              :      *  @note The implementation must generate a random element from [0, q) where q is the curve order.
    1303              :      *
    1304              :      *  @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1305              :      **/
    1306              :     virtual CHIP_ERROR FEGenerate(void * fe) = 0;
    1307              : 
    1308              :     /**
    1309              :      * @brief Multiply two field elements, fer = fe1 * fe2.
    1310              :      *
    1311              :      *  @param fer   A pointer to an initialized implementation dependant field element.
    1312              :      *  @param fe1  A pointer to an initialized implementation dependant field element.
    1313              :      *  @param fe2  A pointer to an initialized implementation dependant field element.
    1314              :      *
    1315              :      *  @note The result must be a field element (i.e. reduced by the curve order).
    1316              :      *
    1317              :      *  @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1318              :      **/
    1319              :     virtual CHIP_ERROR FEMul(void * fer, const void * fe1, const void * fe2) = 0;
    1320              : 
    1321              :     /**
    1322              :      * @brief Load a point from 0x04 || X || Y format
    1323              :      *
    1324              :      * @param in     Input buffer
    1325              :      * @param in_len Input buffer length
    1326              :      * @param R      A pointer to an initialized implementation dependant point.
    1327              :      *
    1328              :      *  @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1329              :      **/
    1330              :     virtual CHIP_ERROR PointLoad(const uint8_t * in, size_t in_len, void * R) = 0;
    1331              : 
    1332              :     /**
    1333              :      * @brief Write a point in 0x04 || X || Y format
    1334              :      *
    1335              :      * @param R       A pointer to an initialized implementation dependant point.
    1336              :      * @param out     Output buffer
    1337              :      * @param out_len Length of the output buffer
    1338              :      *
    1339              :      *  @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1340              :      **/
    1341              :     virtual CHIP_ERROR PointWrite(const void * R, uint8_t * out, size_t out_len) = 0;
    1342              : 
    1343              :     /**
    1344              :      * @brief Scalar multiplication, R = fe1 * P1.
    1345              :      *
    1346              :      * @param R   Resultant point
    1347              :      * @param P1  Input point
    1348              :      * @param fe1  Input field element.
    1349              :      *
    1350              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1351              :      **/
    1352              :     virtual CHIP_ERROR PointMul(void * R, const void * P1, const void * fe1) = 0;
    1353              : 
    1354              :     /**
    1355              :      * @brief Scalar multiplication with addition, R = fe1 * P1 + fe2 * P2.
    1356              :      *
    1357              :      * @param R   Resultant point
    1358              :      * @param P1  Input point
    1359              :      * @param fe1  Input field element.
    1360              :      * @param P2  Input point
    1361              :      * @param fe2  Input field element.
    1362              :      *
    1363              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1364              :      **/
    1365              :     virtual CHIP_ERROR PointAddMul(void * R, const void * P1, const void * fe1, const void * P2, const void * fe2) = 0;
    1366              : 
    1367              :     /**
    1368              :      * @brief Point inversion.
    1369              :      *
    1370              :      * @param R   Input/Output point to point_invert
    1371              :      *
    1372              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1373              :      **/
    1374              :     virtual CHIP_ERROR PointInvert(void * R) = 0;
    1375              : 
    1376              :     /**
    1377              :      * @brief Multiply a point by the curve cofactor.
    1378              :      *
    1379              :      * @param R   Input/Output point to point_invert
    1380              :      *
    1381              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1382              :      **/
    1383              :     virtual CHIP_ERROR PointCofactorMul(void * R) = 0;
    1384              : 
    1385              :     /*
    1386              :      *   @synopsis Check if a point is on the curve.
    1387              :      *
    1388              :      *   @param R   Input point to check.
    1389              :      *
    1390              :      *   @return CHIP_NO_ERROR if the point is valid, CHIP_ERROR otherwise.
    1391              :      */
    1392              :     virtual CHIP_ERROR PointIsValid(void * R) = 0;
    1393              : 
    1394              :     /*
    1395              :      *   @synopsis Compute w0sin mod p
    1396              :      *
    1397              :      *   @param w0out       Output field element w0
    1398              :      *   @param w0_len      Output field element length
    1399              :      *   @param w0sin       Input field element
    1400              :      *   @param w0sin_len   Input field element length
    1401              :      *
    1402              :      *   @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1403              :      **/
    1404              :     virtual CHIP_ERROR ComputeW0(uint8_t * w0out, size_t * w0_len, const uint8_t * w0sin, size_t w0sin_len) = 0;
    1405              : 
    1406              :     /*
    1407              :      *   @synopsis Compute w1in*G where w1in is w1sin mod p
    1408              :      *
    1409              :      *   @param Lout        Output point in 0x04 || X || Y format.
    1410              :      *   @param L_len       Output point length
    1411              :      *   @param w1sin       Input field element
    1412              :      *   @param w1sin_len   Input field element size
    1413              :      *
    1414              :      *   @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1415              :      **/
    1416              :     virtual CHIP_ERROR ComputeL(uint8_t * Lout, size_t * L_len, const uint8_t * w1sin, size_t w1sin_len) = 0;
    1417              : 
    1418              :     void * M;
    1419              :     void * N;
    1420              :     const void * G;
    1421              :     void * X;
    1422              :     void * Y;
    1423              :     void * L;
    1424              :     void * Z;
    1425              :     void * V;
    1426              :     void * w0;
    1427              :     void * w1;
    1428              :     void * xy;
    1429              :     void * order;
    1430              :     void * tempbn;
    1431              : 
    1432              : protected:
    1433              :     /**
    1434              :      * @brief Initialize underlying implementation curve, points, field elements, etc.
    1435              :      *
    1436              :      * @details The implementation needs to:
    1437              :      *     1. Initialize each of the points below and set the relevant pointers on the class:
    1438              :      *        a. M
    1439              :      *        b. N
    1440              :      *        c. G
    1441              :      *        d. X
    1442              :      *        e. Y
    1443              :      *        f. L
    1444              :      *        g. Z
    1445              :      *        h. V
    1446              :      *
    1447              :      *        As an example:
    1448              :      *           this.M = implementation_alloc_point();
    1449              :      *     2. Initialize each of the field elements below and set the relevant pointers on the class:
    1450              :      *        a. w0
    1451              :      *        b. w1
    1452              :      *        c. xy
    1453              :      *        d. tempbn
    1454              :      *     3. The hashing context should be initialized
    1455              :      *
    1456              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1457              :      **/
    1458              :     virtual CHIP_ERROR InitImpl() = 0;
    1459              : 
    1460              :     /**
    1461              :      * @brief Hash in_len bytes of in into the internal hash context.
    1462              :      *
    1463              :      * @param in     The input buffer.
    1464              :      * @param in_len Size of the input buffer in bytes.
    1465              :      *
    1466              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1467              :      **/
    1468              :     virtual CHIP_ERROR Hash(const uint8_t * in, size_t in_len) = 0;
    1469              : 
    1470              :     /**
    1471              :      * @brief Return the hash.
    1472              :      *
    1473              :      * @param out_span Output buffer. The size available must be >= the hash size. It gets resized
    1474              :      *                 to hash size on success.
    1475              :      *
    1476              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1477              :      **/
    1478              :     virtual CHIP_ERROR HashFinalize(MutableByteSpan & out_span) = 0;
    1479              : 
    1480              :     /**
    1481              :      * @brief Generate a message authentication code.
    1482              :      *
    1483              :      * @param key      The MAC key buffer.
    1484              :      * @param key_len  The size of the MAC key in bytes.
    1485              :      * @param in       The input buffer.
    1486              :      * @param in_len   The size of the input data to MAC in bytes.
    1487              :      * @param out_span The output MAC buffer span. Size must be >= the hash_size. Output size is updated to fit on success.
    1488              :      *
    1489              :      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
    1490              :      **/
    1491              :     virtual CHIP_ERROR Mac(const uint8_t * key, size_t key_len, const uint8_t * in, size_t in_len, MutableByteSpan & out_span) = 0;
    1492              : 
    1493              :     /**
    1494              :      * @brief Verify a message authentication code.
    1495              :      *
    1496              :      *  @param key     The MAC key buffer.
    1497              :      *  @param key_len The size of the MAC key in bytes.
    1498              :      *  @param mac     The input MAC buffer.
    1499              :      *  @param mac_len The size of the MAC in bytes.
    1500              :      *  @param in      The input buffer to verify.
    1501              :      *  @param in_len  The size of the input data to verify in bytes.
    1502              :      *
    1503              :      *  @return Returns a CHIP_ERROR when the MAC doesn't validate, CHIP_NO_ERROR otherwise.
    1504              :      **/
    1505              :     virtual CHIP_ERROR MacVerify(const uint8_t * key, size_t key_len, const uint8_t * mac, size_t mac_len, const uint8_t * in,
    1506              :                                  size_t in_len) = 0;
    1507              : 
    1508              :     /**
    1509              :      * @brief Derive an key of length out_len.
    1510              :      *
    1511              :      * @param ikm      The input key material buffer.
    1512              :      * @param ikm_len  The input key material length.
    1513              :      * @param salt     The optional salt. This may be NULL.
    1514              :      * @param salt_len The size of the salt in bytes.
    1515              :      * @param info     The info.
    1516              :      * @param info_len The size of the info in bytes.
    1517              :      * @param out      The output key
    1518              :      * @param out_len  The output key length
    1519              :      *
    1520              :      * @return Returns a CHIP_ERROR when the MAC doesn't validate, CHIP_NO_ERROR otherwise.
    1521              :      **/
    1522              :     virtual CHIP_ERROR KDF(const uint8_t * ikm, size_t ikm_len, const uint8_t * salt, size_t salt_len, const uint8_t * info,
    1523              :                            size_t info_len, uint8_t * out, size_t out_len) = 0;
    1524              : 
    1525              :     CHIP_SPAKE2P_ROLE role;
    1526              :     CHIP_SPAKE2P_STATE state = CHIP_SPAKE2P_STATE::PREINIT;
    1527              :     size_t fe_size;
    1528              :     size_t hash_size;
    1529              :     size_t point_size;
    1530              :     uint8_t Kcab[kMAX_Hash_Length];
    1531              :     uint8_t Kae[kMAX_Hash_Length];
    1532              :     uint8_t * Kca;
    1533              :     uint8_t * Kcb;
    1534              :     uint8_t * Ka;
    1535              :     uint8_t * Ke;
    1536              : };
    1537              : 
    1538              : struct alignas(size_t) Spake2pOpaqueContext
    1539              : {
    1540              :     uint8_t mOpaque[kMAX_Spake2p_Context_Size];
    1541              : };
    1542              : 
    1543              : class Spake2p_P256_SHA256_HKDF_HMAC : public Spake2p
    1544              : {
    1545              : public:
    1546           10 :     Spake2p_P256_SHA256_HKDF_HMAC() : Spake2p(kP256_FE_Length, kP256_Point_Length, kSHA256_Hash_Length)
    1547              :     {
    1548           10 :         memset(&mSpake2pContext, 0, sizeof(mSpake2pContext));
    1549           10 :     }
    1550              : 
    1551           25 :     ~Spake2p_P256_SHA256_HKDF_HMAC() override { Spake2p_P256_SHA256_HKDF_HMAC::Clear(); }
    1552              : 
    1553              :     void Clear() override;
    1554              :     CHIP_ERROR Mac(const uint8_t * key, size_t key_len, const uint8_t * in, size_t in_len, MutableByteSpan & out_span) override;
    1555              :     CHIP_ERROR MacVerify(const uint8_t * key, size_t key_len, const uint8_t * mac, size_t mac_len, const uint8_t * in,
    1556              :                          size_t in_len) override;
    1557              :     CHIP_ERROR FELoad(const uint8_t * in, size_t in_len, void * fe) override;
    1558              :     CHIP_ERROR FEWrite(const void * fe, uint8_t * out, size_t out_len) override;
    1559              :     CHIP_ERROR FEGenerate(void * fe) override;
    1560              :     CHIP_ERROR FEMul(void * fer, const void * fe1, const void * fe2) override;
    1561              : 
    1562              :     CHIP_ERROR PointLoad(const uint8_t * in, size_t in_len, void * R) override;
    1563              :     CHIP_ERROR PointWrite(const void * R, uint8_t * out, size_t out_len) override;
    1564              :     CHIP_ERROR PointMul(void * R, const void * P1, const void * fe1) override;
    1565              :     CHIP_ERROR PointAddMul(void * R, const void * P1, const void * fe1, const void * P2, const void * fe2) override;
    1566              :     CHIP_ERROR PointInvert(void * R) override;
    1567              :     CHIP_ERROR PointCofactorMul(void * R) override;
    1568              :     CHIP_ERROR PointIsValid(void * R) override;
    1569              : 
    1570              :     CHIP_ERROR ComputeW0(uint8_t * w0out, size_t * w0_len, const uint8_t * w0sin, size_t w0sin_len) override;
    1571              :     CHIP_ERROR ComputeL(uint8_t * Lout, size_t * L_len, const uint8_t * w1sin, size_t w1sin_len) override;
    1572              : 
    1573              : protected:
    1574              :     CHIP_ERROR InitImpl() override;
    1575              :     CHIP_ERROR Hash(const uint8_t * in, size_t in_len) override;
    1576              :     CHIP_ERROR HashFinalize(MutableByteSpan & out_span) override;
    1577              :     CHIP_ERROR KDF(const uint8_t * secret, size_t secret_length, const uint8_t * salt, size_t salt_length, const uint8_t * info,
    1578              :                    size_t info_length, uint8_t * out, size_t out_length) override;
    1579              : 
    1580              : private:
    1581              :     CHIP_ERROR InitInternal();
    1582              :     Hash_SHA256_stream sha256_hash_ctx;
    1583              : 
    1584              :     Spake2pOpaqueContext mSpake2pContext;
    1585              : };
    1586              : 
    1587              : /**
    1588              :  * @brief Class used for verifying PASE secure sessions.
    1589              :  **/
    1590              : class Spake2pVerifier
    1591              : {
    1592              : public:
    1593              :     uint8_t mW0[kP256_FE_Length];
    1594              :     uint8_t mL[kP256_Point_Length];
    1595              : 
    1596              :     CHIP_ERROR Serialize(MutableByteSpan & outSerialized) const;
    1597              :     CHIP_ERROR Deserialize(const ByteSpan & inSerialized);
    1598              : 
    1599              :     /**
    1600              :      * @brief Generate the Spake2+ verifier.
    1601              :      *
    1602              :      * @param pbkdf2IterCount Iteration count for PBKDF2 function
    1603              :      * @param salt            Salt to be used for Spake2+ operation
    1604              :      * @param setupPin        Provided setup PIN (passcode)
    1605              :      *
    1606              :      * @return CHIP_ERROR     The result of Spake2+ verifier generation
    1607              :      */
    1608              :     CHIP_ERROR Generate(uint32_t pbkdf2IterCount, const ByteSpan & salt, uint32_t setupPin);
    1609              : 
    1610              :     /**
    1611              :      * @brief Compute the initiator values (w0s, w1s) used for PAKE input.
    1612              :      *
    1613              :      * @param pbkdf2IterCount Iteration count for PBKDF2 function
    1614              :      * @param salt            Salt to be used for Spake2+ operation
    1615              :      * @param setupPin        Provided setup PIN (passcode)
    1616              :      * @param ws              The output pair (w0s, w1s) stored sequentially
    1617              :      * @param ws_len          The output length
    1618              :      *
    1619              :      * @return CHIP_ERROR     The result from running PBKDF2
    1620              :      */
    1621              :     static CHIP_ERROR ComputeWS(uint32_t pbkdf2IterCount, const ByteSpan & salt, uint32_t setupPin, uint8_t * ws, uint32_t ws_len);
    1622              : };
    1623              : 
    1624              : /**
    1625              :  * @brief Serialized format of the Spake2+ Verifier components.
    1626              :  *
    1627              :  *  This is used when the Verifier should be presented in a serialized form.
    1628              :  *  For example, when it is generated using PBKDF function, when stored in the
    1629              :  *  memory or when sent over the wire.
    1630              :  *  The serialized format is concatentation of 'W0' and 'L' verifier components:
    1631              :  *      { Spake2pVerifier.mW0[kP256_FE_Length], Spake2pVerifier.mL[kP256_Point_Length] }
    1632              :  **/
    1633              : typedef uint8_t Spake2pVerifierSerialized[kSpake2p_VerifierSerialized_Length];
    1634              : 
    1635              : /**
    1636              :  * @brief Compute the compressed fabric identifier used for operational discovery service
    1637              :  *        records from a Node's root public key and Fabric ID. On success, out_compressed_fabric_id
    1638              :  *        will have a size of exactly kCompressedFabricIdentifierSize.
    1639              :  *
    1640              :  * Errors are:
    1641              :  *   - CHIP_ERROR_INVALID_ARGUMENT if root_public_key is invalid
    1642              :  *   - CHIP_ERROR_BUFFER_TOO_SMALL if out_compressed_fabric_id is too small for serialization
    1643              :  *   - CHIP_ERROR_INTERNAL on any unexpected crypto or data conversion errors.
    1644              :  *
    1645              :  * @param[in] root_public_key The root public key associated with the node's fabric
    1646              :  * @param[in] fabric_id The fabric ID associated with the node's fabric
    1647              :  * @param[out] out_compressed_fabric_id Span where output will be written. Its size must be >= kCompressedFabricIdentifierSize.
    1648              :  * @returns a CHIP_ERROR (see above) on failure or CHIP_NO_ERROR otherwise.
    1649              :  */
    1650              : CHIP_ERROR GenerateCompressedFabricId(const Crypto::P256PublicKey & root_public_key, uint64_t fabric_id,
    1651              :                                       MutableByteSpan & out_compressed_fabric_id);
    1652              : 
    1653              : /**
    1654              :  * @brief Compute the compressed fabric identifier used for operational discovery service
    1655              :  *        records from a Node's root public key and Fabric ID.  This is a conveniance
    1656              :  *        overload that writes to a uint64_t (CompressedFabricId) type.
    1657              :  *
    1658              :  * @param[in] rootPublicKey The root public key associated with the node's fabric
    1659              :  * @param[in] fabricId The fabric ID associated with the node's fabric
    1660              :  * @param[out] compressedFabricId output location for compressed fabric ID
    1661              :  * @returns a CHIP_ERROR on failure or CHIP_NO_ERROR otherwise.
    1662              :  */
    1663              : CHIP_ERROR GenerateCompressedFabricId(const Crypto::P256PublicKey & rootPublicKey, uint64_t fabricId,
    1664              :                                       uint64_t & compressedFabricId);
    1665              : 
    1666              : enum class CertificateChainValidationResult
    1667              : {
    1668              :     kSuccess = 0,
    1669              : 
    1670              :     kRootFormatInvalid   = 100,
    1671              :     kRootArgumentInvalid = 101,
    1672              : 
    1673              :     kICAFormatInvalid   = 200,
    1674              :     kICAArgumentInvalid = 201,
    1675              : 
    1676              :     kLeafFormatInvalid   = 300,
    1677              :     kLeafArgumentInvalid = 301,
    1678              : 
    1679              :     kChainInvalid = 400,
    1680              : 
    1681              :     kNoMemory = 500,
    1682              : 
    1683              :     kInternalFrameworkError = 600,
    1684              : };
    1685              : 
    1686              : CHIP_ERROR ValidateCertificateChain(const uint8_t * rootCertificate, size_t rootCertificateLen, const uint8_t * caCertificate,
    1687              :                                     size_t caCertificateLen, const uint8_t * leafCertificate, size_t leafCertificateLen,
    1688              :                                     CertificateChainValidationResult & result);
    1689              : 
    1690              : enum class AttestationCertType
    1691              : {
    1692              :     kPAA = 0,
    1693              :     kPAI = 1,
    1694              :     kDAC = 2,
    1695              : };
    1696              : 
    1697              : CHIP_ERROR VerifyAttestationCertificateFormat(const ByteSpan & cert, AttestationCertType certType);
    1698              : 
    1699              : /**
    1700              :  * @brief Generate a VendorFabricBindingMessage as used by the Fabric Table Vendor ID Verification Procedure.
    1701              :  *
    1702              :  * @param[in] fabricBindingVersion - Version of binding payload to generate. outputSpan size requirements are based on this.
    1703              :  * @param[in] rootPublicKey - Root public key for the fabric in question
    1704              :  * @param[in] fabricId - Fabric ID for the fabric in question
    1705              :  * @param[in] vendorId - Vendor ID for the fabric in question
    1706              :  * @param[inout] outputSpan - Span that will receive the binding message. Must be large enough for the
    1707              :  *                            payload (otherwise CHIP_ERROR_BUFFER_TOO_SMALL) and will be resized to fit.
    1708              :  * @return CHIP_NO_ERROR on success, otherwise another CHIP_ERROR value representative of the failure.
    1709              :  */
    1710              : CHIP_ERROR GenerateVendorFabricBindingMessage(FabricBindingVersion fabricBindingVersion, const P256PublicKey & rootPublicKey,
    1711              :                                               FabricId fabricId, uint16_t vendorId, MutableByteSpan & outputSpan);
    1712              : 
    1713              : /**
    1714              :  * @brief Generate the message to be signed for the Fabric Table Vendor ID Verification Procedure.
    1715              :  *
    1716              :  * The Fabric Binding Version value will be recovered from the vendorFabricBindingMessage.
    1717              :  *
    1718              :  * @param fabricIndex - Fabric Index for the fabric in question
    1719              :  * @param clientChallenge - Client challenge to use
    1720              :  * @param attestationChallenge - Attestation challenge to use
    1721              :  * @param vendorFabricBindingMessage - The VendorFabricBindingMessage previously computed for the fabric
    1722              :  * @param vidVerificationStatement - The VID Verification Statement to include in signature (may be empty)
    1723              :  * @param outputSpan - Span that will receive the to-be-signed message. Must be large enough for the
    1724              :  *                     payload (otherwise CHIP_ERROR_BUFFER_TOO_SMALL) and will be resized to fit.
    1725              :  * @return CHIP_NO_ERROR on success, otherwise another CHIP_ERROR value representative of the failure.
    1726              :  */
    1727              : CHIP_ERROR GenerateVendorIdVerificationToBeSigned(FabricIndex fabricIndex, const ByteSpan & clientChallenge,
    1728              :                                                   const ByteSpan & attestationChallenge,
    1729              :                                                   const ByteSpan & vendorFabricBindingMessage,
    1730              :                                                   const ByteSpan & vidVerificationStatement, MutableByteSpan & outputSpan);
    1731              : 
    1732              : /**
    1733              :  * @brief Validate notBefore timestamp of a certificate (candidateCertificate) against validity period of the
    1734              :  *        issuer certificate (issuerCertificate).
    1735              :  *
    1736              :  * Errors are:
    1737              :  *   - CHIP_ERROR_CERT_EXPIRED if the candidateCertificate timestamp does not satisfy the issuerCertificate's timestamp.
    1738              :  *   - CHIP_ERROR_INVALID_ARGUMENT when passing an invalid argument.
    1739              :  *   - CHIP_ERROR_INTERNAL on any unexpected crypto or data conversion errors.
    1740              :  *
    1741              :  *  @param candidateCertificate     A DER Certificate ByteSpan those notBefore timestamp to be evaluated.
    1742              :  *  @param issuerCertificate        A DER Certificate ByteSpan used to evaluate validity timestamp of the candidateCertificate.
    1743              :  *
    1744              :  *  @returns a CHIP_ERROR (see above) on failure or CHIP_NO_ERROR otherwise.
    1745              :  **/
    1746              : CHIP_ERROR IsCertificateValidAtIssuance(const ByteSpan & candidateCertificate, const ByteSpan & issuerCertificate);
    1747              : 
    1748              : /**
    1749              :  * @brief Validate a certificate's validity date against current time.
    1750              :  *
    1751              :  * Errors are:
    1752              :  *   - CHIP_ERROR_CERT_EXPIRED if the certificate has expired.
    1753              :  *   - CHIP_ERROR_INVALID_ARGUMENT when passing an invalid argument.
    1754              :  *   - CHIP_ERROR_INTERNAL on any unexpected crypto or data conversion errors.
    1755              :  *
    1756              :  *  @param certificate A DER Certificate ByteSpan used as the validity reference to be checked against current time.
    1757              :  *
    1758              :  *  @returns a CHIP_ERROR (see above) on failure or CHIP_NO_ERROR otherwise.
    1759              :  **/
    1760              : CHIP_ERROR IsCertificateValidAtCurrentTime(const ByteSpan & certificate);
    1761              : 
    1762              : CHIP_ERROR ExtractPubkeyFromX509Cert(const ByteSpan & certificate, Crypto::P256PublicKey & pubkey);
    1763              : 
    1764              : /**
    1765              :  * @brief Extracts the Subject Key Identifier from an X509 Certificate.
    1766              :  **/
    1767              : CHIP_ERROR ExtractSKIDFromX509Cert(const ByteSpan & certificate, MutableByteSpan & skid);
    1768              : 
    1769              : /**
    1770              :  * @brief Extracts the Authority Key Identifier from an X509 Certificate.
    1771              :  **/
    1772              : CHIP_ERROR ExtractAKIDFromX509Cert(const ByteSpan & certificate, MutableByteSpan & akid);
    1773              : 
    1774              : /**
    1775              :  * @brief Extracts the CRL Distribution Point (CDP) extension from an X509 ASN.1 Encoded Certificate.
    1776              :  *        The returned value only covers the URI of the CDP. Only a single URI distribution point
    1777              :  *        GeneralName is supported, and only those that start with "http://" and "https://".
    1778              :  *
    1779              :  * @returns CHIP_ERROR_NOT_FOUND if not found or wrong format.
    1780              :  *          CHIP_NO_ERROR otherwise.
    1781              :  **/
    1782              : CHIP_ERROR ExtractCRLDistributionPointURIFromX509Cert(const ByteSpan & certificate, MutableCharSpan & cdpurl);
    1783              : 
    1784              : /**
    1785              :  * @brief Extracts the CRL Distribution Point (CDP) extension's cRLIssuer Name from an X509 ASN.1 Encoded Certificate.
    1786              :  *        The value is copied into buffer in a raw ASN.1 X.509 format. This format should be directly comparable
    1787              :  *        with the result of ExtractSubjectFromX509Cert().
    1788              :  *
    1789              :  * @returns CHIP_ERROR_NOT_FOUND if not found or wrong format.
    1790              :  *          CHIP_NO_ERROR otherwise.
    1791              :  **/
    1792              : CHIP_ERROR ExtractCDPExtensionCRLIssuerFromX509Cert(const ByteSpan & certificate, MutableByteSpan & crlIssuer);
    1793              : 
    1794              : /**
    1795              :  * @brief Extracts Serial Number from X509 Certificate.
    1796              :  **/
    1797              : CHIP_ERROR ExtractSerialNumberFromX509Cert(const ByteSpan & certificate, MutableByteSpan & serialNumber);
    1798              : 
    1799              : /**
    1800              :  * @brief Extracts Subject Distinguished Name from X509 Certificate. The value is copied into buffer in a raw ASN.1 X.509 format.
    1801              :  **/
    1802              : CHIP_ERROR ExtractSubjectFromX509Cert(const ByteSpan & certificate, MutableByteSpan & subject);
    1803              : 
    1804              : /**
    1805              :  * @brief Extracts Issuer Distinguished Name from X509 Certificate. The value is copied into buffer in a raw ASN.1 X.509 format.
    1806              :  **/
    1807              : CHIP_ERROR ExtractIssuerFromX509Cert(const ByteSpan & certificate, MutableByteSpan & issuer);
    1808              : 
    1809              : class PemEncoder
    1810              : {
    1811              : public:
    1812              :     /**
    1813              :      * @brief Construct a PEM encoder for element type `encodedElement` whose DER data is in `derBytes` span.
    1814              :      *
    1815              :      * LIFETIME: both encodedElement and derBytes lifetime must be >= PemEncoder lifetime.
    1816              :      *           PemEncoder references these while processing `NextLine()` calls.
    1817              :      *
    1818              :      * @param encodedElement - Element type string to include in header/footer (e.g. "CERTIFICATE"). Caller must provide correct
    1819              :      * uppercase.
    1820              :      * @param derBytes - Byte span containing data to encode. May be empty.
    1821              :      */
    1822            3 :     explicit PemEncoder(const char * encodedElement, ByteSpan derBytes) : mEncodedElement(encodedElement), mDerBytes(derBytes) {}
    1823              : 
    1824              :     // No copies.
    1825              :     PemEncoder(const PemEncoder &)             = delete;
    1826              :     PemEncoder & operator=(const PemEncoder &) = delete;
    1827              : 
    1828              :     /**
    1829              :      * @brief Returns the pointer to the next null-terminated line of the encoding, or nullptr if done.
    1830              :      *
    1831              :      * The returned pointer has the lifetime of this class and during that lifetime will always point
    1832              :      * to valid memory.
    1833              :      *
    1834              :      * When header/footer are written, the heading type (`encodedElement` value) such as
    1835              :      * `CERTIFICATE` is clamped so that the entire header line with `-----BEGIN ${encodedElement}-----`
    1836              :      * and footer line with `-----END ${encodedElement}-----` are not wider than 64 bytes. This
    1837              :      * will not happen in practice with the types of things this is meant to encode.
    1838              :      *
    1839              :      * Usage should be in a loop, for example:
    1840              :      *
    1841              :      *   std::vector<std::string> pemLines;
    1842              :      *
    1843              :      *   PemEncoder encoder("CERTIFICATE", TestCerts::sTestCert_PAA_FFF1_Cert);
    1844              :      *
    1845              :      *   const char* line = encoder.NextLine();
    1846              :      *   while (line)
    1847              :      *   {
    1848              :      *       pemLines.push_back(std::string{ line });
    1849              :      *       line = encoder.NextLine();
    1850              :      *   }
    1851              :      *
    1852              :      * @return a pointer to the internal line buffer for next line or nullptr when done.
    1853              :      */
    1854              :     const char * NextLine();
    1855              : 
    1856              : private:
    1857              :     static constexpr size_t kNumBytesPerLine = 48u;
    1858              :     static constexpr size_t kLineBufferSize  = 64u + 1u; // PEM expects 64 characters wide and a null terminator at least.
    1859              :     static_assert(kLineBufferSize == (BASE64_ENCODED_LEN(kNumBytesPerLine) + 1), "Internal incoherence of library configuration!");
    1860              : 
    1861              :     enum State : int
    1862              :     {
    1863              :         kPrintHeader = 0,
    1864              :         kPrintBody   = 1,
    1865              :         kPrintFooter = 2,
    1866              :         kDone        = 3,
    1867              :     };
    1868              : 
    1869              :     const char * mEncodedElement; // "CERTIFICATE", "EC PUBLIC KEY", etc. Must be capitalized by caller.
    1870              :     ByteSpan mDerBytes;
    1871              :     State mState           = State::kPrintHeader;
    1872              :     size_t mProcessedBytes = 0;
    1873              :     StringBuilder<kLineBufferSize> mStringBuilder{};
    1874              : };
    1875              : 
    1876              : // Utility class to take subject Key IDs (AKID/SKID) and convert them to DCL format ("A5:FF:00.....:DE:AD").
    1877              : class KeyIdStringifier
    1878              : {
    1879              : public:
    1880            9 :     KeyIdStringifier() = default;
    1881              : 
    1882              :     /**
    1883              :      * @brief Returns the null-terminated string buffer owned by the class containing converted KeyID.
    1884              :      *
    1885              :      * LIFETIME NOTE: The last returned value from KeyIdToHex is valid until the next call.
    1886              :      *
    1887              :      * This is optimized for standard 20-byte AKID/SKID but works for any length, truncating very long ones.
    1888              :      *
    1889              :      * @param keyIdBuffer - buffer of bytes of the key ID.
    1890              :      * @return pointer to class-owned storage of a null-terminated string in DCL format.
    1891              :      */
    1892            9 :     const char * KeyIdToHex(ByteSpan keyIdBuffer)
    1893              :     {
    1894            9 :         mStringBuilder.Reset();
    1895            9 :         if (keyIdBuffer.empty())
    1896              :         {
    1897            0 :             mStringBuilder.Add("<EMPTY KEY ID>");
    1898            0 :             return mStringBuilder.c_str();
    1899              :         }
    1900              : 
    1901            9 :         mStringBuilder.AddFormat("%02X", keyIdBuffer[0]);
    1902          180 :         for (size_t i = 1; i < keyIdBuffer.size(); ++i)
    1903              :         {
    1904          171 :             mStringBuilder.Add(":");
    1905          171 :             mStringBuilder.AddFormat("%02X", keyIdBuffer[i]);
    1906              :         }
    1907              : 
    1908            9 :         return mStringBuilder.AddMarkerIfOverflow().c_str();
    1909              :     }
    1910              : 
    1911              : private:
    1912              :     StringBuilder<(Crypto::kAuthorityKeyIdentifierLength * 3) + 1> mStringBuilder;
    1913              : };
    1914              : 
    1915              : /**
    1916              :  * @brief Checks for resigned version of the certificate in the list and returns it.
    1917              :  *
    1918              :  * The following conditions SHOULD be satisfied for the certificate to qualify as
    1919              :  * a resigned version of a reference certificate:
    1920              :  *   - SKID of the candidate and the reference certificate should match.
    1921              :  *   - SubjectDN of the candidate and the reference certificate should match.
    1922              :  *
    1923              :  * If no resigned version is found then reference certificate itself is returned.
    1924              :  *
    1925              :  *  @param referenceCertificate       A DER certificate.
    1926              :  *  @param candidateCertificates      A pointer to the list of DER Certificates, which should be searched
    1927              :  *                                    for the resigned version of `referenceCertificate`.
    1928              :  *  @param candidateCertificatesCount Number of certificates in the `candidateCertificates` list.
    1929              :  *  @param outCertificate             A reference to the certificate or it's resigned version if found.
    1930              :  *                                    Note that it points to either `referenceCertificate` or one of
    1931              :  *                                    `candidateCertificates`, but it doesn't copy data.
    1932              :  *
    1933              :  *  @returns error if there is certificate parsing/format issue or CHIP_NO_ERROR otherwise.
    1934              :  **/
    1935              : CHIP_ERROR ReplaceCertIfResignedCertFound(const ByteSpan & referenceCertificate, const ByteSpan * candidateCertificates,
    1936              :                                           size_t candidateCertificatesCount, ByteSpan & outCertificate);
    1937              : 
    1938              : /**
    1939              :  * Defines DN attribute types that can include endocing of VID/PID parameters.
    1940              :  */
    1941              : enum class DNAttrType
    1942              : {
    1943              :     kUnspecified = 0,
    1944              :     kCommonName  = 1,
    1945              :     kMatterVID   = 2,
    1946              :     kMatterPID   = 3,
    1947              : };
    1948              : 
    1949              : /**
    1950              :  *  @struct AttestationCertVidPid
    1951              :  *
    1952              :  *  @brief
    1953              :  *    A data structure representing Attestation Certificate VID and PID attributes.
    1954              :  */
    1955              : struct AttestationCertVidPid
    1956              : {
    1957              :     Optional<VendorId> mVendorId;
    1958              :     Optional<uint16_t> mProductId;
    1959              : 
    1960          620 :     bool Initialized() const { return (mVendorId.HasValue() || mProductId.HasValue()); }
    1961              : };
    1962              : 
    1963              : /**
    1964              :  * @brief Extracts VID and PID attributes from the DN Attribute string.
    1965              :  *        If attribute is not present the corresponding output value stays uninitialized.
    1966              :  *
    1967              :  * @return CHIP_ERROR_INVALID_ARGUMENT if wrong input is provided.
    1968              :  *         CHIP_ERROR_WRONG_CERT_DN if encoding of kMatterVID and kMatterPID attributes is wrong.
    1969              :  *         CHIP_NO_ERROR otherwise.
    1970              :  **/
    1971              : CHIP_ERROR ExtractVIDPIDFromAttributeString(DNAttrType attrType, const ByteSpan & attr,
    1972              :                                             AttestationCertVidPid & vidpidFromMatterAttr, AttestationCertVidPid & vidpidFromCNAttr);
    1973              : 
    1974              : /**
    1975              :  * @brief Extracts VID and PID attributes from the Subject DN of an X509 Certificate.
    1976              :  *        If attribute is not present the corresponding output value stays uninitialized.
    1977              :  **/
    1978              : CHIP_ERROR ExtractVIDPIDFromX509Cert(const ByteSpan & x509Cert, AttestationCertVidPid & vidpid);
    1979              : 
    1980              : /**
    1981              :  * @brief The set of credentials needed to operate group message security with symmetric keys.
    1982              :  */
    1983              : typedef struct GroupOperationalCredentials
    1984              : {
    1985              :     /// Validity start time in microseconds since 2000-01-01T00:00:00 UTC ("the Epoch")
    1986              :     uint64_t start_time;
    1987              :     /// Session Id
    1988              :     uint16_t hash;
    1989              :     /// Operational group key
    1990              :     uint8_t encryption_key[Crypto::CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES];
    1991              :     /// Privacy key
    1992              :     uint8_t privacy_key[Crypto::CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES];
    1993              : } GroupOperationalCredentials;
    1994              : 
    1995              : /**
    1996              :  * @brief Opaque context used to protect a symmetric key. The key operations must
    1997              :  *        be performed without exposing the protected key value.
    1998              :  */
    1999              : class SymmetricKeyContext
    2000              : {
    2001              : public:
    2002              :     /**
    2003              :      * @brief Returns the symmetric key hash
    2004              :      *
    2005              :      * TODO: Replace GetKeyHash() with DeriveGroupSessionId(SymmetricKeyContext &, uint16_t & session_id)
    2006              :      *
    2007              :      * @return Group Key Hash
    2008              :      */
    2009              :     virtual uint16_t GetKeyHash() = 0;
    2010              : 
    2011           11 :     virtual ~SymmetricKeyContext() = default;
    2012              :     /**
    2013              :      * @brief Perform the message encryption as described in 4.7.2. (Security Processing of Outgoing Messages)
    2014              :      * @param[in] plaintext     Outgoing message payload.
    2015              :      * @param[in] aad           Additional data (message header contents)
    2016              :      * @param[in] nonce         Nonce (Security Flags | Message Counter | Source Node ID)
    2017              :      * @param[out] mic          Outgoing Message Integrity Check
    2018              :      * @param[out] ciphertext   Outgoing encrypted payload. Must be at least as big as plaintext. The same buffer may be used both
    2019              :      * for ciphertext, and plaintext.
    2020              :      * @return CHIP_ERROR
    2021              :      */
    2022              :     virtual CHIP_ERROR MessageEncrypt(const ByteSpan & plaintext, const ByteSpan & aad, const ByteSpan & nonce,
    2023              :                                       MutableByteSpan & mic, MutableByteSpan & ciphertext) const = 0;
    2024              :     /**
    2025              :      * @brief Perform the message decryption as described in 4.7.3.(Security Processing of Incoming Messages)
    2026              :      * @param[in] ciphertext    Incoming encrypted payload
    2027              :      * @param[in] aad           Additional data (message header contents)
    2028              :      * @param[in] nonce         Nonce (Security Flags | Message Counter | Source Node ID)
    2029              :      * @param[in] mic           Incoming Message Integrity Check
    2030              :      * @param[out] plaintext     Incoming message payload. Must be at least as big as ciphertext. The same buffer may be used both
    2031              :      * for plaintext, and ciphertext.
    2032              :      * @return CHIP_ERROR
    2033              :      */
    2034              :     virtual CHIP_ERROR MessageDecrypt(const ByteSpan & ciphertext, const ByteSpan & aad, const ByteSpan & nonce,
    2035              :                                       const ByteSpan & mic, MutableByteSpan & plaintext) const = 0;
    2036              : 
    2037              :     /**
    2038              :      * @brief Perform privacy encoding as described in 4.8.2. (Privacy Processing of Outgoing Messages)
    2039              :      * @param[in] input         Message header to privacy encrypt
    2040              :      * @param[in] nonce         Privacy Nonce = session_id | mic
    2041              :      * @param[out] output       Message header obfuscated
    2042              :      * @return CHIP_ERROR
    2043              :      */
    2044              :     virtual CHIP_ERROR PrivacyEncrypt(const ByteSpan & input, const ByteSpan & nonce, MutableByteSpan & output) const = 0;
    2045              : 
    2046              :     /**
    2047              :      * @brief Perform privacy decoding as described in 4.8.3. (Privacy Processing of Incoming Messages)
    2048              :      * @param[in] input         Message header to privacy decrypt
    2049              :      * @param[in] nonce         Privacy Nonce = session_id | mic
    2050              :      * @param[out] output       Message header deobfuscated
    2051              :      * @return CHIP_ERROR
    2052              :      */
    2053              :     virtual CHIP_ERROR PrivacyDecrypt(const ByteSpan & input, const ByteSpan & nonce, MutableByteSpan & output) const = 0;
    2054              : 
    2055              :     /**
    2056              :      * @brief Release resources such as dynamic memory used to allocate this instance of the SymmetricKeyContext
    2057              :      */
    2058              :     virtual void Release() = 0;
    2059              : };
    2060              : 
    2061              : /**
    2062              :  *  @brief Derives the Operational Group Key using the Key Derivation Function (KDF) from the given epoch key.
    2063              :  * @param[in] epoch_key  The epoch key. Must be CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES bytes length.
    2064              :  * @param[in] compressed_fabric_id The compressed fabric ID for the fabric (big endian byte string)
    2065              :  * @param[out] out_key  Symmetric key used as the encryption key during message processing for group communication.
    2066              :  The buffer size must be at least CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES bytes length.
    2067              :  * @return Returns a CHIP_NO_ERROR on succcess, or CHIP_ERROR_INTERNAL if the provided key is invalid.
    2068              :  **/
    2069              : CHIP_ERROR DeriveGroupOperationalKey(const ByteSpan & epoch_key, const ByteSpan & compressed_fabric_id, MutableByteSpan & out_key);
    2070              : 
    2071              : /**
    2072              :  *  @brief Derives the Group Session ID from a given operational group key using
    2073              :  *         the Key Derivation Function (Group Key Hash)
    2074              :  * @param[in] operational_key  The operational group key. Must be CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES bytes length.
    2075              :  * @param[out] session_id  Output of the Group Key Hash
    2076              :  * @return Returns a CHIP_NO_ERROR on succcess, or CHIP_ERROR_INVALID_ARGUMENT if the provided key is invalid.
    2077              :  **/
    2078              : CHIP_ERROR DeriveGroupSessionId(const ByteSpan & operational_key, uint16_t & session_id);
    2079              : 
    2080              : /**
    2081              :  *  @brief Derives the Privacy Group Key using the Key Derivation Function (KDF) from the given epoch key.
    2082              :  * @param[in] epoch_key  The epoch key. Must be CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES bytes length.
    2083              :  * @param[out] out_key  Symmetric key used as the privacy key during message processing for group communication.
    2084              :  *                      The buffer size must be at least CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES bytes length.
    2085              :  * @return Returns a CHIP_NO_ERROR on succcess, or CHIP_ERROR_INTERNAL if the provided key is invalid.
    2086              :  **/
    2087              : CHIP_ERROR DeriveGroupPrivacyKey(const ByteSpan & epoch_key, MutableByteSpan & out_key);
    2088              : 
    2089              : /**
    2090              :  *  @brief Derives the complete set of credentials needed for group security.
    2091              :  *
    2092              :  * This function will derive the Encryption Key, Group Key Hash (Session Id), and Privacy Key
    2093              :  * for the given Epoch Key and Compressed Fabric Id.
    2094              :  * @param[in] epoch_key  The epoch key. Must be CHIP_CRYPTO_SYMMETRIC_KEY_LENGTH_BYTES bytes length.
    2095              :  * @param[in] compressed_fabric_id The compressed fabric ID for the fabric (big endian byte string)
    2096              :  * @param[out] operational_credentials The set of Symmetric keys used during message processing for group communication.
    2097              :  * @return Returns a CHIP_NO_ERROR on succcess, or CHIP_ERROR_INTERNAL if the provided key is invalid.
    2098              :  **/
    2099              : CHIP_ERROR DeriveGroupOperationalCredentials(const ByteSpan & epoch_key, const ByteSpan & compressed_fabric_id,
    2100              :                                              GroupOperationalCredentials & operational_credentials);
    2101              : } // namespace Crypto
    2102              : } // namespace chip
        

Generated by: LCOV version 2.0-1