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