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