iPXE
net80211.h
Go to the documentation of this file.
00001 #ifndef _IPXE_NET80211_H
00002 #define _IPXE_NET80211_H
00003 
00004 #include <ipxe/process.h>
00005 #include <ipxe/ieee80211.h>
00006 #include <ipxe/iobuf.h>
00007 #include <ipxe/netdevice.h>
00008 #include <ipxe/rc80211.h>
00009 
00010 /** @file
00011  *
00012  * The iPXE 802.11 MAC layer.
00013  */
00014 
00015 /*
00016  * Major things NOT YET supported:
00017  * - any type of security
00018  * - 802.11n
00019  *
00020  * Major things that probably will NEVER be supported, barring a
00021  * compelling use case and/or corporate sponsorship:
00022  * - QoS
00023  * - 802.1X authentication ("WPA Enterprise")
00024  * - Contention-free periods
00025  * - "ad-hoc" networks (IBSS), monitor mode, host AP mode
00026  * - hidden networks on the 5GHz band due to regulatory issues
00027  * - spectrum management on the 5GHz band (TPC and DFS), as required
00028  *   in some non-US regulatory domains
00029  * - Clause 14 PHYs (Frequency-Hopping Spread Spectrum on 2.4GHz)
00030  *   and Clause 16 PHYs (infrared) - I'm not aware of any real-world
00031  *   use of these.
00032  */
00033 
00034 FILE_LICENCE ( GPL2_OR_LATER );
00035 
00036 /* All 802.11 devices are handled using a generic "802.11 device"
00037    net_device, with a link in its `priv' field to a net80211_device
00038    which we use to handle 802.11-specific details. */
00039 
00040 
00041 /** @defgroup net80211_band RF bands on which an 802.11 device can transmit */
00042 /** @{ */
00043 
00044 /** The 2.4 GHz ISM band, unlicensed in most countries */
00045 #define NET80211_BAND_2GHZ      0
00046 /** The band from 4.9 GHz to 5.7 GHz, which tends to be more restricted */
00047 #define NET80211_BAND_5GHZ      1
00048 /** Number of RF bands */
00049 #define NET80211_NR_BANDS       2
00050 
00051 /** Bitmask for the 2GHz band */
00052 #define NET80211_BAND_BIT_2GHZ  (1 << 0)
00053 /** Bitmask for the 5GHz band */
00054 #define NET80211_BAND_BIT_5GHZ  (1 << 1)
00055 
00056 /** @} */
00057 
00058 
00059 /** @defgroup net80211_mode 802.11 operation modes supported by hardware */
00060 /** @{ */
00061 
00062 /** 802.11a: 54 Mbps operation using OFDM signaling on the 5GHz band */
00063 #define NET80211_MODE_A         (1 << 0)
00064 
00065 /** 802.11b: 1-11 Mbps operation using DSSS/CCK signaling on the 2.4GHz band */
00066 #define NET80211_MODE_B         (1 << 1)
00067 
00068 /** 802.11g: 54 Mbps operation using ERP/OFDM signaling on the 2.4GHz band */
00069 #define NET80211_MODE_G         (1 << 2)
00070 
00071 /** 802.11n: High-rate operation using MIMO technology on 2.4GHz or 5GHz */
00072 #define NET80211_MODE_N         (1 << 3)
00073 
00074 /** @} */
00075 
00076 
00077 /** @defgroup net80211_cfg Constants for the net80211 config callback */
00078 /** @{ */
00079 
00080 /** Channel choice (@c dev->channel) or regulatory parameters have changed */
00081 #define NET80211_CFG_CHANNEL    (1 << 0)
00082 
00083 /** Requested transmission rate (@c dev->rate) has changed */
00084 #define NET80211_CFG_RATE       (1 << 1)
00085 
00086 /** Association has been established with a new BSS (@c dev->bssid) */
00087 #define NET80211_CFG_ASSOC      (1 << 2)
00088 
00089 /** Low-level link parameters (short preamble, protection, etc) have changed */
00090 #define NET80211_CFG_PHY_PARAMS (1 << 3)
00091 
00092 /** @} */
00093 
00094 
00095 /** An 802.11 security handshaking protocol */
00096 enum net80211_security_proto {
00097         /** No security handshaking
00098          *
00099          * This might be used with an open network or with WEP, as
00100          * WEP does not have a cryptographic handshaking phase.
00101          */
00102         NET80211_SECPROT_NONE = 0,
00103 
00104         /** Pre-shared key handshaking
00105          *
00106          * This implements the "WPA Personal" handshake. 802.1X
00107          * authentication is not performed -- the user supplies a
00108          * pre-shared key directly -- but there is a 4-way handshake
00109          * between client and AP to verify that both have the same key
00110          * without revealing the contents of that key.
00111          */
00112         NET80211_SECPROT_PSK = 1,
00113 
00114         /** Full EAP 802.1X handshaking
00115          *
00116          * This implements the "WPA Enterprise" handshake, connecting
00117          * to an 802.1X authentication server to provide credentials
00118          * and receive a pairwise master key (PMK), which is then used
00119          * in the same 4-way handshake as the PSK method.
00120          */
00121         NET80211_SECPROT_EAP = 2,
00122 
00123         /** Dummy value used when the handshaking type can't be detected */
00124         NET80211_SECPROT_UNKNOWN = 3,
00125 };
00126 
00127 
00128 /** An 802.11 data encryption algorithm */
00129 enum net80211_crypto_alg {
00130         /** No security, an "Open" network */
00131         NET80211_CRYPT_NONE = 0,
00132 
00133         /** Network protected with WEP (awful RC4-based system)
00134          *
00135          * WEP uses a naive application of RC4, with a monotonically
00136          * increasing initialization vector that is prepended to the
00137          * key to initialize the RC4 keystream. It is highly insecure
00138          * and can be completely cracked or subverted using automated,
00139          * robust, freely available tools (aircrack-ng) in minutes.
00140          *
00141          * 40-bit and 104-bit WEP are differentiated only by the size
00142          * of the key. They may be advertised as 64-bit and 128-bit,
00143          * counting the non-random IV as part of the key bits.
00144          */
00145         NET80211_CRYPT_WEP = 1,
00146 
00147         /** Network protected with TKIP (better RC4-based system)
00148          *
00149          * Usually known by its trade name of WPA (Wi-Fi Protected
00150          * Access), TKIP implements a message integrity code (MIC)
00151          * called Michael, a timestamp counter for replay prevention,
00152          * and a key mixing function that together remove almost all
00153          * the security problems with WEP. Countermeasures are
00154          * implemented to prevent high data-rate attacks.
00155          *
00156          * There exists one known attack on TKIP, that allows one to
00157          * send between 7 and 15 arbitrary short data packets on a
00158          * QoS-enabled network given about an hour of data
00159          * gathering. Since iPXE does not support QoS for 802.11
00160          * networks, this is not a threat to us. The only other method
00161          * is a brute-force passphrase attack.
00162          */
00163         NET80211_CRYPT_TKIP = 2,
00164 
00165         /** Network protected with CCMP (AES-based system)
00166          *
00167          * Often called WPA2 in commerce, or RSNA (Robust Security
00168          * Network Architecture) in the 802.11 standard, CCMP is
00169          * highly secure and does not have any known attack vectors.
00170          * Since it is based on a block cipher, the statistical
00171          * correlation and "chopchop" attacks used with great success
00172          * against WEP and minor success against TKIP fail.
00173          */
00174         NET80211_CRYPT_CCMP = 3,
00175 
00176         /** Dummy value used when the cryptosystem can't be detected */
00177         NET80211_CRYPT_UNKNOWN = 4,
00178 };
00179 
00180 
00181 /** @defgroup net80211_state Bits for the 802.11 association state field */
00182 /** @{ */
00183 
00184 /** An error code indicating the failure mode, or 0 if successful */
00185 #define NET80211_STATUS_MASK    0x7F
00186 
00187 /** Whether the error code provided is a "reason" code, not a "status" code */
00188 #define NET80211_IS_REASON      0x80
00189 
00190 /** Whether we have found the network we will be associating with */
00191 #define NET80211_PROBED         (1 << 8)
00192 
00193 /** Whether we have successfully authenticated with the network
00194  *
00195  * This usually has nothing to do with actual security; it is a
00196  * holdover from older 802.11 implementation ideas.
00197  */
00198 #define NET80211_AUTHENTICATED  (1 << 9)
00199 
00200 /** Whether we have successfully associated with the network */
00201 #define NET80211_ASSOCIATED     (1 << 10)
00202 
00203 /** Whether we have completed security handshaking with the network
00204  *
00205  * Once this is set, we can send data packets. For that reason this
00206  * bit is set even in cases where no security handshaking is
00207  * required.
00208  */
00209 #define NET80211_CRYPTO_SYNCED  (1 << 11)
00210 
00211 /** Whether the auto-association task is running */
00212 #define NET80211_WORKING        (1 << 12)
00213 
00214 /** Whether the auto-association task is waiting for a reply from the AP */
00215 #define NET80211_WAITING        (1 << 13)
00216 
00217 /** Whether the auto-association task should be suppressed
00218  *
00219  * This is set by the `iwlist' command so that it can open the device
00220  * without starting another probe process that will interfere with its
00221  * own.
00222  */
00223 #define NET80211_NO_ASSOC       (1 << 14)
00224 
00225 /** Whether this association was performed using a broadcast SSID
00226  *
00227  * If the user opened this device without netX/ssid set, the device's
00228  * SSID will be set to that of the network it chooses to associate
00229  * with, but the netX/ssid setting will remain blank. If we don't
00230  * remember that we started from no specified SSID, it will appear
00231  * every time settings are updated (e.g. after DHCP) that we need to
00232  * reassociate due to the difference between the set SSID and our own.
00233  */
00234 #define NET80211_AUTO_SSID      (1 << 15)
00235 
00236 
00237 /** @} */
00238 
00239 
00240 /** @defgroup net80211_phy 802.11 physical layer flags */
00241 /** @{ */
00242 
00243 /** Whether to use RTS/CTS or CTS-to-self protection for transmissions
00244  *
00245  * Since the RTS or CTS is transmitted using 802.11b signaling, and
00246  * includes a field indicating the amount of time that will be used by
00247  * transmission of the following packet, this serves as an effective
00248  * protection mechanism to avoid 802.11b clients interfering with
00249  * 802.11g clients on mixed networks.
00250  */
00251 #define NET80211_PHY_USE_PROTECTION      (1 << 1)
00252 
00253 /** Whether to use 802.11b short preamble operation
00254  *
00255  * Short-preamble operation can moderately increase throughput on
00256  * 802.11b networks operating between 2Mbps and 11Mbps. It is
00257  * irrelevant for 802.11g data rates, since they use a different
00258  * modulation scheme.
00259  */
00260 #define NET80211_PHY_USE_SHORT_PREAMBLE  (1 << 2)
00261 
00262 /** Whether to use 802.11g short slot operation
00263  *
00264  * This affects a low-level timing parameter of 802.11g transmissions.
00265  */
00266 #define NET80211_PHY_USE_SHORT_SLOT      (1 << 3)
00267 
00268 /** @} */
00269 
00270 
00271 /** The maximum number of TX rates we allow to be configured simultaneously */
00272 #define NET80211_MAX_RATES      16
00273 
00274 /** The maximum number of channels we allow to be configured simultaneously */
00275 #define NET80211_MAX_CHANNELS   40
00276 
00277 /** Seconds we'll wait to get all fragments of a packet */
00278 #define NET80211_FRAG_TIMEOUT   2
00279 
00280 /** The number of fragments we can receive at once
00281  *
00282  * The 802.11 standard requires that this be at least 3.
00283  */
00284 #define NET80211_NR_CONCURRENT_FRAGS 3
00285 
00286 /** Maximum TX power to allow (dBm), if we don't get a regulatory hint */
00287 #define NET80211_REG_TXPOWER    20
00288 
00289 
00290 struct net80211_device;
00291 
00292 /** Operations that must be implemented by an 802.11 driver */
00293 struct net80211_device_operations {
00294         /** Open 802.11 device
00295          *
00296          * @v dev       802.11 device
00297          * @ret rc      Return status code
00298          *
00299          * This method should allocate RX I/O buffers and enable the
00300          * hardware to start transmitting and receiving packets on the
00301          * channels its net80211_register() call indicated it could
00302          * handle. It does not need to tune the antenna to receive
00303          * packets on any particular channel.
00304          */
00305         int ( * open ) ( struct net80211_device *dev );
00306 
00307         /** Close 802.11 network device
00308          *
00309          * @v dev       802.11 device
00310          *
00311          * This method should stop the flow of packets, and call
00312          * net80211_tx_complete() for any packets remaining in the
00313          * device's TX queue.
00314          */
00315         void ( * close ) ( struct net80211_device *dev );
00316 
00317         /** Transmit packet on 802.11 network device
00318          *
00319          * @v dev       802.11 device
00320          * @v iobuf     I/O buffer
00321          * @ret rc      Return status code
00322          *
00323          * This method should cause the hardware to initiate
00324          * transmission of the I/O buffer, using the channel and rate
00325          * most recently indicated by an appropriate call to the
00326          * @c config callback. The 802.11 layer guarantees that said
00327          * channel and rate will be the same as those currently
00328          * reflected in the fields of @a dev.
00329          *
00330          * If this method returns success, the I/O buffer remains
00331          * owned by the network layer's TX queue, and the driver must
00332          * eventually call net80211_tx_complete() to free the buffer
00333          * whether transmission succeeded or not. If this method
00334          * returns failure, it will be interpreted as "failure to
00335          * enqueue buffer" and the I/O buffer will be immediately
00336          * released.
00337          *
00338          * This method is guaranteed to be called only when the device
00339          * is open.
00340          */
00341         int ( * transmit ) ( struct net80211_device *dev,
00342                              struct io_buffer *iobuf );
00343 
00344         /** Poll for completed and received packets
00345          *
00346          * @v dev       802.11 device
00347          *
00348          * This method should cause the hardware to check for
00349          * completed transmissions and received packets. Any received
00350          * packets should be delivered via net80211_rx(), and
00351          * completed transmissions should be indicated using
00352          * net80211_tx_complete().
00353          *
00354          * This method is guaranteed to be called only when the device
00355          * is open.
00356          */
00357         void ( * poll ) ( struct net80211_device *dev );
00358 
00359         /** Enable or disable interrupts
00360          *
00361          * @v dev       802.11 device
00362          * @v enable    If TRUE, interrupts should be enabled
00363          */
00364         void ( * irq ) ( struct net80211_device *dev, int enable );
00365 
00366         /** Update hardware state to match 802.11 layer state
00367          *
00368          * @v dev       802.11 device
00369          * @v changed   Set of flags indicating what may have changed
00370          * @ret rc      Return status code
00371          *
00372          * This method should cause the hardware state to be
00373          * reinitialized from the state indicated in fields of
00374          * net80211_device, in the areas indicated by bits set in
00375          * @a changed. If the hardware is unable to do so, this method
00376          * may return an appropriate error indication.
00377          *
00378          * This method is guaranteed to be called only when the device
00379          * is open.
00380          */
00381         int ( * config ) ( struct net80211_device *dev, int changed );
00382 };
00383 
00384 /** An 802.11 RF channel. */
00385 struct net80211_channel
00386 {
00387         /** The band with which this channel is associated */
00388         u8 band;
00389 
00390         /** A channel number interpreted according to the band
00391          *
00392          * The 2.4GHz band uses channel numbers from 1-13 at 5MHz
00393          * intervals such that channel 1 is 2407 MHz; channel 14,
00394          * legal for use only in Japan, is defined separately as 2484
00395          * MHz. Adjacent channels will overlap, since 802.11
00396          * transmissions use a 20 MHz (4-channel) bandwidth. Most
00397          * commonly, channels 1, 6, and 11 are used.
00398          *
00399          * The 5GHz band uses channel numbers derived directly from
00400          * the frequency; channel 0 is 5000 MHz, and channels are
00401          * always spaced 5 MHz apart. Channel numbers over 180 are
00402          * relative to 4GHz instead of 5GHz, but these are rarely
00403          * seen. Most channels are not legal for use.
00404          */
00405         u8 channel_nr;
00406 
00407         /** The center frequency for this channel
00408          *
00409          * Currently a bandwidth of 20 MHz is assumed.
00410          */
00411         u16 center_freq;
00412 
00413         /** Hardware channel value */
00414         u16 hw_value;
00415 
00416         /** Maximum allowable transmit power, in dBm
00417          *
00418          * This should be interpreted as EIRP, the power supplied to
00419          * an ideal isotropic antenna in order to achieve the same
00420          * average signal intensity as the real hardware at a
00421          * particular distance.
00422          *
00423          * Currently no provision is made for directional antennas.
00424          */
00425         u8 maxpower;
00426 };
00427 
00428 /** Information on the capabilities of an 802.11 hardware device
00429  *
00430  * In its probe callback, an 802.11 driver must read hardware
00431  * registers to determine the appropriate contents of this structure,
00432  * fill it, and pass it to net80211_register() so that the 802.11
00433  * layer knows how to treat the hardware and what to advertise as
00434  * supported to access points.
00435  */
00436 struct net80211_hw_info
00437 {
00438         /** Default hardware MAC address.
00439          *
00440          * The user may change this by setting the @c netX/mac setting
00441          * before the driver's open function is called; in that case
00442          * the driver must set the hardware MAC address to the address
00443          * contained in the wrapping net_device's ll_addr field, or if
00444          * that is impossible, set that ll_addr field back to the
00445          * unchangeable hardware MAC address.
00446          */
00447         u8 hwaddr[ETH_ALEN];
00448 
00449         /** A bitwise OR of the 802.11x modes supported by this device */
00450         int modes;
00451 
00452         /** A bitwise OR of the bands on which this device can communicate */
00453         int bands;
00454 
00455         /** A set of flags indicating peculiarities of this device. */
00456         enum {
00457                 /** Received frames include a frame check sequence. */
00458                 NET80211_HW_RX_HAS_FCS = (1 << 1),
00459 
00460                 /** Hardware doesn't support 2.4GHz short preambles
00461                  *
00462                  * This is only relevant for 802.11b operation above
00463                  * 2Mbps. All 802.11g devices support short preambles.
00464                  */
00465                 NET80211_HW_NO_SHORT_PREAMBLE = (1 << 2),
00466 
00467                 /** Hardware doesn't support 802.11g short slot operation */
00468                 NET80211_HW_NO_SHORT_SLOT = (1 << 3),
00469         } flags;
00470 
00471         /** Signal strength information that can be provided by the device
00472          *
00473          * Signal strength is passed to net80211_rx(), primarily to
00474          * allow determination of the closest access point for a
00475          * multi-AP network. The units are provided for completeness
00476          * of status displays.
00477          */
00478         enum {
00479                 /** No signal strength information supported */
00480                 NET80211_SIGNAL_NONE = 0,
00481                 /** Signal strength in arbitrary units */
00482                 NET80211_SIGNAL_ARBITRARY,
00483                 /** Signal strength in decibels relative to arbitrary base */
00484                 NET80211_SIGNAL_DB,
00485                 /** Signal strength in decibels relative to 1mW */
00486                 NET80211_SIGNAL_DBM,
00487         } signal_type;
00488 
00489         /** Maximum signal in arbitrary cases
00490          *
00491          * If signal_type is NET80211_SIGNAL_ARBITRARY or
00492          * NET80211_SIGNAL_DB, the driver should report it on a scale
00493          * from 0 to signal_max.
00494          */
00495         unsigned signal_max;
00496 
00497         /** List of RF channels supported by the card */
00498         struct net80211_channel channels[NET80211_MAX_CHANNELS];
00499 
00500         /** Number of supported channels */
00501         int nr_channels;
00502 
00503         /** List of transmission rates supported by the card, indexed by band
00504          *
00505          * Rates should be in 100kbps increments (e.g. 11 Mbps would
00506          * be represented as the number 110).
00507          */
00508         u16 rates[NET80211_NR_BANDS][NET80211_MAX_RATES];
00509 
00510         /** Number of supported rates, indexed by band */
00511         int nr_rates[NET80211_NR_BANDS];
00512 
00513         /** Estimate of the time required to change channels, in microseconds
00514          *
00515          * If this is not known, a guess on the order of a few
00516          * milliseconds (value of 1000-5000) is reasonable.
00517          */
00518         unsigned channel_change_time;
00519 };
00520 
00521 /** Structure tracking received fragments for a packet
00522  *
00523  * We set up a fragment cache entry when we receive a packet marked as
00524  * fragment 0 with the "more fragments" bit set in its frame control
00525  * header. We are required by the 802.11 standard to track 3
00526  * fragmented packets arriving simultaneously; if we receive more we
00527  * may drop some. Upon receipt of a new fragment-0 packet, if no entry
00528  * is available or expired, we take over the most @e recent entry for
00529  * the new packet, since we don't want to starve old entries from ever
00530  * finishing at all. If we get a fragment after the zeroth with no
00531  * cache entry for its packet, we drop it.
00532  */
00533 struct net80211_frag_cache
00534 {
00535         /** Whether this cache entry is in use */
00536         u8 in_use;
00537 
00538         /** Sequence number of this MSDU (packet) */
00539         u16 seqnr;
00540 
00541         /** Timestamp from point at which first fragment was collected */
00542         u32 start_ticks;
00543 
00544         /** Buffers for each fragment */
00545         struct io_buffer *iob[16];
00546 };
00547 
00548 
00549 /** Interface to an 802.11 security handshaking protocol
00550  *
00551  * Security handshaking protocols handle parsing a user-specified key
00552  * into a suitable input to the encryption algorithm, and for WPA and
00553  * better systems, manage performing whatever authentication with the
00554  * network is necessary.
00555  *
00556  * At all times when any method in this structure is called with a
00557  * net80211_device argument @a dev, a dynamically allocated copy of
00558  * the handshaker structure itself with space for the requested amount
00559  * of private data may be accessed as @c dev->handshaker. The
00560  * structure will not be modified, and will only be freed during
00561  * reassociation and device closing after the @a stop method has been
00562  * called.
00563  */
00564 struct net80211_handshaker
00565 {
00566         /** The security handshaking protocol implemented */
00567         enum net80211_security_proto protocol;
00568 
00569         /** Initialize security handshaking protocol
00570          *
00571          * @v dev       802.11 device
00572          * @ret rc      Return status code
00573          *
00574          * This method is expected to access @c netX/key or other
00575          * applicable settings to determine the parameters for
00576          * handshaking. If no handshaking is required, it should call
00577          * sec80211_install() with the cryptosystem and key that are
00578          * to be used, and @c start and @c step should be set to @c
00579          * NULL.
00580          *
00581          * This is always called just before association is performed,
00582          * but after its parameters have been set; in particular, you
00583          * may rely on the contents of the @a essid field in @a dev.
00584          */
00585         int ( * init ) ( struct net80211_device *dev );
00586 
00587         /** Start handshaking
00588          *
00589          * @v dev       802.11 device
00590          * @ret rc      Return status code
00591          *
00592          * This method is expected to set up internal state so that
00593          * packets sent immediately after association, before @a step
00594          * can be called, will be handled appropriately.
00595          *
00596          * This is always called just before association is attempted.
00597          */
00598         int ( * start ) ( struct net80211_device *dev );
00599 
00600         /** Process handshaking state
00601          *
00602          * @v dev       802.11 device
00603          * @ret rc      Return status code, or positive if done
00604          *
00605          * This method is expected to perform as much progress on the
00606          * protocol it implements as is possible without blocking. It
00607          * should return 0 if it wishes to be called again, a negative
00608          * return status code on error, or a positive value if
00609          * handshaking is complete. In the case of a positive return,
00610          * net80211_crypto_install() must have been called.
00611          *
00612          * If handshaking may require further action (e.g. an AP that
00613          * might decide to rekey), handlers must be installed by this
00614          * function that will act without further calls to @a step.
00615          */
00616         int ( * step ) ( struct net80211_device *dev );
00617 
00618         /** Change cryptographic key based on setting
00619          *
00620          * @v dev       802.11 device
00621          * @ret rc      Return status code
00622          *
00623          * This method is called whenever the @c netX/key setting
00624          * @e may have been changed. It is expected to determine
00625          * whether it did in fact change, and if so, to install the
00626          * new key using net80211_crypto_install(). If it is not
00627          * possible to do this immediately, this method should return
00628          * an error; in that case the 802.11 stack will reassociate,
00629          * following the usual init/start/step sequence.
00630          *
00631          * This method is only relevant when it is possible to
00632          * associate successfully with an incorrect key. When it is
00633          * not, a failed association will be retried until the user
00634          * changes the key setting, and a successful association will
00635          * not be dropped due to such a change. When association with
00636          * an incorrect key is impossible, this function should return
00637          * 0 after performing no action.
00638          */
00639         int ( * change_key ) ( struct net80211_device *dev );
00640 
00641         /** Stop security handshaking handlers
00642          *
00643          * @v dev       802.11 device
00644          *
00645          * This method is called just before freeing a security
00646          * handshaker; it could, for example, delete a process that @a
00647          * start had created to manage the security of the connection.
00648          * If not needed it may be set to NULL.
00649          */
00650         void ( * stop ) ( struct net80211_device *dev );
00651 
00652         /** Amount of private data requested
00653          *
00654          * Before @c init is called for the first time, this structure's
00655          * @c priv pointer will point to this many bytes of allocated
00656          * data, where the allocation will be performed separately for
00657          * each net80211_device.
00658          */
00659         int priv_len;
00660 
00661         /** Whether @a start has been called
00662          *
00663          * Reset to 0 after @a stop is called.
00664          */
00665         int started;
00666 
00667         /** Pointer to private data
00668          *
00669          * In initializing this structure statically for a linker
00670          * table, set this to NULL.
00671          */
00672         void *priv;
00673 };
00674 
00675 #define NET80211_HANDSHAKERS __table ( struct net80211_handshaker, \
00676                                        "net80211_handshakers" )
00677 #define __net80211_handshaker __table_entry ( NET80211_HANDSHAKERS, 01 )
00678 
00679 
00680 /** Interface to an 802.11 cryptosystem
00681  *
00682  * Cryptosystems define a net80211_crypto structure statically, using
00683  * a iPXE linker table to make it available to the 802.11 layer. When
00684  * the cryptosystem needs to be used, the 802.11 code will allocate a
00685  * copy of the static definition plus whatever space the algorithm has
00686  * requested for private state, and point net80211_device::crypto or
00687  * net80211_device::gcrypto at it.
00688  */
00689 struct net80211_crypto
00690 {
00691         /** The cryptographic algorithm implemented */
00692         enum net80211_crypto_alg algorithm;
00693 
00694         /** Initialize cryptosystem using a given key
00695          *
00696          * @v crypto    802.11 cryptosystem
00697          * @v key       Pointer to key bytes
00698          * @v keylen    Number of key bytes
00699          * @v rsc       Initial receive sequence counter, if applicable
00700          * @ret rc      Return status code
00701          *
00702          * This method is passed the communication key provided by the
00703          * security handshake handler, which will already be in the
00704          * low-level form required. It may not store a pointer to the
00705          * key after returning; it must copy it to its private storage.
00706          */
00707         int ( * init ) ( struct net80211_crypto *crypto, const void *key,
00708                          int keylen, const void *rsc );
00709 
00710         /** Encrypt a frame using the cryptosystem
00711          *
00712          * @v crypto    802.11 cryptosystem
00713          * @v iob       I/O buffer
00714          * @ret eiob    Newly allocated I/O buffer with encrypted packet
00715          *
00716          * This method is called to encrypt a single frame. It is
00717          * guaranteed that initialize() will have completed
00718          * successfully before this method is called.
00719          *
00720          * The frame passed already has an 802.11 header prepended,
00721          * but the PROTECTED bit in the frame control field will not
00722          * be set; this method is responsible for setting it. The
00723          * returned I/O buffer should contain a complete copy of @a
00724          * iob, including the 802.11 header, but with the PROTECTED
00725          * bit set, the data encrypted, and whatever encryption
00726          * headers/trailers are necessary added.
00727          *
00728          * This method should never free the passed I/O buffer.
00729          *
00730          * Return NULL if the packet could not be encrypted, due to
00731          * memory limitations or otherwise.
00732          */
00733         struct io_buffer * ( * encrypt ) ( struct net80211_crypto *crypto,
00734                                            struct io_buffer *iob );
00735 
00736         /** Decrypt a frame using the cryptosystem
00737          *
00738          * @v crypto    802.11 cryptosystem
00739          * @v eiob      Encrypted I/O buffer
00740          * @ret iob     Newly allocated I/O buffer with decrypted packet
00741          *
00742          * This method is called to decrypt a single frame. It is
00743          * guaranteed that initialize() will have completed
00744          * successfully before this method is called.
00745          *
00746          * Decryption follows the reverse of the pattern used for
00747          * encryption: this method must copy the 802.11 header into
00748          * the returned packet, decrypt the data stream, remove any
00749          * encryption header or trailer, and clear the PROTECTED bit
00750          * in the frame control header.
00751          *
00752          * This method should never free the passed I/O buffer.
00753          *
00754          * Return NULL if memory was not available for decryption, if
00755          * a consistency or integrity check on the decrypted frame
00756          * failed, or if the decrypted frame should not be processed
00757          * by the network stack for any other reason.
00758          */
00759         struct io_buffer * ( * decrypt ) ( struct net80211_crypto *crypto,
00760                                            struct io_buffer *iob );
00761 
00762         /** Length of private data requested to be allocated */
00763         int priv_len;
00764 
00765         /** Private data for the algorithm to store key and state info */
00766         void *priv;
00767 };
00768 
00769 #define NET80211_CRYPTOS __table ( struct net80211_crypto, "net80211_cryptos" )
00770 #define __net80211_crypto __table_entry ( NET80211_CRYPTOS, 01 )
00771 
00772 
00773 struct net80211_probe_ctx;
00774 struct net80211_assoc_ctx;
00775 
00776 
00777 /** Structure encapsulating the complete state of an 802.11 device
00778  *
00779  * An 802.11 device is always wrapped by a network device, and this
00780  * network device is always pointed to by the @a netdev field. In
00781  * general, operations should never be performed by 802.11 code using
00782  * netdev functions directly. It is usually the case that the 802.11
00783  * layer might need to do some processing or bookkeeping on top of
00784  * what the netdevice code will do.
00785  */
00786 struct net80211_device
00787 {
00788         /** The net_device that wraps us. */
00789         struct net_device *netdev;
00790 
00791         /** List of 802.11 devices. */
00792         struct list_head list;
00793 
00794         /** 802.11 device operations */
00795         struct net80211_device_operations *op;
00796 
00797         /** Driver private data */
00798         void *priv;
00799 
00800         /** Information about the hardware, provided to net80211_register() */
00801         struct net80211_hw_info *hw;
00802 
00803         /* ---------- Channel and rate fields ---------- */
00804 
00805         /** A list of all possible channels we might use */
00806         struct net80211_channel channels[NET80211_MAX_CHANNELS];
00807 
00808         /** The number of channels in the channels array */
00809         u8 nr_channels;
00810 
00811         /** The channel currently in use, as an index into the channels array */
00812         u8 channel;
00813 
00814         /** A list of all possible TX rates we might use
00815          *
00816          * Rates are in units of 100 kbps.
00817          */
00818         u16 rates[NET80211_MAX_RATES];
00819 
00820         /** The number of transmission rates in the rates array */
00821         u8 nr_rates;
00822 
00823         /** The rate currently in use, as an index into the rates array */
00824         u8 rate;
00825 
00826         /** The rate to use for RTS/CTS transmissions
00827          *
00828          * This is always the fastest basic rate that is not faster
00829          * than the data rate in use. Also an index into the rates array.
00830          */
00831         u8 rtscts_rate;
00832 
00833         /** Bitmask of basic rates
00834          *
00835          * If bit N is set in this value, with the LSB considered to
00836          * be bit 0, then rate N in the rates array is a "basic" rate.
00837          *
00838          * We don't decide which rates are "basic"; our AP does, and
00839          * we respect its wishes. We need to be able to identify basic
00840          * rates in order to calculate the duration of a CTS packet
00841          * used for 802.11 g/b interoperability.
00842          */
00843         u32 basic_rates;
00844 
00845         /* ---------- Association fields ---------- */
00846 
00847         /** The asynchronous association process.
00848          *
00849          * When an 802.11 netdev is opened, or when the user changes
00850          * the SSID setting on an open 802.11 device, an
00851          * autoassociation task is started by net80211_autoassocate()
00852          * to associate with the new best network. The association is
00853          * asynchronous, but no packets can be transmitted until it is
00854          * complete. If it is successful, the wrapping net_device is
00855          * set as "link up". If it fails, @c assoc_rc will be set with
00856          * an error indication.
00857          */
00858         struct process proc_assoc;
00859 
00860         /** Network with which we are associating
00861          *
00862          * This will be NULL when we are not actively in the process
00863          * of associating with a network we have already successfully
00864          * probed for.
00865          */
00866         struct net80211_wlan *associating;
00867 
00868         /** Context for the association process
00869          *
00870          * This is a probe_ctx if the @c PROBED flag is not set in @c
00871          * state, and an assoc_ctx otherwise.
00872          */
00873         union {
00874                 struct net80211_probe_ctx *probe;
00875                 struct net80211_assoc_ctx *assoc;
00876         } ctx;
00877 
00878         /** Security handshaker being used */
00879         struct net80211_handshaker *handshaker;
00880 
00881         /** State of our association to the network
00882          *
00883          * Since the association process happens asynchronously, it's
00884          * necessary to have some channel of communication so the
00885          * driver can say "I got an association reply and we're OK" or
00886          * similar. This variable provides that link. It is a bitmask
00887          * of any of NET80211_PROBED, NET80211_AUTHENTICATED,
00888          * NET80211_ASSOCIATED, NET80211_CRYPTO_SYNCED to indicate how
00889          * far along in associating we are; NET80211_WORKING if the
00890          * association task is running; and NET80211_WAITING if a
00891          * packet has been sent that we're waiting for a reply to. We
00892          * can only be crypto-synced if we're associated, we can
00893          * only be associated if we're authenticated, we can only be
00894          * authenticated if we've probed.
00895          *
00896          * If an association process fails (that is, we receive a
00897          * packet with an error indication), the error code is copied
00898          * into bits 6-0 of this variable and bit 7 is set to specify
00899          * what type of error code it is. An AP can provide either a
00900          * "status code" (0-51 are defined) explaining why it refused
00901          * an association immediately, or a "reason code" (0-45 are
00902          * defined) explaining why it canceled an association after it
00903          * had originally OK'ed it. Status and reason codes serve
00904          * similar functions, but they use separate error message
00905          * tables. A iPXE-formatted return status code (negative) is
00906          * placed in @c assoc_rc.
00907          *
00908          * If the failure to associate is indicated by a status code,
00909          * the NET80211_IS_REASON bit will be clear; if it is
00910          * indicated by a reason code, the bit will be set. If we were
00911          * successful, both zero status and zero reason mean success,
00912          * so there is no ambiguity.
00913          *
00914          * To prevent association when opening the device, user code
00915          * can set the NET80211_NO_ASSOC bit. The final bit in this
00916          * variable, NET80211_AUTO_SSID, is used to remember whether
00917          * we picked our SSID through automated probing as opposed to
00918          * user specification; the distinction becomes relevant in the
00919          * settings applicator.
00920          */
00921         u16 state;
00922 
00923         /** Return status code associated with @c state */
00924         int assoc_rc;
00925 
00926         /** RSN or WPA information element to include with association
00927          *
00928          * If set to @c NULL, none will be included. It is expected
00929          * that this will be set by the @a init function of a security
00930          * handshaker if it is needed.
00931          */
00932         union ieee80211_ie *rsn_ie;
00933 
00934         /* ---------- Parameters of currently associated network ---------- */
00935 
00936         /** 802.11 cryptosystem for our current network
00937          *
00938          * For an open network, this will be set to NULL.
00939          */
00940         struct net80211_crypto *crypto;
00941 
00942         /** 802.11 cryptosystem for multicast and broadcast frames
00943          *
00944          * If this is NULL, the cryptosystem used for receiving
00945          * unicast frames will also be used for receiving multicast
00946          * and broadcast frames. Transmitted multicast and broadcast
00947          * frames are always sent unicast to the AP, who multicasts
00948          * them on our behalf; thus they always use the unicast
00949          * cryptosystem.
00950          */
00951         struct net80211_crypto *gcrypto;
00952 
00953         /** MAC address of the access point most recently associated */
00954         u8 bssid[ETH_ALEN];
00955 
00956         /** SSID of the access point we are or will be associated with
00957          *
00958          * Although the SSID field in 802.11 packets is generally not
00959          * NUL-terminated, here and in net80211_wlan we add a NUL for
00960          * convenience.
00961          */
00962         char essid[IEEE80211_MAX_SSID_LEN+1];
00963 
00964         /** Association ID given to us by the AP */
00965         u16 aid;
00966 
00967         /** TSFT value for last beacon received, microseconds */
00968         u64 last_beacon_timestamp;
00969 
00970         /** Time between AP sending beacons, microseconds */
00971         u32 tx_beacon_interval;
00972 
00973         /** Smoothed average time between beacons, microseconds */
00974         u32 rx_beacon_interval;
00975 
00976         /* ---------- Physical layer information ---------- */
00977 
00978         /** Physical layer options
00979          *
00980          * These control the use of CTS protection, short preambles,
00981          * and short-slot operation.
00982          */
00983         int phy_flags;
00984 
00985         /** Signal strength of last received packet */
00986         int last_signal;
00987 
00988         /** Rate control state */
00989         struct rc80211_ctx *rctl;
00990 
00991         /* ---------- Packet handling state ---------- */
00992 
00993         /** Fragment reassembly state */
00994         struct net80211_frag_cache frags[NET80211_NR_CONCURRENT_FRAGS];
00995 
00996         /** The sequence number of the last packet we sent */
00997         u16 last_tx_seqnr;
00998 
00999         /** Packet duplication elimination state
01000          *
01001          * We are only required to handle immediate duplicates for
01002          * each direct sender, and since we can only have one direct
01003          * sender (the AP), we need only keep the sequence control
01004          * field from the most recent packet we've received. Thus,
01005          * this field stores the last sequence control field we've
01006          * received for a packet from the AP.
01007          */
01008         u16 last_rx_seq;
01009 
01010         /** RX management packet queue
01011          *
01012          * Sometimes we want to keep probe, beacon, and action packets
01013          * that we receive, such as when we're scanning for networks.
01014          * Ordinarily we drop them because they are sent at a large
01015          * volume (ten beacons per second per AP, broadcast) and we
01016          * have no need of them except when we're scanning.
01017          *
01018          * When keep_mgmt is TRUE, received probe, beacon, and action
01019          * management packets will be stored in this queue.
01020          */
01021         struct list_head mgmt_queue;
01022 
01023         /** RX management packet info queue
01024          *
01025          * We need to keep track of the signal strength for management
01026          * packets we're keeping, because that provides the only way
01027          * to distinguish between multiple APs for the same network.
01028          * Since we can't extend io_buffer to store signal, this field
01029          * heads a linked list of "RX packet info" structures that
01030          * contain that signal strength field. Its entries always
01031          * parallel the entries in mgmt_queue, because the two queues
01032          * are always added to or removed from in parallel.
01033          */
01034         struct list_head mgmt_info_queue;
01035 
01036         /** Whether to store management packets
01037          *
01038          * Received beacon, probe, and action packets will be added to
01039          * mgmt_queue (and their signal strengths added to
01040          * mgmt_info_queue) only when this variable is TRUE. It should
01041          * be set by net80211_keep_mgmt() (which returns the old
01042          * value) only when calling code is prepared to poll the
01043          * management queue frequently, because packets will otherwise
01044          * pile up and exhaust memory.
01045          */
01046         int keep_mgmt;
01047 };
01048 
01049 /** Structure representing a probed network.
01050  *
01051  * This is returned from the net80211_probe_finish functions and
01052  * passed to the low-level association functions. At least essid,
01053  * bssid, channel, beacon, and security must be filled in if you want
01054  * to build this structure manually.
01055  */
01056 struct net80211_wlan
01057 {
01058         /** The human-readable ESSID (network name)
01059          *
01060          * Although the 802.11 SSID field is generally not
01061          * NUL-terminated, the iPXE code adds an extra NUL (and
01062          * expects one in this structure) for convenience.
01063          */
01064         char essid[IEEE80211_MAX_SSID_LEN+1];
01065 
01066         /** MAC address of the strongest-signal access point for this ESSID */
01067         u8 bssid[ETH_ALEN];
01068 
01069         /** Signal strength of beacon frame from that access point */
01070         int signal;
01071 
01072         /** The channel on which that access point communicates
01073          *
01074          * This is a raw channel number (net80211_channel::channel_nr),
01075          * so that it will not be affected by reconfiguration of the
01076          * device channels array.
01077          */
01078         int channel;
01079 
01080         /** The complete beacon or probe-response frame received */
01081         struct io_buffer *beacon;
01082 
01083         /** Security handshaking method used on the network */
01084         enum net80211_security_proto handshaking;
01085 
01086         /** Cryptographic algorithm used on the network */
01087         enum net80211_crypto_alg crypto;
01088 
01089         /** Link to allow chaining multiple structures into a list to
01090             be returned from net80211_probe_finish_all(). */
01091         struct list_head list;
01092 };
01093 
01094 
01095 /** 802.11 encryption key setting */
01096 extern const struct setting
01097 net80211_key_setting __setting ( SETTING_NETDEV_EXTRA, key );
01098 
01099 
01100 /**
01101  * @defgroup net80211_probe 802.11 network location API
01102  * @{
01103  */
01104 int net80211_prepare_probe ( struct net80211_device *dev, int band,
01105                              int active );
01106 struct net80211_probe_ctx * net80211_probe_start ( struct net80211_device *dev,
01107                                                    const char *essid,
01108                                                    int active );
01109 int net80211_probe_step ( struct net80211_probe_ctx *ctx );
01110 struct net80211_wlan *
01111 net80211_probe_finish_best ( struct net80211_probe_ctx *ctx );
01112 struct list_head *net80211_probe_finish_all ( struct net80211_probe_ctx *ctx );
01113 
01114 void net80211_free_wlan ( struct net80211_wlan *wlan );
01115 void net80211_free_wlanlist ( struct list_head *list );
01116 /** @} */
01117 
01118 
01119 /**
01120  * @defgroup net80211_mgmt 802.11 network management API
01121  * @{
01122  */
01123 struct net80211_device * net80211_get ( struct net_device *netdev );
01124 void net80211_autoassociate ( struct net80211_device *dev );
01125 
01126 int net80211_change_channel ( struct net80211_device *dev, int channel );
01127 void net80211_set_rate_idx ( struct net80211_device *dev, int rate );
01128 
01129 int net80211_keep_mgmt ( struct net80211_device *dev, int enable );
01130 struct io_buffer * net80211_mgmt_dequeue ( struct net80211_device *dev,
01131                                            int *signal );
01132 int net80211_tx_mgmt ( struct net80211_device *dev, u16 fc,
01133                        u8 bssid[ETH_ALEN], struct io_buffer *iob );
01134 /** @} */
01135 
01136 
01137 /**
01138  * @defgroup net80211_assoc 802.11 network association API
01139  * @{
01140  */
01141 int net80211_prepare_assoc ( struct net80211_device *dev,
01142                              struct net80211_wlan *wlan );
01143 int net80211_send_auth ( struct net80211_device *dev,
01144                          struct net80211_wlan *wlan, int method );
01145 int net80211_send_assoc ( struct net80211_device *dev,
01146                           struct net80211_wlan *wlan );
01147 void net80211_deauthenticate ( struct net80211_device *dev, int rc );
01148 /** @} */
01149 
01150 
01151 /**
01152  * @defgroup net80211_driver 802.11 driver interface API
01153  * @{
01154  */
01155 struct net80211_device *net80211_alloc ( size_t priv_size );
01156 int net80211_register ( struct net80211_device *dev,
01157                         struct net80211_device_operations *ops,
01158                         struct net80211_hw_info *hw );
01159 u16 net80211_duration ( struct net80211_device *dev, int bytes, u16 rate );
01160 void net80211_rx ( struct net80211_device *dev, struct io_buffer *iob,
01161                    int signal, u16 rate );
01162 void net80211_rx_err ( struct net80211_device *dev,
01163                        struct io_buffer *iob, int rc );
01164 void net80211_tx_complete ( struct net80211_device *dev,
01165                             struct io_buffer *iob, int retries, int rc );
01166 void net80211_unregister ( struct net80211_device *dev );
01167 void net80211_free ( struct net80211_device *dev );
01168 /** @} */
01169 
01170 /**
01171  * Calculate duration field for a CTS control frame
01172  *
01173  * @v dev       802.11 device
01174  * @v size      Size of the packet being cleared to send
01175  *
01176  * A CTS control frame's duration field captures the frame being
01177  * protected and its 10-byte ACK.
01178  */
01179 static inline u16 net80211_cts_duration ( struct net80211_device *dev,
01180                                           int size )
01181 {
01182         return ( net80211_duration ( dev, 10,
01183                                      dev->rates[dev->rtscts_rate] ) +
01184                  net80211_duration ( dev, size, dev->rates[dev->rate] ) );
01185 }
01186 
01187 #endif