iPXE - Open Source Boot Firmware

[eepro100] Remove link-state checking
[ipxe.git] / src / include / gpxe / net80211.h
1 #ifndef _GPXE_NET80211_H
2 #define _GPXE_NET80211_H
3
4 #include <gpxe/process.h>
5 #include <gpxe/ieee80211.h>
6 #include <gpxe/iobuf.h>
7 #include <gpxe/netdevice.h>
8 #include <gpxe/rc80211.h>
9
10 /** @file
11  *
12  * The gPXE 802.11 MAC layer.
13  */
14
15 /*
16  * Major things NOT YET supported:
17  * - any type of security
18  * - 802.11n
19  *
20  * Major things that probably will NEVER be supported, barring a
21  * compelling use case and/or corporate sponsorship:
22  * - QoS
23  * - 802.1X authentication ("WPA Enterprise")
24  * - Contention-free periods
25  * - "ad-hoc" networks (IBSS), monitor mode, host AP mode
26  * - hidden networks on the 5GHz band due to regulatory issues
27  * - spectrum management on the 5GHz band (TPC and DFS), as required
28  *   in some non-US regulatory domains
29  * - Clause 14 PHYs (Frequency-Hopping Spread Spectrum on 2.4GHz)
30  *   and Clause 16 PHYs (infrared) - I'm not aware of any real-world
31  *   use of these.
32  */
33
34 FILE_LICENCE ( GPL2_OR_LATER );
35
36 /* All 802.11 devices are handled using a generic "802.11 device"
37    net_device, with a link in its `priv' field to a net80211_device
38    which we use to handle 802.11-specific details. */
39
40
41 /** @defgroup net80211_band RF bands on which an 802.11 device can transmit */
42 /** @{ */
43
44 /** The 2.4 GHz ISM band, unlicensed in most countries */
45 #define NET80211_BAND_2GHZ      0
46 /** The band from 4.9 GHz to 5.7 GHz, which tends to be more restricted */
47 #define NET80211_BAND_5GHZ      1
48 /** Number of RF bands */
49 #define NET80211_NR_BANDS       2
50
51 /** Bitmask for the 2GHz band */
52 #define NET80211_BAND_BIT_2GHZ  (1 << 0)
53 /** Bitmask for the 5GHz band */
54 #define NET80211_BAND_BIT_5GHZ  (1 << 1)
55
56 /** @} */
57
58
59 /** @defgroup net80211_mode 802.11 operation modes supported by hardware */
60 /** @{ */
61
62 /** 802.11a: 54 Mbps operation using OFDM signaling on the 5GHz band */
63 #define NET80211_MODE_A         (1 << 0)
64
65 /** 802.11b: 1-11 Mbps operation using DSSS/CCK signaling on the 2.4GHz band */
66 #define NET80211_MODE_B         (1 << 1)
67
68 /** 802.11g: 54 Mbps operation using ERP/OFDM signaling on the 2.4GHz band */
69 #define NET80211_MODE_G         (1 << 2)
70
71 /** 802.11n: High-rate operation using MIMO technology on 2.4GHz or 5GHz */
72 #define NET80211_MODE_N         (1 << 3)
73
74 /** @} */
75
76
77 /** @defgroup net80211_cfg Constants for the net80211 config callback */
78 /** @{ */
79
80 /** Channel choice (@c dev->channel) or regulatory parameters have changed */
81 #define NET80211_CFG_CHANNEL    (1 << 0)
82
83 /** Requested transmission rate (@c dev->rate) has changed */
84 #define NET80211_CFG_RATE       (1 << 1)
85
86 /** Association has been established with a new BSS (@c dev->bssid) */
87 #define NET80211_CFG_ASSOC      (1 << 2)
88
89 /** Low-level link parameters (short preamble, protection, etc) have changed */
90 #define NET80211_CFG_PHY_PARAMS (1 << 3)
91
92 /** @} */
93
94
95 /** An 802.11 security handshaking protocol */
96 enum net80211_security_proto {
97         /** No security handshaking
98          *
99          * This might be used with an open network or with WEP, as
100          * WEP does not have a cryptographic handshaking phase.
101          */
102         NET80211_SECPROT_NONE = 0,
103
104         /** Pre-shared key handshaking
105          *
106          * This implements the "WPA Personal" handshake. 802.1X
107          * authentication is not performed -- the user supplies a
108          * pre-shared key directly -- but there is a 4-way handshake
109          * between client and AP to verify that both have the same key
110          * without revealing the contents of that key.
111          */
112         NET80211_SECPROT_PSK = 1,
113
114         /** Full EAP 802.1X handshaking
115          *
116          * This implements the "WPA Enterprise" handshake, connecting
117          * to an 802.1X authentication server to provide credentials
118          * and receive a pairwise master key (PMK), which is then used
119          * in the same 4-way handshake as the PSK method.
120          */
121         NET80211_SECPROT_EAP = 2,
122
123         /** Dummy value used when the handshaking type can't be detected */
124         NET80211_SECPROT_UNKNOWN = 3,
125 };
126
127
128 /** An 802.11 data encryption algorithm */
129 enum net80211_crypto_alg {
130         /** No security, an "Open" network */
131         NET80211_CRYPT_NONE = 0,
132
133         /** Network protected with WEP (awful RC4-based system)
134          *
135          * WEP uses a naive application of RC4, with a monotonically
136          * increasing initialization vector that is prepended to the
137          * key to initialize the RC4 keystream. It is highly insecure
138          * and can be completely cracked or subverted using automated,
139          * robust, freely available tools (aircrack-ng) in minutes.
140          *
141          * 40-bit and 104-bit WEP are differentiated only by the size
142          * of the key. They may be advertised as 64-bit and 128-bit,
143          * counting the non-random IV as part of the key bits.
144          */
145         NET80211_CRYPT_WEP = 1,
146
147         /** Network protected with TKIP (better RC4-based system)
148          *
149          * Usually known by its trade name of WPA (Wi-Fi Protected
150          * Access), TKIP implements a message integrity code (MIC)
151          * called Michael, a timestamp counter for replay prevention,
152          * and a key mixing function that together remove almost all
153          * the security problems with WEP. Countermeasures are
154          * implemented to prevent high data-rate attacks.
155          *
156          * There exists one known attack on TKIP, that allows one to
157          * send between 7 and 15 arbitrary short data packets on a
158          * QoS-enabled network given about an hour of data
159          * gathering. Since gPXE does not support QoS for 802.11
160          * networks, this is not a threat to us. The only other method
161          * is a brute-force passphrase attack.
162          */
163         NET80211_CRYPT_TKIP = 2,
164
165         /** Network protected with CCMP (AES-based system)
166          *
167          * Often called WPA2 in commerce, or RSNA (Robust Security
168          * Network Architecture) in the 802.11 standard, CCMP is
169          * highly secure and does not have any known attack vectors.
170          * Since it is based on a block cipher, the statistical
171          * correlation and "chopchop" attacks used with great success
172          * against WEP and minor success against TKIP fail.
173          */
174         NET80211_CRYPT_CCMP = 3,
175
176         /** Dummy value used when the cryptosystem can't be detected */
177         NET80211_CRYPT_UNKNOWN = 4,
178 };
179
180
181 /** @defgroup net80211_state Bits for the 802.11 association state field */
182 /** @{ */
183
184 /** An error code indicating the failure mode, or 0 if successful */
185 #define NET80211_STATUS_MASK    0x7F
186
187 /** Whether the error code provided is a "reason" code, not a "status" code */
188 #define NET80211_IS_REASON      0x80
189
190 /** Whether we have found the network we will be associating with */
191 #define NET80211_PROBED         (1 << 8)
192
193 /** Whether we have successfully authenticated with the network
194  *
195  * This usually has nothing to do with actual security; it is a
196  * holdover from older 802.11 implementation ideas.
197  */
198 #define NET80211_AUTHENTICATED  (1 << 9)
199
200 /** Whether we have successfully associated with the network */
201 #define NET80211_ASSOCIATED     (1 << 10)
202
203 /** Whether we have completed security handshaking with the network
204  *
205  * Once this is set, we can send data packets. For that reason this
206  * bit is set even in cases where no security handshaking is
207  * required.
208  */
209 #define NET80211_CRYPTO_SYNCED  (1 << 11)
210
211 /** Whether the auto-association task is running */
212 #define NET80211_WORKING        (1 << 12)
213
214 /** Whether the auto-association task is waiting for a reply from the AP */
215 #define NET80211_WAITING        (1 << 13)
216
217 /** Whether the auto-association task should be suppressed
218  *
219  * This is set by the `iwlist' command so that it can open the device
220  * without starting another probe process that will interfere with its
221  * own.
222  */
223 #define NET80211_NO_ASSOC       (1 << 14)
224
225 /** Whether this association was performed using a broadcast SSID
226  *
227  * If the user opened this device without netX/ssid set, the device's
228  * SSID will be set to that of the network it chooses to associate
229  * with, but the netX/ssid setting will remain blank. If we don't
230  * remember that we started from no specified SSID, it will appear
231  * every time settings are updated (e.g. after DHCP) that we need to
232  * reassociate due to the difference between the set SSID and our own.
233  */
234 #define NET80211_AUTO_SSID      (1 << 15)
235
236
237 /** @} */
238
239
240 /** @defgroup net80211_phy 802.11 physical layer flags */
241 /** @{ */
242
243 /** Whether to use RTS/CTS or CTS-to-self protection for transmissions
244  *
245  * Since the RTS or CTS is transmitted using 802.11b signaling, and
246  * includes a field indicating the amount of time that will be used by
247  * transmission of the following packet, this serves as an effective
248  * protection mechanism to avoid 802.11b clients interfering with
249  * 802.11g clients on mixed networks.
250  */
251 #define NET80211_PHY_USE_PROTECTION      (1 << 1)
252
253 /** Whether to use 802.11b short preamble operation
254  *
255  * Short-preamble operation can moderately increase throughput on
256  * 802.11b networks operating between 2Mbps and 11Mbps. It is
257  * irrelevant for 802.11g data rates, since they use a different
258  * modulation scheme.
259  */
260 #define NET80211_PHY_USE_SHORT_PREAMBLE  (1 << 2)
261
262 /** Whether to use 802.11g short slot operation
263  *
264  * This affects a low-level timing parameter of 802.11g transmissions.
265  */
266 #define NET80211_PHY_USE_SHORT_SLOT      (1 << 3)
267
268 /** @} */
269
270
271 /** The maximum number of TX rates we allow to be configured simultaneously */
272 #define NET80211_MAX_RATES      16
273
274 /** The maximum number of channels we allow to be configured simultaneously */
275 #define NET80211_MAX_CHANNELS   32
276
277 /** Seconds we'll wait to get all fragments of a packet */
278 #define NET80211_FRAG_TIMEOUT   2
279
280 /** The number of fragments we can receive at once
281  *
282  * The 802.11 standard requires that this be at least 3.
283  */
284 #define NET80211_NR_CONCURRENT_FRAGS 3
285
286 /** Maximum TX power to allow (dBm), if we don't get a regulatory hint */
287 #define NET80211_REG_TXPOWER    20
288
289
290 struct net80211_device;
291
292 /** Operations that must be implemented by an 802.11 driver */
293 struct net80211_device_operations {
294         /** Open 802.11 device
295          *
296          * @v dev       802.11 device
297          * @ret rc      Return status code
298          *
299          * This method should allocate RX I/O buffers and enable the
300          * hardware to start transmitting and receiving packets on the
301          * channels its net80211_register() call indicated it could
302          * handle. It does not need to tune the antenna to receive
303          * packets on any particular channel.
304          */
305         int ( * open ) ( struct net80211_device *dev );
306
307         /** Close 802.11 network device
308          *
309          * @v dev       802.11 device
310          *
311          * This method should stop the flow of packets, and call
312          * net80211_tx_complete() for any packets remaining in the
313          * device's TX queue.
314          */
315         void ( * close ) ( struct net80211_device *dev );
316
317         /** Transmit packet on 802.11 network device
318          *
319          * @v dev       802.11 device
320          * @v iobuf     I/O buffer
321          * @ret rc      Return status code
322          *
323          * This method should cause the hardware to initiate
324          * transmission of the I/O buffer, using the channel and rate
325          * most recently indicated by an appropriate call to the
326          * @c config callback. The 802.11 layer guarantees that said
327          * channel and rate will be the same as those currently
328          * reflected in the fields of @a dev.
329          *
330          * If this method returns success, the I/O buffer remains
331          * owned by the network layer's TX queue, and the driver must
332          * eventually call net80211_tx_complete() to free the buffer
333          * whether transmission succeeded or not. If this method
334          * returns failure, it will be interpreted as "failure to
335          * enqueue buffer" and the I/O buffer will be immediately
336          * released.
337          *
338          * This method is guaranteed to be called only when the device
339          * is open.
340          */
341         int ( * transmit ) ( struct net80211_device *dev,
342                              struct io_buffer *iobuf );
343
344         /** Poll for completed and received packets
345          *
346          * @v dev       802.11 device
347          *
348          * This method should cause the hardware to check for
349          * completed transmissions and received packets. Any received
350          * packets should be delivered via net80211_rx(), and
351          * completed transmissions should be indicated using
352          * net80211_tx_complete().
353          *
354          * This method is guaranteed to be called only when the device
355          * is open.
356          */
357         void ( * poll ) ( struct net80211_device *dev );
358
359         /** Enable or disable interrupts
360          *
361          * @v dev       802.11 device
362          * @v enable    If TRUE, interrupts should be enabled
363          */
364         void ( * irq ) ( struct net80211_device *dev, int enable );
365
366         /** Update hardware state to match 802.11 layer state
367          *
368          * @v dev       802.11 device
369          * @v changed   Set of flags indicating what may have changed
370          * @ret rc      Return status code
371          *
372          * This method should cause the hardware state to be
373          * reinitialized from the state indicated in fields of
374          * net80211_device, in the areas indicated by bits set in
375          * @a changed. If the hardware is unable to do so, this method
376          * may return an appropriate error indication.
377          *
378          * This method is guaranteed to be called only when the device
379          * is open.
380          */
381         int ( * config ) ( struct net80211_device *dev, int changed );
382 };
383
384 /** An 802.11 RF channel. */
385 struct net80211_channel
386 {
387         /** The band with which this channel is associated */
388         u8 band;
389
390         /** A channel number interpreted according to the band
391          *
392          * The 2.4GHz band uses channel numbers from 1-13 at 5MHz
393          * intervals such that channel 1 is 2407 MHz; channel 14,
394          * legal for use only in Japan, is defined separately as 2484
395          * MHz. Adjacent channels will overlap, since 802.11
396          * transmissions use a 20 MHz (4-channel) bandwidth. Most
397          * commonly, channels 1, 6, and 11 are used.
398          *
399          * The 5GHz band uses channel numbers derived directly from
400          * the frequency; channel 0 is 5000 MHz, and channels are
401          * always spaced 5 MHz apart. Channel numbers over 180 are
402          * relative to 4GHz instead of 5GHz, but these are rarely
403          * seen. Most channels are not legal for use.
404          */
405         u8 channel_nr;
406
407         /** The center frequency for this channel
408          *
409          * Currently a bandwidth of 20 MHz is assumed.
410          */
411         u16 center_freq;
412
413         /** Hardware channel value */
414         u16 hw_value;
415
416         /** Maximum allowable transmit power, in dBm
417          *
418          * This should be interpreted as EIRP, the power supplied to
419          * an ideal isotropic antenna in order to achieve the same
420          * average signal intensity as the real hardware at a
421          * particular distance.
422          *
423          * Currently no provision is made for directional antennas.
424          */
425         u8 maxpower;
426 };
427
428 /** Information on the capabilities of an 802.11 hardware device
429  *
430  * In its probe callback, an 802.11 driver must read hardware
431  * registers to determine the appropriate contents of this structure,
432  * fill it, and pass it to net80211_register() so that the 802.11
433  * layer knows how to treat the hardware and what to advertise as
434  * supported to access points.
435  */
436 struct net80211_hw_info
437 {
438         /** Default hardware MAC address.
439          *
440          * The user may change this by setting the @c netX/mac setting
441          * before the driver's open function is called; in that case
442          * the driver must set the hardware MAC address to the address
443          * contained in the wrapping net_device's ll_addr field, or if
444          * that is impossible, set that ll_addr field back to the
445          * unchangeable hardware MAC address.
446          */
447         u8 hwaddr[ETH_ALEN];
448
449         /** A bitwise OR of the 802.11x modes supported by this device */
450         int modes;
451
452         /** A bitwise OR of the bands on which this device can communicate */
453         int bands;
454
455         /** A set of flags indicating peculiarities of this device. */
456         enum {
457                 /** Received frames include a frame check sequence. */
458                 NET80211_HW_RX_HAS_FCS = (1 << 1),
459
460                 /** Hardware doesn't support 2.4GHz short preambles
461                  *
462                  * This is only relevant for 802.11b operation above
463                  * 2Mbps. All 802.11g devices support short preambles.
464                  */
465                 NET80211_HW_NO_SHORT_PREAMBLE = (1 << 2),
466
467                 /** Hardware doesn't support 802.11g short slot operation */
468                 NET80211_HW_NO_SHORT_SLOT = (1 << 3),
469         } flags;
470
471         /** Signal strength information that can be provided by the device
472          *
473          * Signal strength is passed to net80211_rx(), primarily to
474          * allow determination of the closest access point for a
475          * multi-AP network. The units are provided for completeness
476          * of status displays.
477          */
478         enum {
479                 /** No signal strength information supported */
480                 NET80211_SIGNAL_NONE = 0,
481                 /** Signal strength in arbitrary units */
482                 NET80211_SIGNAL_ARBITRARY,
483                 /** Signal strength in decibels relative to arbitrary base */
484                 NET80211_SIGNAL_DB,
485                 /** Signal strength in decibels relative to 1mW */
486                 NET80211_SIGNAL_DBM,
487         } signal_type;
488
489         /** Maximum signal in arbitrary cases
490          *
491          * If signal_type is NET80211_SIGNAL_ARBITRARY or
492          * NET80211_SIGNAL_DB, the driver should report it on a scale
493          * from 0 to signal_max.
494          */
495         unsigned signal_max;
496
497         /** List of RF channels supported by the card */
498         struct net80211_channel channels[NET80211_MAX_CHANNELS];
499
500         /** Number of supported channels */
501         int nr_channels;
502
503         /** List of transmission rates supported by the card, indexed by band
504          *
505          * Rates should be in 100kbps increments (e.g. 11 Mbps would
506          * be represented as the number 110).
507          */
508         u16 rates[NET80211_NR_BANDS][NET80211_MAX_RATES];
509
510         /** Number of supported rates, indexed by band */
511         int nr_rates[NET80211_NR_BANDS];
512
513         /** Estimate of the time required to change channels, in microseconds
514          *
515          * If this is not known, a guess on the order of a few
516          * milliseconds (value of 1000-5000) is reasonable.
517          */
518         unsigned channel_change_time;
519 };
520
521 /** Structure tracking received fragments for a packet
522  *
523  * We set up a fragment cache entry when we receive a packet marked as
524  * fragment 0 with the "more fragments" bit set in its frame control
525  * header. We are required by the 802.11 standard to track 3
526  * fragmented packets arriving simultaneously; if we receive more we
527  * may drop some. Upon receipt of a new fragment-0 packet, if no entry
528  * is available or expired, we take over the most @e recent entry for
529  * the new packet, since we don't want to starve old entries from ever
530  * finishing at all. If we get a fragment after the zeroth with no
531  * cache entry for its packet, we drop it.
532  */
533 struct net80211_frag_cache
534 {
535         /** Whether this cache entry is in use */
536         u8 in_use;
537
538         /** Sequence number of this MSDU (packet) */
539         u16 seqnr;
540
541         /** Timestamp from point at which first fragment was collected */
542         u32 start_ticks;
543
544         /** Buffers for each fragment */
545         struct io_buffer *iob[16];
546 };
547
548
549 /** Interface to an 802.11 security handshaking protocol
550  *
551  * Security handshaking protocols handle parsing a user-specified key
552  * into a suitable input to the encryption algorithm, and for WPA and
553  * better systems, manage performing whatever authentication with the
554  * network is necessary.
555  *
556  * At all times when any method in this structure is called with a
557  * net80211_device argument @a dev, a dynamically allocated copy of
558  * the handshaker structure itself with space for the requested amount
559  * of private data may be accessed as @c dev->handshaker. The
560  * structure will not be modified, and will only be freed during
561  * reassociation and device closing after the @a stop method has been
562  * called.
563  */
564 struct net80211_handshaker
565 {
566         /** The security handshaking protocol implemented */
567         enum net80211_security_proto protocol;
568
569         /** Initialize security handshaking protocol
570          *
571          * @v dev       802.11 device
572          * @ret rc      Return status code
573          *
574          * This method is expected to access @c netX/key or other
575          * applicable settings to determine the parameters for
576          * handshaking. If no handshaking is required, it should call
577          * sec80211_install() with the cryptosystem and key that are
578          * to be used, and @c start and @c step should be set to @c
579          * NULL.
580          *
581          * This is always called just before association is performed,
582          * but after its parameters have been set; in particular, you
583          * may rely on the contents of the @a essid field in @a dev.
584          */
585         int ( * init ) ( struct net80211_device *dev );
586
587         /** Start handshaking
588          *
589          * @v dev       802.11 device
590          * @ret rc      Return status code
591          *
592          * This method is expected to set up internal state so that
593          * packets sent immediately after association, before @a step
594          * can be called, will be handled appropriately.
595          *
596          * This is always called just before association is attempted.
597          */
598         int ( * start ) ( struct net80211_device *dev );
599
600         /** Process handshaking state
601          *
602          * @v dev       802.11 device
603          * @ret rc      Return status code, or positive if done
604          *
605          * This method is expected to perform as much progress on the
606          * protocol it implements as is possible without blocking. It
607          * should return 0 if it wishes to be called again, a negative
608          * return status code on error, or a positive value if
609          * handshaking is complete. In the case of a positive return,
610          * net80211_crypto_install() must have been called.
611          *
612          * If handshaking may require further action (e.g. an AP that
613          * might decide to rekey), handlers must be installed by this
614          * function that will act without further calls to @a step.
615          */
616         int ( * step ) ( struct net80211_device *dev );
617
618         /** Change cryptographic key based on setting
619          *
620          * @v dev       802.11 device
621          * @ret rc      Return status code
622          *
623          * This method is called whenever the @c netX/key setting
624          * @e may have been changed. It is expected to determine
625          * whether it did in fact change, and if so, to install the
626          * new key using net80211_crypto_install(). If it is not
627          * possible to do this immediately, this method should return
628          * an error; in that case the 802.11 stack will reassociate,
629          * following the usual init/start/step sequence.
630          *
631          * This method is only relevant when it is possible to
632          * associate successfully with an incorrect key. When it is
633          * not, a failed association will be retried until the user
634          * changes the key setting, and a successful association will
635          * not be dropped due to such a change. When association with
636          * an incorrect key is impossible, this function should return
637          * 0 after performing no action.
638          */
639         int ( * change_key ) ( struct net80211_device *dev );
640
641         /** Stop security handshaking handlers
642          *
643          * @v dev       802.11 device
644          *
645          * This method is called just before freeing a security
646          * handshaker; it could, for example, delete a process that @a
647          * start had created to manage the security of the connection.
648          * If not needed it may be set to NULL.
649          */
650         void ( * stop ) ( struct net80211_device *dev );
651
652         /** Amount of private data requested
653          *
654          * Before @c init is called for the first time, this structure's
655          * @c priv pointer will point to this many bytes of allocated
656          * data, where the allocation will be performed separately for
657          * each net80211_device.
658          */
659         int priv_len;
660
661         /** Whether @a start has been called
662          *
663          * Reset to 0 after @a stop is called.
664          */
665         int started;
666
667         /** Pointer to private data
668          *
669          * In initializing this structure statically for a linker
670          * table, set this to NULL.
671          */
672         void *priv;
673 };
674
675 #define NET80211_HANDSHAKERS __table ( struct net80211_handshaker, \
676                                        "net80211_handshakers" )
677 #define __net80211_handshaker __table_entry ( NET80211_HANDSHAKERS, 01 )
678
679
680 /** Interface to an 802.11 cryptosystem
681  *
682  * Cryptosystems define a net80211_crypto structure statically, using
683  * a gPXE linker table to make it available to the 802.11 layer. When
684  * the cryptosystem needs to be used, the 802.11 code will allocate a
685  * copy of the static definition plus whatever space the algorithm has
686  * requested for private state, and point net80211_device::crypto or
687  * net80211_device::gcrypto at it.
688  */
689 struct net80211_crypto
690 {
691         /** The cryptographic algorithm implemented */
692         enum net80211_crypto_alg algorithm;
693
694         /** Initialize cryptosystem using a given key
695          *
696          * @v crypto    802.11 cryptosystem
697          * @v key       Pointer to key bytes
698          * @v keylen    Number of key bytes
699          * @v rsc       Initial receive sequence counter, if applicable
700          * @ret rc      Return status code
701          *
702          * This method is passed the communication key provided by the
703          * security handshake handler, which will already be in the
704          * low-level form required. It may not store a pointer to the
705          * key after returning; it must copy it to its private storage.
706          */
707         int ( * init ) ( struct net80211_crypto *crypto, const void *key,
708                          int keylen, const void *rsc );
709
710         /** Encrypt a frame using the cryptosystem
711          *
712          * @v crypto    802.11 cryptosystem
713          * @v iob       I/O buffer
714          * @ret eiob    Newly allocated I/O buffer with encrypted packet
715          *
716          * This method is called to encrypt a single frame. It is
717          * guaranteed that initialize() will have completed
718          * successfully before this method is called.
719          *
720          * The frame passed already has an 802.11 header prepended,
721          * but the PROTECTED bit in the frame control field will not
722          * be set; this method is responsible for setting it. The
723          * returned I/O buffer should contain a complete copy of @a
724          * iob, including the 802.11 header, but with the PROTECTED
725          * bit set, the data encrypted, and whatever encryption
726          * headers/trailers are necessary added.
727          *
728          * This method should never free the passed I/O buffer.
729          *
730          * Return NULL if the packet could not be encrypted, due to
731          * memory limitations or otherwise.
732          */
733         struct io_buffer * ( * encrypt ) ( struct net80211_crypto *crypto,
734                                            struct io_buffer *iob );
735
736         /** Decrypt a frame using the cryptosystem
737          *
738          * @v crypto    802.11 cryptosystem
739          * @v eiob      Encrypted I/O buffer
740          * @ret iob     Newly allocated I/O buffer with decrypted packet
741          *
742          * This method is called to decrypt a single frame. It is
743          * guaranteed that initialize() will have completed
744          * successfully before this method is called.
745          *
746          * Decryption follows the reverse of the pattern used for
747          * encryption: this method must copy the 802.11 header into
748          * the returned packet, decrypt the data stream, remove any
749          * encryption header or trailer, and clear the PROTECTED bit
750          * in the frame control header.
751          *
752          * This method should never free the passed I/O buffer.
753          *
754          * Return NULL if memory was not available for decryption, if
755          * a consistency or integrity check on the decrypted frame
756          * failed, or if the decrypted frame should not be processed
757          * by the network stack for any other reason.
758          */
759         struct io_buffer * ( * decrypt ) ( struct net80211_crypto *crypto,
760                                            struct io_buffer *iob );
761
762         /** Length of private data requested to be allocated */
763         int priv_len;
764
765         /** Private data for the algorithm to store key and state info */
766         void *priv;
767 };
768
769 #define NET80211_CRYPTOS __table ( struct net80211_crypto, "net80211_cryptos" )
770 #define __net80211_crypto __table_entry ( NET80211_CRYPTOS, 01 )
771
772
773 struct net80211_probe_ctx;
774 struct net80211_assoc_ctx;
775
776
777 /** Structure encapsulating the complete state of an 802.11 device
778  *
779  * An 802.11 device is always wrapped by a network device, and this
780  * network device is always pointed to by the @a netdev field. In
781  * general, operations should never be performed by 802.11 code using
782  * netdev functions directly. It is usually the case that the 802.11
783  * layer might need to do some processing or bookkeeping on top of
784  * what the netdevice code will do.
785  */
786 struct net80211_device
787 {
788         /** The net_device that wraps us. */
789         struct net_device *netdev;
790
791         /** List of 802.11 devices. */
792         struct list_head list;
793
794         /** 802.11 device operations */
795         struct net80211_device_operations *op;
796
797         /** Driver private data */
798         void *priv;
799
800         /** Information about the hardware, provided to net80211_register() */
801         struct net80211_hw_info *hw;
802
803         /* ---------- Channel and rate fields ---------- */
804
805         /** A list of all possible channels we might use */
806         struct net80211_channel channels[NET80211_MAX_CHANNELS];
807
808         /** The number of channels in the channels array */
809         u8 nr_channels;
810
811         /** The channel currently in use, as an index into the channels array */
812         u8 channel;
813
814         /** A list of all possible TX rates we might use
815          *
816          * Rates are in units of 100 kbps.
817          */
818         u16 rates[NET80211_MAX_RATES];
819
820         /** The number of transmission rates in the rates array */
821         u8 nr_rates;
822
823         /** The rate currently in use, as an index into the rates array */
824         u8 rate;
825
826         /** The rate to use for RTS/CTS transmissions
827          *
828          * This is always the fastest basic rate that is not faster
829          * than the data rate in use. Also an index into the rates array.
830          */
831         u8 rtscts_rate;
832
833         /** Bitmask of basic rates
834          *
835          * If bit N is set in this value, with the LSB considered to
836          * be bit 0, then rate N in the rates array is a "basic" rate.
837          *
838          * We don't decide which rates are "basic"; our AP does, and
839          * we respect its wishes. We need to be able to identify basic
840          * rates in order to calculate the duration of a CTS packet
841          * used for 802.11 g/b interoperability.
842          */
843         u32 basic_rates;
844
845         /* ---------- Association fields ---------- */
846
847         /** The asynchronous association process.
848          *
849          * When an 802.11 netdev is opened, or when the user changes
850          * the SSID setting on an open 802.11 device, an
851          * autoassociation task is started by net80211_autoassocate()
852          * to associate with the new best network. The association is
853          * asynchronous, but no packets can be transmitted until it is
854          * complete. If it is successful, the wrapping net_device is
855          * set as "link up". If it fails, @c assoc_rc will be set with
856          * an error indication.
857          */
858         struct process proc_assoc;
859
860         /** Network with which we are associating
861          *
862          * This will be NULL when we are not actively in the process
863          * of associating with a network we have already successfully
864          * probed for.
865          */
866         struct net80211_wlan *associating;
867
868         /** Context for the association process
869          *
870          * This is a probe_ctx if the @c PROBED flag is not set in @c
871          * state, and an assoc_ctx otherwise.
872          */
873         union {
874                 struct net80211_probe_ctx *probe;
875                 struct net80211_assoc_ctx *assoc;
876         } ctx;
877
878         /** Security handshaker being used */
879         struct net80211_handshaker *handshaker;
880
881         /** State of our association to the network
882          *
883          * Since the association process happens asynchronously, it's
884          * necessary to have some channel of communication so the
885          * driver can say "I got an association reply and we're OK" or
886          * similar. This variable provides that link. It is a bitmask
887          * of any of NET80211_PROBED, NET80211_AUTHENTICATED,
888          * NET80211_ASSOCIATED, NET80211_CRYPTO_SYNCED to indicate how
889          * far along in associating we are; NET80211_WORKING if the
890          * association task is running; and NET80211_WAITING if a
891          * packet has been sent that we're waiting for a reply to. We
892          * can only be crypto-synced if we're associated, we can
893          * only be associated if we're authenticated, we can only be
894          * authenticated if we've probed.
895          *
896          * If an association process fails (that is, we receive a
897          * packet with an error indication), the error code is copied
898          * into bits 6-0 of this variable and bit 7 is set to specify
899          * what type of error code it is. An AP can provide either a
900          * "status code" (0-51 are defined) explaining why it refused
901          * an association immediately, or a "reason code" (0-45 are
902          * defined) explaining why it canceled an association after it
903          * had originally OK'ed it. Status and reason codes serve
904          * similar functions, but they use separate error message
905          * tables. A gPXE-formatted return status code (negative) is
906          * placed in @c assoc_rc.
907          *
908          * If the failure to associate is indicated by a status code,
909          * the NET80211_IS_REASON bit will be clear; if it is
910          * indicated by a reason code, the bit will be set. If we were
911          * successful, both zero status and zero reason mean success,
912          * so there is no ambiguity.
913          *
914          * To prevent association when opening the device, user code
915          * can set the NET80211_NO_ASSOC bit. The final bit in this
916          * variable, NET80211_AUTO_SSID, is used to remember whether
917          * we picked our SSID through automated probing as opposed to
918          * user specification; the distinction becomes relevant in the
919          * settings applicator.
920          */
921         u16 state;
922
923         /** Return status code associated with @c state */
924         int assoc_rc;
925
926         /** RSN or WPA information element to include with association
927          *
928          * If set to @c NULL, none will be included. It is expected
929          * that this will be set by the @a init function of a security
930          * handshaker if it is needed.
931          */
932         union ieee80211_ie *rsn_ie;
933
934         /* ---------- Parameters of currently associated network ---------- */
935
936         /** 802.11 cryptosystem for our current network
937          *
938          * For an open network, this will be set to NULL.
939          */
940         struct net80211_crypto *crypto;
941
942         /** 802.11 cryptosystem for multicast and broadcast frames
943          *
944          * If this is NULL, the cryptosystem used for receiving
945          * unicast frames will also be used for receiving multicast
946          * and broadcast frames. Transmitted multicast and broadcast
947          * frames are always sent unicast to the AP, who multicasts
948          * them on our behalf; thus they always use the unicast
949          * cryptosystem.
950          */
951         struct net80211_crypto *gcrypto;
952
953         /** MAC address of the access point most recently associated */
954         u8 bssid[ETH_ALEN];
955
956         /** SSID of the access point we are or will be associated with
957          *
958          * Although the SSID field in 802.11 packets is generally not
959          * NUL-terminated, here and in net80211_wlan we add a NUL for
960          * convenience.
961          */
962         char essid[IEEE80211_MAX_SSID_LEN+1];
963
964         /** Association ID given to us by the AP */
965         u16 aid;
966
967         /** TSFT value for last beacon received, microseconds */
968         u64 last_beacon_timestamp;
969
970         /** Time between AP sending beacons, microseconds */
971         u32 tx_beacon_interval;
972
973         /** Smoothed average time between beacons, microseconds */
974         u32 rx_beacon_interval;
975
976         /* ---------- Physical layer information ---------- */
977
978         /** Physical layer options
979          *
980          * These control the use of CTS protection, short preambles,
981          * and short-slot operation.
982          */
983         int phy_flags;
984
985         /** Signal strength of last received packet */
986         int last_signal;
987
988         /** Rate control state */
989         struct rc80211_ctx *rctl;
990
991         /* ---------- Packet handling state ---------- */
992
993         /** Fragment reassembly state */
994         struct net80211_frag_cache frags[NET80211_NR_CONCURRENT_FRAGS];
995
996         /** The sequence number of the last packet we sent */
997         u16 last_tx_seqnr;
998
999         /** Packet duplication elimination state
1000          *
1001          * We are only required to handle immediate duplicates for
1002          * each direct sender, and since we can only have one direct
1003          * sender (the AP), we need only keep the sequence control
1004          * field from the most recent packet we've received. Thus,
1005          * this field stores the last sequence control field we've
1006          * received for a packet from the AP.
1007          */
1008         u16 last_rx_seq;
1009
1010         /** RX management packet queue
1011          *
1012          * Sometimes we want to keep probe, beacon, and action packets
1013          * that we receive, such as when we're scanning for networks.
1014          * Ordinarily we drop them because they are sent at a large
1015          * volume (ten beacons per second per AP, broadcast) and we
1016          * have no need of them except when we're scanning.
1017          *
1018          * When keep_mgmt is TRUE, received probe, beacon, and action
1019          * management packets will be stored in this queue.
1020          */
1021         struct list_head mgmt_queue;
1022
1023         /** RX management packet info queue
1024          *
1025          * We need to keep track of the signal strength for management
1026          * packets we're keeping, because that provides the only way
1027          * to distinguish between multiple APs for the same network.
1028          * Since we can't extend io_buffer to store signal, this field
1029          * heads a linked list of "RX packet info" structures that
1030          * contain that signal strength field. Its entries always
1031          * parallel the entries in mgmt_queue, because the two queues
1032          * are always added to or removed from in parallel.
1033          */
1034         struct list_head mgmt_info_queue;
1035
1036         /** Whether to store management packets
1037          *
1038          * Received beacon, probe, and action packets will be added to
1039          * mgmt_queue (and their signal strengths added to
1040          * mgmt_info_queue) only when this variable is TRUE. It should
1041          * be set by net80211_keep_mgmt() (which returns the old
1042          * value) only when calling code is prepared to poll the
1043          * management queue frequently, because packets will otherwise
1044          * pile up and exhaust memory.
1045          */
1046         int keep_mgmt;
1047 };
1048
1049 /** Structure representing a probed network.
1050  *
1051  * This is returned from the net80211_probe_finish functions and
1052  * passed to the low-level association functions. At least essid,
1053  * bssid, channel, beacon, and security must be filled in if you want
1054  * to build this structure manually.
1055  */
1056 struct net80211_wlan
1057 {
1058         /** The human-readable ESSID (network name)
1059          *
1060          * Although the 802.11 SSID field is generally not
1061          * NUL-terminated, the gPXE code adds an extra NUL (and
1062          * expects one in this structure) for convenience.
1063          */
1064         char essid[IEEE80211_MAX_SSID_LEN+1];
1065
1066         /** MAC address of the strongest-signal access point for this ESSID */
1067         u8 bssid[ETH_ALEN];
1068
1069         /** Signal strength of beacon frame from that access point */
1070         int signal;
1071
1072         /** The channel on which that access point communicates
1073          *
1074          * This is a raw channel number (net80211_channel::channel_nr),
1075          * so that it will not be affected by reconfiguration of the
1076          * device channels array.
1077          */
1078         int channel;
1079
1080         /** The complete beacon or probe-response frame received */
1081         struct io_buffer *beacon;
1082
1083         /** Security handshaking method used on the network */
1084         enum net80211_security_proto handshaking;
1085
1086         /** Cryptographic algorithm used on the network */
1087         enum net80211_crypto_alg crypto;
1088
1089         /** Link to allow chaining multiple structures into a list to
1090             be returned from net80211_probe_finish_all(). */
1091         struct list_head list;
1092 };
1093
1094
1095 /** 802.11 encryption key setting */
1096 extern struct setting net80211_key_setting __setting;
1097
1098
1099 /**
1100  * @defgroup net80211_probe 802.11 network location API
1101  * @{
1102  */
1103 int net80211_prepare_probe ( struct net80211_device *dev, int band,
1104                              int active );
1105 struct net80211_probe_ctx * net80211_probe_start ( struct net80211_device *dev,
1106                                                    const char *essid,
1107                                                    int active );
1108 int net80211_probe_step ( struct net80211_probe_ctx *ctx );
1109 struct net80211_wlan *
1110 net80211_probe_finish_best ( struct net80211_probe_ctx *ctx );
1111 struct list_head *net80211_probe_finish_all ( struct net80211_probe_ctx *ctx );
1112
1113 void net80211_free_wlan ( struct net80211_wlan *wlan );
1114 void net80211_free_wlanlist ( struct list_head *list );
1115 /** @} */
1116
1117
1118 /**
1119  * @defgroup net80211_mgmt 802.11 network management API
1120  * @{
1121  */
1122 struct net80211_device * net80211_get ( struct net_device *netdev );
1123 void net80211_autoassociate ( struct net80211_device *dev );
1124
1125 int net80211_change_channel ( struct net80211_device *dev, int channel );
1126 void net80211_set_rate_idx ( struct net80211_device *dev, int rate );
1127
1128 int net80211_keep_mgmt ( struct net80211_device *dev, int enable );
1129 struct io_buffer * net80211_mgmt_dequeue ( struct net80211_device *dev,
1130                                            int *signal );
1131 int net80211_tx_mgmt ( struct net80211_device *dev, u16 fc,
1132                        u8 bssid[ETH_ALEN], struct io_buffer *iob );
1133 /** @} */
1134
1135
1136 /**
1137  * @defgroup net80211_assoc 802.11 network association API
1138  * @{
1139  */
1140 int net80211_prepare_assoc ( struct net80211_device *dev,
1141                              struct net80211_wlan *wlan );
1142 int net80211_send_auth ( struct net80211_device *dev,
1143                          struct net80211_wlan *wlan, int method );
1144 int net80211_send_assoc ( struct net80211_device *dev,
1145                           struct net80211_wlan *wlan );
1146 void net80211_deauthenticate ( struct net80211_device *dev, int rc );
1147 /** @} */
1148
1149
1150 /**
1151  * @defgroup net80211_driver 802.11 driver interface API
1152  * @{
1153  */
1154 struct net80211_device *net80211_alloc ( size_t priv_size );
1155 int net80211_register ( struct net80211_device *dev,
1156                         struct net80211_device_operations *ops,
1157                         struct net80211_hw_info *hw );
1158 u16 net80211_duration ( struct net80211_device *dev, int bytes, u16 rate );
1159 void net80211_rx ( struct net80211_device *dev, struct io_buffer *iob,
1160                    int signal, u16 rate );
1161 void net80211_rx_err ( struct net80211_device *dev,
1162                        struct io_buffer *iob, int rc );
1163 void net80211_tx_complete ( struct net80211_device *dev,
1164                             struct io_buffer *iob, int retries, int rc );
1165 void net80211_unregister ( struct net80211_device *dev );
1166 void net80211_free ( struct net80211_device *dev );
1167 /** @} */
1168
1169 /**
1170  * Calculate duration field for a CTS control frame
1171  *
1172  * @v dev       802.11 device
1173  * @v size      Size of the packet being cleared to send
1174  *
1175  * A CTS control frame's duration field captures the frame being
1176  * protected and its 10-byte ACK.
1177  */
1178 static inline u16 net80211_cts_duration ( struct net80211_device *dev,
1179                                           int size )
1180 {
1181         return ( net80211_duration ( dev, 10,
1182                                      dev->rates[dev->rtscts_rate] ) +
1183                  net80211_duration ( dev, size, dev->rates[dev->rate] ) );
1184 }
1185
1186 #endif