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