src/transport/CASESession.h

   1 /*
   2  *
   3  *    Copyright (c) 2021 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 CASE Session object that provides
  22  *      APIs for constructing a secure session using a certificate from the device's
  23  *      operational credentials.
  24  */
  25
  26 #pragma once
  27
  28 #include <crypto/CHIPCryptoPAL.h>
  29 #include <protocols/secure_channel/Constants.h>
  30 #include <support/Base64.h>
  31 #include <system/SystemPacketBuffer.h>
  32 #include <transport/PeerConnectionState.h>
  33 #include <transport/SecureSession.h>
  34 #include <transport/SessionEstablishmentDelegate.h>
  35 #include <transport/raw/MessageHeader.h>
  36 #include <transport/raw/PeerAddress.h>
  37
  38 namespace chip {
  39
  40 using namespace Crypto;
  41
  42 class DLL_EXPORT CASESession
  43 {
  44 public:
  45     CASESession();
  46     CASESession(CASESession &&)      = default;
  47     CASESession(const CASESession &) = default;
  48     CASESession & operator=(const CASESession &) = default;
  49     CASESession & operator=(CASESession &&) = default;
  50
  51     virtual ~CASESession();
  52
  53     /**
  54      * @brief
  55      *   Initialize using operational credentials code and wait for session establishment requests.
  56      *
  57      * @param myNodeId        Node id of local node
  58      * @param myKeyId         Key ID to be assigned to the secure session on the peer node
  59      * @param delegate        Callback object
  60      *
  61      * @return CHIP_ERROR     The result of initialization
  62      */
  63     CHIP_ERROR WaitForSessionEstablishment(NodeId myNodeId, uint16_t myKeyId, SessionEstablishmentDelegate * delegate);
  64
  65     /**
  66      * @brief
  67      *   Create and send session establishment request using device's operational credentials.
  68      *
  69      * @param peerAddress      Address of peer with which to establish a session.
  70      * @param myNodeId         Node id of local node
  71      * @param peerNodeId       Node id of the peer node
  72      * @param myKeyId          Key ID to be assigned to the secure session on the peer node
  73      * @param delegate         Callback object
  74      *
  75      * @return CHIP_ERROR      The result of initialization
  76      */
  77     CHIP_ERROR EstablishSession(const Transport::PeerAddress peerAddress, NodeId myNodeId, NodeId peerNodeId, uint16_t myKeyId,
  78                                 SessionEstablishmentDelegate * delegate);
  79
  80     /**
  81      * @brief
  82      *   Derive a secure session from the established session. The API will return error
  83      *   if called before session is established.
  84      *
  85      * @param session     Reference to the secure session that will be
  86      *                    initialized once session establishment is complete
  87      * @return CHIP_ERROR The result of session derivation
  88      */
  89     virtual CHIP_ERROR DeriveSecureSession(SecureSession & session);
  90
  91     /**
  92      * @brief
  93      *   Handler for peer's messages, exchanged during pairing handshake.
  94      *
  95      * @param packetHeader Message header for the received message
  96      * @param peerAddress  Source of the message
  97      * @param msg          Message sent by the peer
  98      * @return CHIP_ERROR The result of message processing
  99      */
 100     virtual CHIP_ERROR HandlePeerMessage(const PacketHeader & packetHeader, const Transport::PeerAddress & peerAddress,
 101                                          System::PacketBufferHandle msg);
 102
 103     /**
 104      * @brief
 105      *  Return the associated secure session peer NodeId
 106      *
 107      * @return NodeId The associated peer NodeId
 108      */
 109     NodeId GetPeerNodeId() const { return mConnectionState.GetPeerNodeId(); }
 110
 111     /**
 112      * @brief
 113      *  Return the associated peer key id
 114      *
 115      * @return uint16_t The associated peer key id
 116      */
 117     uint16_t GetPeerKeyId() { return mConnectionState.GetPeerKeyID(); }
 118
 119     /**
 120      * @brief
 121      *  Return the associated local key id
 122      *
 123      * @return uint16_t The assocated local key id
 124      */
 125     uint16_t GetLocalKeyId() { return mConnectionState.GetLocalKeyID(); }
 126
 127     Transport::PeerConnectionState & PeerConnection() { return mConnectionState; }
 128
 129 private:
 130     enum SigmaErrorType : uint8_t
 131     {
 132         kNoSharedTrustRoots   = 0x01,
 133         kInvalidSignature     = 0x04,
 134         kInvalidResumptionTag = 0x05,
 135         kUnsupportedVersion   = 0x06,
 136         kUnexpected           = 0xff,
 137     };
 138
 139     CHIP_ERROR SendSigmaR1();
 140     CHIP_ERROR HandleSigmaR1_and_SendSigmaR2(const PacketHeader & header, const System::PacketBufferHandle & msg);
 141     CHIP_ERROR HandleSigmaR2_and_SendSigmaR3(const PacketHeader & header, const System::PacketBufferHandle & msg);
 142     CHIP_ERROR HandleSigmaR3(const PacketHeader & header, const System::PacketBufferHandle & msg);
 143
 144     CHIP_ERROR SendSigmaR1Resume();
 145     CHIP_ERROR HandleSigmaR1Resume_and_SendSigmaR2Resume(const PacketHeader & header, const System::PacketBufferHandle & msg);
 146
 147     void SendErrorMsg(SigmaErrorType errorCode);
 148     void HandleErrorMsg(const PacketHeader & header, const System::PacketBufferHandle & msg);
 149
 150     CHIP_ERROR AttachHeaderAndSend(Protocols::SecureChannel::MsgType msgType, System::PacketBufferHandle msgBuf);
 151
 152     void Clear();
 153
 154     SessionEstablishmentDelegate * mDelegate = nullptr;
 155
 156     Protocols::SecureChannel::MsgType mNextExpectedMsg = Protocols::SecureChannel::MsgType::CASE_SigmaErr;
 157
 158     struct SigmaErrorMsg
 159     {
 160         SigmaErrorType error;
 161     };
 162
 163 protected:
 164     NodeId mLocalNodeId = kUndefinedNodeId;
 165
 166     bool mPairingComplete = false;
 167
 168     Transport::PeerConnectionState mConnectionState;
 169 };
 170
 171 } // namespace chip