README revision 1f69aa52ea2e0a73ac502565df8c666ee49cab6a
1WPA Supplicant 2============== 3 4Copyright (c) 2003-2011, Jouni Malinen <j@w1.fi> and contributors 5All Rights Reserved. 6 7This program is dual-licensed under both the GPL version 2 and BSD 8license. Either license may be used at your option. 9 10 11 12License 13------- 14 15GPL v2: 16 17This program is free software; you can redistribute it and/or modify 18it under the terms of the GNU General Public License version 2 as 19published by the Free Software Foundation. 20 21This program is distributed in the hope that it will be useful, 22but WITHOUT ANY WARRANTY; without even the implied warranty of 23MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 24GNU General Public License for more details. 25 26You should have received a copy of the GNU General Public License 27along with this program; if not, write to the Free Software 28Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 29 30(this copy of the license is in COPYING file) 31 32 33Alternatively, this software may be distributed, used, and modified 34under the terms of BSD license: 35 36Redistribution and use in source and binary forms, with or without 37modification, are permitted provided that the following conditions are 38met: 39 401. Redistributions of source code must retain the above copyright 41 notice, this list of conditions and the following disclaimer. 42 432. Redistributions in binary form must reproduce the above copyright 44 notice, this list of conditions and the following disclaimer in the 45 documentation and/or other materials provided with the distribution. 46 473. Neither the name(s) of the above-listed copyright holder(s) nor the 48 names of its contributors may be used to endorse or promote products 49 derived from this software without specific prior written permission. 50 51THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 52"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 53LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 54A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 55OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 56SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 57LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 58DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 59THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 60(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 61OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 62 63 64 65Features 66-------- 67 68Supported WPA/IEEE 802.11i features: 69- WPA-PSK ("WPA-Personal") 70- WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise") 71 Following authentication methods are supported with an integrate IEEE 802.1X 72 Supplicant: 73 * EAP-TLS 74 * EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1) 75 * EAP-PEAP/TLS (both PEAPv0 and PEAPv1) 76 * EAP-PEAP/GTC (both PEAPv0 and PEAPv1) 77 * EAP-PEAP/OTP (both PEAPv0 and PEAPv1) 78 * EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1) 79 * EAP-TTLS/EAP-MD5-Challenge 80 * EAP-TTLS/EAP-GTC 81 * EAP-TTLS/EAP-OTP 82 * EAP-TTLS/EAP-MSCHAPv2 83 * EAP-TTLS/EAP-TLS 84 * EAP-TTLS/MSCHAPv2 85 * EAP-TTLS/MSCHAP 86 * EAP-TTLS/PAP 87 * EAP-TTLS/CHAP 88 * EAP-SIM 89 * EAP-AKA 90 * EAP-PSK 91 * EAP-PAX 92 * EAP-SAKE 93 * EAP-IKEv2 94 * EAP-GPSK 95 * LEAP (note: requires special support from the driver for IEEE 802.11 96 authentication) 97 (following methods are supported, but since they do not generate keying 98 material, they cannot be used with WPA or IEEE 802.1X WEP keying) 99 * EAP-MD5-Challenge 100 * EAP-MSCHAPv2 101 * EAP-GTC 102 * EAP-OTP 103- key management for CCMP, TKIP, WEP104, WEP40 104- RSN/WPA2 (IEEE 802.11i) 105 * pre-authentication 106 * PMKSA caching 107 108Supported TLS/crypto libraries: 109- OpenSSL (default) 110- GnuTLS 111 112Internal TLS/crypto implementation (optional): 113- can be used in place of an external TLS/crypto library 114- TLSv1 115- X.509 certificate processing 116- PKCS #1 117- ASN.1 118- RSA 119- bignum 120- minimal size (ca. 50 kB binary, parts of which are already needed for WPA; 121 TLSv1/X.509/ASN.1/RSA/bignum parts are about 25 kB on x86) 122 123 124Requirements 125------------ 126 127Current hardware/software requirements: 128- Linux kernel 2.4.x or 2.6.x with Linux Wireless Extensions v15 or newer 129- FreeBSD 6-CURRENT 130- NetBSD-current 131- Microsoft Windows with WinPcap (at least WinXP, may work with other versions) 132- drivers: 133 Linux drivers that support WPA/WPA2 configuration with the generic 134 Linux wireless extensions (WE-18 or newer). Even though there are 135 number of driver specific interface included in wpa_supplicant, please 136 note that Linux drivers are moving to use generic wireless extensions 137 and driver_wext (-Dwext on wpa_supplicant command line) should be the 138 default option to start with before falling back to driver specific 139 interface. 140 141 In theory, any driver that supports Linux wireless extensions can be 142 used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in 143 configuration file. 144 145 Wired Ethernet drivers (with ap_scan=0) 146 147 BSD net80211 layer (e.g., Atheros driver) 148 At the moment, this is for FreeBSD 6-CURRENT branch and NetBSD-current. 149 150 Windows NDIS 151 The current Windows port requires WinPcap (http://winpcap.polito.it/). 152 See README-Windows.txt for more information. 153 154wpa_supplicant was designed to be portable for different drivers and 155operating systems. Hopefully, support for more wlan cards and OSes will be 156added in the future. See developer's documentation 157(http://hostap.epitest.fi/wpa_supplicant/devel/) for more information about the 158design of wpa_supplicant and porting to other drivers. One main goal 159is to add full WPA/WPA2 support to Linux wireless extensions to allow 160new drivers to be supported without having to implement new 161driver-specific interface code in wpa_supplicant. 162 163Optional libraries for layer2 packet processing: 164- libpcap (tested with 0.7.2, most relatively recent versions assumed to work, 165 this is likely to be available with most distributions, 166 http://tcpdump.org/) 167- libdnet (tested with v1.4, most versions assumed to work, 168 http://libdnet.sourceforge.net/) 169 170These libraries are _not_ used in the default Linux build. Instead, 171internal Linux specific implementation is used. libpcap/libdnet are 172more portable and they can be used by adding CONFIG_L2_PACKET=pcap into 173.config. They may also be selected automatically for other operating 174systems. In case of Windows builds, WinPcap is used by default 175(CONFIG_L2_PACKET=winpcap). 176 177 178Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS: 179- OpenSSL (tested with 0.9.7c and 0.9.7d, and 0.9.8 versions; assumed to 180 work with most relatively recent versions; this is likely to be 181 available with most distributions, http://www.openssl.org/) 182- GnuTLS 183- internal TLSv1 implementation 184 185TLS options for EAP-FAST: 186- OpenSSL 0.9.8d _with_ openssl-0.9.8d-tls-extensions.patch applied 187 (i.e., the default OpenSSL package does not include support for 188 extensions needed for EAP-FAST) 189- internal TLSv1 implementation 190 191One of these libraries is needed when EAP-TLS, EAP-PEAP, EAP-TTLS, or 192EAP-FAST support is enabled. WPA-PSK mode does not require this or EAPOL/EAP 193implementation. A configuration file, .config, for compilation is 194needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5, 195EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so 196they should only be enabled if testing the EAPOL/EAP state 197machines. However, there can be used as inner authentication 198algorithms with EAP-PEAP and EAP-TTLS. 199 200See Building and installing section below for more detailed 201information about the wpa_supplicant build time configuration. 202 203 204 205WPA 206--- 207 208The original security mechanism of IEEE 802.11 standard was not 209designed to be strong and has proven to be insufficient for most 210networks that require some kind of security. Task group I (Security) 211of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked 212to address the flaws of the base standard and has in practice 213completed its work in May 2004. The IEEE 802.11i amendment to the IEEE 214802.11 standard was approved in June 2004 and published in July 2004. 215 216Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the 217IEEE 802.11i work (draft 3.0) to define a subset of the security 218enhancements that can be implemented with existing wlan hardware. This 219is called Wi-Fi Protected Access<TM> (WPA). This has now become a 220mandatory component of interoperability testing and certification done 221by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web 222site (http://www.wi-fi.org/OpenSection/protected_access.asp). 223 224IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm 225for protecting wireless networks. WEP uses RC4 with 40-bit keys, 22624-bit initialization vector (IV), and CRC32 to protect against packet 227forgery. All these choices have proven to be insufficient: key space is 228too small against current attacks, RC4 key scheduling is insufficient 229(beginning of the pseudorandom stream should be skipped), IV space is 230too small and IV reuse makes attacks easier, there is no replay 231protection, and non-keyed authentication does not protect against bit 232flipping packet data. 233 234WPA is an intermediate solution for the security issues. It uses 235Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a 236compromise on strong security and possibility to use existing 237hardware. It still uses RC4 for the encryption like WEP, but with 238per-packet RC4 keys. In addition, it implements replay protection, 239keyed packet authentication mechanism (Michael MIC). 240 241Keys can be managed using two different mechanisms. WPA can either use 242an external authentication server (e.g., RADIUS) and EAP just like 243IEEE 802.1X is using or pre-shared keys without need for additional 244servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal", 245respectively. Both mechanisms will generate a master session key for 246the Authenticator (AP) and Supplicant (client station). 247 248WPA implements a new key handshake (4-Way Handshake and Group Key 249Handshake) for generating and exchanging data encryption keys between 250the Authenticator and Supplicant. This handshake is also used to 251verify that both Authenticator and Supplicant know the master session 252key. These handshakes are identical regardless of the selected key 253management mechanism (only the method for generating master session 254key changes). 255 256 257 258IEEE 802.11i / WPA2 259------------------- 260 261The design for parts of IEEE 802.11i that were not included in WPA has 262finished (May 2004) and this amendment to IEEE 802.11 was approved in 263June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new 264version of WPA called WPA2. This includes, e.g., support for more 265robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC) 266to replace TKIP and optimizations for handoff (reduced number of 267messages in initial key handshake, pre-authentication, and PMKSA caching). 268 269 270 271wpa_supplicant 272-------------- 273 274wpa_supplicant is an implementation of the WPA Supplicant component, 275i.e., the part that runs in the client stations. It implements WPA key 276negotiation with a WPA Authenticator and EAP authentication with 277Authentication Server. In addition, it controls the roaming and IEEE 278802.11 authentication/association of the wlan driver. 279 280wpa_supplicant is designed to be a "daemon" program that runs in the 281background and acts as the backend component controlling the wireless 282connection. wpa_supplicant supports separate frontend programs and an 283example text-based frontend, wpa_cli, is included with wpa_supplicant. 284 285Following steps are used when associating with an AP using WPA: 286 287- wpa_supplicant requests the kernel driver to scan neighboring BSSes 288- wpa_supplicant selects a BSS based on its configuration 289- wpa_supplicant requests the kernel driver to associate with the chosen 290 BSS 291- If WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP 292 authentication with the authentication server (proxied by the 293 Authenticator in the AP) 294- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant 295- If WPA-PSK: wpa_supplicant uses PSK as the master session key 296- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake 297 with the Authenticator (AP) 298- wpa_supplicant configures encryption keys for unicast and broadcast 299- normal data packets can be transmitted and received 300 301 302 303Building and installing 304----------------------- 305 306In order to be able to build wpa_supplicant, you will first need to 307select which parts of it will be included. This is done by creating a 308build time configuration file, .config, in the wpa_supplicant root 309directory. Configuration options are text lines using following 310format: CONFIG_<option>=y. Lines starting with # are considered 311comments and are ignored. See defconfig file for an example configuration 312and a list of available options and additional notes. 313 314The build time configuration can be used to select only the needed 315features and limit the binary size and requirements for external 316libraries. The main configuration parts are the selection of which 317driver interfaces (e.g., nl80211, wext, ..) and which authentication 318methods (e.g., EAP-TLS, EAP-PEAP, ..) are included. 319 320Following build time configuration options are used to control IEEE 321802.1X/EAPOL and EAP state machines and all EAP methods. Including 322TLS, PEAP, or TTLS will require linking wpa_supplicant with OpenSSL 323library for TLS implementation. Alternatively, GnuTLS or the internal 324TLSv1 implementation can be used for TLS functionaly. 325 326CONFIG_IEEE8021X_EAPOL=y 327CONFIG_EAP_MD5=y 328CONFIG_EAP_MSCHAPV2=y 329CONFIG_EAP_TLS=y 330CONFIG_EAP_PEAP=y 331CONFIG_EAP_TTLS=y 332CONFIG_EAP_GTC=y 333CONFIG_EAP_OTP=y 334CONFIG_EAP_SIM=y 335CONFIG_EAP_AKA=y 336CONFIG_EAP_PSK=y 337CONFIG_EAP_SAKE=y 338CONFIG_EAP_GPSK=y 339CONFIG_EAP_PAX=y 340CONFIG_EAP_LEAP=y 341CONFIG_EAP_IKEV2=y 342 343Following option can be used to include GSM SIM/USIM interface for GSM/UMTS 344authentication algorithm (for EAP-SIM/EAP-AKA). This requires pcsc-lite 345(http://www.linuxnet.com/) for smart card access. 346 347CONFIG_PCSC=y 348 349Following options can be added to .config to select which driver 350interfaces are included. 351 352CONFIG_DRIVER_NL80211=y 353CONFIG_DRIVER_WEXT=y 354CONFIG_DRIVER_BSD=y 355CONFIG_DRIVER_NDIS=y 356 357Following example includes some more features and driver interfaces that 358are included in the wpa_supplicant package: 359 360CONFIG_DRIVER_NL80211=y 361CONFIG_DRIVER_WEXT=y 362CONFIG_DRIVER_BSD=y 363CONFIG_DRIVER_NDIS=y 364CONFIG_IEEE8021X_EAPOL=y 365CONFIG_EAP_MD5=y 366CONFIG_EAP_MSCHAPV2=y 367CONFIG_EAP_TLS=y 368CONFIG_EAP_PEAP=y 369CONFIG_EAP_TTLS=y 370CONFIG_EAP_GTC=y 371CONFIG_EAP_OTP=y 372CONFIG_EAP_SIM=y 373CONFIG_EAP_AKA=y 374CONFIG_EAP_PSK=y 375CONFIG_EAP_SAKE=y 376CONFIG_EAP_GPSK=y 377CONFIG_EAP_PAX=y 378CONFIG_EAP_LEAP=y 379CONFIG_EAP_IKEV2=y 380CONFIG_PCSC=y 381 382EAP-PEAP and EAP-TTLS will automatically include configured EAP 383methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection. 384 385 386After you have created a configuration file, you can build 387wpa_supplicant and wpa_cli with 'make' command. You may then install 388the binaries to a suitable system directory, e.g., /usr/local/bin. 389 390Example commands: 391 392# build wpa_supplicant and wpa_cli 393make 394# install binaries (this may need root privileges) 395cp wpa_cli wpa_supplicant /usr/local/bin 396 397 398You will need to make a configuration file, e.g., 399/etc/wpa_supplicant.conf, with network configuration for the networks 400you are going to use. Configuration file section below includes 401explanation fo the configuration file format and includes various 402examples. Once the configuration is ready, you can test whether the 403configuration work by first running wpa_supplicant with following 404command to start it on foreground with debugging enabled: 405 406wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d 407 408Assuming everything goes fine, you can start using following command 409to start wpa_supplicant on background without debugging: 410 411wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B 412 413Please note that if you included more than one driver interface in the 414build time configuration (.config), you may need to specify which 415interface to use by including -D<driver name> option on the command 416line. See following section for more details on command line options 417for wpa_supplicant. 418 419 420 421Command line options 422-------------------- 423 424usage: 425 wpa_supplicant [-BddfhKLqqtuvwW] [-P<pid file>] [-g<global ctrl>] \ 426 -i<ifname> -c<config file> [-C<ctrl>] [-D<driver>] [-p<driver_param>] \ 427 [-b<br_ifname> [-N -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] \ 428 [-p<driver_param>] [-b<br_ifname>] ...] 429 430options: 431 -b = optional bridge interface name 432 -B = run daemon in the background 433 -c = Configuration file 434 -C = ctrl_interface parameter (only used if -c is not) 435 -i = interface name 436 -d = increase debugging verbosity (-dd even more) 437 -D = driver name (can be multiple drivers: nl80211,wext) 438 -f = Log output to default log location (normally /tmp) 439 -g = global ctrl_interface 440 -K = include keys (passwords, etc.) in debug output 441 -t = include timestamp in debug messages 442 -h = show this help text 443 -L = show license (GPL and BSD) 444 -p = driver parameters 445 -P = PID file 446 -q = decrease debugging verbosity (-qq even less) 447 -u = enable DBus control interface 448 -v = show version 449 -w = wait for interface to be added, if needed 450 -W = wait for a control interface monitor before starting 451 -N = start describing new interface 452 453drivers: 454 wext = Linux wireless extensions (generic) 455 wired = wpa_supplicant wired Ethernet driver 456 roboswitch = wpa_supplicant Broadcom switch driver 457 bsd = BSD 802.11 support (Atheros, etc.) 458 ndis = Windows NDIS driver 459 460In most common cases, wpa_supplicant is started with 461 462wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0 463 464This makes the process fork into background. 465 466The easiest way to debug problems, and to get debug log for bug 467reports, is to start wpa_supplicant on foreground with debugging 468enabled: 469 470wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d 471 472If the specific driver wrapper is not known beforehand, it is possible 473to specify multiple comma separated driver wrappers on the command 474line. wpa_supplicant will use the first driver wrapper that is able to 475initialize the interface. 476 477wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0 478 479 480wpa_supplicant can control multiple interfaces (radios) either by 481running one process for each interface separately or by running just 482one process and list of options at command line. Each interface is 483separated with -N argument. As an example, following command would 484start wpa_supplicant for two interfaces: 485 486wpa_supplicant \ 487 -c wpa1.conf -i wlan0 -D nl80211 -N \ 488 -c wpa2.conf -i wlan1 -D wext 489 490 491If the interface is added in a Linux bridge (e.g., br0), the bridge 492interface needs to be configured to wpa_supplicant in addition to the 493main interface: 494 495wpa_supplicant -cw.conf -Dwext -iwlan0 -bbr0 496 497 498Configuration file 499------------------ 500 501wpa_supplicant is configured using a text file that lists all accepted 502networks and security policies, including pre-shared keys. See 503example configuration file, wpa_supplicant.conf, for detailed 504information about the configuration format and supported fields. 505 506Changes to configuration file can be reloaded be sending SIGHUP signal 507to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly, 508reloading can be triggered with 'wpa_cli reconfigure' command. 509 510Configuration file can include one or more network blocks, e.g., one 511for each used SSID. wpa_supplicant will automatically select the best 512betwork based on the order of network blocks in the configuration 513file, network security level (WPA/WPA2 is preferred), and signal 514strength. 515 516Example configuration files for some common configurations: 517 5181) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work 519 network 520 521# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group 522ctrl_interface=/var/run/wpa_supplicant 523ctrl_interface_group=wheel 524# 525# home network; allow all valid ciphers 526network={ 527 ssid="home" 528 scan_ssid=1 529 key_mgmt=WPA-PSK 530 psk="very secret passphrase" 531} 532# 533# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers 534network={ 535 ssid="work" 536 scan_ssid=1 537 key_mgmt=WPA-EAP 538 pairwise=CCMP TKIP 539 group=CCMP TKIP 540 eap=TLS 541 identity="user@example.com" 542 ca_cert="/etc/cert/ca.pem" 543 client_cert="/etc/cert/user.pem" 544 private_key="/etc/cert/user.prv" 545 private_key_passwd="password" 546} 547 548 5492) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel 550 (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series) 551 552ctrl_interface=/var/run/wpa_supplicant 553ctrl_interface_group=wheel 554network={ 555 ssid="example" 556 scan_ssid=1 557 key_mgmt=WPA-EAP 558 eap=PEAP 559 identity="user@example.com" 560 password="foobar" 561 ca_cert="/etc/cert/ca.pem" 562 phase1="peaplabel=0" 563 phase2="auth=MSCHAPV2" 564} 565 566 5673) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the 568 unencrypted use. Real identity is sent only within an encrypted TLS tunnel. 569 570ctrl_interface=/var/run/wpa_supplicant 571ctrl_interface_group=wheel 572network={ 573 ssid="example" 574 scan_ssid=1 575 key_mgmt=WPA-EAP 576 eap=TTLS 577 identity="user@example.com" 578 anonymous_identity="anonymous@example.com" 579 password="foobar" 580 ca_cert="/etc/cert/ca.pem" 581 phase2="auth=MD5" 582} 583 584 5854) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and 586 broadcast); use EAP-TLS for authentication 587 588ctrl_interface=/var/run/wpa_supplicant 589ctrl_interface_group=wheel 590network={ 591 ssid="1x-test" 592 scan_ssid=1 593 key_mgmt=IEEE8021X 594 eap=TLS 595 identity="user@example.com" 596 ca_cert="/etc/cert/ca.pem" 597 client_cert="/etc/cert/user.pem" 598 private_key="/etc/cert/user.prv" 599 private_key_passwd="password" 600 eapol_flags=3 601} 602 603 6045) Catch all example that allows more or less all configuration modes. The 605 configuration options are used based on what security policy is used in the 606 selected SSID. This is mostly for testing and is not recommended for normal 607 use. 608 609ctrl_interface=/var/run/wpa_supplicant 610ctrl_interface_group=wheel 611network={ 612 ssid="example" 613 scan_ssid=1 614 key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE 615 pairwise=CCMP TKIP 616 group=CCMP TKIP WEP104 WEP40 617 psk="very secret passphrase" 618 eap=TTLS PEAP TLS 619 identity="user@example.com" 620 password="foobar" 621 ca_cert="/etc/cert/ca.pem" 622 client_cert="/etc/cert/user.pem" 623 private_key="/etc/cert/user.prv" 624 private_key_passwd="password" 625 phase1="peaplabel=0" 626 ca_cert2="/etc/cert/ca2.pem" 627 client_cert2="/etc/cer/user.pem" 628 private_key2="/etc/cer/user.prv" 629 private_key2_passwd="password" 630} 631 632 6336) Authentication for wired Ethernet. This can be used with 'wired' or 634 'roboswitch' interface (-Dwired or -Droboswitch on command line). 635 636ctrl_interface=/var/run/wpa_supplicant 637ctrl_interface_group=wheel 638ap_scan=0 639network={ 640 key_mgmt=IEEE8021X 641 eap=MD5 642 identity="user" 643 password="password" 644 eapol_flags=0 645} 646 647 648 649Certificates 650------------ 651 652Some EAP authentication methods require use of certificates. EAP-TLS 653uses both server side and client certificates whereas EAP-PEAP and 654EAP-TTLS only require the server side certificate. When client 655certificate is used, a matching private key file has to also be 656included in configuration. If the private key uses a passphrase, this 657has to be configured in wpa_supplicant.conf ("private_key_passwd"). 658 659wpa_supplicant supports X.509 certificates in PEM and DER 660formats. User certificate and private key can be included in the same 661file. 662 663If the user certificate and private key is received in PKCS#12/PFX 664format, they need to be converted to suitable PEM/DER format for 665wpa_supplicant. This can be done, e.g., with following commands: 666 667# convert client certificate and private key to PEM format 668openssl pkcs12 -in example.pfx -out user.pem -clcerts 669# convert CA certificate (if included in PFX file) to PEM format 670openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys 671 672 673 674wpa_cli 675------- 676 677wpa_cli is a text-based frontend program for interacting with 678wpa_supplicant. It is used to query current status, change 679configuration, trigger events, and request interactive user input. 680 681wpa_cli can show the current authentication status, selected security 682mode, dot11 and dot1x MIBs, etc. In addition, it can configure some 683variables like EAPOL state machine parameters and trigger events like 684reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user 685interface to request authentication information, like username and 686password, if these are not included in the configuration. This can be 687used to implement, e.g., one-time-passwords or generic token card 688authentication where the authentication is based on a 689challenge-response that uses an external device for generating the 690response. 691 692The control interface of wpa_supplicant can be configured to allow 693non-root user access (ctrl_interface_group in the configuration 694file). This makes it possible to run wpa_cli with a normal user 695account. 696 697wpa_cli supports two modes: interactive and command line. Both modes 698share the same command set and the main difference is in interactive 699mode providing access to unsolicited messages (event messages, 700username/password requests). 701 702Interactive mode is started when wpa_cli is executed without including 703the command as a command line parameter. Commands are then entered on 704the wpa_cli prompt. In command line mode, the same commands are 705entered as command line arguments for wpa_cli. 706 707 708Interactive authentication parameters request 709 710When wpa_supplicant need authentication parameters, like username and 711password, which are not present in the configuration file, it sends a 712request message to all attached frontend programs, e.g., wpa_cli in 713interactive mode. wpa_cli shows these requests with 714"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or 715OTP (one-time-password). <id> is a unique identifier for the current 716network. <text> is description of the request. In case of OTP request, 717it includes the challenge from the authentication server. 718 719The reply to these requests can be given with 'identity', 'password', 720and 'otp' commands. <id> needs to be copied from the the matching 721request. 'password' and 'otp' commands can be used regardless of 722whether the request was for PASSWORD or OTP. The main difference 723between these two commands is that values given with 'password' are 724remembered as long as wpa_supplicant is running whereas values given 725with 'otp' are used only once and then forgotten, i.e., wpa_supplicant 726will ask frontend for a new value for every use. This can be used to 727implement one-time-password lists and generic token card -based 728authentication. 729 730Example request for password and a matching reply: 731 732CTRL-REQ-PASSWORD-1:Password needed for SSID foobar 733> password 1 mysecretpassword 734 735Example request for generic token card challenge-response: 736 737CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 738> otp 2 9876 739 740 741wpa_cli commands 742 743 status = get current WPA/EAPOL/EAP status 744 mib = get MIB variables (dot1x, dot11) 745 help = show this usage help 746 interface [ifname] = show interfaces/select interface 747 level <debug level> = change debug level 748 license = show full wpa_cli license 749 logoff = IEEE 802.1X EAPOL state machine logoff 750 logon = IEEE 802.1X EAPOL state machine logon 751 set = set variables (shows list of variables when run without arguments) 752 pmksa = show PMKSA cache 753 reassociate = force reassociation 754 reconfigure = force wpa_supplicant to re-read its configuration file 755 preauthenticate <BSSID> = force preauthentication 756 identity <network id> <identity> = configure identity for an SSID 757 password <network id> <password> = configure password for an SSID 758 pin <network id> <pin> = configure pin for an SSID 759 otp <network id> <password> = configure one-time-password for an SSID 760 passphrase <network id> <passphrase> = configure private key passphrase 761 for an SSID 762 bssid <network id> <BSSID> = set preferred BSSID for an SSID 763 list_networks = list configured networks 764 select_network <network id> = select a network (disable others) 765 enable_network <network id> = enable a network 766 disable_network <network id> = disable a network 767 add_network = add a network 768 remove_network <network id> = remove a network 769 set_network <network id> <variable> <value> = set network variables (shows 770 list of variables when run without arguments) 771 get_network <network id> <variable> = get network variables 772 save_config = save the current configuration 773 disconnect = disconnect and wait for reassociate command before connecting 774 scan = request new BSS scan 775 scan_results = get latest scan results 776 get_capability <eap/pairwise/group/key_mgmt/proto/auth_alg> = get capabilies 777 terminate = terminate wpa_supplicant 778 quit = exit wpa_cli 779 780 781wpa_cli command line options 782 783wpa_cli [-p<path to ctrl sockets>] [-i<ifname>] [-hvB] [-a<action file>] \ 784 [-P<pid file>] [-g<global ctrl>] [command..] 785 -h = help (show this usage text) 786 -v = shown version information 787 -a = run in daemon mode executing the action file based on events from 788 wpa_supplicant 789 -B = run a daemon in the background 790 default path: /var/run/wpa_supplicant 791 default interface: first interface found in socket path 792 793 794Using wpa_cli to run external program on connect/disconnect 795----------------------------------------------------------- 796 797wpa_cli can used to run external programs whenever wpa_supplicant 798connects or disconnects from a network. This can be used, e.g., to 799update network configuration and/or trigget DHCP client to update IP 800addresses, etc. 801 802One wpa_cli process in "action" mode needs to be started for each 803interface. For example, the following command starts wpa_cli for the 804default ingterface (-i can be used to select the interface in case of 805more than one interface being used at the same time): 806 807wpa_cli -a/sbin/wpa_action.sh -B 808 809The action file (-a option, /sbin/wpa_action.sh in this example) will 810be executed whenever wpa_supplicant completes authentication (connect 811event) or detects disconnection). The action script will be called 812with two command line arguments: interface name and event (CONNECTED 813or DISCONNECTED). If the action script needs to get more information 814about the current network, it can use 'wpa_cli status' to query 815wpa_supplicant for more information. 816 817Following example can be used as a simple template for an action 818script: 819 820#!/bin/sh 821 822IFNAME=$1 823CMD=$2 824 825if [ "$CMD" = "CONNECTED" ]; then 826 SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=` 827 # configure network, signal DHCP client, etc. 828fi 829 830if [ "$CMD" = "DISCONNECTED" ]; then 831 # remove network configuration, if needed 832 SSID= 833fi 834 835 836 837Integrating with pcmcia-cs/cardmgr scripts 838------------------------------------------ 839 840wpa_supplicant needs to be running when using a wireless network with 841WPA. It can be started either from system startup scripts or from 842pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be 843completed before data frames can be exchanged, so wpa_supplicant 844should be started before DHCP client. 845 846For example, following small changes to pcmcia-cs scripts can be used 847to enable WPA support: 848 849Add MODE="Managed" and WPA="y" to the network scheme in 850/etc/pcmcia/wireless.opts. 851 852Add the following block to the end of 'start' action handler in 853/etc/pcmcia/wireless: 854 855 if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then 856 /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf \ 857 -i$DEVICE 858 fi 859 860Add the following block to the end of 'stop' action handler (may need 861to be separated from other actions) in /etc/pcmcia/wireless: 862 863 if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then 864 killall wpa_supplicant 865 fi 866 867This will make cardmgr start wpa_supplicant when the card is plugged 868in. 869 870 871 872Dynamic interface add and operation without configuration files 873--------------------------------------------------------------- 874 875wpa_supplicant can be started without any configuration files or 876network interfaces. When used in this way, a global (i.e., per 877wpa_supplicant process) control interface is used to add and remove 878network interfaces. Each network interface can then be configured 879through a per-network interface control interface. For example, 880following commands show how to start wpa_supplicant without any 881network interfaces and then add a network interface and configure a 882network (SSID): 883 884# Start wpa_supplicant in the background 885wpa_supplicant -g/var/run/wpa_supplicant-global -B 886 887# Add a new interface (wlan0, no configuration file, driver=wext, and 888# enable control interface) 889wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \ 890 "" wext /var/run/wpa_supplicant 891 892# Configure a network using the newly added network interface: 893wpa_cli -iwlan0 add_network 894wpa_cli -iwlan0 set_network 0 ssid '"test"' 895wpa_cli -iwlan0 set_network 0 key_mgmt WPA-PSK 896wpa_cli -iwlan0 set_network 0 psk '"12345678"' 897wpa_cli -iwlan0 set_network 0 pairwise TKIP 898wpa_cli -iwlan0 set_network 0 group TKIP 899wpa_cli -iwlan0 set_network 0 proto WPA 900wpa_cli -iwlan0 enable_network 0 901 902# At this point, the new network interface should start trying to associate 903# with the WPA-PSK network using SSID test. 904 905# Remove network interface 906wpa_cli -g/var/run/wpa_supplicant-global interface_remove wlan0 907 908 909Privilege separation 910-------------------- 911 912To minimize the size of code that needs to be run with root privileges 913(e.g., to control wireless interface operation), wpa_supplicant 914supports optional privilege separation. If enabled, this separates the 915privileged operations into a separate process (wpa_priv) while leaving 916rest of the code (e.g., EAP authentication and WPA handshakes) into an 917unprivileged process (wpa_supplicant) that can be run as non-root 918user. Privilege separation restricts the effects of potential software 919errors by containing the majority of the code in an unprivileged 920process to avoid full system compromise. 921 922Privilege separation is not enabled by default and it can be enabled 923by adding CONFIG_PRIVSEP=y to the build configuration (.config). When 924enabled, the privileged operations (driver wrapper and l2_packet) are 925linked into a separate daemon program, wpa_priv. The unprivileged 926program, wpa_supplicant, will be built with a special driver/l2_packet 927wrappers that communicate with the privileged wpa_priv process to 928perform the needed operations. wpa_priv can control what privileged 929are allowed. 930 931wpa_priv needs to be run with network admin privileges (usually, root 932user). It opens a UNIX domain socket for each interface that is 933included on the command line; any other interface will be off limits 934for wpa_supplicant in this kind of configuration. After this, 935wpa_supplicant can be run as a non-root user (e.g., all standard users 936on a laptop or as a special non-privileged user account created just 937for this purpose to limit access to user files even further). 938 939 940Example configuration: 941- create user group for users that are allowed to use wpa_supplicant 942 ('wpapriv' in this example) and assign users that should be able to 943 use wpa_supplicant into that group 944- create /var/run/wpa_priv directory for UNIX domain sockets and control 945 user access by setting it accessible only for the wpapriv group: 946 mkdir /var/run/wpa_priv 947 chown root:wpapriv /var/run/wpa_priv 948 chmod 0750 /var/run/wpa_priv 949- start wpa_priv as root (e.g., from system startup scripts) with the 950 enabled interfaces configured on the command line: 951 wpa_priv -B -P /var/run/wpa_priv.pid wext:ath0 952- run wpa_supplicant as non-root with a user that is in wpapriv group: 953 wpa_supplicant -i ath0 -c wpa_supplicant.conf 954 955wpa_priv does not use the network interface before wpa_supplicant is 956started, so it is fine to include network interfaces that are not 957available at the time wpa_priv is started. As an alternative, wpa_priv 958can be started when an interface is added (hotplug/udev/etc. scripts). 959wpa_priv can control multiple interface with one process, but it is 960also possible to run multiple wpa_priv processes at the same time, if 961desired. 962