Subject: [Capwap] Issue 160: All strings should be changed from US-ASCII to UTF-8

From: "Pat Calhoun (pacalhou)" <[email-masked]>
Date: Thu, 17 Aug 2006 08:58:48 -0700

All,

I've address the above mentioned issue by ensuring that all references
to strings now specifically state that the string is UTF-8 encoded.
There are, however, some exceptions, which I will list below as well.

<proposed text>
4.4.4.  AC Name

   The AC name message element contains an UTF-8 representation of the
   AC's identity.  The value is a variable length byte string.  The
   string is NOT zero terminated.

      0
      0 1 2 3 4 5 6 7
     +-+-+-+-+-+-+-+-+
     | Name ...
     +-+-+-+-+-+-+-+-+

   Type:   4 for AC Name

   Length:   > 0

   Name:   A variable length UTF-8 encoded string containing the AC's
      name

4.4.5.  AC Name with Index

   The AC Name with Index message element is sent by the AC to the WTP
   to configure preferred ACs.  The number of instances where this
   message element would be present is equal to the number of ACs
   configured on the WTP.

      0                   1
      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |     Index     |   AC Name...
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Type:   5 for AC Name with Index

   Length:   > 2

   Index:   The index of the preferred server (e.g., 1=primary,
      2=secondary).

   AC Name:   A variable length UTF-8 encoded string containing the AC's
      name.

4.4.8.  Add Station

   The Add Station message element is used by the AC to inform a WTP
   that it should forward traffic for a particular STA.  The Add Station
   message element will be accompanied by technology specific binding
   information element which may include security parameters.
   Consequently, the security parameters must be applied by the WTP for
   the particular STA.

   Once a STA's policy has been pushed to the WTP through this message

Calhoun, Editor, et al.  Expires November 2, 2006              [Page 49]

Internet-Draft        CAPWAP Protocol Specification             May 2006

   element, an AC may change any policies by simply sending a modified
   Add Station message element.  When a WTP receives an Add Station
   message element for an existing STA, it must override any existing
   state it may have for the STA in question.  The latest Add Station
   message element data overrides any previously received messages.

      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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |    Radio ID   |                  MAC Address                  |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                  MAC Address                  |  VLAN Name...
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Type:   8 for Add Station

   Length:   >= 7

   Radio ID:   An 8-bit value representing the radio

   MAC Address:   The STA's MAC Address

   VLAN Name:   An optional variable length UTF-8 encoded string
      containing the VLAN Name on which the WTP is to locally bridge
      user data.  Note this field is only valid with WTPs configured in
      Local MAC mode.

4.4.24.  Image Filename

   The image filename message element is sent by the WTP to the AC and
   is used to initiate the firmware download process.  This message
   element contains the image filename, which the AC subsequently
   transfers to the WTP via the Image Data message element.  The value
   is a variable length UTF-8 encoded string, which is NOT zero
   terminated.

      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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                           Filename ...                        |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Type:   24 for Image Filename

   Length:   >= 1

   Filename:   A variable length UTF-8 encoded string containing the
      filename to download.

4.4.26.  Location Data

   The Location Data message element is a variable length byte UTF-8
   encoded string containing user defined location information (e.g.
   "Next to Fridge").  This information is configurable by the network
   administrator, and allows for the WTP location to be determined

Calhoun, Editor, et al.  Expires November 2, 2006              [Page 59]

Internet-Draft        CAPWAP Protocol Specification             May 2006

   through this field.  The string is not zero terminated.

      0
      0 1 2 3 4 5 6 7
     +-+-+-+-+-+-+-+-+-
     | Location ...
     +-+-+-+-+-+-+-+-+-

   Type:   26 for Location Data

   Length:   > 0

   Timeout:   A non-zero terminated UTF-8 encoded string containing the
      WTP location.

4.4.42.  WTP Name

   The WTP Name message element is a variable length byte UTF-8 encoded
   string.  The string is not zero terminated.

      0
      0 1 2 3 4 5 6 7
     +-+-+-+-+-+-+-+-+-
     | WTP Name ...
     +-+-+-+-+-+-+-+-+-

Calhoun, Editor, et al.  Expires November 2, 2006              [Page 70]

Internet-Draft        CAPWAP Protocol Specification             May 2006

   Type:   42 for WTP Name

   Length:   variable

   WTP Name:   A non-zero terminated UTF-8 encoded string containing the
      WTP name.
</proposed text> 

As I mentioned above, there are exceptions in the specification, which I
will mention here:

<exception text>
2.4.4.3.  Certificate Usage

   Validation of the certificates by the AC and WTP is required so that
   only an AC may perform the functions of an AC and that only a WTP may
   perform the functions of a WTP.  This restriction of functions to the
   AC or WTP requires that the certificates used by the AC MUST be
   distinguishable from the certificate used by the WTP.  To accomplish
   this differentiation, the x.509v3 certificates MUST include the
   Extensions field [11] and MUST include the NetscapeComment [15]
   extension.

   For an AC, the value of the NetscapeComment extension MUST be the
   string "CAPWAP AC Device Certificate".  For a WTP, the value of the
   NetscapeComment extension MUST be the string "CAPWAP WTP Device
   Certificate".

   Part of the CAPWAP certificate validation process includes ensuring
   that the proper string is included in the NetscapeComment extension,
   and only allowing the CAPWAP session to be established if the
   extension does not represent the same role as the device validating
   the certificate.  For instance, a WTP MUST NOT accept a certificate
   whose NetscapeComment field is set to "CAPWAP WTP Device
   Certificate".

<PRC> The contents of the certificate will be encoded based on the rules
defined in the X.509 specification.

11.10.23.  IEEE 802.11 WTP Radio Configuration

   The WTP WLAN radio configuration is used by the AC to configure a
   Radio on the WTP, and by the WTP to deliver its radio configuration
   to the AC.  The message element value contains the following fields:

         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
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |    Radio ID   |    Reserved   | Num of BSSIDs |  DTIM Period  |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |                            BSSID                              |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |          BSSID                |      Beacon Period            |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |                         Country Code                          |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Type:   1046 for IEEE 802.11 WTP WLAN Radio Configuration

[...]

   Country Code:   This attribute identifies the country in which the
      station is operating.  The value of this field comes from the IEEE
      802.11 dot11CountryString MIB element (see [6]).  Special
      attention is required with use of this field, as implementations
      which take action based on this field could violate regulatory
      requirements.  Some regulatory bodies do permit configuration of
      the country code under certain restrictions, such as the FCC, when
      WTPs are certified as Software Defined Radios.

      The WTP and AC may ignore the value of this field, depending upon
      regulatory requirements, for example to avoid classification as a
      Software Defined Radio.  When this field is used, the first two
      octets of this string is the two character country code as
      described in document ISO/IEC 3166- 1, and the third octet MUST
      have the value 1, 2 or 3 as defined below.  When the value of the
      third octet is 255, the country code field is not used, and MUST
      be ignored.

      1  an ASCII space character, if the regulations under which the
         station is operating encompass all environments in the country,

      2  an ASCII 'O' character, if the regulations under which the
         station is operating are for an outdoor environment only, or

      3  an ASCII 'I' character, if the regulations under which the
         station is operating are for an indoor environment only

      255  Country Code field is not used; ignore the field.

<PRC> It is not appropriate to change the format of this string as this
is defined in the IEEE 802.11 specification.
</exception text>

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