qemu/roms/ipxe/src/include/ipxe/ieee80211.h

   1 #ifndef _IPXE_IEEE80211_H
   2 #define _IPXE_IEEE80211_H
   3
   4 #include <stddef.h>
   5 #include <ipxe/if_ether.h>      /* for ETH_ALEN */
   6 #include <endian.h>
   7
   8 /** @file
   9  * Constants and data structures defined in IEEE 802.11, subsetted
  10  * according to what iPXE knows how to use.
  11  */
  12
  13 FILE_LICENCE(GPL2_OR_LATER);
  14
  15 /* ---------- Maximum lengths of things ---------- */
  16
  17 /**
  18  * @defgroup ieee80211_maxlen Maximum lengths in the 802.11 protocol
  19  * @{
  20  */
  21
  22 /** Maximum length of frame payload
  23  *
  24  * This does not include cryptographic overhead, which can be up to 20
  25  * bytes, but it DOES include the 802.2 LLC/SNAP headers that are used
  26  * on data frames (but not management frames).
  27  */
  28 #define IEEE80211_MAX_DATA_LEN          2304
  29
  30 /** Length of LLC/SNAP headers on data frames */
  31 #define IEEE80211_LLC_HEADER_LEN        8
  32
  33 /** Maximum cryptographic overhead before encrypted data */
  34 #define IEEE80211_MAX_CRYPTO_HEADER     8
  35
  36 /** Maximum cryptographic overhead after encrypted data
  37  *
  38  * This does not count the MIC in TKIP frames, since that is
  39  * considered to be part of the MSDU and thus contributes to the size
  40  * of the data field.
  41  *
  42  * It @e does count the MIC in CCMP frames, which is considered part
  43  * of the MPDU (outside the data field).
  44  */
  45 #define IEEE80211_MAX_CRYPTO_TRAILER    8
  46
  47 /** Total maximum cryptographic overhead */
  48 #define IEEE80211_MAX_CRYPTO_OVERHEAD   16
  49
  50 /** Bytes of network-layer data that can go into a regular data frame */
  51 #define IEEE80211_MAX_FRAME_DATA        2296
  52
  53 /** Frame header length for frames we might work with
  54  *
  55  * QoS adds a two-byte field on top of this, and APs communicating
  56  * with each other in Wireless Distribution System (WDS) mode add an
  57  * extra 6-byte MAC address field, but we do not work with such
  58  * frames.
  59  */
  60 #define IEEE80211_TYP_FRAME_HEADER_LEN  24
  61
  62 /** Theoretical maximum frame header length
  63  *
  64  * This includes the QoS and WDS Addr4 fields that we should never
  65  * see.
  66  */
  67 #define IEEE80211_MAX_FRAME_HEADER_LEN  32
  68
  69 /** Maximum combined frame length
  70  *
  71  * The biggest frame will include 32 frame header bytes, 16 bytes of
  72  * crypto overhead, and 2304 data bytes.
  73  */
  74 #define IEEE80211_MAX_FRAME_LEN         2352
  75
  76 /** Maximum length of an ESSID */
  77 #define IEEE80211_MAX_SSID_LEN          32
  78
  79 /** @} */
  80
  81
  82 /* ---------- Frame Control defines ---------- */
  83
  84 /**
  85  * @defgroup ieee80211_fc 802.11 Frame Control field bits
  86  * @{
  87  */
  88
  89 /** 802.11 Frame Control field, Version bitmask */
  90 #define IEEE80211_FC_VERSION    0x0003
  91
  92 /** Expected value of Version bits in Frame Control */
  93 #define  IEEE80211_THIS_VERSION  0x0000
  94
  95
  96 /** 802.11 Frame Control field, Frame Type bitmask */
  97 #define IEEE80211_FC_TYPE       0x000C
  98
  99 /** Type value for management (layer-2) frames */
 100 #define  IEEE80211_TYPE_MGMT     0x0000
 101
 102 /** Type value for control (layer-1, hardware-managed) frames */
 103 #define  IEEE80211_TYPE_CTRL     0x0004
 104
 105 /** Type value for data frames */
 106 #define  IEEE80211_TYPE_DATA     0x0008
 107
 108
 109 /** 802.11 Frame Control field, Frame Subtype bitmask */
 110 #define IEEE80211_FC_SUBTYPE    0x00F0
 111
 112 /** Subtype value for association-request management frames
 113  *
 114  * Association request frames are sent after authentication from the
 115  * client to the Access Point to establish the client as part of the
 116  * Access Point's network.
 117  */
 118 #define  IEEE80211_STYPE_ASSOC_REQ    0x0000
 119
 120 /** Subtype value for association-response management frames
 121  *
 122  * Association response frames are sent by the Access Point to confirm
 123  * or deny the association requested in an association request frame.
 124  */
 125 #define  IEEE80211_STYPE_ASSOC_RESP   0x0010
 126
 127 /** Subtype value for reassociation-request management frames
 128  *
 129  * Reassociation request frames are sent by clients wishing to change
 130  * from one Access Point to another while roaming within the same
 131  * extended network (same ESSID).
 132  */
 133 #define  IEEE80211_STYPE_REASSOC_REQ  0x0020
 134
 135 /** Subtype value for reassociation-response management frames
 136  *
 137  * Reassociation response frames are sent by the Access Point to
 138  * confirm or deny the swap requested in a reassociation request
 139  * frame.
 140  */
 141 #define  IEEE80211_STYPE_REASSOC_RESP 0x0030
 142
 143 /** Subtype value for probe-request management frames
 144  *
 145  * Probe request frames are sent by clients to request that all Access
 146  * Points on the sending channel, or all belonging to a particular
 147  * ESSID, identify themselves by BSSID, supported transfer rates, RF
 148  * configuration, and other capabilities.
 149  */
 150 #define  IEEE80211_STYPE_PROBE_REQ    0x0040
 151
 152 /** Subtype value for probe-response management frames
 153  *
 154  * Probe response frames are sent by Access Points in response to
 155  * probe request frames, providing the requested information.
 156  */
 157 #define  IEEE80211_STYPE_PROBE_RESP   0x0050
 158
 159 /** Subtype value for beacon management frames
 160  *
 161  * Beacon frames are sent by Access Points at regular intervals,
 162  * usually ten per second, on the channel on which they communicate.
 163  * They can be used to probe passively for access points on a channel
 164  * where local regulatory restrictions prohibit active scanning, or
 165  * due to their regularity as a mechanism to determine the fraction of
 166  * packets that are being dropped.
 167  */
 168 #define  IEEE80211_STYPE_BEACON       0x0080
 169
 170 /** Subtype value for disassociation management frames
 171  *
 172  * Disassociation frames are sent by either a client or an Access
 173  * Point to unequivocally terminate the association between the two.
 174  * They may be sent by clients upon leaving the network, or by an
 175  * Access Point upon reconfiguration, among other reasons; they are
 176  * usually more "polite" than deauthentication frames.
 177  */
 178 #define  IEEE80211_STYPE_DISASSOC     0x00A0
 179
 180 /** Subtype value for authentication management frames
 181  *
 182  * Authentication frames are exchanged between a client and an Access
 183  * Point before association may be performed. Confusingly, in the most
 184  * common authentication method (Open System) no security tokens are
 185  * exchanged at all. Modern 802.11 security handshaking takes place
 186  * after association.
 187  */
 188 #define  IEEE80211_STYPE_AUTH         0x00B0
 189
 190 /** Subtype value for deauthentication management frames
 191  *
 192  * Deauthentication frames are sent by either a client or an Access
 193  * Point to terminate the authentication (and therefore also the
 194  * association) between the two. They are generally more forceful than
 195  * disassociation frames, sent for such reasons as a failure to
 196  * set up security properly after associating.
 197  */
 198 #define  IEEE80211_STYPE_DEAUTH       0x00C0
 199
 200 /** Subtype value for action management frames
 201  *
 202  * Action frames are used to implement spectrum management and QoS
 203  * features that iPXE currently does not support.
 204  */
 205 #define  IEEE80211_STYPE_ACTION       0x00D0
 206
 207
 208 /** Subtype value for RTS (request to send) control frames */
 209 #define  IEEE80211_STYPE_RTS          0x00B0
 210
 211 /** Subtype value for CTS (clear to send) control frames */
 212 #define  IEEE80211_STYPE_CTS          0x00C0
 213
 214 /** Subtype value for ACK (acknowledgement) control frames */
 215 #define  IEEE80211_STYPE_ACK          0x00D0
 216
 217
 218 /** Subtype value for ordinary data frames, with no QoS or CF add-ons */
 219 #define  IEEE80211_STYPE_DATA         0x0000
 220
 221 /** Subtype value for data frames containing no data */
 222 #define  IEEE80211_STYPE_NODATA       0x0040
 223
 224
 225 /** 802.11 Frame Control field: To Data System flag
 226  *
 227  * This is set on data frames sent to an Access Point.
 228  */
 229 #define IEEE80211_FC_TODS       0x0100
 230
 231 /** 802.11 Frame Control field: From Data System flag
 232  *
 233  * This is set on data frames sent from an Access Point. If both TODS
 234  * and FROMDS are set, the frame header is a 4-address format used for
 235  * inter-Access Point communication.
 236  */
 237 #define IEEE80211_FC_FROMDS     0x0200
 238
 239 /** 802.11 Frame Control field: More Fragments flag */
 240 #define IEEE80211_FC_MORE_FRAG  0x0400
 241
 242 /** 802.11 Frame Control field: Retransmission flag */
 243 #define IEEE80211_FC_RETRY      0x0800
 244
 245 /** 802.11 Frame Control field: Power Managed flag
 246  *
 247  * This is set on any frame sent by a low-power station that will go
 248  * into a power-saving mode immediately after this frame. Access
 249  * Points are not allowed to act as low-power stations.
 250  */
 251 #define IEEE80211_FC_PWR_MGMT   0x1000
 252
 253 /** 802.11 Frame Control field: More Data flag
 254  *
 255  * This is set on any frame sent by a station that has more data
 256  * queued to be sent than is in the frame.
 257  */
 258 #define IEEE80211_FC_MORE_DATA  0x2000
 259
 260 /** 802.11 Frame Control field: Protected flag
 261  *
 262  * This is set on frames in which data is encrypted (by any method).
 263  */
 264 #define IEEE80211_FC_PROTECTED  0x4000
 265
 266 /** 802.11 Frame Control field: Ordered flag [?] */
 267 #define IEEE80211_FC_ORDER      0x8000
 268
 269 /** @} */
 270
 271
 272 /* ---------- Sequence Control defines ---------- */
 273
 274 /**
 275  * @defgroup ieee80211_seq 802.11 Sequence Control field handling
 276  * @{
 277  */
 278
 279 /** Extract sequence number from 802.11 Sequence Control field */
 280 #define IEEE80211_SEQNR( seq )          ( ( seq ) >> 4 )
 281
 282 /** Extract fragment number from 802.11 Sequence Control field */
 283 #define IEEE80211_FRAG( seq )           ( ( seq ) & 0x000F )
 284
 285 /** Make 802.11 Sequence Control field from sequence and fragment numbers */
 286 #define IEEE80211_MAKESEQ( seqnr, frag )        \
 287         ( ( ( ( seqnr ) & 0xFFF ) << 4 ) | ( ( frag ) & 0xF ) )
 288
 289 /** @} */
 290
 291
 292 /* ---------- Frame header formats ---------- */
 293
 294 /**
 295  * @defgroup ieee80211_hdr 802.11 frame header formats
 296  * @{
 297  */
 298
 299 /** An 802.11 data or management frame without QoS or WDS header fields */
 300 struct ieee80211_frame
 301 {
 302         u16 fc;                 /**< 802.11 Frame Control field */
 303         u16 duration;           /**< Microseconds to reserve link */
 304         u8 addr1[ETH_ALEN];     /**< Address 1 (immediate receiver) */
 305         u8 addr2[ETH_ALEN];     /**< Address 2 (immediate sender) */
 306         u8 addr3[ETH_ALEN];     /**< Address 3 (often "forward to") */
 307         u16 seq;                /**< 802.11 Sequence Control field */
 308         u8 data[0];             /**< Beginning of frame data */
 309 } __attribute__((packed));
 310
 311 /** The 802.2 LLC/SNAP header sent before actual data in a data frame
 312  *
 313  * This header is not acknowledged in the 802.11 standard at all; it
 314  * is treated just like data for MAC-layer purposes, including
 315  * fragmentation and encryption. It is actually two headers
 316  * concatenated: a three-byte 802.2 LLC header indicating Subnetwork
 317  * Accesss Protocol (SNAP) in both source and destination Service
 318  * Access Point (SAP) fields, and a five-byte SNAP header indicating a
 319  * zero OUI and two-byte Ethernet protocol type field.
 320  *
 321  * Thus, an eight-byte header in which six of the bytes are redundant.
 322  * Lovely, isn't it?
 323  */
 324 struct ieee80211_llc_snap_header
 325 {
 326         /* LLC part: */
 327         u8 dsap;                /**< Destination SAP ID */
 328         u8 ssap;                /**< Source SAP ID */
 329         u8 ctrl;                /**< Control information */
 330
 331         /* SNAP part: */
 332         u8 oui[3];              /**< Organization code, usually 0 */
 333         u16 ethertype;          /**< Ethernet Type field */
 334 } __attribute__((packed));
 335
 336 /** Value for DSAP field in 802.2 LLC header for 802.11 frames: SNAP */
 337 #define IEEE80211_LLC_DSAP      0xAA
 338
 339 /** Value for SSAP field in 802.2 LLC header for 802.11 frames: SNAP */
 340 #define IEEE80211_LLC_SSAP      0xAA
 341
 342 /** Value for control field in 802.2 LLC header for 802.11 frames
 343  *
 344  * "Unnumbered Information".
 345  */
 346 #define IEEE80211_LLC_CTRL      0x03
 347
 348
 349 /** 16-byte RTS frame format, with abbreviated header */
 350 struct ieee80211_rts
 351 {
 352         u16 fc;                 /**< 802.11 Frame Control field */
 353         u16 duration;           /**< Microseconds to reserve link */
 354         u8 addr1[ETH_ALEN];     /**< Address 1 (immediate receiver) */
 355         u8 addr2[ETH_ALEN];     /**< Address 2 (immediate sender) */
 356 } __attribute__((packed));
 357
 358 /** Length of 802.11 RTS control frame */
 359 #define IEEE80211_RTS_LEN       16
 360
 361 /** 10-byte CTS or ACK frame format, with abbreviated header */
 362 struct ieee80211_cts_or_ack
 363 {
 364         u16 fc;                 /**< 802.11 Frame Control field */
 365         u16 duration;           /**< Microseconds to reserve link */
 366         u8 addr1[ETH_ALEN];     /**< Address 1 (immediate receiver) */
 367 } __attribute__((packed));
 368
 369 #define ieee80211_cts ieee80211_cts_or_ack
 370 #define ieee80211_ack ieee80211_cts_or_ack
 371
 372 /** Length of 802.11 CTS control frame */
 373 #define IEEE80211_CTS_LEN       10
 374
 375 /** Length of 802.11 ACK control frame */
 376 #define IEEE80211_ACK_LEN       10
 377
 378 /** @} */
 379
 380
 381 /* ---------- Capability bits, status and reason codes ---------- */
 382
 383 /**
 384  * @defgroup ieee80211_capab 802.11 management frame capability field bits
 385  * @{
 386  */
 387
 388 /** Set if using an Access Point (managed mode) */
 389 #define IEEE80211_CAPAB_MANAGED       0x0001
 390
 391 /** Set if operating in IBSS (no-AP, "Ad-Hoc") mode */
 392 #define IEEE80211_CAPAB_ADHOC         0x0002
 393
 394 /** Set if we support Contention-Free Period operation */
 395 #define IEEE80211_CAPAB_CFPOLL        0x0004
 396
 397 /** Set if we wish to be polled for Contention-Free operation */
 398 #define IEEE80211_CAPAB_CFPR          0x0008
 399
 400 /** Set if the network is encrypted (by any method) */
 401 #define IEEE80211_CAPAB_PRIVACY       0x0010
 402
 403 /** Set if PHY supports short preambles on 802.11b */
 404 #define IEEE80211_CAPAB_SHORT_PMBL    0x0020
 405
 406 /** Set if PHY supports PBCC modulation */
 407 #define IEEE80211_CAPAB_PBCC          0x0040
 408
 409 /** Set if we support Channel Agility */
 410 #define IEEE80211_CAPAB_CHAN_AGILITY  0x0080
 411
 412 /** Set if we support spectrum management (DFS and TPC) on the 5GHz band */
 413 #define IEEE80211_CAPAB_SPECTRUM_MGMT 0x0100
 414
 415 /** Set if we support Quality of Service enhancements */
 416 #define IEEE80211_CAPAB_QOS           0x0200
 417
 418 /** Set if PHY supports short slot time on 802.11g */
 419 #define IEEE80211_CAPAB_SHORT_SLOT    0x0400
 420
 421 /** Set if PHY supports APSD option */
 422 #define IEEE80211_CAPAB_APSD          0x0800
 423
 424 /** Set if PHY supports DSSS/OFDM modulation (one way of 802.11 b/g mixing) */
 425 #define IEEE80211_CAPAB_DSSS_OFDM     0x2000
 426
 427 /** Set if we support delayed block ACK */
 428 #define IEEE80211_CAPAB_DELAYED_BACK  0x4000
 429
 430 /** Set if we support immediate block ACK */
 431 #define IEEE80211_CAPAB_IMMED_BACK    0x8000
 432
 433 /** @} */
 434
 435
 436 /**
 437  * @defgroup ieee80211_status 802.11 status codes
 438  *
 439  * These are returned to indicate an immediate denial of
 440  * authentication or association. In iPXE, the lower 5 bits of the
 441  * status code are encoded into the file-unique portion of an error
 442  * code, the ERRFILE portion is always @c ERRFILE_net80211, and the
 443  * POSIX error code is @c ECONNREFUSED for status 0-31 or @c
 444  * EHOSTUNREACH for status 32-63.
 445  *
 446  * For a complete table with non-abbreviated error messages, see IEEE
 447  * Std 802.11-2007, Table 7-23, p.94.
 448  *
 449  * @{
 450  */
 451
 452 #define IEEE80211_STATUS_SUCCESS                0
 453 #define IEEE80211_STATUS_FAILURE                1
 454 #define IEEE80211_STATUS_CAPAB_UNSUPP           10
 455 #define IEEE80211_STATUS_REASSOC_INVALID        11
 456 #define IEEE80211_STATUS_ASSOC_DENIED           12
 457 #define IEEE80211_STATUS_AUTH_ALGO_UNSUPP       13
 458 #define IEEE80211_STATUS_AUTH_SEQ_INVALID       14
 459 #define IEEE80211_STATUS_AUTH_CHALL_INVALID     15
 460 #define IEEE80211_STATUS_AUTH_TIMEOUT           16
 461 #define IEEE80211_STATUS_ASSOC_NO_ROOM          17
 462 #define IEEE80211_STATUS_ASSOC_NEED_RATE        18
 463 #define IEEE80211_STATUS_ASSOC_NEED_SHORT_PMBL  19
 464 #define IEEE80211_STATUS_ASSOC_NEED_PBCC        20
 465 #define IEEE80211_STATUS_ASSOC_NEED_CHAN_AGILITY 21
 466 #define IEEE80211_STATUS_ASSOC_NEED_SPECTRUM_MGMT 22
 467 #define IEEE80211_STATUS_ASSOC_BAD_POWER        23
 468 #define IEEE80211_STATUS_ASSOC_BAD_CHANNELS     24
 469 #define IEEE80211_STATUS_ASSOC_NEED_SHORT_SLOT  25
 470 #define IEEE80211_STATUS_ASSOC_NEED_DSSS_OFDM   26
 471 #define IEEE80211_STATUS_QOS_FAILURE            32
 472 #define IEEE80211_STATUS_QOS_NO_ROOM            33
 473 #define IEEE80211_STATUS_LINK_IS_HORRIBLE       34
 474 #define IEEE80211_STATUS_ASSOC_NEED_QOS         35
 475 #define IEEE80211_STATUS_REQUEST_DECLINED       37
 476 #define IEEE80211_STATUS_REQUEST_INVALID        38
 477 #define IEEE80211_STATUS_TS_NOT_CREATED_AGAIN   39
 478 #define IEEE80211_STATUS_INVALID_IE             40
 479 #define IEEE80211_STATUS_GROUP_CIPHER_INVALID   41
 480 #define IEEE80211_STATUS_PAIR_CIPHER_INVALID    42
 481 #define IEEE80211_STATUS_AKMP_INVALID           43
 482 #define IEEE80211_STATUS_RSN_VERSION_UNSUPP     44
 483 #define IEEE80211_STATUS_RSN_CAPAB_INVALID      45
 484 #define IEEE80211_STATUS_CIPHER_REJECTED        46
 485 #define IEEE80211_STATUS_TS_NOT_CREATED_WAIT    47
 486 #define IEEE80211_STATUS_DIRECT_LINK_FORBIDDEN  48
 487 #define IEEE80211_STATUS_DEST_NOT_PRESENT       49
 488 #define IEEE80211_STATUS_DEST_NOT_QOS           50
 489 #define IEEE80211_STATUS_ASSOC_LISTEN_TOO_HIGH  51
 490
 491 /** @} */
 492
 493
 494
 495 /**
 496  * @defgroup ieee80211_reason 802.11 reason codes
 497  *
 498  * These are returned to indicate the reason for a deauthentication or
 499  * disassociation sent (usually) after authentication or association
 500  * had succeeded.  In iPXE, the lower 5 bits of the reason code are
 501  * encoded into the file-unique portion of an error code, the ERRFILE
 502  * portion is always @c ERRFILE_net80211, and the POSIX error code is
 503  * @c ECONNRESET for reason 0-31 or @c ENETRESET for reason 32-63.
 504  *
 505  * For a complete table with non-abbreviated error messages, see IEEE
 506  * Std 802.11-2007, Table 7-22, p.92.
 507  *
 508  * @{
 509  */
 510
 511 #define IEEE80211_REASON_NONE                   0
 512 #define IEEE80211_REASON_UNSPECIFIED            1
 513 #define IEEE80211_REASON_AUTH_NO_LONGER_VALID   2
 514 #define IEEE80211_REASON_LEAVING                3
 515 #define IEEE80211_REASON_INACTIVITY             4
 516 #define IEEE80211_REASON_OUT_OF_RESOURCES       5
 517 #define IEEE80211_REASON_NEED_AUTH              6
 518 #define IEEE80211_REASON_NEED_ASSOC             7
 519 #define IEEE80211_REASON_LEAVING_TO_ROAM        8
 520 #define IEEE80211_REASON_REASSOC_INVALID        9
 521 #define IEEE80211_REASON_BAD_POWER              10
 522 #define IEEE80211_REASON_BAD_CHANNELS           11
 523 #define IEEE80211_REASON_INVALID_IE             13
 524 #define IEEE80211_REASON_MIC_FAILURE            14
 525 #define IEEE80211_REASON_4WAY_TIMEOUT           15
 526 #define IEEE80211_REASON_GROUPKEY_TIMEOUT       16
 527 #define IEEE80211_REASON_4WAY_INVALID           17
 528 #define IEEE80211_REASON_GROUP_CIPHER_INVALID   18
 529 #define IEEE80211_REASON_PAIR_CIPHER_INVALID    19
 530 #define IEEE80211_REASON_AKMP_INVALID           20
 531 #define IEEE80211_REASON_RSN_VERSION_INVALID    21
 532 #define IEEE80211_REASON_RSN_CAPAB_INVALID      22
 533 #define IEEE80211_REASON_8021X_FAILURE          23
 534 #define IEEE80211_REASON_CIPHER_REJECTED        24
 535 #define IEEE80211_REASON_QOS_UNSPECIFIED        32
 536 #define IEEE80211_REASON_QOS_OUT_OF_RESOURCES   33
 537 #define IEEE80211_REASON_LINK_IS_HORRIBLE       34
 538 #define IEEE80211_REASON_INVALID_TXOP           35
 539 #define IEEE80211_REASON_REQUESTED_LEAVING      36
 540 #define IEEE80211_REASON_REQUESTED_NO_USE       37
 541 #define IEEE80211_REASON_REQUESTED_NEED_SETUP   38
 542 #define IEEE80211_REASON_REQUESTED_TIMEOUT      39
 543 #define IEEE80211_REASON_CIPHER_UNSUPPORTED     45
 544
 545 /** @} */
 546
 547 /* ---------- Information element declarations ---------- */
 548
 549 /**
 550  * @defgroup ieee80211_ie 802.11 information elements
 551  *
 552  * Many management frames include a section that amounts to a
 553  * concatenation of these information elements, so that the sender can
 554  * choose which information to send and the receiver can ignore the
 555  * parts it doesn't understand. Each IE contains a two-byte header,
 556  * one byte ID and one byte length, followed by IE-specific data. The
 557  * length does not include the two-byte header. Information elements
 558  * are required to be sorted by ID, but iPXE does not require that in
 559  * those it receives.
 560  *
 561  * This group also includes a few inline functions to simplify common
 562  * tasks in IE processing.
 563  *
 564  * @{
 565  */
 566
 567 /** Generic 802.11 information element header */
 568 struct ieee80211_ie_header {
 569         u8 id;                  /**< Information element ID */
 570         u8 len;                 /**< Information element length */
 571 } __attribute__ ((packed));
 572
 573
 574 /** 802.11 SSID information element */
 575 struct ieee80211_ie_ssid {
 576         u8 id;                  /**< SSID ID: 0 */
 577         u8 len;                 /**< SSID length */
 578         char ssid[0];           /**< SSID data, not NUL-terminated */
 579 } __attribute__ ((packed));
 580
 581 /** Information element ID for SSID information element */
 582 #define IEEE80211_IE_SSID       0
 583
 584
 585 /** 802.11 rates information element
 586  *
 587  * The first 8 rates go in an IE of type RATES (1), and any more rates
 588  * go in one of type EXT_RATES (50). Each rate is a byte with the low
 589  * 7 bits equal to the rate in units of 500 kbps, and the high bit set
 590  * if and only if the rate is "basic" (must be supported by all
 591  * connected stations).
 592  */
 593 struct ieee80211_ie_rates {
 594         u8 id;                  /**< Rates ID: 1 or 50 */
 595         u8 len;                 /**< Number of rates */
 596         u8 rates[0];            /**< Rates data, one rate per byte */
 597 } __attribute__ ((packed));
 598
 599 /** Information element ID for rates information element */
 600 #define IEEE80211_IE_RATES      1
 601
 602 /** Information element ID for extended rates information element */
 603 #define IEEE80211_IE_EXT_RATES  50
 604
 605
 606 /** 802.11 Direct Spectrum parameter information element
 607  *
 608  * This just contains the channel number. It has the fancy name
 609  * because IEEE 802.11 also defines a frequency-hopping PHY that
 610  * changes channels at regular intervals following a predetermined
 611  * pattern; in practice nobody uses the FH PHY.
 612  */
 613 struct ieee80211_ie_ds_param {
 614         u8 id;                  /**< DS parameter ID: 3 */
 615         u8 len;                 /**< DS parameter length: 1 */
 616         u8 current_channel;     /**< Current channel number, 1-14 */
 617 } __attribute__ ((packed));
 618
 619 /** Information element ID for Direct Spectrum parameter information element */
 620 #define IEEE80211_IE_DS_PARAM   3
 621
 622
 623 /** 802.11 Country information element regulatory extension triplet */
 624 struct ieee80211_ie_country_ext_triplet {
 625         u8 reg_ext_id;          /**< Regulatory extension ID */
 626         u8 reg_class_id;        /**< Regulatory class ID */
 627         u8 coverage_class;      /**< Coverage class */
 628 } __attribute__ ((packed));
 629
 630 /** 802.11 Country information element regulatory band triplet */
 631 struct ieee80211_ie_country_band_triplet {
 632         u8 first_channel;       /**< Channel number for first channel in band */
 633         u8 nr_channels;         /**< Number of contiguous channels in band */
 634         u8 max_txpower;         /**< Maximum TX power in dBm */
 635 } __attribute__ ((packed));
 636
 637 /** 802.11 Country information element regulatory triplet
 638  *
 639  * It is a band triplet if the first byte is 200 or less, and a
 640  * regulatory extension triplet otherwise.
 641  */
 642 union ieee80211_ie_country_triplet {
 643         /** Differentiator between band and ext triplets */
 644         u8 first;
 645
 646         /** Information about a band of channels */
 647         struct ieee80211_ie_country_band_triplet band;
 648
 649         /** Regulatory extension information */
 650         struct ieee80211_ie_country_ext_triplet ext;
 651 };
 652
 653 /** 802.11 Country information element
 654  *
 655  * This contains some data about RF regulations.
 656  */
 657 struct ieee80211_ie_country {
 658         u8 id;                  /**< Country information ID: 7 */
 659         u8 len;                 /**< Country information length: varies */
 660         char name[2];           /**< ISO Alpha2 country code */
 661         char in_out;            /**< 'I' for indoor, 'O' for outdoor */
 662
 663         /** List of regulatory triplets */
 664         union ieee80211_ie_country_triplet triplet[0];
 665 } __attribute__ ((packed));
 666
 667 /** Information element ID for Country information element */
 668 #define IEEE80211_IE_COUNTRY    7
 669
 670
 671 /** 802.11 Request information element
 672  *
 673  * This contains a list of information element types we would like to
 674  * be included in probe response frames.
 675  */
 676 struct ieee80211_ie_request {
 677         u8 id;                  /**< Request ID: 10 */
 678         u8 len;                 /**< Number of IEs requested */
 679         u8 request[0];          /**< List of IEs requested */
 680 } __attribute__ ((packed));
 681
 682 /** Information element ID for Request information element */
 683 #define IEEE80211_IE_REQUEST    10
 684
 685
 686 /** 802.11 Challenge Text information element
 687  *
 688  * This is used in authentication frames under Shared Key
 689  * authentication.
 690  */
 691 struct ieee80211_ie_challenge_text {
 692         u8 id;                  /**< Challenge Text ID: 16 */
 693         u8 len;                 /**< Challenge Text length: usually 128 */
 694         u8 challenge_text[0];   /**< Challenge Text data */
 695 } __attribute__ ((packed));
 696
 697 /** Information element ID for Challenge Text information element */
 698 #define IEEE80211_IE_CHALLENGE_TEXT     16
 699
 700
 701 /** 802.11 Power Constraint information element
 702  *
 703  * This is used to specify an additional power limitation on top of
 704  * the Country requirements.
 705  */
 706 struct ieee80211_ie_power_constraint {
 707         u8 id;                  /**< Power Constraint ID: 52 */
 708         u8 len;                 /**< Power Constraint length: 1 */
 709         u8 power_constraint;    /**< Decrease in allowed TX power, dBm */
 710 } __attribute__ ((packed));
 711
 712 /** Information element ID for Power Constraint information element */
 713 #define IEEE80211_IE_POWER_CONSTRAINT   52
 714
 715
 716 /** 802.11 Power Capability information element
 717  *
 718  * This is used in association request frames to indicate the extremes
 719  * of our TX power abilities. It is required only if we indicate
 720  * support for spectrum management.
 721  */
 722 struct ieee80211_ie_power_capab {
 723         u8 id;                  /**< Power Capability ID: 33 */
 724         u8 len;                 /**< Power Capability length: 2 */
 725         u8 min_txpower;         /**< Minimum possible TX power, dBm */
 726         u8 max_txpower;         /**< Maximum possible TX power, dBm */
 727 } __attribute__ ((packed));
 728
 729 /** Information element ID for Power Capability information element */
 730 #define IEEE80211_IE_POWER_CAPAB        33
 731
 732
 733 /** 802.11 Channels information element channel band tuple */
 734 struct ieee80211_ie_channels_channel_band {
 735         u8 first_channel;       /**< Channel number of first channel in band */
 736         u8 nr_channels;         /**< Number of channels in band */
 737 } __attribute__ ((packed));
 738
 739 /** 802.11 Channels information element
 740  *
 741  * This is used in association frames to indicate the channels we can
 742  * use. It is required only if we indicate support for spectrum
 743  * management.
 744  */
 745 struct ieee80211_ie_channels {
 746         u8 id;                  /**< Channels ID: 36 */
 747         u8 len;                 /**< Channels length: 2 */
 748
 749         /** List of (start, length) channel bands we can use */
 750         struct ieee80211_ie_channels_channel_band channels[0];
 751 } __attribute__ ((packed));
 752
 753 /** Information element ID for Channels information element */
 754 #define IEEE80211_IE_CHANNELS   36
 755
 756
 757 /** 802.11 ERP Information information element
 758  *
 759  * This is used to communicate some PHY-level flags.
 760  */
 761 struct ieee80211_ie_erp_info {
 762         u8 id;                  /**< ERP Information ID: 42 */
 763         u8 len;                 /**< ERP Information length: 1 */
 764         u8 erp_info;            /**< ERP flags */
 765 } __attribute__ ((packed));
 766
 767 /** Information element ID for ERP Information information element */
 768 #define IEEE80211_IE_ERP_INFO   42
 769
 770 /** ERP information element: Flag set if 802.11b stations are present */
 771 #define  IEEE80211_ERP_NONERP_PRESENT   0x01
 772
 773 /** ERP information element: Flag set if CTS protection must be used */
 774 #define  IEEE80211_ERP_USE_PROTECTION   0x02
 775
 776 /** ERP information element: Flag set if long preambles must be used */
 777 #define  IEEE80211_ERP_BARKER_LONG      0x04
 778
 779
 780 /** 802.11 Robust Security Network ("WPA") information element
 781  *
 782  * Showing once again a striking clarity of design, the IEEE folks put
 783  * dynamically-sized data in the middle of this structure. As such,
 784  * the below structure definition only works for IEs we create
 785  * ourselves, which always have one pairwise cipher and one AKM;
 786  * received IEs should be parsed piecemeal.
 787  *
 788  * Also inspired was IEEE's choice of 16-bit fields to count the
 789  * number of 4-byte elements in a structure with a maximum length of
 790  * 255 bytes.
 791  *
 792  * Many fields reference a cipher or authentication-type ID; this is a
 793  * three-byte OUI followed by one byte identifying the cipher with
 794  * respect to that OUI. For all standard ciphers the OUI is 00:0F:AC,
 795  * except in old-style WPA IEs encapsulated in vendor-specific IEs,
 796  * where it's 00:50:F2.
 797  */
 798 struct ieee80211_ie_rsn {
 799         /** Information element ID */
 800         u8 id;
 801
 802         /** Information element length */
 803         u8 len;
 804
 805         /** RSN information element version */
 806         u16 version;
 807
 808         /** Cipher ID for the cipher used in multicast/broadcast frames */
 809         u32 group_cipher;
 810
 811         /** Number of unicast ciphers supported */
 812         u16 pairwise_count;
 813
 814         /** List of cipher IDs for supported unicast frame ciphers */
 815         u32 pairwise_cipher[1];
 816
 817         /** Number of authentication types supported */
 818         u16 akm_count;
 819
 820         /** List of authentication type IDs for supported types */
 821         u32 akm_list[1];
 822
 823         /** Security capabilities field (RSN only) */
 824         u16 rsn_capab;
 825
 826         /** Number of PMKIDs included (present only in association frames) */
 827         u16 pmkid_count;
 828
 829         /** List of PMKIDs included, each a 16-byte SHA1 hash */
 830         u8 pmkid_list[0];
 831 } __attribute__((packed));
 832
 833 /** Information element ID for Robust Security Network information element */
 834 #define IEEE80211_IE_RSN        48
 835
 836 /** Calculate necessary size of RSN information element
 837  *
 838  * @v npair     Number of pairwise ciphers supported
 839  * @v nauth     Number of authentication types supported
 840  * @v npmkid    Number of PMKIDs to include
 841  * @v is_rsn    If TRUE, calculate RSN IE size; if FALSE, calculate WPA IE size
 842  * @ret size    Necessary size of IE, including header bytes
 843  */
 844 static inline size_t ieee80211_rsn_size ( int npair, int nauth, int npmkid,
 845                                           int rsn_ie ) {
 846         return 16 + 4 * ( npair + nauth ) + 16 * npmkid - 4 * ! rsn_ie;
 847 }
 848
 849 /** Make OUI plus type byte into 32-bit integer for easy comparison */
 850 #if __BYTE_ORDER == __BIG_ENDIAN
 851 #define _MKOUI( a, b, c, t )    \
 852                 ( ( ( a ) << 24 ) | ( ( b ) << 16 ) | ( ( c ) << 8 ) | ( d ) )
 853 #define  OUI_ORG_MASK           0xFFFFFF00
 854 #define  OUI_TYPE_MASK          0x000000FF
 855 #else
 856 #define _MKOUI( a, b, c, t )    \
 857                 ( ( ( t ) << 24 ) | ( ( c ) << 16 ) | ( ( b ) << 8 ) | ( a ) )
 858 #define  OUI_ORG_MASK           0x00FFFFFF
 859 #define  OUI_TYPE_MASK          0xFF000000
 860 #endif
 861
 862 /** Organization part for OUIs in standard RSN IE */
 863 #define  IEEE80211_RSN_OUI      _MKOUI ( 0x00, 0x0F, 0xAC, 0 )
 864
 865 /** Organization part for OUIs in old WPA IE */
 866 #define  IEEE80211_WPA_OUI      _MKOUI ( 0x00, 0x50, 0xF2, 0 )
 867
 868 /** Old vendor-type WPA IE OUI type + subtype */
 869 #define  IEEE80211_WPA_OUI_VEN  _MKOUI ( 0x00, 0x50, 0xF2, 0x01 )
 870
 871
 872 /** 802.11 RSN IE: expected version number */
 873 #define  IEEE80211_RSN_VERSION          1
 874
 875 /** 802.11 RSN IE: cipher type for 40-bit WEP */
 876 #define  IEEE80211_RSN_CTYPE_WEP40      _MKOUI ( 0, 0, 0, 0x01 )
 877
 878 /** 802.11 RSN IE: cipher type for 104-bit WEP */
 879 #define  IEEE80211_RSN_CTYPE_WEP104     _MKOUI ( 0, 0, 0, 0x05 )
 880
 881 /** 802.11 RSN IE: cipher type for TKIP ("WPA") */
 882 #define  IEEE80211_RSN_CTYPE_TKIP       _MKOUI ( 0, 0, 0, 0x02 )
 883
 884 /** 802.11 RSN IE: cipher type for CCMP ("WPA2") */
 885 #define  IEEE80211_RSN_CTYPE_CCMP       _MKOUI ( 0, 0, 0, 0x04 )
 886
 887 /** 802.11 RSN IE: cipher type for "use group"
 888  *
 889  * This can only appear as a pairwise cipher, and means unicast frames
 890  * should be encrypted in the same way as broadcast/multicast frames.
 891  */
 892 #define  IEEE80211_RSN_CTYPE_USEGROUP   _MKOUI ( 0, 0, 0, 0x00 )
 893
 894 /** 802.11 RSN IE: auth method type for using an 802.1X server */
 895 #define  IEEE80211_RSN_ATYPE_8021X      _MKOUI ( 0, 0, 0, 0x01 )
 896
 897 /** 802.11 RSN IE: auth method type for using a pre-shared key */
 898 #define  IEEE80211_RSN_ATYPE_PSK        _MKOUI ( 0, 0, 0, 0x02 )
 899
 900 /** 802.11 RSN IE capabilities: AP supports pre-authentication */
 901 #define  IEEE80211_RSN_CAPAB_PREAUTH    0x001
 902
 903 /** 802.11 RSN IE capabilities: Node has conflict between TKIP and WEP
 904  *
 905  * This is a legacy issue; APs always set it to 0, and iPXE sets it to
 906  * 0.
 907  */
 908 #define  IEEE80211_RSN_CAPAB_NO_PAIRWISE 0x002
 909
 910 /** 802.11 RSN IE capabilities: Number of PTKSA replay counters
 911  *
 912  * A value of 0 means one replay counter, 1 means two, 2 means four,
 913  * and 3 means sixteen.
 914  */
 915 #define  IEEE80211_RSN_CAPAB_PTKSA_REPLAY 0x00C
 916
 917 /** 802.11 RSN IE capabilities: Number of GTKSA replay counters
 918  *
 919  * A value of 0 means one replay counter, 1 means two, 2 means four,
 920  * and 3 means sixteen.
 921  */
 922 #define  IEEE80211_RSN_CAPAB_GTKSA_REPLAY 0x030
 923
 924 /** 802.11 RSN IE capabilities: PeerKey Handshaking is suported */
 925 #define  IEEE80211_RSN_CAPAB_PEERKEY    0x200
 926
 927
 928 /** 802.11 RSN IE capabilities: One replay counter
 929  *
 930  * This should be AND'ed with @c IEEE80211_RSN_CAPAB_PTKSA_REPLAY or
 931  * @c IEEE80211_RSN_CAPAB_GTKSA_REPLAY (or both) to produce a value
 932  * which can be OR'ed into the capabilities field.
 933  */
 934 #define IEEE80211_RSN_1_CTR             0x000
 935
 936 /** 802.11 RSN IE capabilities: Two replay counters */
 937 #define IEEE80211_RSN_2_CTR             0x014
 938
 939 /** 802.11 RSN IE capabilities: Four replay counters */
 940 #define IEEE80211_RSN_4_CTR             0x028
 941
 942 /** 802.11 RSN IE capabilities: 16 replay counters */
 943 #define IEEE80211_RSN_16_CTR            0x03C
 944
 945
 946 /** 802.11 Vendor Specific information element
 947  *
 948  * One often sees the RSN IE masquerading as vendor-specific on
 949  * devices that were produced prior to 802.11i (the WPA amendment)
 950  * being finalized.
 951  */
 952 struct ieee80211_ie_vendor {
 953         u8 id;                  /**< Vendor-specific ID: 221 */
 954         u8 len;                 /**< Vendor-specific length: variable */
 955         u32 oui;                /**< OUI and vendor-specific type byte */
 956         u8 data[0];             /**< Vendor-specific data */
 957 } __attribute__ ((packed));
 958
 959 /** Information element ID for Vendor Specific information element */
 960 #define IEEE80211_IE_VENDOR     221
 961
 962
 963
 964
 965 /** Any 802.11 information element
 966  *
 967  * This is formatted for ease of use, so IEs with complex structures
 968  * get referenced in full, while those with only one byte of data or a
 969  * simple array are pulled in to avoid a layer of indirection like
 970  * ie->channels.channels[0].
 971  */
 972 union ieee80211_ie
 973 {
 974         /** Generic and simple information element info */
 975         struct {
 976                 u8 id;          /**< Information element ID */
 977                 u8 len;         /**< Information element data length */
 978                 union {
 979                         char ssid[0];   /**< SSID text */
 980                         u8 rates[0];    /**< Rates data */
 981                         u8 request[0];  /**< Request list */
 982                         u8 challenge_text[0]; /**< Challenge text data */
 983                         u8 power_constraint; /**< Power constraint, dBm */
 984                         u8 erp_info;    /**< ERP information flags */
 985                         /** List of channels */
 986                         struct ieee80211_ie_channels_channel_band channels[0];
 987                 };
 988         };
 989
 990         /** DS parameter set */
 991         struct ieee80211_ie_ds_param ds_param;
 992
 993         /** Country information */
 994         struct ieee80211_ie_country country;
 995
 996         /** Power capability */
 997         struct ieee80211_ie_power_capab power_capab;
 998
 999         /** Security information */
1000         struct ieee80211_ie_rsn rsn;
1001
1002         /** Vendor-specific */
1003         struct ieee80211_ie_vendor vendor;
1004 };
1005
1006 /** Check that 802.11 information element is bounded by buffer
1007  *
1008  * @v ie        Information element
1009  * @v end       End of buffer in which information element is stored
1010  * @ret ok      TRUE if the IE is completely contained within the buffer
1011  */
1012 static inline int ieee80211_ie_bound ( union ieee80211_ie *ie, void *end )
1013 {
1014         void *iep = ie;
1015         return ( iep + 2 <= end && iep + 2 + ie->len <= end );
1016 }
1017
1018 /** Advance to next 802.11 information element
1019  *
1020  * @v ie        Current information element pointer
1021  * @v end       Pointer to first byte not in information element space
1022  * @ret next    Pointer to next information element, or NULL if no more
1023  *
1024  * When processing received IEs, @a end should be set to the I/O
1025  * buffer tail pointer; when marshalling IEs for sending, @a end
1026  * should be NULL.
1027  */
1028 static inline union ieee80211_ie * ieee80211_next_ie ( union ieee80211_ie *ie,
1029                                                        void *end )
1030 {
1031         void *next_ie_byte = ( void * ) ie + ie->len + 2;
1032         union ieee80211_ie *next_ie = next_ie_byte;
1033
1034         if ( ! end )
1035                 return next_ie;
1036
1037         if ( ieee80211_ie_bound ( next_ie, end ) )
1038                 return next_ie;
1039
1040         return NULL;
1041 }
1042
1043 /** @} */
1044
1045
1046 /* ---------- Management frame data formats ---------- */
1047
1048 /**
1049  * @defgroup ieee80211_mgmt_data Management frame data payloads
1050  * @{
1051  */
1052
1053 /** Beacon or probe response frame data */
1054 struct ieee80211_beacon_or_probe_resp
1055 {
1056         /** 802.11 TSFT value at frame send */
1057         u64 timestamp;
1058
1059         /** Interval at which beacons are sent, in units of 1024 us */
1060         u16 beacon_interval;
1061
1062         /** Capability flags */
1063         u16 capability;
1064
1065         /** List of information elements */
1066         union ieee80211_ie info_element[0];
1067 } __attribute__((packed));
1068
1069 #define ieee80211_beacon        ieee80211_beacon_or_probe_resp
1070 #define ieee80211_probe_resp    ieee80211_beacon_or_probe_resp
1071
1072 /** Disassociation or deauthentication frame data */
1073 struct ieee80211_disassoc_or_deauth
1074 {
1075         /** Reason code */
1076         u16 reason;
1077 } __attribute__((packed));
1078
1079 #define ieee80211_disassoc      ieee80211_disassoc_or_deauth
1080 #define ieee80211_deauth        ieee80211_disassoc_or_deauth
1081
1082 /** Association request frame data */
1083 struct ieee80211_assoc_req
1084 {
1085         /** Capability flags */
1086         u16 capability;
1087
1088         /** Interval at which we wake up, in units of the beacon interval */
1089         u16 listen_interval;
1090
1091         /** List of information elements */
1092         union ieee80211_ie info_element[0];
1093 } __attribute__((packed));
1094
1095 /** Association or reassociation response frame data */
1096 struct ieee80211_assoc_or_reassoc_resp
1097 {
1098         /** Capability flags */
1099         u16 capability;
1100
1101         /** Status code */
1102         u16 status;
1103
1104         /** Association ID */
1105         u16 aid;
1106
1107         /** List of information elements */
1108         union ieee80211_ie info_element[0];
1109 } __attribute__((packed));
1110
1111 #define ieee80211_assoc_resp    ieee80211_assoc_or_reassoc_resp
1112 #define ieee80211_reassoc_resp  ieee80211_assoc_or_reassoc_resp
1113
1114 /** Reassociation request frame data */
1115 struct ieee80211_reassoc_req
1116 {
1117         /** Capability flags */
1118         u16 capability;
1119
1120         /** Interval at which we wake up, in units of the beacon interval */
1121         u16 listen_interval;
1122
1123         /** MAC address of current Access Point */
1124         u8 current_addr[ETH_ALEN];
1125
1126         /** List of information elements */
1127         union ieee80211_ie info_element[0];
1128 } __attribute__((packed));
1129
1130 /** Probe request frame data */
1131 struct ieee80211_probe_req
1132 {
1133         /** List of information elements */
1134         union ieee80211_ie info_element[0];
1135 } __attribute__((packed));
1136
1137 /** Authentication frame data */
1138 struct ieee80211_auth
1139 {
1140         /** Authentication algorithm (Open System or Shared Key) */
1141         u16 algorithm;
1142
1143         /** Sequence number of this frame; first from client to AP is 1 */
1144         u16 tx_seq;
1145
1146         /** Status code */
1147         u16 status;
1148
1149         /** List of information elements */
1150         union ieee80211_ie info_element[0];
1151 } __attribute__((packed));
1152
1153 /** Open System authentication algorithm */
1154 #define IEEE80211_AUTH_OPEN_SYSTEM  0
1155
1156 /** Shared Key authentication algorithm */
1157 #define IEEE80211_AUTH_SHARED_KEY   1
1158
1159 /** @} */
1160
1161 #endif