Subject: [Capwap] Proposal for CAPWAP packet format

From: "David T. Perkins" <[email-masked]>
Date: Thu, 8 Jun 2006 01:47:21 -0700 (PDT)

HI,

After going through the CAPWAP-01 doc pretty closely, and
starting an implementation of a prototype AC and WTP,
I would like to submit the following as a replacement
for the definition of the CAPWAP packet formats found
in CAPWAP-01.

--------------------------
Proposal for CAPWAP Packet Format: 7-jun-2007:dtp

  CAPWAP Packet formats:

    CAPWAP Unprotected Data Packet:
    +-----------------------------------------+
    | IP  | UDP  | CAPWAP | CAPWAP | Wireless |
    | Hdr | Hdr  | MUX    | Data   | Payload  |
    |     |      | Hdr    | Hdr    |          |
    +-----------------------------------------+

    CAPWAP DTLS Protected Data Packet:
    +-----------------------------------------------------------+
    | IP  | UDP | CAPWAP | DTLS  | CAPWAP  | Wireless | DTLS    |
    | Hdr | Hdr | MUX    | Hdr   | Data    | Payload  | Trailer |
    |     |     | Hdr    |       | Hdr     |          |         |
    +-----------------------------------------------------------+
                         \--integrity checked-------------------/
                                 \--encrypted-------------------/

    CAPWAP Unprotected Control Packet:
    +------------------------------------------+
    | IP  | UDP  | CAPWAP | CAPWAP  | Message  |
    | Hdr | Hdr  | MUX    | Control | Elements |
    |     |      | Hdr    | Hdr     |          |
    +------------------------------------------+

    CAPWAP DTLS Protected Control Packet:
    +----------------------------------------------------------+
    | IP  | UDP | CAPWAP | DTLS | CAPWAP  | Message  | DTLS    |
    | Hdr | Hdr | MUX    | Hdr  | Control | Elements | Trailer |
    |     |     | Hdr    |      | Hdr     |          |         |
    +----------------------------------------------------------+
                          \--integrity checked-----------------/
                                \--encrypted-------------------/

      UDP: All CAPWAP packets are encapsulated within UDP.

      CAPWAP MUX Header: All CAPWAP protocol packets use a short header
          that specifies the version of CAPWAP and the type of the 
          CAPWAP packet.

      CAPWAP Data Header: This header is used for packets that
          encapsulate user data.

      Wireless Payload: A CAPWAP protocol packet that contains a wireless
          payload is known as a data frame.  The CAPWAP protocol does not
          dictate the format of the wireless payload, which is defined by
          the appropriate wireless standard. 

      DTLS Header: Protected CAPWAP packets use the DTLS protocol to
          provide message integrity and encryption services.

      DTLS Trailer: A field used to provide protection service for
          security of CAPWAP messages

      CAPWAP Control Header: The CAPWAP protocol includes a signalling
          component, known as the CAPWAP control protocol.  All CAPWAP
          control packets include a Control Header.

      Message Elements: A CAPWAP Control packet includes one or more
          message elements, which are found immediately following the
          control header.  These message elements are in a type,
          length, value format.

  NOTE: A CAPWAP MUX header is needed whether or not the same or
        different UDP ports are used for CAPWAP control and 
        data messages. This is because both CAPWAP data and
        control messages can be unprotected or protected by
        DTLS, and the MUX header is needed to distinguish
        protected from unprotected. Remember that CAPWAP
        "discovery requests" and "discovery responses" are
        unprotected, and that all other CAPWAP control
        message types are protected. 

  CAPWAP MUX Header:
                      
     0 1 2 3 4 5 6 7 
    +-+-+-+-+-+-+-+-+
    |Version| Type  |
    +-+-+-+-+-+-+-+-+

      Version - the version of the CAPWAP protocol (the first is 0)

      Type - packet type, values are:
                0 - CAPWAP Unprotected Data Packet
                1 - CAPWAP DTLS Protected Data Packet
                2 - CAPWAP Unprotected Control Packet
                3 - CAPWAP DTLS Protected Control Packet
               4-15 - reserved

  CAPWAP Data Header:

     DISCUSS: I removed the version field and moved it to the
              MUX Header. I also removed the Radio MAC field,
              since I believe that it is redundant with the
              RID field.
     0                   1                   2                   3     
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1   
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  
    | RID     | HLEN  |F|L|W|                      Flags            |  
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  
    |          Fragment ID          |     Frag Offset         |Rsv-2|  
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  
    |            (optional) Wireless Specific Information           |  
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |   ... (optional) Pad                                          |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                                                       
      RID: A 5 bit field which contains the Radio ID number for this
        packet.  WTPs with multiple radios but a single MAC Address range
        use this field to indicate which radio is associated with the
        packet. (DISCUSS: I don't understand what this last sentence
        means. Is there an example?)

      HLEN: Length of CAPWAP data header in multiples of 4 octets.
        (Similar to IP header length).  This length includes the
        optional portion.

      F: The Fragment 'F' bit indicates whether this packet is a
        fragment.  When this bit is one (1), the packet is a fragment
        and the payload MUST be combined with the payloads of other
        corresponding fragments to reassemble the complete payload
        exchanged between the WTP and AC.

      L: The Not Last 'L' bit is valid only if the 'F' bit is set and
        indicates whether the packet contains the last fragment of a
        fragmented exchange between WTP and AC.  When this bit is 1,
        the packet is not the last fragment.  When this bit is 0,
        the packet is the last fragment.

      W: The Wireless 'W' bit is used to specify whether the optional
        wireless specific information field is present in the header.
        A value of one (1) is used to represent the fact that the
        optional "Wireless Specific Information" field is present.

      Flags: A set of reserved bits for future flags in the CAPWAP data
        header.  These bits MUST be set to zero.

      Fragment ID: An 16 bit unsigned integer field whose value is
        assigned to each group of fragments making up a complete set.
        The fragment ID space is managed individually for every
        WTP/AC pair.  The value
        of Fragment ID is incremented with each new set of fragments.
        The value of Fragment ID wraps to zero after the maximum value
        has been used to identify a set of fragments. (DISCUSS: what
        value is used when the packet is not a fragment?)

      Fragment Offset: A 13 bit field that indicates where in the payload
        will this payload fragment belong during re-assembly.  This field
        is valid when the 'F' bit is set to 1.  The fragment offset is
        measured in units of 8 octets (64 bits).  The first fragment has
        offset zero.

      Reserved: The 3-bit Reserved-2 field is reserved and set to 0.

      Wireless Specific Information: This optional field contains
        technology specific information that may be used to carry per
        packet wireless information.  This field is only present if the
        'W' bit is set.

        The field contains the basic format:

       0                   1                   2                   3
       0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |  Wireless ID  |    Length     |             Data ...  
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

          Wireless ID: The wireless binding identifier.  The following
                values are defined:

                1 - : IEEE 802.11

          Length: The length of the data field

          Data: Wireless specific information, whose details are 
                defined in the technology specific binding section.

      Pad: optional octets of zero so that the header will be a multiple
            of 4 octets

  Wireless Payload:
    The format of the wireless payload depends on the encapsulation
    mode. There are two formats defined, which are:

      802.3 Frame - this is the standard IEEE 802.3 frame (DISCUSS:
            this needs to be defined, since IEEE 802.3 frame means
            different things to different people)
      802.11 native frame - DISCUSS: need some help here

  CAPWAP Control Header:

     DISCUSS: I totally removed the old "transport header", since
                I could not see any use for it in control messages.
                However, it means that a control message MUST fit
                in a single UDP message. I don't see that this
                is a problem. Anyone else see a problem with this
                limitation? It really simplifies control packet
                processing!

     0                   1                   2                   3   
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                       Message Type                            |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |  Msg Seq Num  | Msg ID    |res  |F|    Length of Msg Elements |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

      Message Type: This field identifies the function of the CAPWAP
            control message.  The Message Type field is comprised of
            an IANA Enterprise Number and an enterprise specific message
            type number.  The first three octets is the enterprise number
            in network byte order, with zero being used for CAPWAP generic
            message types and the IEEE 802.11 IANA assigned enterprise
            number 13277 being used for IEEE 802.11 technology specific
            message types.  The last octet is the enterprise specific
            message type number, which has a range from 0 to 255.

            The value of the message type field can be expressed as:

            Message type value = IANA Enterprise Number * 256 +
                             enterprise specific message type number

      Message Sequence Number: This field is used by the message
            retry layer to match paired messages, which are a
            response to a request, and a report to an acknowledgement.
            Each time a request (or report is sent) even for retries, 
            the sequence number is monotonically incremented.  After
            the maximum value is reached, the value wraps back to zero.
            The paired response (or acknowledgement) returns the value
            from the request (or report). Note the size is 8-bits, and
            thus a maximum of 255 paired messages can be concurrently
            in flight.

      Message ID: This field is used by the CAPWAP application to match
            responses (or acknowledgements) with requests (or reports).
            The value must be monotonically incremented for each unique
            request (or report). After the maximum value is reached,
            the value wraps back to zero. The paired response
            (or acknowledgement) returns the value from the request
            (or report). Note the size is 6-bits, and thus a maximum
            of 63 CAPWAP operations can be currently outstanding.
        
      F: This bit field indicates if the message is the first
            or second in a message pair. A value of "1" means
            first, and "0" means second. There are two types
            of message pairs, which a request and response,
            or a report and acknowledgement. Thus, the first
            is a request or report message (with the F field
            set to "1"), and the second is a response or
            acknowledgement (with the F field set to "0").

      NOTE: fields "message sequence number", "message ID", and "F"
            may seem confusing or redundant. However, they are needed
            to support the required retry mechanism. For example,
            consider two events, E1 and E2, occurring close together
            in time on a WTP. Say, the next Message ID value is 10.
            It would be used in the first report for the message ID
            value for event E1, and 11 would be used in the report
            for the second message ID value for event E2. The WTP
            would remember the E1-10, and the E2-11 pairing. Both
            messages would be handed off to the layer the provides
            retry service. The F bit is used so that the retry
            service does not have to understand the values of
            the message type, and so the numbers used by the WTP
            and AC for requests (and reports) do not have to
            be coordinated. The top layer must tell the retry
            service if a message to send is the first or second
            in a message pair. In this example, say, 203 is
            the next value for message sequence number. Thus,
            the first report would use 203 for the message
            sequence number, and the second would use 204.
            Say the first report was dropped by the network,
            but the second one was received and acknowledged
            by the AC. The retry layer would indicate to the
            WTP that an acknowledgement was received, and the
            WTP would use the message ID value of 11 to know it
            was for event E2. Since the first report was dropped,
            the retry layer would time it out, and send a retry
            using the next message sequence number of 205. When
            an acknowledgement came back, it would indicate this
            to the WTP, which would use the message ID of 10 to
            know that event E1 was acknowledged. If on the other
            hand, the network continued dropping the report for
            E1, the retry layer would indicate to the WTP that
            the report was not acknowledged by passing message
            ID 10.  The WTP could log this and try to determine
            if the session was still active, and if so, continue
            with other operations.
             
      DISCUSS: This note may be long, and maybe confusing. However,
                there is NO information in CAPWAP-01 to explain
                how retries are suppose to work! The above fields
                allow the round trip timeout to be dynamically
                computed, and for a drop of a request/response or
                report/acknowledgement pair to be handled without
                blowing away the DTLS session. Also, the retry
                service saves responses (and acknowledgements)
                and replies to them without impacting the
                upper level (that is, without causing the
                upper level to reprocess the operation.)

      Res: The Res field is currently unused and must be set to zero.

      Length of Message Elements: This field indicates in octets the
            length of the message elements field, which contains zero,
            one, or more message elements. The field is 14 bits wide,
            and thus the maximum size that can be specified 16K. However,
            the effective maximum size is the UDP packet max, minus
            the overhead of the CAPWAP and DTLS headers.

  Message Elements:
    The message elements field contains, zero, one, or more message
    element field, which has the following format:

    Message Element:

       0                   1                   2                   3
       0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |              Message Element Type                             |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |            Length             |  Value ....
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

        Message Element Type: This field identifies a message element
            of a CAPWAP control message.  The Message Element Type field
            is comprised of an IANA Enterprise Number and an enterprise
            specific message element type number.  The first three octets
            is the enterprise number in network byte order, with zero
            being used for CAPWAP generic message types and the
            IEEE 802.11 IANA assigned enterprise number 13277 being
            used for IEEE 802.11 technology specific message element
            types.  The last octet is the enterprise specific
            message element type number, which has a range from 0 to 255.

            The value of the message element type field can
            be expressed as:

            Message element type value = IANA Enterprise Number * 256 +
                      enterprise specific message element type number

--------------------------

Regards,
/david t. perkins

_________________________________________________________________
To unsubscribe or modify your subscription options, please visit:
http://lists.frascone.com/mailman/listinfo/capwap

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