Subject: [Capwap] Proposed resolution for Issue 226 - revisited

From: "Pat Calhoun (pacalhou)" <[email-masked]>
Date: Sun, 7 Jan 2007 12:46:18 -0800

Based on the feedback I had received on the original submission for
issue 226, I would like to submit the following text. I believe that
it addresses the comments I had received.

Comments welcomed.
==================

2.3.  CAPWAP State Machine Definition

   The following state diagram represents the lifecycle of a WTP-AC
   session.  Use of DTLS by the CAPWAP protocol results in the
   juxtaposition of two nominally separate yet tightly bound state
   machines.  The DTLS and CAPWAP state machines are coupled through an
   API consisting of commands (from CAPWAP to DTLS) and notifications
   (from (DTLS to CAPWAP).  Certain transitions in the DTLS state
   machine are triggered by commands from the CAPWAP state machine,
   while certain transitions in the CAPWAP state machine are triggered
   by notifications from the DTLS state machine.

   This section defines the CAPWAP Integrated State Machine.  In the
   figure below, single lines (denoted with '-' and '|') are used to
   illustrate state transitions.  These state transitions are documented
   in Section 2.3.1.  Double lines (denoted with '=' and '"') are used
   to illustrate commands and notifications between DTLS and CAPWAP.
   These commands and notifications are described in Section 2.3.2.  A
   line composed of '~' characters is used to delineate the boundary
   between nominal CAPWAP and DTLS state machine components.

     /===================>=====================================\
     " /=================<=================================\   "
     " "  /==============<=============================\   "   "
     " "  "  /===========<=========\                   "   "   "
     " "  "  "             n4,n5,n6"                 n8" n3"   v
     " "  "  "   +-----------+   +--------------+     +----------+
     " "  "  "   | DTLS Idle |   |  DTLS Setup  |     | DTLS Run |
     " "  "  "   +-----------+   +--------------+     +----------+
     " "  "  "   ^   "n1   ^c4    ^  ^         "n2   c3^  n7"  ^    
     " "  "  "   "   "     "      "  "         "       "    "  "    DTLS
     "~"~~"~~"~~~"~~~"~~~~~"~~~~~~"~~"~~~~~~~~~"~~~~~~~"~~~~"~~"~~~~~~~~
     " "  "  "   "   "     \======"=="=======\ "  /====/    "  "  CAPWAP
     ^ v  v  v   "   "            "  "       " "  "         "  "
     " "  "  "   "   "    /=======/  "       " "  "         "  "
     " "  "  "   "   "    "          "       " "  "         "  "
     " "  "  "   "c1 v    "c2   d    "c2     " v  "         "  "
     " "  "  \=>+------------+   +------+   +------+        "  "
     " "  "     |    Idle    |-->| Disc |   | Auth |        "  "
     " "  \====>+------------+ a +------+   +------+        "  "
     " "        b|    ^           |d     /==================/  "
     " "         |    |           |      "   /-----------------"----\
     " "         v   f|      /----/      v  r|                 "c5  |
     " "        +---------+  |      +----------+ s +------------+   |
     " "        | Sulking |<=/      |   Run    |-->|   Reset    |   |
     " "        +---------+         +----------+   +------------+   |
     " "                           q     ^         ^       ^        |
     " "                                 |   /-----/       |        |
     " "                                p|  k|         j   |m       v
     " \========>+--------------+     +-----------+     +------------+
     "         c5|    Join      |---->| Configure |---->| Image Data |
     \===========+--------------+  g  +-----------+  h  +------------+

                 Figure 3: CAPWAP Integrated State Machine

   The CAPWAP protocol state machine, depicted above, is used by both
   the AC and the WTP.  In cases where states are not shared (i.e. not
   implemented in one or the other of the AC or WTP), this is explicitly
   called out in the transition descriptions below.  For every state
   defined, only certain messages are permitted to be sent and received.
   The CAPWAP control messages definitions specify the state(s) in which
   each message is valid.

2.3.1.  CAPWAP Protocol State Transitions

   The following text discusses the various state transitions, and the
   events that cause them.  This section does not discuss interactions
   between DTLS- and CAPWAP-specific states.  Those interactions, as
   well as DTLS-specific states and transitions, are discussed in
   Section 2.3.2.

   Idle to Discovery (a):  This transition occurs once device
      initialization is complete.

      WTP:  The WTP enters the Discovery state prior to transmitting the
         first Discovery Request message (see Section 5.1).  Upon
         entering this state, the WTP sets the DiscoveryInterval timer
         (see Section 4.6).  The WTP resets the DiscoveryCount counter
         to zero (0) (see Section 4.7).  The WTP also clears all
         information from ACs it may have received during a previous
         Discovery phase.

      AC:  The AC does not maintain state information for the WTP upon
         reception of the Discovery Request message, but it SHOULD
         respond with a Discovery Response message (see Section 5.2).
         This transition is a no-op for the AC.

   Idle to Sulking (b):  This transition occurs on the DTLS session
      establishment process fails repeatedly to protect against DoS
      attacks.

      WTP:  The WTP enters this state when the FailedDTLSSessionCount
         counter reaches MaxFailedDTLSSessionRetry variable (see
         Section 4.7).  Upon entering this state, the WTP shall start
         the SilentInterval timer.  While in the Sulking state, all
         received CAPWAP and DTLS protocol messages received shall be
         ignored.

      AC:  The AC enters this state when the FailedDTLSSessionCount
         counter reaches MaxFailedDTLSSessionRetry variable (see
         Section 4.7).  Upon entering this state, the AC shall start the
         SilentInterval timer.  While in the Sulking state, all received
         CAPWAP and DTLS protocol messages received shall be ignored.

   Discovery to Discovery (d):  In the Discovery state, the WTP
      determines which AC to connect to.

      WTP:  This transition occurs when the DiscoveryInterval timer
         expires.  If the WTP is configured with a list of ACs, it
         transmits a Discovery Request message to every AC from which it
         has not received a Discovery Response message.  For every
         transition to this event, the WTP increments the DiscoveryCount
         counter.  See Section 5.1 for more information on how the WTP
         knows the ACs to which it should transmit the Discovery Request
         messages.  The WTP restarts the DiscoveryInterval timer
         whenever it transmits Discovery Request messages.

      AC:  This is a no-op.

   Discovery to Sulking (e):  This transition occurs on a WTP when
      Discovery or connectivity to the AC fails.

      WTP:  The WTP enters this state when the DiscoveryInterval timer
         expires and the DiscoveryCount variable is equal to the
         MaxDiscoveries variable (see Section 4.7).  Upon entering this
         state, the WTP shall start the SilentInterval timer.  While in
         the Sulking state, all received CAPWAP protocol messages
         received shall be ignored.

      AC:  This is a no-op.

   Sulking to Idle (f):  This transition occurs on a WTP when it must
      restart the discovery phase.

      WTP:  The WTP enters this state when the SilentInterval timer (see
         Section 4.6) expires.

      AC:  The AC enters this state when the SilentInterval timer (see
         Section 4.6) expires.

   Join to Configure (g):  This state transition is used by the WTP and
      the AC to exchange configuration information.

      WTP:  The WTP enters the Configure state when it successfully
         completes the Join operation.  If it determines that its
         version number and the version number advertised by the AC are
         compatible, the WTP transmits the Configuration Status message
         (see Section 8.2) to the AC with a snapshot of its current
         configuration.  The WTP also starts the ResponseTimeout timer
         (see Section 4.6).  If the version numbers are not compatible,
         the WTP will immediately transition to Image Data state (see
         transition (g)).  If the AC determines that a new firmware
         image should be installed on the WTP, the AC initiates a
         firmware download by sending an Image Data Request Message with
         an Initiate Download message element to the WTP

      AC:  This state transition occurs immediately after the AC
         transmits the Join Response message to the WTP.  If the AC
         receives the Configuration Status message from the WTP, the AC
         must transmit a Configuration Status Response message (see
         Section 8.3) to the WTP, and may include specific message
         elements to override the WTP's configuration.  If the AC
         instead receives the Image Data Request from the WTP, it
         immediately transitions to the Image Data state (see transition
         (g)).

   Configure to Image Data (h):  This state transition is used by the
      WTP and the AC to download executable firmware.

      WTP:  The WTP enters the Image Data state when it successfully
         comletes DTLS session establishment, and determines that its
         version number and the version number advertised by the AC are
         different.  The WTP transmits the Image Data Request (see
         Section 9.1) message requesting that a download of the AC's
         latest firmware be initiated.

      AC:  This state transition occurs when the AC receives the Image
         Data Request message from the WTP.  The AC must transmit an
         Image Data Response message (see Section 9.2) to the WTP, which
         includes a portion of the firmware.

   Image Data to Image Data (j):  The Image Data state is used by WTP
      and the AC during the firmware download phase.

      WTP:  The WTP enters the Image Data state when it receives an
         Image Data Response message indicating that the AC has more
         data to send.

      AC:  This state transition occurs when the AC receives the Image
         Data Request message from the WTP while already in the Image
         Data state, and it detects that the firmware download has not
         completed.

   Configure to Reset (k):  This state transition is used to reset the
      connection to the AC prior to restarting the WTP with a new
      configuration.

      WTP:  The WTP enters the Reset state when it determines that a
         reset of the WTP is required, due to the characteristics of a
         new configuration.

      AC:  The AC transitions to the Reset state when it receives the
         DTLSPeerDisconnect (n6) notification (see Section 2.3.2.2 for
         more information on DTLS notifications).

   Image Data to Reset (m):  This state transition is used to reset the
      DTLS connection prior to restarting the WTP after an image
      download.

      WTP:  When an image download completes, the WTP enters the Reset
         state, and terminates the DTLS connection, sending a
         DTLSShutdown command to the DTLS state machine.

      AC:  The AC enters the Reset state upon receipt of a DTLSIdle (n5)
         notification (see Section 2.3.2.2 for more information on DTLS
         notifications).

   Configure to Run (p):  This state transition occurs when the WTP and
      AC enter their normal state of operation.

      WTP:  The WTP enters this state when it receives a successful
         Configuration Status Response message from the AC.  The WTP
         initializes the HeartBeat timer (see Section 4.6), and
         transmits the Change State Event Request message (see
         Section 8.6).

      AC:  This state transition occurs when the AC receives the Change
         State Event Request message (see Section 8.6) from the WTP.
         The AC responds with a Change State Event Response (see
         Section 8.7) message.  The AC must start the
         NeighborDeadInterval timer (see Section 4.6).

   Run to Run (q):  This is the normal state of operation.

      WTP:  This is the WTP's normal state of operation.  There are many
         events that result this state transition:

         Configuration Update:  The WTP receives a Configuration Update
            Request message(see Section 8.4).  The WTP MUST respond with
            a Configuration Update Response message (see Section 8.5).

         Change State Event:  The WTP receives a Change State Event
            Response message, or determines that it must initiate a
            Change State Event Request message, as a result of a failure
            or change in the state of a radio.

         Echo Request:  The WTP receives an Echo Request message (see
            Section 7.1), to which it MUST respond with an Echo Response
            message(see Section 7.2).

         Clear Config Request:  The WTP receives a Clear Configuration
            Request message (see Section 8.8).  The WTP MUST reset its
            configuration back to manufacturer defaults.

         WTP Event:  The WTP generates a WTP Event Request message to
            send information to the AC (see Section 9.5).  The WTP
            receives a WTP Event Response message from the AC (see
            Section 9.6).

         Data Transfer:  The WTP generates a Data Transfer Request
            message to the AC (see Section 9.7).  The WTP receives a
            Data Transfer Response message from the AC (see
            Section 9.8).

         Station Configuration Request:  The WTP receives a Station
            Config Request message (see Section 10.1), to which it MUST
            respond with a Station Config Response message (see
            Section 10.2).

      AC:  This is the AC's normal state of operation:

         Configuration Update:  The AC sends a Configuration Update
            Request message (see Section 8.4) to the WTP to update its
            configuration.  The AC receives a Configuration Update
            Response message (see Section 8.5) from the WTP.

         Change State Event:  The AC receives a Change State Event
            Request message (see Section 8.6), to which it MUST respond
            with the Change State Event Response message (see
            Section 8.7).

         Echo:  The AC sends an Echo Request message Section 7.1 or
            receives the corresponding Echo Response message, see
            Section 7.2 from the WTP.

         Clear Config Response:  The AC receives a Clear Configuration
            Response message (see Section 8.9).

         Station Config:  The AC sends a Station Configuration Request
            message (see Section 10.1) or receives the corresponding
            Station Configuration Response message (see Section 10.2)
            from the WTP.

         Data Transfer:  The AC receives a Data Transfer Request message
            from the AC (see Section 9.7) and MUST generate a
            corresponding Data Transfer Response message (see
            Section 9.8).

         WTP Event:  The AC receives a WTP Event Request message from
            the AC (see Section 9.5) and MUST generate a corresponding
            WTP Event Response message (see Section 9.6).

   Run to Reset (r):  This state transition is used when the AC or WTP
      wish to tear down the connection.  This may occur as part of
      normal operation, or due to error conditions.

      WTP:  The WTP enters the Reset state when it receives a Reset
         Request from the AC.

      AC:  The AC enters the reset state when it transmits a Reset
         Request to the WTP.

   Run to Image Data (s):  This state transition occurs when the AC
      transmits an Image Data Request to the WTP, with the Initiate
      Download message element.  The means by which the AC decides to
      download firmware is undefined, but could occur through an
      administrative action.

      WTP:  The WTP enters this state when it receives an an Image Data
         Request to the WTP, with the Initiate Download message element.
         The WTP responds by transmitting an Image Data Request with the
         Image Filename message element included..

      AC:  This state transition occurs when the AC decides that an WTP
         is to update its firmware by sending an Image Data Request to
         the WTP, with the Initiate Download message element.

2.3.2.  CAPWAP/DTLS Interface

   This section describes the DTLS Commands used by CAPWAP, as well as
   the notifications received from DTLS to the CAPWAP protocol stack.

2.3.2.1.  CAPWAP to DTLS Commands

   Four commands are defined for the CAPWAP to DTLS API.  These
   "commands" are conceptual, and may be implemented as one or more
   function calls.  This API definition is provided to clarify
   interactions between the DTLS and CAPWAP components of the integrated
   CAPWAP state machine.

   Below is a list of the minimal command API:

   o  c1: DTLSInit is invoked in order to initialize the DTLS protocol
      stack.  The CAPWAP protocol stack includes various elements in the
      initialization procedure, including the crypto algorithms
      supported (see Section 2.4.4).

   o  c2: DTLSStart is sent to the DTLS module to cause a DTLS session
      to be established.  Upon invoking the DTLSStart command, the
      WaitDTLS timer is started.  The WTP is the only CAPWAP device that
      initiates this DTLS command, as the AC does not initiate DTLS
      sessions.

   o  c3: DTLSEstablishSession is sent to the DTLS module to allow the
      DTLS session establishment to continue successfully.

   o  c4: DTLSAbortSession is sent to the DTLS module to cause the
      session that is in the process of being established, to be
      aborted.  This command is also sent when the WaitDTLS timer
      expires.  When this command is executed, the
      FailedDTLSSessionCount counter is incremented.

   o  c5: DTLSShutdown is sent to the DTLS module to cause session
      teardown.

2.3.2.2.  DTLS to CAPWAP Notifications

   DTLS notifications are defined for the DTLS to CAPWAP API.  These
   "notifications" are conceptual, and may be implemented in numerous
   ways (e.g. as function return values).  This API definition is
   provided to clarify interactions between the DTLS and CAPWAP
   components of the integrated CAPWAP state machine.  It is important
   to note that the notifications listed below MAY cause the CAPWAP
   state machine to jump from one state to another using a state
   transition not listed in section Section 2.3.1.  When a notification
   listed below occurs, the target CAPWAP state shown in Figure 3
   becomes the current state.

   Below is a list of the API notifications:

   o  n1: DTLSInitComplete is sent by the DTLS library to the CAPWAP
      protocol stack when initialization is complete.  The
      initialization may be successful, in which case the CAPWAP state
      machine proceeds.  Alternatively, if the initialization fails,
      which could occurs due to lack of memory, or some other internal
      error condition, causes the CAPWAP state machine to stop in the
      Idle state.

   o  n2: DTLSIncomingSession is sent to the CAPWAP protocol stack
      during the DTLS session establishment once the peer's identity has
      been received.  This notification MAY be used by the CAPWAP
      protocol stack in order to authorize the session, based on the
      peer's identity.  The authorization process will lead to the
      CAPWAP protocol stack initiating either the DTLSEstablishSession
      or DTLSAbortSession commands.

   o  n3: DTLSEstablished is sent to the CAPWAP module to indicate that
      that a secure channel now exists, using the parameters provided
      during the DTLS initialization process.  When this notification is
      received, the FailedDTLSSessionCount counter is reset to zero.
      When this notification is received, the WaitDTLS is stopped.

   o  n4: DTLSEstablishFail is sent when the DTLS session establishment
      has failed, either due to a local error, or due to the peer
      rejecting the session establishment.  When this notification is
      received, the FailedDTLSSessionCount counter is reset to zero.
      When this notification is received, the WaitDTLS is stopped.

   o  n5: DTLSAborted is sent to the CAPWAP module to indicate that
      session abort (as requested by CAPWAP) is complete; this occurs to
      confirm a DTLS session abort, or when the WaitDTLS timer expires.
      When this notification is received, the WaitDTLS is stopped.

   o  n6: DTLSReassemblyFailure may be sent to the CAPWAP module to
      indicate DTLS fragment reassembly failure.

   o  n7: DTLSDecapFailure may be sent to CAPWAP to indicate an
      decapsulation failure.  DTLSDecapFailure may be sent to CAPWAP to
      indicate an encryption/authentication failure.

   o  n8: DTLSPeerDisconnect is sent to the CAPWAP module to indicate
      the DTLS session has been torn down.  Note that this notification
      is only received if the DTLS session has been established.

2.4.  Use of DTLS in the CAPWAP Protocol

   DTLS is used as a tightly-integrated, secure wrapper for the CAPWAP
   protocol.  In this document DTLS and CAPWAP are discussed as
   nominally distinct entitites; however they are very closely coupled,
   and may even be implemented inseparably.  Since there are DTLS
   library implementations currently available, and since security
   protocols (e.g.  IPsec, TLS) are often implemented in widely
   available acceleration hardware, it is both convenient and forward-
   looking to maintain a modular distinction in this document.

   This section describes a detailed walk-through of the interactions
   between the DTLS module and the CAPWAP module, via 'commands' (CAPWAP
   to DTLS) and 'notifications' (DTLS to CAPWAP) as they would be
   encountered during the normal course of operation.

2.4.1.  DTLS Handshake Processing

   Details of the DTLS handshake process are specified in [9].  This
   section describes the interactions between the DTLS session
   establishment process and the CAPWAP protocol.  Note that the
   conceptual DTLS state is shown below to help understand the point at
   which the DTLS states transition.  In the normal case, the DTLS
   handshake will proceed as follows (NOTE: this example uses
   certificates, but preshared keys are also supported):

           ============                         ============
               WTP                                   AC
           ============                         ============
           <DTLS Idle>                       <DTLS Idle>
           ClientHello           ------>
                                 <------       HelloVerifyRequest
                                                   (with cookie)

           <DTLS Setup>
           ClientHello           ------>
           (with cookie)
                                                  <DTLS Setup>
                                 <------       ServerHello
                                 <------       Certificate
                                 <------       ServerHelloDone

           (WTP callout for AC authorization
                    occurs in CAPWAP Auth state)

           <DTLS Run>
           Certificate*
           ClientKeyExchange
           CertificateVerify*
           [ChangeCipherSpec]
           Finished              ------>

                                (AC callout for WTP authorization
                                 occurs in CAPWAP Auth state)

                                               <DTLS Run>
                                               [ChangeCipherSpec]
                                 <------       Finished

   DTLS, as specified, provides its own retransmit timers with an
   exponential back-off.  However, it will never terminate the handshake
   due to non-responsiveness; rather, it will continue to increase its
   back-off timer period.  Hence, timing out incomplete DTLS handshakes
   is entirely the responsiblity of the CAPWAP protocol.

2.4.2.  DTLS Session Establishment

   The WTP, either through the Discovery process, or through pre-
   configuration, determines the AC to connect to.  The WTP uses the
   DTLSStart command to request that a secure connection be established
   to the selected AC.  Prior to initiation of the DTLS handshake, the
   WTP sets the WaitDTLS timer.  Upon receiving the DTLSIncomingSession
   DTLS notification, the AC sets the WaitDTLS timer.  If the
   DTLSEstablished notification is not received prior to timer
   expiration, the DTLS session is aborted by issuing the
   DTLSAbortSession DTLS command.  This notification causes the CAPWAP
   state to transition back to the Idle state.  Upon receiving a
   DTLSEstablished notification, the WaitDTLS timer is deactivated.

2.4.3.  DTLS Error Handling

   If the AC does not respond to any DTLS messages sent by the WTP, the
   DTLS specification calls for the WTP to retransmit these messages.
   If the WaitDTLS timer expires, CAPWAP will issue the DTLSAbortSession
   command, causing DTLS to terminate the handshake and remove any
   allocated session context.  Note that DTLS MAY send a single TLS
   Alert message to the AC to indicate session termination.

   If the WTP does not respond to any DTLS messages sent by the AC, the
   CAPWAP protocol allows for three possiblities, listed below.  Note
   that DTLS MAY send a single TLS Alert message to the AC to indicate
   session termination.

   o  The message was lost in transit; in this case, the WTP will re-
      transmit its last outstanding message, since it did not receive
      the reply.

   o  The WTP sent a DTLS Alert, which was lost in transit; in this
      case, the AC's WaitDTLS timer will expire, and the session will be
      terminated.

   o  Communication with the WTP has completely failed; in this case,
      the AC's WaitDTLS timer will expire, and the session will be
      terminated.

   The DTLS specification provides for retransmission of unacknowledged
   requests.  If retransmissions remain unacknowledged, the WaitDTLS
   timer will eventually expire, at which time the CAPWAP module will
   terminate the session.

   If a cookie fails to validate, this could represent a WTP error, or
   it could represent a DoS attack.  Hence, AC resource utilization
   SHOULD be minimized.  The AC MAY log a message indicating the
   failure, but SHOULD NOT attempt to reply to the WTP.

   Since DTLS handshake messages are potentially larger than the maximum
   record size, DTLS supports fragmenting of handshake messages across
   multiple records.  There are several potential causes of re-assembly
   errors, including overlapping and/or lost fragments.  The DTLS module
   MUST send a DTLSReassemblyFailure notification to CAPWAP.  Whether
   precise information is given along with notification is an

   implementation issue, and hence is beyond the scope of this document.
   Upon receipt of such an error, the CAPWAP protocol implementation
   SHOULD log an appropriate error message.  Whether processing
   continues or the DTLS session is terminated is implementation
   dependent.

   DTLS decapsulation errors consist of three types: decryption errors,
   and authentication errors, and malformed DTLS record headers.  Since
   DTLS authenticates the data prior to encapsulation, if decryption
   fails, it is difficult to detect this without first attempting to
   authenticate the packet.  If authentication fails, a decryption error
   is also likely, but not guaranteed.  Rather than attempt to derive
   (and require the implementation of) algorithms for detecting
   decryption failures, these are reported as authentication failures.
   The DTLS module MUST provide a DTLSDecapFailure notification to
   CAPWAP when such errors occur.  If a malformed DTLS record header is
   detected, the packets SHOULD be silently discarded, and the receiver
   MAY log an error message.

   There is currently only one encapsulation error defined: MTU
   exceeeded.  As part of DTLS session establishment, CAPWAP informs
   DTLS of the MTU size.  This may be dynamically modified at any time
   when CAPWAP sends the DTLSMtuUpdate command to DTLS.  DTLS returns
   this notification to CAPWAP whenever a transmission request will
   result in a packet which exceeds the MTU.

Pat Calhoun
CTO, Wireless Networking Business Unit
Cisco Systems
_________________________________________________________________
To unsubscribe or modify your subscription options, please visit:
http://lists.frascone.com/mailman/listinfo/capwap

Archives: http://lists.frascone.com/pipermail/capwap

---

From: "Pat Calhoun (pacalhou)" <[email-masked]>
Date: Tue, 23 Jan 2007 06:34:29 -0800

All,

Based on conversations with the CAPWAP security advisors, they had
issues with the previously proposed state machine. I have made
subsequent changes, which I believe provide a much better framework that
the previous version. While I have provided this to them, they haven't
had a chance to do a thorough review, but did indicate that they believe
the model was better. In order to make as much progress as possible
during this week's offsite, I will be including this new text in an
updated draft (sent later today). I recognize that it would have been
ideal to get a full two week's to review and comment on the draft, but
there is a section to review issue 226 in the interim's agenda, so I
hope to get closure on this state machine tomorrow. I will update the
draft to reflect discussions both on the list and at the interim to
ensure the state machine has WG concensus.

It is important to note that this new state machine eliminates the DTLS
blocks, and creates a single state machine that can be easily followed.
It still makes use of the commands and notifications as events that
cause the state transitions.

   The following state diagram represents the lifecycle of a WTP-AC
   session.  Use of DTLS by the CAPWAP protocol results in the
   juxtaposition of two nominally separate yet tightly bound state
   machines.  The DTLS and CAPWAP state machines are coupled through an
   API consisting of commands (from CAPWAP to DTLS) and notifications
   (from DTLS to CAPWAP).  Certain transitions in the DTLS state machine
   are triggered by commands from the CAPWAP state machine, while
   certain transitions in the CAPWAP state machine are triggered by
   notifications from the DTLS state machine.

                                       /-------------------------\
                                      w|                         |
                                 5+----------+ x +------------+  |
                                  |   Run    |-->|   Reset    |-\|
                                  +----------+   +------------+ ||
                               u      ^           ^     ^      y||
                +------------+--------/           |     |       ||
                | Data Check |             /-------/    |       ||
                +------------+<-------\   |             |       ||
                                     t|  s|    4       o|       ||
               +--------+     +-----------+     +------------+  ||
               |  Join  |---->| Configure |---->| Image Data |  ||
               +--------+  q  +-----------+  r  +------------+  ||
                   ^  p|                                        ||
                   |   \------------------------------------\   ||
                   \---------------------\                  |   ||
         /--------------<----------------+---------------\  |   ||
         | /------------<-------------\  |               |  |   ||
         | |                         m|  |n             z|  v   vv
         | |   +----------------+   +--------------+   +-----------+
         | |   |   DTLS Setup   |   | DTLS Connect |   |  DTLS TD  |
         | |   +----------------+   +--------------+   +-----------+
         | |    g|  ^     ^   |h         ^               ^
         v v     |  |     |   |          |               |
         | |     |  |     |   \-------\  |   /-----------/
         | |     |  |     |           |  |   |
         | |     v  |e   f|      2    v  |j  |k
         | \->+------+   +------+   +-----------+
         |    | Idle |-->| Disc |   | Authorize |
         \--->+------+ a +------+   +-----------+
              b|    ^           |c
               |    |      /----/
               v   d|      |
              +---------+  |
              | Sulking |<-/
            3 +---------+

   Idle to Sulking (b):  This transition occurs to force the WTP and AC
      to enter a quiet period to avoid repeatedly attempting to
      establish a connection.

      AC:  The AC enters this state with the specific WTP when the
         FailedDTLSSessionCount counter reaches
         MaxFailedDTLSSessionRetry variable (see Section 4.7).  Upon
         entering this state, the AC shall start the SilentInterval
         timer.  While in the Sulking state, all received CAPWAP and
         DTLS protocol messages received from the WTP shall be ignored.

   Discovery to Discovery (2):  In the Discovery state, the WTP
      determines which AC to connect to.

      AC:  This is a no-op.

   Discovery to Sulking (c):  This transition occurs on a WTP when
      Discovery or connectivity to the AC fails.

         expires or the DiscoveryCount variable is equal to the

      AC:  This is a no-op.

   Sulking to Idle (d):  This transition occurs on a WTP when it must
      restart the discovery phase.

      WTP:  The WTP enters this state when the SilentInterval timer (see
         Section 4.6) expires.  The FailedDTLSSessionCount and
         DiscoveryCount counters are reset to zero.

      AC:  The AC enters this state when the SilentInterval timer (see
         Section 4.6) expires.  The FailedDTLSSessionCount and
         DiscoveryCount counters are reset to zero.

   Sulking to Sulking (3):  The Sulking state provides the silent
      period, minimizing the possibility for Denial of service attacks.

      WTP:  All packets received from the AC while in the sulking state
         are ignored.

      AC:  All packets receive from the WTP while in the sulking state
         are ignored.

   Idle to DTLS Setup (e):  This transition occurs to establish a secure
      DTLS session with the peer.

      WTP:  The WTP initiates this transition by invoking the DTLSStart
         command, which starts the DTLS session establishment with the
         chosen AC.  This decision is performed via local configuration
         of the AC.

      AC:  The AC initiates this transition by invoking the DTLSListen
         command, which informs the DTLS stack that it is willing to
         listen for an incoming session.  The AC MAY provide optional
         qualifiers in the DTLSListen to only accept session requests
         from specific WTP.

   Discovery to DTLS Setup (f):  This transition occurs to establish a
      secure DTLS session with the peer.

      WTP:  The WTP initiates this transition by invoking the DTLSStart
         command (see Section 2.3.2.1), which starts the DTLS session
         establishment with the chosen AC.  The decision of which AC to
         connect to is the result of the discovery phase, which is
         described in Section 3.2.

      AC:  The AC initiates this transition by invoking the DTLSListen
         command (see Section 2.3.2.1), which informs the DTLS stack
         that it is willing to listen for an incoming session.  The AC
         MAY have maintained state information when it received the
         Discovery Request in order to provide optional qualifiers in
         the DTLSListen command to only accept session requests from
         specific WTP.  Note that maintaining state information based on
         an unsecured discovery request MAY lead to a Denial of Service
         attack.  Therefore the AC SHOULD ensure that the state
         information is freed after a period, which is implementation
         specific.

   DTLS Setup to Idle (g):  This transition occurs when the DTLS Session
      failed to be established.

      WTP:  The WTP initiates this state transition when it receives a
         DTLSEstablishFail notification from DTLS (see Section 2.3.2.2).
         This error notification aborts the secure DTLS session
         establishment.  When this transition occurs, the
         FailedDTLSSessionCount counter is incremented.

      AC:  The WTP initiates this state transition when it receives a
         DTLSEstablishFail notification from DTLS (see Section 2.3.2.2).
         This error notification means a DTLS session was attempted with
         a WTP, but failed.  The notification should include information
         such as the offending WTP, and the reason for the failure.
         When this transition occurs, the FailedDTLSSessionCount counter
         is incremented.

   DTLS Setup to Authorize (h):  This transition occurs an incoming DTLS
      session is being established, and the DTLS stack needs
      authorization to proceed with the session establishment.

      WTP:  This state transition occurs when the WTP receives the
         DTLSPeerAuthorize notification (see Section 2.3.2.2).  Upon
         entering this state, the WTP MAY perform an authorization check
         against the AC's credentials.  The method by which this
         authorization is performed is outside the scope of the CAPWAP
         specification.

      AC:  This state transition occurs when the AC receives the
         DTLSPeerAuthorize notification (see Section 2.3.2.2).  Upon
         entering this state, the AC MAY perform an authorization check
         against the WTP's credentials.  The method by which this
         authorization is performed is outside the scope of the CAPWAP
         specification.

   Authorize to DTLS Connect (j):  This transition occurs to notify the
      DTLS stack that the session should be established.

      WTP:  This state transition occurs when the WTP has either opted
         to forgo the authorization check of the AC's credentials, or
         the credentials were successfully authorized.  This is done by
         invoking the DTLSAccept DTLS command (see Section 2.3.2.1).

      AC:  This state transition occurs when the AC has either opted to
         forgo the authorization check of the WTP's credentials, or the
         credentials were successfully authorized.  This is done by
         invoking the DTLSAccept DTLS command (see Section 2.3.2.1).

   Authorize to DTLS Teardown (k):  This transition occurs to notify the
      DTLS stack that the session should be aborted.

      WTP:  This state transition occurs when the WTP was unable to
         authorize the AC, via its credentials.  The WTP then aborts the
         DTLS session, which is done by invoking DTLSAbortSession (see
         Section 2.3.2.1).

      AC:  This state transition occurs when the AC was unable to
         authorize the WTP, via its credentials.  The AC then aborts the
         DTLS session, which is done by invoking DTLSAbortSession (see
         Section 2.3.2.1).

   DTLS Connect to Idle (m):  This transition occurs when the DTLS
      Session failed to be established.

      WTP:  This state transition occurs when the WTP receives the
         DTLSAborted notification (see Section 2.3.2.2), indicating that
         the DTLS session was not successfully established.  When this
         notification is received, the FailedDTLSSessionCount counter is
         incremented.

      AC:  This state transition occurs when the AC receives the
         DTLSAborted notification (see Section 2.3.2.2), indicating that
         the DTLS session was not successfully established.  When this
         notification is received, the FailedDTLSSessionCount counter is
         incremented.

   DTLS Connect to Join (n):  This transition occurs when the DTLS
      Session is successfully established.

      WTP:  This state transition occurs when the WTP receives the
         DTLSEstablished notification (see Section 2.3.2.2), indicating
         that the DTLS session was successfully established.  When this
         notification is received, the FailedDTLSSessionCount counter is
         set to zero.

      AC:  This state transition occurs when the AC receives the
         DTLSEstablished notification (see Section 2.3.2.2), indicating
         that the DTLS session was successfully established.  When this
         notification is received, the FailedDTLSSessionCount counter is
         set to zero.

   Join to DTLS Teardown (p):  This transition occurs when the join
      process failed.

      WTP:  This state transition occurs when the WTP receives a Join
         Response with a Result Code message element containing an
         error.  This causes the WTP to initiate the DTLSShutdown
         command (see Section 2.3.2.1).

      AC:  This state transition occurs when the AC transmits a Join
         Response with a Result Code message element containing an
         error.  This causes the WTP to initiate the DTLSShutdown
         command (see Section 2.3.2.1).

   Configure to Reset (s):  This state transition is used to reset the
      connection either due to an error during the configuration phase,
      or when the WTP determines it needs to reset in order for the new
      configuration to take effect.

      WTP:  The WTP enters the Reset state when it receives a
         Configuration Status Response indicating an error or when it
         determines that a reset of the WTP is required, due to the
         characteristics of a new configuration.

      AC:  The AC transitions to the Reset state when it receives a
         Change State Event message from the WTP that contains an error
         for which the AC's policy does not permit the WTP providing
         service.

   Configure to Image Data (r):  This state transition is used by the
      WTP and the AC to download executable firmware.

   Image Data to Image Data (4):  The Image Data state is used by WTP
      and the AC during the firmware download phase.

   Image Data to Reset (o):  This state transition is used to reset the
      DTLS connection prior to restarting the WTP after an image
      download.

      WTP:  When an image download completes, the WTP enters the Reset
         state.  The WTP MAY also transition to this state upon
         receiving an Image Data Response from the AC (see Section 9.2)
         indicating a failure.

      AC:  The AC enters the Reset state when the image download is
         complete, or if an error occurs during the image download
         process.

   Configure to Data Check (t):  This state transition occurs when the
      WTP and AC confirm the configuration.

      AC:  This state transition occurs when the AC receives the Change
         State Event Request message (see Section 8.7) from the WTP.
         The AC responds with a Change State Event Response (see
         Section 8.8) message.  The AC must start the
         NeighborDeadInterval timer (see Section 4.6).

   Data Check to Run (u):  This state transition occurs once the linkage
      between the control and data channels has occured, which causes
      the WTP and AC to enter their normal state of operation.

      WTP:  The WTP enters this state when it receives a successful
         Change State Event Response from the AC.  The WTP initiates the
         data channel, which MAY require the establishment of a DTLS
         session, starts the DataChannelKeepAlive timer (see
         Section 4.6) and transmits a Data Channel Keep Alive (see
         Section 4.3.1).  The WTP then starts the
         DataChannelDeadInterval timer (see Section 4.6).

      AC:  This state transition occurs when the AC receives the Data
         Channel Keep Alive (see Section 4.3.1), whose Session ID
         message element matches the one included by the WTP in the Join
         Request.  Note that if the AC's policy is to require the data
         channel to be encrypted, this process would also require the
         establishment of the data channel's DTLS session.  Upon
         receiving the Data Channel Keep Alive, the AC transmits its own
         Data Channel Keep Alive.

   Run to DTLS Teardown (u):  This state transition occurs when an error
      has occured in the DTLS stack, causing the DTLS session to be
      torndown.

      WTP:  The WTP enters this state when it receives a one of the
         following DTLS notifications: DTLSAborted,
         DTLSReassemblyFailure, DTLSDecapFailure or DTLSPeerDisconnect
         (see Section 2.3.2.2).

      AC:  The AC enters this state when it receives a one of the
         following DTLS notifications: DTLSAborted,
         DTLSReassemblyFailure, DTLSDecapFailure or DTLSPeerDisconnect
         (see Section 2.3.2.2).

   Run to Run (5):  This is the normal state of operation.

         Configuration Update:  The WTP receives a Configuration Update
            Request message(see Section 8.5).  The WTP MUST respond with
            a Configuration Update Response message (see Section 8.6).

         Clear Config Request:  The WTP receives a Clear Configuration
            Request message (see Section 8.9).  The WTP MUST reset its
            configuration back to manufacturer defaults.

         Configuration Update:  The AC sends a Configuration Update
            Request message (see Section 8.5) to the WTP to update its
            configuration.  The AC receives a Configuration Update
            Response message (see Section 8.6) from the WTP.

         Change State Event:  The AC receives a Change State Event
            Request message (see Section 8.7), to which it MUST respond
            with the Change State Event Response message (see
            Section 8.8).

         Clear Config Response:  The AC receives a Clear Configuration
            Response message (see Section 8.10).

   Run to Reset (x):  This state transition is used when the AC or WTP
      wish to tear down the connection.  This may occur as part of
      normal operation, or due to error conditions.

   Reset to DTLS Teardown (y):  This transition occurs when the CAPWAP
      reset is complete to terminate the DTLS session.

      WTP:  This state transition occurs when the WTP receives a Reset
         Response.  This causes the WTP to initiate the DTLSShutdown
         command (see Section 2.3.2.1).

      AC:  This state transition occurs when the AC transmits a Reset
         Response.  This causes the WTP to initiate the DTLSShutdown
         command (see Section 2.3.2.1).

   DTLS Teardown to Idle (z):  This transition occurs when the DTLS
      session has been shutdown.

      WTP:  This state transition occurs when the WTP receives a
         DTLSPeerDisconnect notification (see Section 2.3.2.2).

      AC:  This state transition occurs when the AC receives a
         DTLSPeerDisconnect notification (see Section 2.3.2.2).

   o  DTLSStart is sent to the DTLS module to cause a DTLS session to be
      established.  Upon invoking the DTLSStart command, the WaitDTLS
      timer is started.  The WTP is the only CAPWAP device that
      initiates this DTLS command, as the AC does not initiate DTLS
      sessions.

   o  DTLSListen is sent to the DTLS module to allow the DTLS to listen
      for incoming DTLS session requests.

   o  DTLSAccept is sent to the DTLS module to allow the DTLS session
      establishment to continue successfully.

   o  DTLSAbortSession is sent to the DTLS module to cause the session
      that is in the process of being established, to be aborted.  This
      command is also sent when the WaitDTLS timer expires.  When this
      command is executed, the FailedDTLSSessionCount counter is
      incremented.

   o  DTLSShutdown is sent to the DTLS module to cause session teardown.

   o  DTLSIncomingSession is sent to the CAPWAP protocol stack during
      the DTLS session establishment once the peer's identity has been
      received.  This notification MAY be used by the CAPWAP protocol
      stack in order to authorize the session, based on the peer's
      identity.  The authorization process will lead to the CAPWAP
      protocol stack initiating either the DTLSAccept or
      DTLSAbortSession commands.

   o  DTLSEstablished is sent to the CAPWAP module to indicate that that
      a secure channel now exists, using the parameters provided during
      the DTLS initialization process.  When this notification is
      received, the FailedDTLSSessionCount counter is reset to zero.
      When this notification is received, the WaitDTLS is stopped.

   o  DTLSEstablishFail is sent when the DTLS session establishment has
      failed, either due to a local error, or due to the peer rejecting
      the session establishment.  When this notification is received,
      the FailedDTLSSessionCount counter is reset to zero.  When this
      notification is received, the WaitDTLS is stopped.

   o  DTLSAborted is sent to the CAPWAP module to indicate that session
      abort (as requested by CAPWAP) is complete; this occurs to confirm
      a DTLS session abort, or when the WaitDTLS timer expires.  When
      this notification is received, the WaitDTLS is stopped.

   o  DTLSReassemblyFailure may be sent to the CAPWAP module to indicate
      DTLS fragment reassembly failure.

   o  DTLSDecapFailure may be sent to CAPWAP to indicate an
      decapsulation failure.  DTLSDecapFailure may be sent to CAPWAP to
      indicate an encryption/authentication failure.

   o  DTLSPeerDisconnect is sent to the CAPWAP module to indicate the
      DTLS session has been torn down.  Note that this notification is
      only received if the DTLS session has been established.

Pat Calhoun

> -----Original Message-----
> From: Pat Calhoun (pacalhou) 
> Sent: Sunday, January 07, 2007 12:46 PM
> To: capwap
> Subject: [Capwap] Proposed resolution for Issue 226 - revisited
> 
> Based on the feedback I had received on the original 
> submission for issue 226, I would like to submit the 
> following text. I believe that it addresses the comments I 
> had received.
> 
> Comments welcomed.
> ==================
>