Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2020 Project CHIP Authors
       4             :  *    All rights reserved.
       5             :  *
       6             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       7             :  *    you may not use this file except in compliance with the License.
       8             :  *    You may obtain a copy of the License at
       9             :  *
      10             :  *        http://www.apache.org/licenses/LICENSE-2.0
      11             :  *
      12             :  *    Unless required by applicable law or agreed to in writing, software
      13             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      14             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15             :  *    See the License for the specific language governing permissions and
      16             :  *    limitations under the License.
      17             :  */
      18             : 
      19             : /**
      20             :  *    @file
      21             :  *      This file defines the CHIP Secure Session object that provides
      22             :  *      APIs for encrypting/decryting data using cryptographic keys.
      23             :  *
      24             :  */
      25             : 
      26             : #pragma once
      27             : 
      28             : #include <crypto/CHIPCryptoPAL.h>
      29             : #include <crypto/SessionKeystore.h>
      30             : #include <lib/core/CHIPCore.h>
      31             : #include <lib/support/Span.h>
      32             : #include <transport/raw/MessageHeader.h>
      33             : 
      34             : namespace chip {
      35             : 
      36             : class DLL_EXPORT CryptoContext
      37             : {
      38             : public:
      39             :     static constexpr size_t kPrivacyNonceMicFragmentOffset = 5;
      40             :     static constexpr size_t kPrivacyNonceMicFragmentLength = 11;
      41             :     static constexpr size_t kAESCCMNonceLen                = 13;
      42             :     using NonceStorage                                     = std::array<uint8_t, kAESCCMNonceLen>;
      43             :     using NonceView                                        = FixedSpan<uint8_t, kAESCCMNonceLen>;
      44             :     using ConstNonceView                                   = FixedSpan<const uint8_t, kAESCCMNonceLen>;
      45             : 
      46             :     CryptoContext();
      47             :     ~CryptoContext();
      48             :     CryptoContext(CryptoContext &&)      = delete;
      49             :     CryptoContext(const CryptoContext &) = delete;
      50          15 :     explicit CryptoContext(Crypto::SymmetricKeyContext * context) : mKeyContext(context) {}
      51             :     CryptoContext & operator=(const CryptoContext &) = delete;
      52             :     CryptoContext & operator=(CryptoContext &&)      = delete;
      53             : 
      54             :     /**
      55             :      *    Whether the current node initiated the session, or it is responded to a session request.
      56             :      */
      57             :     enum class SessionRole : uint8_t
      58             :     {
      59             :         kInitiator, /**< We initiated the session. */
      60             :         kResponder, /**< We responded to the session request. */
      61             :     };
      62             : 
      63             :     enum class SessionInfoType : uint8_t
      64             :     {
      65             :         kSessionEstablishment, /**< A new secure session is established. */
      66             :         kSessionResumption,    /**< An old session is being resumed. */
      67             :     };
      68             : 
      69             :     /**
      70             :      * @brief
      71             :      *   Derive a shared key. The derived key will be used for encrypting/decrypting
      72             :      *   data exchanged on the secure channel.
      73             :      *
      74             :      * @param keystore           Session keystore for management of symmetric encryption keys
      75             :      * @param local_keypair      A reference to local ECP keypair
      76             :      * @param remote_public_key  A reference to peer's public key
      77             :      * @param salt               A reference to the initial salt used for deriving the keys
      78             :      * @param infoType           The info buffer to use for deriving session keys
      79             :      * @param role               Role of the new session (initiator or responder)
      80             :      * @return CHIP_ERROR        The result of key derivation
      81             :      */
      82             :     CHIP_ERROR InitFromKeyPair(Crypto::SessionKeystore & keystore, const Crypto::P256Keypair & local_keypair,
      83             :                                const Crypto::P256PublicKey & remote_public_key, const ByteSpan & salt, SessionInfoType infoType,
      84             :                                SessionRole role);
      85             : 
      86             :     /**
      87             :      * @brief Derive session keys and the attestation challenge from the shared secret.
      88             :      *
      89             :      * @param keystore           Session keystore for management of symmetric encryption keys
      90             :      * @param secret             A reference to the shared secret
      91             :      * @param salt               A reference to the initial salt used for deriving the keys
      92             :      * @param infoType           The info buffer to use for deriving session keys
      93             :      * @param role               Role of the new session (initiator or responder)
      94             :      * @return CHIP_ERROR        The result of key derivation
      95             :      */
      96             :     CHIP_ERROR InitFromSecret(Crypto::SessionKeystore & keystore, const ByteSpan & secret, const ByteSpan & salt,
      97             :                               SessionInfoType infoType, SessionRole role);
      98             : 
      99             :     /**
     100             :      * @brief Derive session keys and the attestation challenge from the HKDF key.
     101             :      *
     102             :      * @param keystore           Session keystore for management of symmetric encryption keys
     103             :      * @param hkdfKey            HKDF key handle
     104             :      * @param salt               A reference to the initial salt used for deriving the keys
     105             :      * @param infoType           The info buffer to use for deriving session keys
     106             :      * @param role               Role of the new session (initiator or responder)
     107             :      * @return CHIP_ERROR        The result of key derivation
     108             :      */
     109             :     CHIP_ERROR InitFromSecret(Crypto::SessionKeystore & keystore, const Crypto::HkdfKeyHandle & hkdfKey, const ByteSpan & salt,
     110             :                               SessionInfoType infoType, SessionRole role);
     111             : 
     112             :     /** @brief Build a Nonce buffer using given parameters for encrypt or decrypt. */
     113             :     static CHIP_ERROR BuildNonce(NonceView nonce, uint8_t securityFlags, uint32_t messageCounter, NodeId nodeId);
     114             : 
     115             :     /** @brief Build a Nonce buffer using given parameters for encrypt or decrypt. */
     116             :     static CHIP_ERROR BuildPrivacyNonce(NonceView nonce, uint16_t sessionId, const MessageAuthenticationCode & mac);
     117             : 
     118             :     /**
     119             :      * @brief
     120             :      *   Encrypt the input data using keys established in the secure channel
     121             :      *
     122             :      * @param input Unencrypted input data
     123             :      * @param input_length Length of the input data
     124             :      * @param output Output buffer for encrypted data
     125             :      * @param nonce Nonce buffer for encrypt
     126             :      * @param header message header structure. Encryption type will be set on the header.
     127             :      * @param mac - output the resulting mac
     128             :      *
     129             :      * @return CHIP_ERROR The result of encryption
     130             :      */
     131             :     CHIP_ERROR Encrypt(const uint8_t * input, size_t input_length, uint8_t * output, ConstNonceView nonce, PacketHeader & header,
     132             :                        MessageAuthenticationCode & mac) const;
     133             : 
     134             :     /**
     135             :      * @brief
     136             :      *   Decrypt the input data using keys established in the secure channel
     137             :      *
     138             :      * @param input Encrypted input data
     139             :      * @param input_length Length of the input data
     140             :      * @param output Output buffer for decrypted data
     141             :      * @param nonce Nonce buffer for decrypt
     142             :      * @param header message header structure
     143             :      * @return CHIP_ERROR The result of decryption
     144             :      * @param mac Input mac
     145             :      */
     146             :     CHIP_ERROR Decrypt(const uint8_t * input, size_t input_length, uint8_t * output, ConstNonceView nonce,
     147             :                        const PacketHeader & header, const MessageAuthenticationCode & mac) const;
     148             : 
     149             :     CHIP_ERROR PrivacyEncrypt(const uint8_t * input, size_t input_length, uint8_t * output, PacketHeader & header,
     150             :                               MessageAuthenticationCode & mac) const;
     151             : 
     152             :     CHIP_ERROR PrivacyDecrypt(const uint8_t * input, size_t input_length, uint8_t * output, const PacketHeader & header,
     153             :                               const MessageAuthenticationCode & mac) const;
     154             : 
     155           0 :     ByteSpan GetAttestationChallenge() const { return mAttestationChallenge.Span(); }
     156             : 
     157             :     /**
     158             :      * @brief
     159             :      *   Memory overhead of encrypting data. The overhead is independent of size of
     160             :      *   the data being encrypted. The extra space is used for storing the common header.
     161             :      *
     162             :      * @return number of bytes.
     163             :      */
     164             :     size_t EncryptionOverhead();
     165             : 
     166             :     bool IsInitiator() const { return mKeyAvailable && mSessionRole == SessionRole::kInitiator; }
     167             : 
     168           0 :     bool IsResponder() const { return mKeyAvailable && mSessionRole == SessionRole::kResponder; }
     169             : 
     170             : private:
     171             :     CHIP_ERROR InitTestMode(Crypto::SessionKeystore & keystore, Crypto::Aes128KeyHandle & i2rKey, Crypto::Aes128KeyHandle & r2iKey);
     172             : 
     173             :     SessionRole mSessionRole;
     174             : 
     175             :     bool mKeyAvailable;
     176             :     Crypto::Aes128KeyHandle mEncryptionKey;
     177             :     Crypto::Aes128KeyHandle mDecryptionKey;
     178             :     Crypto::AttestationChallenge mAttestationChallenge;
     179             :     Crypto::SessionKeystore * mKeystore       = nullptr;
     180             :     Crypto::SymmetricKeyContext * mKeyContext = nullptr;
     181             : 
     182             :     // Use unencrypted header as additional authenticated data (AAD) during encryption and decryption.
     183             :     // The encryption operations includes AAD when message authentication tag is generated. This tag
     184             :     // is used at the time of decryption to integrity check the received data.
     185             :     static CHIP_ERROR GetAdditionalAuthData(const PacketHeader & header, uint8_t * aad, uint16_t & len);
     186             : };
     187             : 
     188             : } // namespace chip