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