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 1187
