src/messaging/ChannelContext.h

   1 /*
   2  *
   3  *    Copyright (c) 2021 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  *      This file defines the internal classes used by CHIP Channel.
  21  */
  22
  23 #pragma once
  24
  25 #include <variant>
  26
  27 #include <lib/core/ReferenceCounted.h>
  28 #include <lib/mdns/platform/Mdns.h>
  29 #include <messaging/Channel.h>
  30 #include <transport/CASESession.h>
  31 #include <transport/PeerConnectionState.h>
  32 #include <transport/SecureSessionMgr.h>
  33
  34 namespace chip {
  35 namespace Messaging {
  36
  37 class ExchangeManager;
  38 class ChannelContext;
  39
  40 class ChannelContextDeletor
  41 {
  42 public:
  43     static void Release(ChannelContext * context);
  44 };
  45
  46 /**
  47  * @brief
  48  *  The object of the class holds all state of a channel. It is a state machine, with following states:
  49  *
  50  *  N: None, the initial state
  51  *  P: Preparing
  52  *  R: Ready, the channel is ready to use
  53  *  C: Closed, the channel is closed
  54  *  F: Failed, the channel is failed
  55  *
  56  *    +---+   +---+   +---+   +---+
  57  *    | N |-->| P |-->| R |-->| C |
  58  *    +---+   +---+   +---+   +---+
  59  *              |       |
  60  *              |       |     +---+
  61  *              +-------+---->| F |
  62  *                            +---+
  63  *
  64  *  Note: The state never goes back, when a channel is failed, it can't be reset or fixed. The application must create a
  65  *  new channel to replace the failed channel
  66  *
  67  *  Preparing Substates:
  68  *    A: AddressResolving, use mDNS to resolve the node address
  69  *    C: CasePairing, do SIGMA key exchange
  70  *    CD: CasePairingDone, wait for OnNewConnection from SecureSessionManager
  71  *
  72  *  /---\   +---+   +---+   +----+   /---\
  73  *  |   |-->| A |-->| C |-->| CD |-->| O |
  74  *  \---/   +---+   +---+   +----+   \---/
  75  */
  76 class ChannelContext : public ReferenceCounted<ChannelContext, ChannelContextDeletor>, public SessionEstablishmentDelegate
  77 {
  78 public:
  79     ChannelContext(ExchangeManager * exchangeManager) : mState(ChannelState::kNone), mExchangeManager(exchangeManager) {}
  80
  81     void Start(const ChannelBuilder & builder);
  82
  83     /*
  84      * @brief
  85      *  Create a new exchange on the channel.
  86      *
  87      * @pre GetState() == ChannelState::kReady
  88      */
  89     ExchangeContext * NewExchange(ExchangeDelegate * delegate);
  90
  91     ChannelState GetState() const { return mState; }
  92
  93     bool MatchNodeId(NodeId nodeId);
  94     bool MatchTransport(Transport::Type transport);
  95     bool MatchTransportPreference(ChannelBuilder::TransportPreference transport);
  96     bool MatchCaseParameters();
  97
  98     bool IsCasePairing();
  99
 100     bool MatchesBuilder(const ChannelBuilder & builder);
 101     bool MatchesSession(SecureSessionHandle session, SecureSessionMgr * ssm);
 102
 103     // events of ResolveDelegate, propagated from ExchangeManager
 104     void HandleNodeIdResolve(CHIP_ERROR error, uint64_t nodeId, const Mdns::MdnsService & address);
 105
 106     // events of SecureSessionManager, propagated from ExchangeManager
 107     void OnNewConnection(SecureSessionHandle session);
 108     void OnConnectionExpired(SecureSessionHandle session);
 109
 110     // Pairing callbacks
 111     CHIP_ERROR HandlePairingMessage(const PacketHeader & packetHeader, const Transport::PeerAddress & peerAddress,
 112                                     System::PacketBufferHandle && msg);
 113     CHIP_ERROR SendSessionEstablishmentMessage(const PacketHeader & header, const Transport::PeerAddress & peerAddress,
 114                                                System::PacketBufferHandle msgIn) override;
 115     void OnSessionEstablishmentError(CHIP_ERROR error) override;
 116     void OnSessionEstablished() override;
 117
 118 private:
 119     friend class ChannelContextDeletor;
 120     friend class ChannelHandle;
 121
 122     ChannelState mState;
 123     ExchangeManager * mExchangeManager;
 124
 125     enum class PrepareState
 126     {
 127         kAddressResolving,
 128         kCasePairing,
 129         kCasePairingDone,
 130     };
 131
 132     union StateVars
 133     {
 134         StateVars() {}
 135
 136         // mPreparing is pretty big, consider move it outside
 137         struct PrepareVars
 138         {
 139             PrepareState mState;
 140             Inet::IPAddressType mAddressType;
 141             Inet::IPAddress mAddress;
 142             CASESession * mCasePairingSession;
 143             ChannelBuilder mBuilder;
 144         } mPreparing;
 145
 146         struct ReadyVars
 147         {
 148             SecureSessionHandle mSession;
 149         } mReady;
 150     } mStateVars;
 151
 152     // State machine functions
 153     void EnterPreparingState(const ChannelBuilder & builder);
 154     void ExitPreparingState();
 155
 156     void EnterReadyState(SecureSessionHandle session);
 157     void ExitReadyState();
 158
 159     void EnterFailedState(CHIP_ERROR error);
 160     void EnterClosedState();
 161
 162     // Preparing sub-states
 163     void EnterAddressResolve();
 164     static void AddressResolveTimeout(System::Layer * aLayer, void * aAppState, System::Error aError);
 165     void AddressResolveTimeout();
 166     void ExitAddressResolve() {}
 167
 168     void EnterCasePairingState();
 169     void ExitCasePairingState();
 170 };
 171
 172 class ChannelContextHandleAssociation
 173 {
 174 public:
 175     ChannelContextHandleAssociation(ChannelContext * channelContext, ChannelDelegate * channelDelegate) :
 176         mChannelContext(channelContext), mChannelDelegate(channelDelegate)
 177     {
 178         mChannelContext->Retain();
 179     }
 180     ~ChannelContextHandleAssociation() { mChannelContext->Release(); }
 181
 182 private:
 183     friend class ExchangeManager;
 184     friend class ChannelHandle;
 185     ChannelContext * mChannelContext;
 186     ChannelDelegate * mChannelDelegate;
 187 };
 188
 189 } // namespace Messaging
 190 } // namespace chip