1WPA Supplicant 2============== 3 4Copyright (c) 2003-2004, Jouni Malinen <jkmaline@cc.hut.fi> 5All Rights Reserved. 6 7Sun elects to license this software under the BSD license. 8 9 10License 11------- 12 13BSD license: 14 15Redistribution and use in source and binary forms, with or without 16modification, are permitted provided that the following conditions are 17met: 18 191. Redistributions of source code must retain the above copyright 20 notice, this list of conditions and the following disclaimer. 21 222. Redistributions in binary form must reproduce the above copyright 23 notice, this list of conditions and the following disclaimer in the 24 documentation and/or other materials provided with the distribution. 25 263. Neither the name(s) of the above-listed copyright holder(s) nor the 27 names of its contributors may be used to endorse or promote products 28 derived from this software without specific prior written permission. 29 30THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 31"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 32LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 33A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 34OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 35SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 36LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 37DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 38THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 39(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 40OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 41 42 43 44Features 45-------- 46 47Supported WPA/IEEE 802.11i features: 48- WPA-PSK ("WPA-Personal") 49- WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise") 50 Following authentication methods are supported with an integrate IEEE 802.1X 51 Supplicant: 52 * EAP-TLS 53 * EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1) 54 * EAP-PEAP/TLS (both PEAPv0 and PEAPv1) 55 * EAP-PEAP/GTC (both PEAPv0 and PEAPv1) 56 * EAP-PEAP/OTP (both PEAPv0 and PEAPv1) 57 * EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1) 58 * EAP-TTLS/EAP-MD5-Challenge 59 * EAP-TTLS/EAP-GTC 60 * EAP-TTLS/EAP-OTP 61 * EAP-TTLS/EAP-MSCHAPv2 62 * EAP-TTLS/EAP-TLS 63 * EAP-TTLS/MSCHAPv2 64 * EAP-TTLS/MSCHAP 65 * EAP-TTLS/PAP 66 * EAP-TTLS/CHAP 67 * EAP-SIM 68 * LEAP (note: only with WEP keys, i.e., not for WPA; in addition, LEAP 69 requires special support from the driver for IEEE 802.11 70 authentication) 71 (following methods are supported, but since they do not generate keying 72 material, they cannot be used with WPA or IEEE 802.1X WEP keying) 73 * EAP-MD5-Challenge 74 * EAP-MSCHAPv2 75 * EAP-GTC 76 * EAP-OTP 77 Alternatively, an external program, e.g., Xsupplicant, can be used for EAP 78 authentication. 79- key management for CCMP, TKIP, WEP104, WEP40 80- RSN/WPA2 (IEEE 802.11i) 81 * pre-authentication 82 * PMKSA caching 83 84 85 86Requirements 87------------ 88 89Current hardware/software requirements: 90- Linux kernel 2.4.x or 2.6.x 91- Linux Wireless Extensions v15 or newer 92- drivers: 93 Host AP driver for Prism2/2.5/3 (development snapshot/v0.2.x) 94 in Managed mode ('iwconfig wlan0 mode managed'). Please note that 95 station firmware version needs to be 1.7.0 or newer to work in 96 WPA mode. 97 98 Linuxant DriverLoader (http://www.linuxant.com/driverloader/) 99 with Windows NDIS driver for your wlan card supporting WPA. 100 101 Agere Systems Inc. Linux Driver 102 (http://www.agere.com/support/drivers/) 103 Please note that the driver interface file (driver_hermes.c) and 104 hardware specific include files are not included in the 105 wpa_supplicant distribution. You will need to copy these from the 106 source package of the Agere driver. 107 108 madwifi driver for cards based on Atheros chip set (ar521x) 109 (http://sourceforge.net/projects/madwifi/) 110 Please note that you will need to modify the wpa_supplicant Makefile 111 to use correct path for madwifi driver root directory 112 (CFLAGS += -I../madwifi/wpa line in Makefile). 113 114 ATMEL AT76C5XXx driver for USB and PCMCIA cards 115 (http://atmelwlandriver.sourceforge.net/). 116 117 Linux ndiswrapper (http://ndiswrapper.sourceforge.net/) with 118 Windows NDIS driver. 119 120 In theory, any driver that supports Linux wireless extensions can be 121 used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in 122 configuration file. 123 124wpa_supplicant was designed to be portable for different drivers and 125operating systems. Hopefully, support for more wlan cards will be 126added in the future. See developer.txt for more information about the 127design of wpa_supplicant and porting to other drivers. One main goal 128is to add full WPA/WPA2 support to Linux wireless extensions to allow 129new drivers to be supported without having to implement new 130driver-specific interface code in wpa_supplicant. 131 132Optional libraries for layer2 packet processing: 133- libpcap (tested with 0.7.2, most relatively recent versions assumed to work, 134 this is likely to be available with most distributions, 135 http://tcpdump.org/) 136- libdnet (tested with v1.4, most versions assumed to work, 137 http://libdnet.sourceforge.net/) 138 139These libraries are _not_ used in the default build. Instead, internal 140Linux specific implementation is used. libpcap/libdnet are more 141portable and they can be used by modifying Makefile (define 142USE_DNET_PCAP and link with these libraries). 143 144 145Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS: 146- openssl (tested with 0.9.7c and 0.9.7d, assumed to work with most 147 relatively recent versions; this is likely to be available with most 148 distributions, http://www.openssl.org/) 149 150This library is only needed when EAP-TLS, EAP-PEAP, or EAP-TTLS 151support is enabled. WPA-PSK mode does not require this or EAPOL/EAP 152implementation. A configuration file, .config, for compilation is 153needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5, 154EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so 155they should only be enabled if testing the EAPOL/EAP state 156machines. However, there can be used as inner authentication 157algorithms with EAP-PEAP and EAP-TTLS. 158 159See Building and installing section below for more detailed 160information about the wpa_supplicant build time configuration. 161 162 163 164WPA 165--- 166 167The original security mechanism of IEEE 802.11 standard was not 168designed to be strong and has proved to be insufficient for most 169networks that require some kind of security. Task group I (Security) 170of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked 171to address the flaws of the base standard and has in practice 172completed its work in May 2004. The IEEE 802.11i amendment to the IEEE 173802.11 standard was approved in June 2004 and this amendment is likely 174to be published in July 2004. 175 176Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the 177IEEE 802.11i work (draft 3.0) to define a subset of the security 178enhancements that can be implemented with existing wlan hardware. This 179is called Wi-Fi Protected Access<TM> (WPA). This has now become a 180mandatory component of interoperability testing and certification done 181by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web 182site (http://www.wi-fi.org/OpenSection/protected_access.asp). 183 184IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm 185for protecting wireless networks. WEP uses RC4 with 40-bit keys, 18624-bit initialization vector (IV), and CRC32 to protect against packet 187forgery. All these choice have proved to be insufficient: key space is 188too small against current attacks, RC4 key scheduling is insufficient 189(beginning of the pseudorandom stream should be skipped), IV space is 190too small and IV reuse makes attacks easier, there is no replay 191protection, and non-keyed authentication does not protect against bit 192flipping packet data. 193 194WPA is an intermediate solution for the security issues. It uses 195temporal key integrity protocol (TKIP) to replace WEP. TKIP is a 196compromise on strong security and possibility to use existing 197hardware. It still uses RC4 for the encryption like WEP, but with 198per-packet RC4 keys. In addition, it implements replay protection, 199keyed packet authentication mechanism (Michael MIC). 200 201Keys can be managed using two different mechanisms. WPA can either use 202an external authentication server (e.g., RADIUS) and EAP just like 203IEEE 802.1X is using or pre-shared keys without need for additional 204servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal", 205respectively. Both mechanisms will generate a master session key for 206the Authenticator (AP) and Supplicant (client station). 207 208WPA implements a new key handshake (4-Way Handshake and Group Key 209Handshake) for generating and exchanging data encryption keys between 210the Authenticator and Supplicant. This handshake is also used to 211verify that both Authenticator and Supplicant know the master session 212key. These handshakes are identical regardless of the selected key 213management mechanism (only the method for generating master session 214key changes). 215 216 217 218IEEE 802.11i / WPA2 219------------------- 220 221The design for parts of IEEE 802.11i that were not included in WPA has 222finished (May 2004) and this amendment to IEEE 802.11 was approved in 223June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new 224version of WPA called WPA2. This includes, e.g., support for more 225robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC) 226to replace TKIP and optimizations for handoff (reduced number of 227messages in initial key handshake, pre-authentication, key caching). 228 229Some wireless LAN vendors are already providing support for CCMP in 230their WPA products. There is no "official" interoperability 231certification for CCMP and/or mixed modes using both TKIP and CCMP, so 232some interoperability issues can be expected even though many 233combinations seem to be working with equipment from different vendors. 234Certification for WPA2 is likely to start during the second half of 2352004. 236 237 238 239wpa_supplicant 240-------------- 241 242wpa_supplicant is an implementation of the WPA Supplicant component, 243i.e., the part that runs in the client stations. It implements WPA key 244negotiation with a WPA Authenticator and EAP authentication with 245Authentication Server. In addition, it controls the roaming and IEEE 246802.11 authentication/association of the wlan driver. 247 248wpa_supplicant is designed to be a "daemon" program that runs in the 249background and acts as the backend component controlling the wireless 250connection. wpa_supplicant supports separate frontend programs and an 251example text-based frontend, wpa_cli, is included with wpa_supplicant. 252 253Following steps are used when associating with an AP using WPA: 254 255- wpa_supplicant requests the kernel driver to scan neighboring BSSes 256- wpa_supplicant selects a BSS based on its configuration 257- wpa_supplicant requests the kernel driver to associate with the chosen 258 BSS 259- If WPA-EAP: integrated IEEE 802.1X Supplicant or external Xsupplicant 260 completes EAP authentication with the authentication server (proxied 261 by the Authenticator in the AP) 262- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant 263- If WPA-PSK: wpa_supplicant uses PSK as the master session key 264- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake 265 with the Authenticator (AP) 266- wpa_supplicant configures encryption keys for unicast and broadcast 267- normal data packets can be transmitted and received 268 269 270 271Building and installing 272----------------------- 273 274In order to be able to build wpa_supplicant, you will first need to 275select which parts of it will be included. This is done by creating a 276build time configuration file, .config, in the wpa_supplicant root 277directory. Configuration options are text lines using following 278format: CONFIG_<option>=y. Lines starting with # are considered 279comments and are ignored. 280 281The build time configuration can be used to select only the needed 282features and limit the binary size and requirements for external 283libraries. The main configuration parts are the selection of which 284driver interfaces (e.g., hostap, madwifi, ..) and which authentication 285methods (e.g., EAP-TLS, EAP-PEAP, ..) are included. 286 287Following build time configuration options are used to control IEEE 288802.1X/EAPOL and EAP state machines and all EAP methods. Including 289TLS, PEAP, or TTLS will require linking wpa_supplicant with openssl 290library for TLS implementation. 291 292CONFIG_IEEE8021X_EAPOL=y 293CONFIG_EAP_MD5=y 294CONFIG_MSCHAPV2=y 295CONFIG_EAP_TLS=y 296CONFIG_EAP_PEAP=y 297CONFIG_EAP_TTLS=y 298CONFIG_EAP_GTC=y 299CONFIG_EAP_OTP=y 300CONFIG_EAP_SIM=y 301CONFIG_EAP_LEAP=y 302 303Following option can be used to include GSM SIM/USIM interface for GSM 304authentication algorithm (for EAP-SIM). This requires pcsc-lite 305(http://www.linuxnet.com/) for smart card access. 306 307CONFIG_PCSC=y 308 309Following options can be added to .config to select which driver 310interfaces are included. Prism54.org driver is not yet complete and 311Hermes driver interface needs to be downloaded from Agere (see above). 312Most Linux driver need to include CONFIG_WIRELESS_EXTENSION. 313 314CONFIG_WIRELESS_EXTENSION=y 315CONFIG_DRIVER_HOSTAP=y 316CONFIG_DRIVER_PRISM54=y 317CONFIG_DRIVER_HERMES=y 318CONFIG_DRIVER_MADWIFI=y 319CONFIG_DRIVER_ATMEL=y 320CONFIG_DRIVER_WEXT=y 321CONFIG_DRIVER_NDISWRAPPER=y 322 323Following example includes all features and driver interfaces that are 324included in the wpa_supplicant package: 325 326CONFIG_DRIVER_HOSTAP=y 327CONFIG_DRIVER_PRISM54=y 328CONFIG_DRIVER_HERMES=y 329CONFIG_DRIVER_MADWIFI=y 330CONFIG_DRIVER_ATMEL=y 331CONFIG_DRIVER_WEXT=y 332CONFIG_DRIVER_NDISWRAPPER=y 333CONFIG_WIRELESS_EXTENSION=y 334CONFIG_IEEE8021X_EAPOL=y 335CONFIG_EAP_MD5=y 336CONFIG_MSCHAPV2=y 337CONFIG_EAP_TLS=y 338CONFIG_EAP_PEAP=y 339CONFIG_EAP_TTLS=y 340CONFIG_EAP_GTC=y 341CONFIG_EAP_OTP=y 342CONFIG_EAP_SIM=y 343CONFIG_EAP_LEAP=y 344CONFIG_PCSC=y 345 346EAP-PEAP and EAP-TTLS will automatically include configured EAP 347methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection. 348 349 350After you have created a configuration file, you can build 351wpa_supplicant and wpa_cli with 'make' command. You may then install 352the binaries to a suitable system directory, e.g., /usr/local/bin. 353 354Example commands: 355 356# build wpa_supplicant and wpa_cli 357make 358# install binaries (this may need root privileges) 359cp wpa_cli wpa_supplicant /usr/local/bin 360 361 362You will need to make a configuration file, e.g., 363/etc/wpa_supplicant.conf, with network configuration for the networks 364you are going to use. Configuration file section below includes 365explanation fo the configuration file format and includes various 366examples. Once the configuration is ready, you can test whether the 367configuration work by first running wpa_supplicant with following 368command to start it on foreground with debugging enabled: 369 370wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d 371 372Assuming everything goes fine, you can start using following command 373to start wpa_supplicant on background without debugging: 374 375wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B 376 377Please note that if you included more than one driver interface in the 378build time configuration (.config), you may need to specify which 379interface to use by including -D<driver name> option on the command 380line. See following section for more details on command line options 381for wpa_supplicant. 382 383 384 385Command line options 386-------------------- 387 388usage: 389 wpa_supplicant [-BddehLqqvw] -i<ifname> -c<config file> [-D<driver>] 390 391options: 392 -B = run daemon in the background 393 -d = increase debugging verbosity (-dd even more) 394 -e = use external IEEE 802.1X Supplicant (e.g., xsupplicant) 395 (this disables the internal Supplicant) 396 -h = show this help text 397 -L = show license (GPL and BSD) 398 -q = decrease debugging verbosity (-qq even less) 399 -v = show version 400 -w = wait for interface to be added, if needed 401 402drivers: 403 hostap = Host AP driver (Intersil Prism2/2.5/3) [default] 404 (this can also be used with Linuxant DriverLoader) 405 prism54 = Prism54.org driver (Intersil Prism GT/Duette/Indigo) 406 not yet fully implemented 407 hermes = Agere Systems Inc. driver (Hermes-I/Hermes-II) 408 madwifi = MADWIFI 802.11 support (Atheros, etc.) 409 atmel = ATMEL AT76C5XXx (USB, PCMCIA) 410 wext = Linux wireless extensions (generic) 411 ndiswrapper = Linux ndiswrapper 412 413In most common cases, wpa_supplicant is started with 414 415wpa_supplicant -Bw -c/etc/wpa_supplicant.conf -iwlan0 416 417This makes the process fork into background and wait for the wlan0 418interface if it is not available at startup time. 419 420 421 422Configuration file 423------------------ 424 425wpa_supplicant is configured using a text file that lists all accepted 426networks and security policies, including pre-shared keys. See 427example configuration file, wpa_supplicant.conf, for detailed 428information about the configuration format and supported fields. 429 430Changes to configuration file can be reloaded be sending SIGHUP signal 431to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarily, 432reloading can be triggered with 'wpa_cli reconfigure' command. 433 434Configuration file can include one or more network blocks, e.g., one 435for each used SSID. wpa_supplicant will automatically select the best 436betwork based on the order of network blocks in the configuration 437file, network security level (WPA/WPA2 is prefered), and signal 438strength. 439 440Example configuration files for some common configurations: 441 4421) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work 443 network 444 445# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group 446ctrl_interface=/var/run/wpa_supplicant 447ctrl_interface_group=wheel 448# 449# home network; allow all valid ciphers 450network={ 451 ssid="home" 452 scan_ssid=1 453 key_mgmt=WPA-PSK 454 psk="very secret passphrase" 455} 456# 457# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers 458network={ 459 ssid="work" 460 scan_ssid=1 461 key_mgmt=WPA-EAP 462 pairwise=CCMP TKIP 463 group=CCMP TKIP 464 eap=TLS 465 identity="user@example.com" 466 ca_cert="/etc/cert/ca.pem" 467 client_cert="/etc/cert/user.pem" 468 private_key="/etc/cert/user.prv" 469 private_key_passwd="password" 470} 471 472 4732) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel 474 (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series) 475 476ctrl_interface=/var/run/wpa_supplicant 477ctrl_interface_group=wheel 478network={ 479 ssid="example" 480 scan_ssid=1 481 key_mgmt=WPA-EAP 482 eap=PEAP 483 identity="user@example.com" 484 password="foobar" 485 ca_cert="/etc/cert/ca.pem" 486 phase1="peaplabel=0" 487 phase2="auth=MSCHAPV2" 488} 489 490 4913) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the 492 unencrypted use. Real identity is sent only within an encrypted TLS tunnel. 493 494ctrl_interface=/var/run/wpa_supplicant 495ctrl_interface_group=wheel 496network={ 497 ssid="example" 498 scan_ssid=1 499 key_mgmt=WPA-EAP 500 eap=TTLS 501 identity="user@example.com" 502 anonymous_identity="anonymous@example.com" 503 password="foobar" 504 ca_cert="/etc/cert/ca.pem" 505 phase2="auth=MD5" 506} 507 508 5094) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and 510 broadcast); use EAP-TLS for authentication 511 512ctrl_interface=/var/run/wpa_supplicant 513ctrl_interface_group=wheel 514network={ 515 ssid="1x-test" 516 scan_ssid=1 517 key_mgmt=IEEE8021X 518 eap=TLS 519 identity="user@example.com" 520 ca_cert="/etc/cert/ca.pem" 521 client_cert="/etc/cert/user.pem" 522 private_key="/etc/cert/user.prv" 523 private_key_passwd="password" 524 eapol_flags=3 525} 526 527 5285) Catch all example that allows more or less all configuration modes. The 529 configuration options are used based on what security policy is used in the 530 selected SSID. This is mostly for testing and is not recommended for normal 531 use. 532 533ctrl_interface=/var/run/wpa_supplicant 534ctrl_interface_group=wheel 535network={ 536 ssid="example" 537 scan_ssid=1 538 key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE 539 pairwise=CCMP TKIP 540 group=CCMP TKIP WEP104 WEP40 541 psk="very secret passphrase" 542 eap=TTLS PEAP TLS 543 identity="user@example.com" 544 password="foobar" 545 ca_cert="/etc/cert/ca.pem" 546 client_cert="/etc/cert/user.pem" 547 private_key="/etc/cert/user.prv" 548 private_key_passwd="password" 549 phase1="peaplabel=0" 550 ca_cert2="/etc/cert/ca2.pem" 551 client_cert2="/etc/cer/user.pem" 552 private_key2="/etc/cer/user.prv" 553 private_key2_passwd="password" 554} 555 556 557 558Certificates 559------------ 560 561Some EAP authentication methods require use of certificates. EAP-TLS 562uses both server side and client certificates whereas EAP-PEAP and 563EAP-TTLS only require the server side certificate. When client 564certificate is used, a matching private key file has to also be 565included in configuration. If the private key uses a passphrase, this 566has to be configured in wpa_supplicant.conf ("private_key_passwd"). 567 568wpa_supplicant supports X.509 certificates in PEM and DER 569formats. User certificate and private key can be included in the same 570file. 571 572If the user certificate and private key is received in PKCS#12/PFX 573format, they need to be converted to suitable PEM/DER format for 574wpa_supplicant. This can be done, e.g., with following commands: 575 576# convert client certificate and private key to PEM format 577openssl pkcs12 -in example.pfx -out user.pem -clcerts 578# convert CA certificate (if included in PFX file) to PEM format 579openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys 580 581 582 583wpa_cli 584------- 585 586wpa_cli is a text-based frontend program for interacting with 587wpa_supplicant. It is used to query current status, change 588configuration, trigger events, and request interactive user input. 589 590wpa_cli can show the current authentication status, selected security 591mode, dot11 and dot1x MIBs, etc. In addition, it can configuring some 592variables like EAPOL state machine parameters and trigger events like 593reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user 594interface to request authentication information, like username and 595password, if these are not included in the configuration. This can be 596used to implement, e.g., one-time-passwords or generic token card 597authentication where the authentication is based on a 598challenge-response that uses an external device for generating the 599response. 600 601The control interface of wpa_supplicant can be configured to allow 602non-root user access (ctrl_interface_group in the configuration 603file). This makes it possible to run wpa_cli with a normal user 604account. 605 606wpa_cli supports two modes: interactive and command line. Both modes 607share the same command set and the main difference is in interactive 608mode providing access to unsolicited messages (event messages, 609username/password requests). 610 611Interactive mode is started when wpa_cli is executed without including 612the command as a command line parameter. Commands are then entered on 613the wpa_cli prompt. In command line mode, the same commands are 614entered as command line arguments for wpa_cli. 615 616 617Interactive authentication parameters request 618 619When wpa_supplicant need authentication parameters, like username and 620password, which are not present in the configuration file, it sends a 621request message to all attached frontend programs, e.g., wpa_cli in 622interactive mode. wpa_cli shows these requests with 623"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or 624OTP (one-time-password). <id> is a unique identifier for the current 625network. <text> is description of the request. In case of OTP request, 626it includes the challenge from the authentication server. 627 628The reply to these requests can be given with 'identity', 'password', 629and 'otp' commands. <id> needs to be copied from the the matching 630request. 'password' and 'otp' commands can be used regardless of 631whether the request was for PASSWORD or OTP. The main difference 632between these two commands is that values given with 'password' are 633remembered as long as wpa_supplicant is running whereas values given 634with 'otp' are used only once and then forgotten, i.e., wpa_supplicant 635will ask frontend for a new value for every use. This can be used to 636implement one-time-password lists and generic token card -based 637authentication. 638 639Example request for password and a matching reply: 640 641CTRL-REQ-PASSWORD-1:Password needed for SSID foobar 642> password 1 mysecretpassword 643 644Example request for generic token card challenge-response: 645 646CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 647> otp 2 9876 648 649 650wpa_cli commands 651 652 status = get current WPA/EAPOL/EAP status 653 mib = get MIB variables (dot1x, dot11) 654 help = show this usage help 655 interface [ifname] = show interfaces/select interface 656 level <debug level> = change debug level 657 license = show full wpa_cli license 658 logoff = IEEE 802.1X EAPOL state machine logoff 659 logon = IEEE 802.1X EAPOL state machine logon 660 set = set variables (shows list of variables when run without arguments) 661 pmksa = show PMKSA cache 662 reassociate = force reassociation 663 reconfigure = force wpa_supplicant to re-read its configuration file 664 preauthenticate <BSSID> = force preauthentication 665 identity <network id> <identity> = configure identity for an SSID 666 password <network id> <password> = configure password for an SSID 667 otp <network id> <password> = configure one-time-password for an SSID 668 quit = exit wpa_cli 669 670 671 672Integrating with pcmcia-cs/cardmgr scripts 673------------------------------------------ 674 675wpa_supplicant needs to be running when using a wireless network with 676WPA. It can be started either from system startup scripts or from 677pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be 678completed before data frames can be exchanged, so wpa_supplicant 679should be started before DHCP client. 680 681Command line option '-w' can be used if wpa_supplicant is started 682before the wireless LAN interface is present (e.g., before inserting 683the PC Card) or is not yet up. 684 685For example, following small changes to pcmcia-cs scripts can be used 686to enable WPA support: 687 688Add MODE="Managed" and WPA="y" to the network scheme in 689/etc/pcmcia/wireless.opts. 690 691Add the following block to the end of 'start' action handler in 692/etc/pcmcia/wireless: 693 694 if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then 695 /usr/local/bin/wpa_supplicant -Bw -c/etc/wpa_supplicant.conf \ 696 -i$DEVICE 697 fi 698 699Add the following block to the end of 'stop' action handler (may need 700to be separated from other actions) in /etc/pcmcia/wireless: 701 702 if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then 703 killall wpa_supplicant 704 fi 705 706This will make cardmgr start wpa_supplicant when the card is plugged 707in. wpa_supplicant will wait until the interface is set up--either 708when a static IP address is configured or when DHCP client is 709started--and will then negotiate keys with the AP. 710 711 712 713Optional integration with Xsupplicant 714------------------------------------- 715 716wpa_supplicant has an integrated IEEE 802.1X Supplicant that supports 717most commonly used EAP methods. In addition, wpa_supplicant has an 718experimental interface for integrating it with Xsupplicant 719(http://www.open1x.org/) for the WPA with EAP authentication. 720 721Xsupplicant needs to be modified to send master session key to 722wpa_supplicant after successful EAP authentication. The included patch 723(xsupplicant.patch) shows the changes needed. This was merged into 724xsupplicant CVS on February 6, 2004, so any snapshot after that should 725have the needed functionality already included. 726 727When using WPA-EAP, both wpa_supplicant and Xsupplicant must be 728configured with the network security policy. See Xsupplicant documents 729for information about its configuration. Please also note, that a new 730command line option -W (enable WPA; added by xsupplicant.patch) must 731be used when starting xsupplicant. 732 733Example configuration for xsupplicant: 734 735network_list = all 736default_netname = jkm 737 738jkm 739{ 740 type = wireless 741 allow_types = eap_peap 742 identity = <BEGIN_ID>jkm<END_ID> 743 eap-peap { 744 random_file = /dev/urandom 745 root_cert = /home/jkm/CA.pem 746 chunk_size = 1398 747 allow_types = eap_mschapv2 748 eap-mschapv2 { 749 username = <BEGIN_UNAME>jkm<END_UNAME> 750 password = <BEGIN_PASS>jkm<END_PASS> 751 } 752 } 753} 754 755 756Example configuration for wpa_supplicant: 757 758network={ 759 ssid="jkm" 760 key_mgmt=WPA-EAP 761} 762 763 764Both wpa_supplicant and xsupplicant need to be started. Please remember 765to add '-W' option for xsupplicant in order to provide keying material 766for wpa_supplicant and '-e' option for wpa_supplicant to disable internal 767IEEE 802.1X implementation. 768 769wpa_supplicant -iwlan0 -cwpa_supplicant.conf -e 770xsupplicant -iwlan0 -cxsupplicant.conf -W 771