1*a1157835SDaniel Fojtwpa_supplicant 26d49e1aeSJan Lentfer============== 36d49e1aeSJan Lentfer 4*a1157835SDaniel FojtCopyright (c) 2003-2019, Jouni Malinen <j@w1.fi> and contributors 56d49e1aeSJan LentferAll Rights Reserved. 66d49e1aeSJan Lentfer 73ff40c12SJohn MarinoThis program is licensed under the BSD license (the one with 83ff40c12SJohn Marinoadvertisement clause removed). 93ff40c12SJohn Marino 103ff40c12SJohn MarinoIf you are submitting changes to the project, please see CONTRIBUTIONS 113ff40c12SJohn Marinofile for more instructions. 126d49e1aeSJan Lentfer 136d49e1aeSJan Lentfer 146d49e1aeSJan Lentfer 156d49e1aeSJan LentferLicense 166d49e1aeSJan Lentfer------- 176d49e1aeSJan Lentfer 183ff40c12SJohn MarinoThis software may be distributed, used, and modified under the terms of 193ff40c12SJohn MarinoBSD license: 206d49e1aeSJan Lentfer 216d49e1aeSJan LentferRedistribution and use in source and binary forms, with or without 226d49e1aeSJan Lentfermodification, are permitted provided that the following conditions are 236d49e1aeSJan Lentfermet: 246d49e1aeSJan Lentfer 256d49e1aeSJan Lentfer1. Redistributions of source code must retain the above copyright 266d49e1aeSJan Lentfer notice, this list of conditions and the following disclaimer. 276d49e1aeSJan Lentfer 286d49e1aeSJan Lentfer2. Redistributions in binary form must reproduce the above copyright 296d49e1aeSJan Lentfer notice, this list of conditions and the following disclaimer in the 306d49e1aeSJan Lentfer documentation and/or other materials provided with the distribution. 316d49e1aeSJan Lentfer 326d49e1aeSJan Lentfer3. Neither the name(s) of the above-listed copyright holder(s) nor the 336d49e1aeSJan Lentfer names of its contributors may be used to endorse or promote products 346d49e1aeSJan Lentfer derived from this software without specific prior written permission. 356d49e1aeSJan Lentfer 366d49e1aeSJan LentferTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 376d49e1aeSJan Lentfer"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 386d49e1aeSJan LentferLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 396d49e1aeSJan LentferA PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 406d49e1aeSJan LentferOWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 416d49e1aeSJan LentferSPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 426d49e1aeSJan LentferLIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 436d49e1aeSJan LentferDATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 446d49e1aeSJan LentferTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 456d49e1aeSJan Lentfer(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 466d49e1aeSJan LentferOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 476d49e1aeSJan Lentfer 486d49e1aeSJan Lentfer 496d49e1aeSJan Lentfer 506d49e1aeSJan LentferFeatures 516d49e1aeSJan Lentfer-------- 526d49e1aeSJan Lentfer 536d49e1aeSJan LentferSupported WPA/IEEE 802.11i features: 546d49e1aeSJan Lentfer- WPA-PSK ("WPA-Personal") 556d49e1aeSJan Lentfer- WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise") 566d49e1aeSJan Lentfer Following authentication methods are supported with an integrate IEEE 802.1X 576d49e1aeSJan Lentfer Supplicant: 586d49e1aeSJan Lentfer * EAP-TLS 596d49e1aeSJan Lentfer * EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1) 606d49e1aeSJan Lentfer * EAP-PEAP/TLS (both PEAPv0 and PEAPv1) 616d49e1aeSJan Lentfer * EAP-PEAP/GTC (both PEAPv0 and PEAPv1) 626d49e1aeSJan Lentfer * EAP-PEAP/OTP (both PEAPv0 and PEAPv1) 636d49e1aeSJan Lentfer * EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1) 646d49e1aeSJan Lentfer * EAP-TTLS/EAP-MD5-Challenge 656d49e1aeSJan Lentfer * EAP-TTLS/EAP-GTC 666d49e1aeSJan Lentfer * EAP-TTLS/EAP-OTP 676d49e1aeSJan Lentfer * EAP-TTLS/EAP-MSCHAPv2 686d49e1aeSJan Lentfer * EAP-TTLS/EAP-TLS 696d49e1aeSJan Lentfer * EAP-TTLS/MSCHAPv2 706d49e1aeSJan Lentfer * EAP-TTLS/MSCHAP 716d49e1aeSJan Lentfer * EAP-TTLS/PAP 726d49e1aeSJan Lentfer * EAP-TTLS/CHAP 736d49e1aeSJan Lentfer * EAP-SIM 746d49e1aeSJan Lentfer * EAP-AKA 75*a1157835SDaniel Fojt * EAP-AKA' 766d49e1aeSJan Lentfer * EAP-PSK 776d49e1aeSJan Lentfer * EAP-PAX 786d49e1aeSJan Lentfer * EAP-SAKE 796d49e1aeSJan Lentfer * EAP-IKEv2 806d49e1aeSJan Lentfer * EAP-GPSK 81*a1157835SDaniel Fojt * EAP-pwd 826d49e1aeSJan Lentfer * LEAP (note: requires special support from the driver for IEEE 802.11 836d49e1aeSJan Lentfer authentication) 846d49e1aeSJan Lentfer (following methods are supported, but since they do not generate keying 856d49e1aeSJan Lentfer material, they cannot be used with WPA or IEEE 802.1X WEP keying) 866d49e1aeSJan Lentfer * EAP-MD5-Challenge 876d49e1aeSJan Lentfer * EAP-MSCHAPv2 886d49e1aeSJan Lentfer * EAP-GTC 896d49e1aeSJan Lentfer * EAP-OTP 906d49e1aeSJan Lentfer- key management for CCMP, TKIP, WEP104, WEP40 916d49e1aeSJan Lentfer- RSN/WPA2 (IEEE 802.11i) 926d49e1aeSJan Lentfer * pre-authentication 936d49e1aeSJan Lentfer * PMKSA caching 946d49e1aeSJan Lentfer 956d49e1aeSJan LentferSupported TLS/crypto libraries: 966d49e1aeSJan Lentfer- OpenSSL (default) 976d49e1aeSJan Lentfer- GnuTLS 986d49e1aeSJan Lentfer 996d49e1aeSJan LentferInternal TLS/crypto implementation (optional): 1006d49e1aeSJan Lentfer- can be used in place of an external TLS/crypto library 1016d49e1aeSJan Lentfer- TLSv1 1026d49e1aeSJan Lentfer- X.509 certificate processing 1036d49e1aeSJan Lentfer- PKCS #1 1046d49e1aeSJan Lentfer- ASN.1 1056d49e1aeSJan Lentfer- RSA 1066d49e1aeSJan Lentfer- bignum 1076d49e1aeSJan Lentfer- minimal size (ca. 50 kB binary, parts of which are already needed for WPA; 1086d49e1aeSJan Lentfer TLSv1/X.509/ASN.1/RSA/bignum parts are about 25 kB on x86) 1096d49e1aeSJan Lentfer 1106d49e1aeSJan Lentfer 1116d49e1aeSJan LentferRequirements 1126d49e1aeSJan Lentfer------------ 1136d49e1aeSJan Lentfer 1146d49e1aeSJan LentferCurrent hardware/software requirements: 1156d49e1aeSJan Lentfer- Linux kernel 2.4.x or 2.6.x with Linux Wireless Extensions v15 or newer 1166d49e1aeSJan Lentfer- FreeBSD 6-CURRENT 1176d49e1aeSJan Lentfer- NetBSD-current 1186d49e1aeSJan Lentfer- Microsoft Windows with WinPcap (at least WinXP, may work with other versions) 1196d49e1aeSJan Lentfer- drivers: 1203ff40c12SJohn Marino Linux drivers that support cfg80211/nl80211. Even though there are 1216d49e1aeSJan Lentfer number of driver specific interface included in wpa_supplicant, please 1223ff40c12SJohn Marino note that Linux drivers are moving to use generic wireless configuration 1233ff40c12SJohn Marino interface driver_nl80211 (-Dnl80211 on wpa_supplicant command line) 1243ff40c12SJohn Marino should be the default option to start with before falling back to driver 1253ff40c12SJohn Marino specific interface. 1266d49e1aeSJan Lentfer 1273ff40c12SJohn Marino Linux drivers that support WPA/WPA2 configuration with the generic 1283ff40c12SJohn Marino Linux wireless extensions (WE-18 or newer). Obsoleted by nl80211. 1296d49e1aeSJan Lentfer 1306d49e1aeSJan Lentfer In theory, any driver that supports Linux wireless extensions can be 1316d49e1aeSJan Lentfer used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in 1326d49e1aeSJan Lentfer configuration file. 1336d49e1aeSJan Lentfer 1346d49e1aeSJan Lentfer Wired Ethernet drivers (with ap_scan=0) 1356d49e1aeSJan Lentfer 1366d49e1aeSJan Lentfer BSD net80211 layer (e.g., Atheros driver) 1376d49e1aeSJan Lentfer At the moment, this is for FreeBSD 6-CURRENT branch and NetBSD-current. 1386d49e1aeSJan Lentfer 1396d49e1aeSJan Lentfer Windows NDIS 1406d49e1aeSJan Lentfer The current Windows port requires WinPcap (http://winpcap.polito.it/). 1416d49e1aeSJan Lentfer See README-Windows.txt for more information. 1426d49e1aeSJan Lentfer 1436d49e1aeSJan Lentferwpa_supplicant was designed to be portable for different drivers and 1446d49e1aeSJan Lentferoperating systems. Hopefully, support for more wlan cards and OSes will be 1456d49e1aeSJan Lentferadded in the future. See developer's documentation 1466d49e1aeSJan Lentfer(http://hostap.epitest.fi/wpa_supplicant/devel/) for more information about the 1476d49e1aeSJan Lentferdesign of wpa_supplicant and porting to other drivers. One main goal 1486d49e1aeSJan Lentferis to add full WPA/WPA2 support to Linux wireless extensions to allow 1496d49e1aeSJan Lentfernew drivers to be supported without having to implement new 1506d49e1aeSJan Lentferdriver-specific interface code in wpa_supplicant. 1516d49e1aeSJan Lentfer 1526d49e1aeSJan LentferOptional libraries for layer2 packet processing: 1536d49e1aeSJan Lentfer- libpcap (tested with 0.7.2, most relatively recent versions assumed to work, 1546d49e1aeSJan Lentfer this is likely to be available with most distributions, 1556d49e1aeSJan Lentfer http://tcpdump.org/) 1566d49e1aeSJan Lentfer- libdnet (tested with v1.4, most versions assumed to work, 1576d49e1aeSJan Lentfer http://libdnet.sourceforge.net/) 1586d49e1aeSJan Lentfer 1596d49e1aeSJan LentferThese libraries are _not_ used in the default Linux build. Instead, 1606d49e1aeSJan Lentferinternal Linux specific implementation is used. libpcap/libdnet are 1616d49e1aeSJan Lentfermore portable and they can be used by adding CONFIG_L2_PACKET=pcap into 1626d49e1aeSJan Lentfer.config. They may also be selected automatically for other operating 1636d49e1aeSJan Lentfersystems. In case of Windows builds, WinPcap is used by default 1646d49e1aeSJan Lentfer(CONFIG_L2_PACKET=winpcap). 1656d49e1aeSJan Lentfer 1666d49e1aeSJan Lentfer 1676d49e1aeSJan LentferOptional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS: 168*a1157835SDaniel Fojt- OpenSSL (tested with 1.0.1 and 1.0.2 versions; assumed to 1696d49e1aeSJan Lentfer work with most relatively recent versions; this is likely to be 1706d49e1aeSJan Lentfer available with most distributions, http://www.openssl.org/) 1716d49e1aeSJan Lentfer- GnuTLS 1726d49e1aeSJan Lentfer- internal TLSv1 implementation 1736d49e1aeSJan Lentfer 1746d49e1aeSJan LentferOne of these libraries is needed when EAP-TLS, EAP-PEAP, EAP-TTLS, or 1756d49e1aeSJan LentferEAP-FAST support is enabled. WPA-PSK mode does not require this or EAPOL/EAP 1766d49e1aeSJan Lentferimplementation. A configuration file, .config, for compilation is 1776d49e1aeSJan Lentferneeded to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5, 1786d49e1aeSJan LentferEAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so 1796d49e1aeSJan Lentferthey should only be enabled if testing the EAPOL/EAP state 1806d49e1aeSJan Lentfermachines. However, there can be used as inner authentication 1816d49e1aeSJan Lentferalgorithms with EAP-PEAP and EAP-TTLS. 1826d49e1aeSJan Lentfer 1836d49e1aeSJan LentferSee Building and installing section below for more detailed 1846d49e1aeSJan Lentferinformation about the wpa_supplicant build time configuration. 1856d49e1aeSJan Lentfer 1866d49e1aeSJan Lentfer 1876d49e1aeSJan Lentfer 1886d49e1aeSJan LentferWPA 1896d49e1aeSJan Lentfer--- 1906d49e1aeSJan Lentfer 1916d49e1aeSJan LentferThe original security mechanism of IEEE 802.11 standard was not 1926d49e1aeSJan Lentferdesigned to be strong and has proven to be insufficient for most 1936d49e1aeSJan Lentfernetworks that require some kind of security. Task group I (Security) 1946d49e1aeSJan Lentferof IEEE 802.11 working group (http://www.ieee802.org/11/) has worked 1956d49e1aeSJan Lentferto address the flaws of the base standard and has in practice 1966d49e1aeSJan Lentfercompleted its work in May 2004. The IEEE 802.11i amendment to the IEEE 1976d49e1aeSJan Lentfer802.11 standard was approved in June 2004 and published in July 2004. 1986d49e1aeSJan Lentfer 1996d49e1aeSJan LentferWi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the 2006d49e1aeSJan LentferIEEE 802.11i work (draft 3.0) to define a subset of the security 2016d49e1aeSJan Lentferenhancements that can be implemented with existing wlan hardware. This 2026d49e1aeSJan Lentferis called Wi-Fi Protected Access<TM> (WPA). This has now become a 2036d49e1aeSJan Lentfermandatory component of interoperability testing and certification done 2046d49e1aeSJan Lentferby Wi-Fi Alliance. Wi-Fi provides information about WPA at its web 2056d49e1aeSJan Lentfersite (http://www.wi-fi.org/OpenSection/protected_access.asp). 2066d49e1aeSJan Lentfer 2076d49e1aeSJan LentferIEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm 2086d49e1aeSJan Lentferfor protecting wireless networks. WEP uses RC4 with 40-bit keys, 2096d49e1aeSJan Lentfer24-bit initialization vector (IV), and CRC32 to protect against packet 2106d49e1aeSJan Lentferforgery. All these choices have proven to be insufficient: key space is 2116d49e1aeSJan Lentfertoo small against current attacks, RC4 key scheduling is insufficient 2126d49e1aeSJan Lentfer(beginning of the pseudorandom stream should be skipped), IV space is 2136d49e1aeSJan Lentfertoo small and IV reuse makes attacks easier, there is no replay 2146d49e1aeSJan Lentferprotection, and non-keyed authentication does not protect against bit 2156d49e1aeSJan Lentferflipping packet data. 2166d49e1aeSJan Lentfer 2176d49e1aeSJan LentferWPA is an intermediate solution for the security issues. It uses 2186d49e1aeSJan LentferTemporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a 2196d49e1aeSJan Lentfercompromise on strong security and possibility to use existing 2206d49e1aeSJan Lentferhardware. It still uses RC4 for the encryption like WEP, but with 2216d49e1aeSJan Lentferper-packet RC4 keys. In addition, it implements replay protection, 2226d49e1aeSJan Lentferkeyed packet authentication mechanism (Michael MIC). 2236d49e1aeSJan Lentfer 2246d49e1aeSJan LentferKeys can be managed using two different mechanisms. WPA can either use 2256d49e1aeSJan Lentferan external authentication server (e.g., RADIUS) and EAP just like 2266d49e1aeSJan LentferIEEE 802.1X is using or pre-shared keys without need for additional 2276d49e1aeSJan Lentferservers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal", 2286d49e1aeSJan Lentferrespectively. Both mechanisms will generate a master session key for 2296d49e1aeSJan Lentferthe Authenticator (AP) and Supplicant (client station). 2306d49e1aeSJan Lentfer 2316d49e1aeSJan LentferWPA implements a new key handshake (4-Way Handshake and Group Key 2326d49e1aeSJan LentferHandshake) for generating and exchanging data encryption keys between 2336d49e1aeSJan Lentferthe Authenticator and Supplicant. This handshake is also used to 2346d49e1aeSJan Lentferverify that both Authenticator and Supplicant know the master session 2356d49e1aeSJan Lentferkey. These handshakes are identical regardless of the selected key 2366d49e1aeSJan Lentfermanagement mechanism (only the method for generating master session 2376d49e1aeSJan Lentferkey changes). 2386d49e1aeSJan Lentfer 2396d49e1aeSJan Lentfer 2406d49e1aeSJan Lentfer 2416d49e1aeSJan LentferIEEE 802.11i / WPA2 2426d49e1aeSJan Lentfer------------------- 2436d49e1aeSJan Lentfer 2446d49e1aeSJan LentferThe design for parts of IEEE 802.11i that were not included in WPA has 2456d49e1aeSJan Lentferfinished (May 2004) and this amendment to IEEE 802.11 was approved in 2466d49e1aeSJan LentferJune 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new 2476d49e1aeSJan Lentferversion of WPA called WPA2. This includes, e.g., support for more 2486d49e1aeSJan Lentferrobust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC) 2496d49e1aeSJan Lentferto replace TKIP and optimizations for handoff (reduced number of 2506d49e1aeSJan Lentfermessages in initial key handshake, pre-authentication, and PMKSA caching). 2516d49e1aeSJan Lentfer 2526d49e1aeSJan Lentfer 2536d49e1aeSJan Lentfer 2546d49e1aeSJan Lentferwpa_supplicant 2556d49e1aeSJan Lentfer-------------- 2566d49e1aeSJan Lentfer 2576d49e1aeSJan Lentferwpa_supplicant is an implementation of the WPA Supplicant component, 2586d49e1aeSJan Lentferi.e., the part that runs in the client stations. It implements WPA key 2596d49e1aeSJan Lentfernegotiation with a WPA Authenticator and EAP authentication with 2606d49e1aeSJan LentferAuthentication Server. In addition, it controls the roaming and IEEE 2616d49e1aeSJan Lentfer802.11 authentication/association of the wlan driver. 2626d49e1aeSJan Lentfer 2636d49e1aeSJan Lentferwpa_supplicant is designed to be a "daemon" program that runs in the 2646d49e1aeSJan Lentferbackground and acts as the backend component controlling the wireless 2656d49e1aeSJan Lentferconnection. wpa_supplicant supports separate frontend programs and an 2666d49e1aeSJan Lentferexample text-based frontend, wpa_cli, is included with wpa_supplicant. 2676d49e1aeSJan Lentfer 2686d49e1aeSJan LentferFollowing steps are used when associating with an AP using WPA: 2696d49e1aeSJan Lentfer 2706d49e1aeSJan Lentfer- wpa_supplicant requests the kernel driver to scan neighboring BSSes 2716d49e1aeSJan Lentfer- wpa_supplicant selects a BSS based on its configuration 2726d49e1aeSJan Lentfer- wpa_supplicant requests the kernel driver to associate with the chosen 2736d49e1aeSJan Lentfer BSS 2746d49e1aeSJan Lentfer- If WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP 2756d49e1aeSJan Lentfer authentication with the authentication server (proxied by the 2766d49e1aeSJan Lentfer Authenticator in the AP) 2776d49e1aeSJan Lentfer- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant 2786d49e1aeSJan Lentfer- If WPA-PSK: wpa_supplicant uses PSK as the master session key 2796d49e1aeSJan Lentfer- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake 2806d49e1aeSJan Lentfer with the Authenticator (AP) 2816d49e1aeSJan Lentfer- wpa_supplicant configures encryption keys for unicast and broadcast 2826d49e1aeSJan Lentfer- normal data packets can be transmitted and received 2836d49e1aeSJan Lentfer 2846d49e1aeSJan Lentfer 2856d49e1aeSJan Lentfer 2866d49e1aeSJan LentferBuilding and installing 2876d49e1aeSJan Lentfer----------------------- 2886d49e1aeSJan Lentfer 2896d49e1aeSJan LentferIn order to be able to build wpa_supplicant, you will first need to 2906d49e1aeSJan Lentferselect which parts of it will be included. This is done by creating a 2916d49e1aeSJan Lentferbuild time configuration file, .config, in the wpa_supplicant root 2926d49e1aeSJan Lentferdirectory. Configuration options are text lines using following 2936d49e1aeSJan Lentferformat: CONFIG_<option>=y. Lines starting with # are considered 2946d49e1aeSJan Lentfercomments and are ignored. See defconfig file for an example configuration 2956d49e1aeSJan Lentferand a list of available options and additional notes. 2966d49e1aeSJan Lentfer 2976d49e1aeSJan LentferThe build time configuration can be used to select only the needed 2986d49e1aeSJan Lentferfeatures and limit the binary size and requirements for external 2996d49e1aeSJan Lentferlibraries. The main configuration parts are the selection of which 3003ff40c12SJohn Marinodriver interfaces (e.g., nl80211, wext, ..) and which authentication 3016d49e1aeSJan Lentfermethods (e.g., EAP-TLS, EAP-PEAP, ..) are included. 3026d49e1aeSJan Lentfer 3036d49e1aeSJan LentferFollowing build time configuration options are used to control IEEE 3046d49e1aeSJan Lentfer802.1X/EAPOL and EAP state machines and all EAP methods. Including 3056d49e1aeSJan LentferTLS, PEAP, or TTLS will require linking wpa_supplicant with OpenSSL 3066d49e1aeSJan Lentferlibrary for TLS implementation. Alternatively, GnuTLS or the internal 307*a1157835SDaniel FojtTLSv1 implementation can be used for TLS functionality. 3086d49e1aeSJan Lentfer 3096d49e1aeSJan LentferCONFIG_IEEE8021X_EAPOL=y 3106d49e1aeSJan LentferCONFIG_EAP_MD5=y 3116d49e1aeSJan LentferCONFIG_EAP_MSCHAPV2=y 3126d49e1aeSJan LentferCONFIG_EAP_TLS=y 3136d49e1aeSJan LentferCONFIG_EAP_PEAP=y 3146d49e1aeSJan LentferCONFIG_EAP_TTLS=y 3156d49e1aeSJan LentferCONFIG_EAP_GTC=y 3166d49e1aeSJan LentferCONFIG_EAP_OTP=y 3176d49e1aeSJan LentferCONFIG_EAP_SIM=y 3186d49e1aeSJan LentferCONFIG_EAP_AKA=y 319*a1157835SDaniel FojtCONFIG_EAP_AKA_PRIME=y 3206d49e1aeSJan LentferCONFIG_EAP_PSK=y 3216d49e1aeSJan LentferCONFIG_EAP_SAKE=y 3226d49e1aeSJan LentferCONFIG_EAP_GPSK=y 3236d49e1aeSJan LentferCONFIG_EAP_PAX=y 3246d49e1aeSJan LentferCONFIG_EAP_LEAP=y 3256d49e1aeSJan LentferCONFIG_EAP_IKEV2=y 326*a1157835SDaniel FojtCONFIG_EAP_PWD=y 3276d49e1aeSJan Lentfer 3286d49e1aeSJan LentferFollowing option can be used to include GSM SIM/USIM interface for GSM/UMTS 329*a1157835SDaniel Fojtauthentication algorithm (for EAP-SIM/EAP-AKA/EAP-AKA'). This requires pcsc-lite 3306d49e1aeSJan Lentfer(http://www.linuxnet.com/) for smart card access. 3316d49e1aeSJan Lentfer 3326d49e1aeSJan LentferCONFIG_PCSC=y 3336d49e1aeSJan Lentfer 3346d49e1aeSJan LentferFollowing options can be added to .config to select which driver 3353ff40c12SJohn Marinointerfaces are included. 3366d49e1aeSJan Lentfer 3373ff40c12SJohn MarinoCONFIG_DRIVER_NL80211=y 3386d49e1aeSJan LentferCONFIG_DRIVER_WEXT=y 3396d49e1aeSJan LentferCONFIG_DRIVER_BSD=y 3406d49e1aeSJan LentferCONFIG_DRIVER_NDIS=y 3416d49e1aeSJan Lentfer 3423ff40c12SJohn MarinoFollowing example includes some more features and driver interfaces that 3433ff40c12SJohn Marinoare included in the wpa_supplicant package: 3446d49e1aeSJan Lentfer 3453ff40c12SJohn MarinoCONFIG_DRIVER_NL80211=y 3466d49e1aeSJan LentferCONFIG_DRIVER_WEXT=y 3476d49e1aeSJan LentferCONFIG_DRIVER_BSD=y 3486d49e1aeSJan LentferCONFIG_DRIVER_NDIS=y 3496d49e1aeSJan LentferCONFIG_IEEE8021X_EAPOL=y 3506d49e1aeSJan LentferCONFIG_EAP_MD5=y 3516d49e1aeSJan LentferCONFIG_EAP_MSCHAPV2=y 3526d49e1aeSJan LentferCONFIG_EAP_TLS=y 3536d49e1aeSJan LentferCONFIG_EAP_PEAP=y 3546d49e1aeSJan LentferCONFIG_EAP_TTLS=y 3556d49e1aeSJan LentferCONFIG_EAP_GTC=y 3566d49e1aeSJan LentferCONFIG_EAP_OTP=y 3576d49e1aeSJan LentferCONFIG_EAP_SIM=y 3586d49e1aeSJan LentferCONFIG_EAP_AKA=y 3596d49e1aeSJan LentferCONFIG_EAP_PSK=y 3606d49e1aeSJan LentferCONFIG_EAP_SAKE=y 3616d49e1aeSJan LentferCONFIG_EAP_GPSK=y 3626d49e1aeSJan LentferCONFIG_EAP_PAX=y 3636d49e1aeSJan LentferCONFIG_EAP_LEAP=y 3646d49e1aeSJan LentferCONFIG_EAP_IKEV2=y 3656d49e1aeSJan LentferCONFIG_PCSC=y 3666d49e1aeSJan Lentfer 3676d49e1aeSJan LentferEAP-PEAP and EAP-TTLS will automatically include configured EAP 3686d49e1aeSJan Lentfermethods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection. 3696d49e1aeSJan Lentfer 3706d49e1aeSJan Lentfer 3716d49e1aeSJan LentferAfter you have created a configuration file, you can build 3726d49e1aeSJan Lentferwpa_supplicant and wpa_cli with 'make' command. You may then install 3736d49e1aeSJan Lentferthe binaries to a suitable system directory, e.g., /usr/local/bin. 3746d49e1aeSJan Lentfer 3756d49e1aeSJan LentferExample commands: 3766d49e1aeSJan Lentfer 3776d49e1aeSJan Lentfer# build wpa_supplicant and wpa_cli 3786d49e1aeSJan Lentfermake 3796d49e1aeSJan Lentfer# install binaries (this may need root privileges) 3806d49e1aeSJan Lentfercp wpa_cli wpa_supplicant /usr/local/bin 3816d49e1aeSJan Lentfer 3826d49e1aeSJan Lentfer 3836d49e1aeSJan LentferYou will need to make a configuration file, e.g., 3846d49e1aeSJan Lentfer/etc/wpa_supplicant.conf, with network configuration for the networks 3856d49e1aeSJan Lentferyou are going to use. Configuration file section below includes 3866d49e1aeSJan Lentferexplanation fo the configuration file format and includes various 3876d49e1aeSJan Lentferexamples. Once the configuration is ready, you can test whether the 3886d49e1aeSJan Lentferconfiguration work by first running wpa_supplicant with following 3896d49e1aeSJan Lentfercommand to start it on foreground with debugging enabled: 3906d49e1aeSJan Lentfer 3916d49e1aeSJan Lentferwpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d 3926d49e1aeSJan Lentfer 3936d49e1aeSJan LentferAssuming everything goes fine, you can start using following command 3946d49e1aeSJan Lentferto start wpa_supplicant on background without debugging: 3956d49e1aeSJan Lentfer 3966d49e1aeSJan Lentferwpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B 3976d49e1aeSJan Lentfer 3986d49e1aeSJan LentferPlease note that if you included more than one driver interface in the 3996d49e1aeSJan Lentferbuild time configuration (.config), you may need to specify which 4006d49e1aeSJan Lentferinterface to use by including -D<driver name> option on the command 4016d49e1aeSJan Lentferline. See following section for more details on command line options 4026d49e1aeSJan Lentferfor wpa_supplicant. 4036d49e1aeSJan Lentfer 4046d49e1aeSJan Lentfer 4056d49e1aeSJan Lentfer 4066d49e1aeSJan LentferCommand line options 4076d49e1aeSJan Lentfer-------------------- 4086d49e1aeSJan Lentfer 4096d49e1aeSJan Lentferusage: 410*a1157835SDaniel Fojt wpa_supplicant [-BddfhKLqqtuvW] [-P<pid file>] [-g<global ctrl>] \ 4113ff40c12SJohn Marino [-G<group>] \ 4126d49e1aeSJan Lentfer -i<ifname> -c<config file> [-C<ctrl>] [-D<driver>] [-p<driver_param>] \ 413*a1157835SDaniel Fojt [-b<br_ifname> [-MN -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] \ 414*a1157835SDaniel Fojt [-p<driver_param>] [-b<br_ifname>] [-m<P2P Device config file>] ... 4156d49e1aeSJan Lentfer 4166d49e1aeSJan Lentferoptions: 4176d49e1aeSJan Lentfer -b = optional bridge interface name 4186d49e1aeSJan Lentfer -B = run daemon in the background 4196d49e1aeSJan Lentfer -c = Configuration file 4206d49e1aeSJan Lentfer -C = ctrl_interface parameter (only used if -c is not) 4216d49e1aeSJan Lentfer -i = interface name 4226d49e1aeSJan Lentfer -d = increase debugging verbosity (-dd even more) 4233ff40c12SJohn Marino -D = driver name (can be multiple drivers: nl80211,wext) 4246d49e1aeSJan Lentfer -f = Log output to default log location (normally /tmp) 4256d49e1aeSJan Lentfer -g = global ctrl_interface 4263ff40c12SJohn Marino -G = global ctrl_interface group 4276d49e1aeSJan Lentfer -K = include keys (passwords, etc.) in debug output 4286d49e1aeSJan Lentfer -t = include timestamp in debug messages 4296d49e1aeSJan Lentfer -h = show this help text 4303ff40c12SJohn Marino -L = show license (BSD) 4316d49e1aeSJan Lentfer -p = driver parameters 4326d49e1aeSJan Lentfer -P = PID file 4336d49e1aeSJan Lentfer -q = decrease debugging verbosity (-qq even less) 4346d49e1aeSJan Lentfer -u = enable DBus control interface 4356d49e1aeSJan Lentfer -v = show version 4366d49e1aeSJan Lentfer -W = wait for a control interface monitor before starting 437*a1157835SDaniel Fojt -M = start describing matching interface 4386d49e1aeSJan Lentfer -N = start describing new interface 439*a1157835SDaniel Fojt -m = Configuration file for the P2P Device 4406d49e1aeSJan Lentfer 4416d49e1aeSJan Lentferdrivers: 4423ff40c12SJohn Marino nl80211 = Linux nl80211/cfg80211 4436d49e1aeSJan Lentfer wext = Linux wireless extensions (generic) 4446d49e1aeSJan Lentfer wired = wpa_supplicant wired Ethernet driver 4456d49e1aeSJan Lentfer roboswitch = wpa_supplicant Broadcom switch driver 4466d49e1aeSJan Lentfer bsd = BSD 802.11 support (Atheros, etc.) 4476d49e1aeSJan Lentfer ndis = Windows NDIS driver 4486d49e1aeSJan Lentfer 4496d49e1aeSJan LentferIn most common cases, wpa_supplicant is started with 4506d49e1aeSJan Lentfer 4516d49e1aeSJan Lentferwpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0 4526d49e1aeSJan Lentfer 4536d49e1aeSJan LentferThis makes the process fork into background. 4546d49e1aeSJan Lentfer 4556d49e1aeSJan LentferThe easiest way to debug problems, and to get debug log for bug 4566d49e1aeSJan Lentferreports, is to start wpa_supplicant on foreground with debugging 4576d49e1aeSJan Lentferenabled: 4586d49e1aeSJan Lentfer 4596d49e1aeSJan Lentferwpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d 4606d49e1aeSJan Lentfer 4613ff40c12SJohn MarinoIf the specific driver wrapper is not known beforehand, it is possible 4623ff40c12SJohn Marinoto specify multiple comma separated driver wrappers on the command 4633ff40c12SJohn Marinoline. wpa_supplicant will use the first driver wrapper that is able to 4643ff40c12SJohn Marinoinitialize the interface. 4653ff40c12SJohn Marino 4663ff40c12SJohn Marinowpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0 4673ff40c12SJohn Marino 4686d49e1aeSJan Lentfer 4696d49e1aeSJan Lentferwpa_supplicant can control multiple interfaces (radios) either by 4706d49e1aeSJan Lentferrunning one process for each interface separately or by running just 4716d49e1aeSJan Lentferone process and list of options at command line. Each interface is 4726d49e1aeSJan Lentferseparated with -N argument. As an example, following command would 4736d49e1aeSJan Lentferstart wpa_supplicant for two interfaces: 4746d49e1aeSJan Lentfer 4756d49e1aeSJan Lentferwpa_supplicant \ 4763ff40c12SJohn Marino -c wpa1.conf -i wlan0 -D nl80211 -N \ 4773ff40c12SJohn Marino -c wpa2.conf -i wlan1 -D wext 4786d49e1aeSJan Lentfer 4796d49e1aeSJan Lentfer 480*a1157835SDaniel FojtIf the interfaces on which wpa_supplicant is to run are not known or do 481*a1157835SDaniel Fojtnot exist, wpa_supplicant can match an interface when it arrives. Each 482*a1157835SDaniel Fojtmatched interface is separated with -M argument and the -i argument now 483*a1157835SDaniel Fojtallows for pattern matching. 484*a1157835SDaniel Fojt 485*a1157835SDaniel FojtAs an example, the following command would start wpa_supplicant for a 486*a1157835SDaniel Fojtspecific wired interface called lan0, any interface starting with wlan 487*a1157835SDaniel Fojtand lastly any other interface. Each match has its own configuration 488*a1157835SDaniel Fojtfile, and for the wired interface a specific driver has also been given. 489*a1157835SDaniel Fojt 490*a1157835SDaniel Fojtwpa_supplicant \ 491*a1157835SDaniel Fojt -M -c wpa_wired.conf -ilan0 -D wired \ 492*a1157835SDaniel Fojt -M -c wpa1.conf -iwlan* \ 493*a1157835SDaniel Fojt -M -c wpa2.conf 494*a1157835SDaniel Fojt 495*a1157835SDaniel Fojt 4966d49e1aeSJan LentferIf the interface is added in a Linux bridge (e.g., br0), the bridge 4976d49e1aeSJan Lentferinterface needs to be configured to wpa_supplicant in addition to the 4986d49e1aeSJan Lentfermain interface: 4996d49e1aeSJan Lentfer 5003ff40c12SJohn Marinowpa_supplicant -cw.conf -Dnl80211 -iwlan0 -bbr0 5016d49e1aeSJan Lentfer 5026d49e1aeSJan Lentfer 5036d49e1aeSJan LentferConfiguration file 5046d49e1aeSJan Lentfer------------------ 5056d49e1aeSJan Lentfer 5066d49e1aeSJan Lentferwpa_supplicant is configured using a text file that lists all accepted 5076d49e1aeSJan Lentfernetworks and security policies, including pre-shared keys. See 5086d49e1aeSJan Lentferexample configuration file, wpa_supplicant.conf, for detailed 5096d49e1aeSJan Lentferinformation about the configuration format and supported fields. 5106d49e1aeSJan Lentfer 5116d49e1aeSJan LentferChanges to configuration file can be reloaded be sending SIGHUP signal 5126d49e1aeSJan Lentferto wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly, 5136d49e1aeSJan Lentferreloading can be triggered with 'wpa_cli reconfigure' command. 5146d49e1aeSJan Lentfer 5156d49e1aeSJan LentferConfiguration file can include one or more network blocks, e.g., one 5166d49e1aeSJan Lentferfor each used SSID. wpa_supplicant will automatically select the best 517*a1157835SDaniel Fojtnetwork based on the order of network blocks in the configuration 5186d49e1aeSJan Lentferfile, network security level (WPA/WPA2 is preferred), and signal 5196d49e1aeSJan Lentferstrength. 5206d49e1aeSJan Lentfer 5216d49e1aeSJan LentferExample configuration files for some common configurations: 5226d49e1aeSJan Lentfer 5236d49e1aeSJan Lentfer1) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work 5246d49e1aeSJan Lentfer network 5256d49e1aeSJan Lentfer 5266d49e1aeSJan Lentfer# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group 5276d49e1aeSJan Lentferctrl_interface=/var/run/wpa_supplicant 5286d49e1aeSJan Lentferctrl_interface_group=wheel 5296d49e1aeSJan Lentfer# 5306d49e1aeSJan Lentfer# home network; allow all valid ciphers 5316d49e1aeSJan Lentfernetwork={ 5326d49e1aeSJan Lentfer ssid="home" 5336d49e1aeSJan Lentfer scan_ssid=1 5346d49e1aeSJan Lentfer key_mgmt=WPA-PSK 5356d49e1aeSJan Lentfer psk="very secret passphrase" 5366d49e1aeSJan Lentfer} 5376d49e1aeSJan Lentfer# 5386d49e1aeSJan Lentfer# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers 5396d49e1aeSJan Lentfernetwork={ 5406d49e1aeSJan Lentfer ssid="work" 5416d49e1aeSJan Lentfer scan_ssid=1 5426d49e1aeSJan Lentfer key_mgmt=WPA-EAP 5436d49e1aeSJan Lentfer pairwise=CCMP TKIP 5446d49e1aeSJan Lentfer group=CCMP TKIP 5456d49e1aeSJan Lentfer eap=TLS 5466d49e1aeSJan Lentfer identity="user@example.com" 5476d49e1aeSJan Lentfer ca_cert="/etc/cert/ca.pem" 5486d49e1aeSJan Lentfer client_cert="/etc/cert/user.pem" 5496d49e1aeSJan Lentfer private_key="/etc/cert/user.prv" 5506d49e1aeSJan Lentfer private_key_passwd="password" 5516d49e1aeSJan Lentfer} 5526d49e1aeSJan Lentfer 5536d49e1aeSJan Lentfer 5546d49e1aeSJan Lentfer2) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel 5556d49e1aeSJan Lentfer (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series) 5566d49e1aeSJan Lentfer 5576d49e1aeSJan Lentferctrl_interface=/var/run/wpa_supplicant 5586d49e1aeSJan Lentferctrl_interface_group=wheel 5596d49e1aeSJan Lentfernetwork={ 5606d49e1aeSJan Lentfer ssid="example" 5616d49e1aeSJan Lentfer scan_ssid=1 5626d49e1aeSJan Lentfer key_mgmt=WPA-EAP 5636d49e1aeSJan Lentfer eap=PEAP 5646d49e1aeSJan Lentfer identity="user@example.com" 5656d49e1aeSJan Lentfer password="foobar" 5666d49e1aeSJan Lentfer ca_cert="/etc/cert/ca.pem" 5676d49e1aeSJan Lentfer phase1="peaplabel=0" 5686d49e1aeSJan Lentfer phase2="auth=MSCHAPV2" 5696d49e1aeSJan Lentfer} 5706d49e1aeSJan Lentfer 5716d49e1aeSJan Lentfer 5726d49e1aeSJan Lentfer3) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the 5736d49e1aeSJan Lentfer unencrypted use. Real identity is sent only within an encrypted TLS tunnel. 5746d49e1aeSJan Lentfer 5756d49e1aeSJan Lentferctrl_interface=/var/run/wpa_supplicant 5766d49e1aeSJan Lentferctrl_interface_group=wheel 5776d49e1aeSJan Lentfernetwork={ 5786d49e1aeSJan Lentfer ssid="example" 5796d49e1aeSJan Lentfer scan_ssid=1 5806d49e1aeSJan Lentfer key_mgmt=WPA-EAP 5816d49e1aeSJan Lentfer eap=TTLS 5826d49e1aeSJan Lentfer identity="user@example.com" 5836d49e1aeSJan Lentfer anonymous_identity="anonymous@example.com" 5846d49e1aeSJan Lentfer password="foobar" 5856d49e1aeSJan Lentfer ca_cert="/etc/cert/ca.pem" 5866d49e1aeSJan Lentfer phase2="auth=MD5" 5876d49e1aeSJan Lentfer} 5886d49e1aeSJan Lentfer 5896d49e1aeSJan Lentfer 5906d49e1aeSJan Lentfer4) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and 5916d49e1aeSJan Lentfer broadcast); use EAP-TLS for authentication 5926d49e1aeSJan Lentfer 5936d49e1aeSJan Lentferctrl_interface=/var/run/wpa_supplicant 5946d49e1aeSJan Lentferctrl_interface_group=wheel 5956d49e1aeSJan Lentfernetwork={ 5966d49e1aeSJan Lentfer ssid="1x-test" 5976d49e1aeSJan Lentfer scan_ssid=1 5986d49e1aeSJan Lentfer key_mgmt=IEEE8021X 5996d49e1aeSJan Lentfer eap=TLS 6006d49e1aeSJan Lentfer identity="user@example.com" 6016d49e1aeSJan Lentfer ca_cert="/etc/cert/ca.pem" 6026d49e1aeSJan Lentfer client_cert="/etc/cert/user.pem" 6036d49e1aeSJan Lentfer private_key="/etc/cert/user.prv" 6046d49e1aeSJan Lentfer private_key_passwd="password" 6056d49e1aeSJan Lentfer eapol_flags=3 6066d49e1aeSJan Lentfer} 6076d49e1aeSJan Lentfer 6086d49e1aeSJan Lentfer 6096d49e1aeSJan Lentfer5) Catch all example that allows more or less all configuration modes. The 6106d49e1aeSJan Lentfer configuration options are used based on what security policy is used in the 6116d49e1aeSJan Lentfer selected SSID. This is mostly for testing and is not recommended for normal 6126d49e1aeSJan Lentfer use. 6136d49e1aeSJan Lentfer 6146d49e1aeSJan Lentferctrl_interface=/var/run/wpa_supplicant 6156d49e1aeSJan Lentferctrl_interface_group=wheel 6166d49e1aeSJan Lentfernetwork={ 6176d49e1aeSJan Lentfer ssid="example" 6186d49e1aeSJan Lentfer scan_ssid=1 6196d49e1aeSJan Lentfer key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE 6206d49e1aeSJan Lentfer pairwise=CCMP TKIP 6216d49e1aeSJan Lentfer group=CCMP TKIP WEP104 WEP40 6226d49e1aeSJan Lentfer psk="very secret passphrase" 6236d49e1aeSJan Lentfer eap=TTLS PEAP TLS 6246d49e1aeSJan Lentfer identity="user@example.com" 6256d49e1aeSJan Lentfer password="foobar" 6266d49e1aeSJan Lentfer ca_cert="/etc/cert/ca.pem" 6276d49e1aeSJan Lentfer client_cert="/etc/cert/user.pem" 6286d49e1aeSJan Lentfer private_key="/etc/cert/user.prv" 6296d49e1aeSJan Lentfer private_key_passwd="password" 6306d49e1aeSJan Lentfer phase1="peaplabel=0" 6316d49e1aeSJan Lentfer ca_cert2="/etc/cert/ca2.pem" 6326d49e1aeSJan Lentfer client_cert2="/etc/cer/user.pem" 6336d49e1aeSJan Lentfer private_key2="/etc/cer/user.prv" 6346d49e1aeSJan Lentfer private_key2_passwd="password" 6356d49e1aeSJan Lentfer} 6366d49e1aeSJan Lentfer 6376d49e1aeSJan Lentfer 6386d49e1aeSJan Lentfer6) Authentication for wired Ethernet. This can be used with 'wired' or 6396d49e1aeSJan Lentfer 'roboswitch' interface (-Dwired or -Droboswitch on command line). 6406d49e1aeSJan Lentfer 6416d49e1aeSJan Lentferctrl_interface=/var/run/wpa_supplicant 6426d49e1aeSJan Lentferctrl_interface_group=wheel 6436d49e1aeSJan Lentferap_scan=0 6446d49e1aeSJan Lentfernetwork={ 6456d49e1aeSJan Lentfer key_mgmt=IEEE8021X 6466d49e1aeSJan Lentfer eap=MD5 6476d49e1aeSJan Lentfer identity="user" 6486d49e1aeSJan Lentfer password="password" 6496d49e1aeSJan Lentfer eapol_flags=0 6506d49e1aeSJan Lentfer} 6516d49e1aeSJan Lentfer 6526d49e1aeSJan Lentfer 6536d49e1aeSJan Lentfer 6546d49e1aeSJan LentferCertificates 6556d49e1aeSJan Lentfer------------ 6566d49e1aeSJan Lentfer 6576d49e1aeSJan LentferSome EAP authentication methods require use of certificates. EAP-TLS 6586d49e1aeSJan Lentferuses both server side and client certificates whereas EAP-PEAP and 6596d49e1aeSJan LentferEAP-TTLS only require the server side certificate. When client 6606d49e1aeSJan Lentfercertificate is used, a matching private key file has to also be 6616d49e1aeSJan Lentferincluded in configuration. If the private key uses a passphrase, this 6626d49e1aeSJan Lentferhas to be configured in wpa_supplicant.conf ("private_key_passwd"). 6636d49e1aeSJan Lentfer 6646d49e1aeSJan Lentferwpa_supplicant supports X.509 certificates in PEM and DER 6656d49e1aeSJan Lentferformats. User certificate and private key can be included in the same 6666d49e1aeSJan Lentferfile. 6676d49e1aeSJan Lentfer 6686d49e1aeSJan LentferIf the user certificate and private key is received in PKCS#12/PFX 6696d49e1aeSJan Lentferformat, they need to be converted to suitable PEM/DER format for 6706d49e1aeSJan Lentferwpa_supplicant. This can be done, e.g., with following commands: 6716d49e1aeSJan Lentfer 6726d49e1aeSJan Lentfer# convert client certificate and private key to PEM format 6736d49e1aeSJan Lentferopenssl pkcs12 -in example.pfx -out user.pem -clcerts 6746d49e1aeSJan Lentfer# convert CA certificate (if included in PFX file) to PEM format 6756d49e1aeSJan Lentferopenssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys 6766d49e1aeSJan Lentfer 6776d49e1aeSJan Lentfer 6786d49e1aeSJan Lentfer 6796d49e1aeSJan Lentferwpa_cli 6806d49e1aeSJan Lentfer------- 6816d49e1aeSJan Lentfer 6826d49e1aeSJan Lentferwpa_cli is a text-based frontend program for interacting with 6836d49e1aeSJan Lentferwpa_supplicant. It is used to query current status, change 6846d49e1aeSJan Lentferconfiguration, trigger events, and request interactive user input. 6856d49e1aeSJan Lentfer 6866d49e1aeSJan Lentferwpa_cli can show the current authentication status, selected security 6876d49e1aeSJan Lentfermode, dot11 and dot1x MIBs, etc. In addition, it can configure some 6886d49e1aeSJan Lentfervariables like EAPOL state machine parameters and trigger events like 6896d49e1aeSJan Lentferreassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user 6906d49e1aeSJan Lentferinterface to request authentication information, like username and 6916d49e1aeSJan Lentferpassword, if these are not included in the configuration. This can be 6926d49e1aeSJan Lentferused to implement, e.g., one-time-passwords or generic token card 6936d49e1aeSJan Lentferauthentication where the authentication is based on a 6946d49e1aeSJan Lentferchallenge-response that uses an external device for generating the 6956d49e1aeSJan Lentferresponse. 6966d49e1aeSJan Lentfer 6976d49e1aeSJan LentferThe control interface of wpa_supplicant can be configured to allow 6986d49e1aeSJan Lentfernon-root user access (ctrl_interface_group in the configuration 6996d49e1aeSJan Lentferfile). This makes it possible to run wpa_cli with a normal user 7006d49e1aeSJan Lentferaccount. 7016d49e1aeSJan Lentfer 7026d49e1aeSJan Lentferwpa_cli supports two modes: interactive and command line. Both modes 7036d49e1aeSJan Lentfershare the same command set and the main difference is in interactive 7046d49e1aeSJan Lentfermode providing access to unsolicited messages (event messages, 7056d49e1aeSJan Lentferusername/password requests). 7066d49e1aeSJan Lentfer 7076d49e1aeSJan LentferInteractive mode is started when wpa_cli is executed without including 7086d49e1aeSJan Lentferthe command as a command line parameter. Commands are then entered on 7096d49e1aeSJan Lentferthe wpa_cli prompt. In command line mode, the same commands are 7106d49e1aeSJan Lentferentered as command line arguments for wpa_cli. 7116d49e1aeSJan Lentfer 7126d49e1aeSJan Lentfer 7136d49e1aeSJan LentferInteractive authentication parameters request 7146d49e1aeSJan Lentfer 7156d49e1aeSJan LentferWhen wpa_supplicant need authentication parameters, like username and 7166d49e1aeSJan Lentferpassword, which are not present in the configuration file, it sends a 7176d49e1aeSJan Lentferrequest message to all attached frontend programs, e.g., wpa_cli in 7186d49e1aeSJan Lentferinteractive mode. wpa_cli shows these requests with 7196d49e1aeSJan Lentfer"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or 7206d49e1aeSJan LentferOTP (one-time-password). <id> is a unique identifier for the current 7216d49e1aeSJan Lentfernetwork. <text> is description of the request. In case of OTP request, 7226d49e1aeSJan Lentferit includes the challenge from the authentication server. 7236d49e1aeSJan Lentfer 7246d49e1aeSJan LentferThe reply to these requests can be given with 'identity', 'password', 7256d49e1aeSJan Lentferand 'otp' commands. <id> needs to be copied from the the matching 7266d49e1aeSJan Lentferrequest. 'password' and 'otp' commands can be used regardless of 7276d49e1aeSJan Lentferwhether the request was for PASSWORD or OTP. The main difference 7286d49e1aeSJan Lentferbetween these two commands is that values given with 'password' are 7296d49e1aeSJan Lentferremembered as long as wpa_supplicant is running whereas values given 7306d49e1aeSJan Lentferwith 'otp' are used only once and then forgotten, i.e., wpa_supplicant 7316d49e1aeSJan Lentferwill ask frontend for a new value for every use. This can be used to 7326d49e1aeSJan Lentferimplement one-time-password lists and generic token card -based 7336d49e1aeSJan Lentferauthentication. 7346d49e1aeSJan Lentfer 7356d49e1aeSJan LentferExample request for password and a matching reply: 7366d49e1aeSJan Lentfer 7376d49e1aeSJan LentferCTRL-REQ-PASSWORD-1:Password needed for SSID foobar 7386d49e1aeSJan Lentfer> password 1 mysecretpassword 7396d49e1aeSJan Lentfer 7406d49e1aeSJan LentferExample request for generic token card challenge-response: 7416d49e1aeSJan Lentfer 7426d49e1aeSJan LentferCTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 7436d49e1aeSJan Lentfer> otp 2 9876 7446d49e1aeSJan Lentfer 7456d49e1aeSJan Lentfer 7466d49e1aeSJan Lentferwpa_cli commands 7476d49e1aeSJan Lentfer 7486d49e1aeSJan Lentfer status = get current WPA/EAPOL/EAP status 7496d49e1aeSJan Lentfer mib = get MIB variables (dot1x, dot11) 7506d49e1aeSJan Lentfer help = show this usage help 7516d49e1aeSJan Lentfer interface [ifname] = show interfaces/select interface 7526d49e1aeSJan Lentfer level <debug level> = change debug level 7536d49e1aeSJan Lentfer license = show full wpa_cli license 7546d49e1aeSJan Lentfer logoff = IEEE 802.1X EAPOL state machine logoff 7556d49e1aeSJan Lentfer logon = IEEE 802.1X EAPOL state machine logon 7566d49e1aeSJan Lentfer set = set variables (shows list of variables when run without arguments) 7576d49e1aeSJan Lentfer pmksa = show PMKSA cache 7586d49e1aeSJan Lentfer reassociate = force reassociation 7596d49e1aeSJan Lentfer reconfigure = force wpa_supplicant to re-read its configuration file 7606d49e1aeSJan Lentfer preauthenticate <BSSID> = force preauthentication 7616d49e1aeSJan Lentfer identity <network id> <identity> = configure identity for an SSID 7626d49e1aeSJan Lentfer password <network id> <password> = configure password for an SSID 7636d49e1aeSJan Lentfer pin <network id> <pin> = configure pin for an SSID 7646d49e1aeSJan Lentfer otp <network id> <password> = configure one-time-password for an SSID 7656d49e1aeSJan Lentfer passphrase <network id> <passphrase> = configure private key passphrase 7666d49e1aeSJan Lentfer for an SSID 7676d49e1aeSJan Lentfer bssid <network id> <BSSID> = set preferred BSSID for an SSID 7686d49e1aeSJan Lentfer list_networks = list configured networks 7696d49e1aeSJan Lentfer select_network <network id> = select a network (disable others) 7706d49e1aeSJan Lentfer enable_network <network id> = enable a network 7716d49e1aeSJan Lentfer disable_network <network id> = disable a network 7726d49e1aeSJan Lentfer add_network = add a network 7736d49e1aeSJan Lentfer remove_network <network id> = remove a network 7746d49e1aeSJan Lentfer set_network <network id> <variable> <value> = set network variables (shows 7756d49e1aeSJan Lentfer list of variables when run without arguments) 7766d49e1aeSJan Lentfer get_network <network id> <variable> = get network variables 7776d49e1aeSJan Lentfer save_config = save the current configuration 7786d49e1aeSJan Lentfer disconnect = disconnect and wait for reassociate command before connecting 7796d49e1aeSJan Lentfer scan = request new BSS scan 7806d49e1aeSJan Lentfer scan_results = get latest scan results 7816d49e1aeSJan Lentfer get_capability <eap/pairwise/group/key_mgmt/proto/auth_alg> = get capabilies 7826d49e1aeSJan Lentfer terminate = terminate wpa_supplicant 7836d49e1aeSJan Lentfer quit = exit wpa_cli 7846d49e1aeSJan Lentfer 7856d49e1aeSJan Lentfer 7866d49e1aeSJan Lentferwpa_cli command line options 7876d49e1aeSJan Lentfer 7886d49e1aeSJan Lentferwpa_cli [-p<path to ctrl sockets>] [-i<ifname>] [-hvB] [-a<action file>] \ 7896d49e1aeSJan Lentfer [-P<pid file>] [-g<global ctrl>] [command..] 7906d49e1aeSJan Lentfer -h = help (show this usage text) 7916d49e1aeSJan Lentfer -v = shown version information 7926d49e1aeSJan Lentfer -a = run in daemon mode executing the action file based on events from 7936d49e1aeSJan Lentfer wpa_supplicant 7946d49e1aeSJan Lentfer -B = run a daemon in the background 7956d49e1aeSJan Lentfer default path: /var/run/wpa_supplicant 7966d49e1aeSJan Lentfer default interface: first interface found in socket path 7976d49e1aeSJan Lentfer 7986d49e1aeSJan Lentfer 7996d49e1aeSJan LentferUsing wpa_cli to run external program on connect/disconnect 8006d49e1aeSJan Lentfer----------------------------------------------------------- 8016d49e1aeSJan Lentfer 8026d49e1aeSJan Lentferwpa_cli can used to run external programs whenever wpa_supplicant 8036d49e1aeSJan Lentferconnects or disconnects from a network. This can be used, e.g., to 8046d49e1aeSJan Lentferupdate network configuration and/or trigget DHCP client to update IP 8056d49e1aeSJan Lentferaddresses, etc. 8066d49e1aeSJan Lentfer 8076d49e1aeSJan LentferOne wpa_cli process in "action" mode needs to be started for each 8086d49e1aeSJan Lentferinterface. For example, the following command starts wpa_cli for the 809*a1157835SDaniel Fojtdefault interface (-i can be used to select the interface in case of 8106d49e1aeSJan Lentfermore than one interface being used at the same time): 8116d49e1aeSJan Lentfer 8126d49e1aeSJan Lentferwpa_cli -a/sbin/wpa_action.sh -B 8136d49e1aeSJan Lentfer 8146d49e1aeSJan LentferThe action file (-a option, /sbin/wpa_action.sh in this example) will 8156d49e1aeSJan Lentferbe executed whenever wpa_supplicant completes authentication (connect 8166d49e1aeSJan Lentferevent) or detects disconnection). The action script will be called 8176d49e1aeSJan Lentferwith two command line arguments: interface name and event (CONNECTED 8186d49e1aeSJan Lentferor DISCONNECTED). If the action script needs to get more information 8196d49e1aeSJan Lentferabout the current network, it can use 'wpa_cli status' to query 8206d49e1aeSJan Lentferwpa_supplicant for more information. 8216d49e1aeSJan Lentfer 8226d49e1aeSJan LentferFollowing example can be used as a simple template for an action 8236d49e1aeSJan Lentferscript: 8246d49e1aeSJan Lentfer 8256d49e1aeSJan Lentfer#!/bin/sh 8266d49e1aeSJan Lentfer 8276d49e1aeSJan LentferIFNAME=$1 8286d49e1aeSJan LentferCMD=$2 8296d49e1aeSJan Lentfer 8303ff40c12SJohn Marinoif [ "$CMD" = "CONNECTED" ]; then 8316d49e1aeSJan Lentfer SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=` 8326d49e1aeSJan Lentfer # configure network, signal DHCP client, etc. 8336d49e1aeSJan Lentferfi 8346d49e1aeSJan Lentfer 8353ff40c12SJohn Marinoif [ "$CMD" = "DISCONNECTED" ]; then 8366d49e1aeSJan Lentfer # remove network configuration, if needed 8373ff40c12SJohn Marino SSID= 8386d49e1aeSJan Lentferfi 8396d49e1aeSJan Lentfer 8406d49e1aeSJan Lentfer 8416d49e1aeSJan Lentfer 8426d49e1aeSJan LentferIntegrating with pcmcia-cs/cardmgr scripts 8436d49e1aeSJan Lentfer------------------------------------------ 8446d49e1aeSJan Lentfer 8456d49e1aeSJan Lentferwpa_supplicant needs to be running when using a wireless network with 8466d49e1aeSJan LentferWPA. It can be started either from system startup scripts or from 8476d49e1aeSJan Lentferpcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be 8486d49e1aeSJan Lentfercompleted before data frames can be exchanged, so wpa_supplicant 8496d49e1aeSJan Lentfershould be started before DHCP client. 8506d49e1aeSJan Lentfer 8516d49e1aeSJan LentferFor example, following small changes to pcmcia-cs scripts can be used 8526d49e1aeSJan Lentferto enable WPA support: 8536d49e1aeSJan Lentfer 8546d49e1aeSJan LentferAdd MODE="Managed" and WPA="y" to the network scheme in 8556d49e1aeSJan Lentfer/etc/pcmcia/wireless.opts. 8566d49e1aeSJan Lentfer 8576d49e1aeSJan LentferAdd the following block to the end of 'start' action handler in 8586d49e1aeSJan Lentfer/etc/pcmcia/wireless: 8596d49e1aeSJan Lentfer 8606d49e1aeSJan Lentfer if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then 8616d49e1aeSJan Lentfer /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf \ 8626d49e1aeSJan Lentfer -i$DEVICE 8636d49e1aeSJan Lentfer fi 8646d49e1aeSJan Lentfer 8656d49e1aeSJan LentferAdd the following block to the end of 'stop' action handler (may need 8666d49e1aeSJan Lentferto be separated from other actions) in /etc/pcmcia/wireless: 8676d49e1aeSJan Lentfer 8686d49e1aeSJan Lentfer if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then 8696d49e1aeSJan Lentfer killall wpa_supplicant 8706d49e1aeSJan Lentfer fi 8716d49e1aeSJan Lentfer 8726d49e1aeSJan LentferThis will make cardmgr start wpa_supplicant when the card is plugged 8736d49e1aeSJan Lentferin. 8746d49e1aeSJan Lentfer 8756d49e1aeSJan Lentfer 8766d49e1aeSJan Lentfer 8776d49e1aeSJan LentferDynamic interface add and operation without configuration files 8786d49e1aeSJan Lentfer--------------------------------------------------------------- 8796d49e1aeSJan Lentfer 8806d49e1aeSJan Lentferwpa_supplicant can be started without any configuration files or 8816d49e1aeSJan Lentfernetwork interfaces. When used in this way, a global (i.e., per 8826d49e1aeSJan Lentferwpa_supplicant process) control interface is used to add and remove 8836d49e1aeSJan Lentfernetwork interfaces. Each network interface can then be configured 8846d49e1aeSJan Lentferthrough a per-network interface control interface. For example, 8856d49e1aeSJan Lentferfollowing commands show how to start wpa_supplicant without any 8866d49e1aeSJan Lentfernetwork interfaces and then add a network interface and configure a 8876d49e1aeSJan Lentfernetwork (SSID): 8886d49e1aeSJan Lentfer 8896d49e1aeSJan Lentfer# Start wpa_supplicant in the background 8906d49e1aeSJan Lentferwpa_supplicant -g/var/run/wpa_supplicant-global -B 8916d49e1aeSJan Lentfer 8923ff40c12SJohn Marino# Add a new interface (wlan0, no configuration file, driver=nl80211, and 8936d49e1aeSJan Lentfer# enable control interface) 8946d49e1aeSJan Lentferwpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \ 8953ff40c12SJohn Marino "" nl80211 /var/run/wpa_supplicant 8966d49e1aeSJan Lentfer 8976d49e1aeSJan Lentfer# Configure a network using the newly added network interface: 8986d49e1aeSJan Lentferwpa_cli -iwlan0 add_network 8996d49e1aeSJan Lentferwpa_cli -iwlan0 set_network 0 ssid '"test"' 9006d49e1aeSJan Lentferwpa_cli -iwlan0 set_network 0 key_mgmt WPA-PSK 9016d49e1aeSJan Lentferwpa_cli -iwlan0 set_network 0 psk '"12345678"' 9026d49e1aeSJan Lentferwpa_cli -iwlan0 set_network 0 pairwise TKIP 9036d49e1aeSJan Lentferwpa_cli -iwlan0 set_network 0 group TKIP 9046d49e1aeSJan Lentferwpa_cli -iwlan0 set_network 0 proto WPA 9056d49e1aeSJan Lentferwpa_cli -iwlan0 enable_network 0 9066d49e1aeSJan Lentfer 9076d49e1aeSJan Lentfer# At this point, the new network interface should start trying to associate 9086d49e1aeSJan Lentfer# with the WPA-PSK network using SSID test. 9096d49e1aeSJan Lentfer 9106d49e1aeSJan Lentfer# Remove network interface 9116d49e1aeSJan Lentferwpa_cli -g/var/run/wpa_supplicant-global interface_remove wlan0 9126d49e1aeSJan Lentfer 9136d49e1aeSJan Lentfer 9146d49e1aeSJan LentferPrivilege separation 9156d49e1aeSJan Lentfer-------------------- 9166d49e1aeSJan Lentfer 9176d49e1aeSJan LentferTo minimize the size of code that needs to be run with root privileges 9186d49e1aeSJan Lentfer(e.g., to control wireless interface operation), wpa_supplicant 9196d49e1aeSJan Lentfersupports optional privilege separation. If enabled, this separates the 9206d49e1aeSJan Lentferprivileged operations into a separate process (wpa_priv) while leaving 9216d49e1aeSJan Lentferrest of the code (e.g., EAP authentication and WPA handshakes) into an 9226d49e1aeSJan Lentferunprivileged process (wpa_supplicant) that can be run as non-root 9236d49e1aeSJan Lentferuser. Privilege separation restricts the effects of potential software 9246d49e1aeSJan Lentfererrors by containing the majority of the code in an unprivileged 9256d49e1aeSJan Lentferprocess to avoid full system compromise. 9266d49e1aeSJan Lentfer 9276d49e1aeSJan LentferPrivilege separation is not enabled by default and it can be enabled 9286d49e1aeSJan Lentferby adding CONFIG_PRIVSEP=y to the build configuration (.config). When 9296d49e1aeSJan Lentferenabled, the privileged operations (driver wrapper and l2_packet) are 9306d49e1aeSJan Lentferlinked into a separate daemon program, wpa_priv. The unprivileged 9316d49e1aeSJan Lentferprogram, wpa_supplicant, will be built with a special driver/l2_packet 9326d49e1aeSJan Lentferwrappers that communicate with the privileged wpa_priv process to 9336d49e1aeSJan Lentferperform the needed operations. wpa_priv can control what privileged 9346d49e1aeSJan Lentferare allowed. 9356d49e1aeSJan Lentfer 9366d49e1aeSJan Lentferwpa_priv needs to be run with network admin privileges (usually, root 9376d49e1aeSJan Lentferuser). It opens a UNIX domain socket for each interface that is 9386d49e1aeSJan Lentferincluded on the command line; any other interface will be off limits 9396d49e1aeSJan Lentferfor wpa_supplicant in this kind of configuration. After this, 9406d49e1aeSJan Lentferwpa_supplicant can be run as a non-root user (e.g., all standard users 9416d49e1aeSJan Lentferon a laptop or as a special non-privileged user account created just 9426d49e1aeSJan Lentferfor this purpose to limit access to user files even further). 9436d49e1aeSJan Lentfer 9446d49e1aeSJan Lentfer 9456d49e1aeSJan LentferExample configuration: 9466d49e1aeSJan Lentfer- create user group for users that are allowed to use wpa_supplicant 9476d49e1aeSJan Lentfer ('wpapriv' in this example) and assign users that should be able to 9486d49e1aeSJan Lentfer use wpa_supplicant into that group 9496d49e1aeSJan Lentfer- create /var/run/wpa_priv directory for UNIX domain sockets and control 9506d49e1aeSJan Lentfer user access by setting it accessible only for the wpapriv group: 9516d49e1aeSJan Lentfer mkdir /var/run/wpa_priv 9526d49e1aeSJan Lentfer chown root:wpapriv /var/run/wpa_priv 9536d49e1aeSJan Lentfer chmod 0750 /var/run/wpa_priv 9546d49e1aeSJan Lentfer- start wpa_priv as root (e.g., from system startup scripts) with the 9556d49e1aeSJan Lentfer enabled interfaces configured on the command line: 9563ff40c12SJohn Marino wpa_priv -B -P /var/run/wpa_priv.pid nl80211:wlan0 9576d49e1aeSJan Lentfer- run wpa_supplicant as non-root with a user that is in wpapriv group: 9586d49e1aeSJan Lentfer wpa_supplicant -i ath0 -c wpa_supplicant.conf 9596d49e1aeSJan Lentfer 9606d49e1aeSJan Lentferwpa_priv does not use the network interface before wpa_supplicant is 9616d49e1aeSJan Lentferstarted, so it is fine to include network interfaces that are not 9626d49e1aeSJan Lentferavailable at the time wpa_priv is started. As an alternative, wpa_priv 9636d49e1aeSJan Lentfercan be started when an interface is added (hotplug/udev/etc. scripts). 9646d49e1aeSJan Lentferwpa_priv can control multiple interface with one process, but it is 9656d49e1aeSJan Lentferalso possible to run multiple wpa_priv processes at the same time, if 9666d49e1aeSJan Lentferdesired. 9673ff40c12SJohn Marino 968*a1157835SDaniel FojtIt should be noted that the interface used between wpa_supplicant and 969*a1157835SDaniel Fojtwpa_priv does not include all the capabilities of the wpa_supplicant 970*a1157835SDaniel Fojtdriver interface and at times, this interface lacks update especially 971*a1157835SDaniel Fojtfor recent addition. Consequently, use of wpa_priv does come with the 972*a1157835SDaniel Fojtprice of somewhat reduced available functionality. The next section 973*a1157835SDaniel Fojtdescribing how wpa_supplicant can be used with reduced privileges 974*a1157835SDaniel Fojtwithout having to handle the complexity of separate wpa_priv. While that 975*a1157835SDaniel Fojtapprove does not provide separation for network admin capabilities, it 976*a1157835SDaniel Fojtdoes allow other root privileges to be dropped without the drawbacks of 977*a1157835SDaniel Fojtthe wpa_priv process. 978*a1157835SDaniel Fojt 9793ff40c12SJohn Marino 9803ff40c12SJohn MarinoLinux capabilities instead of privileged process 9813ff40c12SJohn Marino------------------------------------------------ 9823ff40c12SJohn Marino 9833ff40c12SJohn Marinowpa_supplicant performs operations that need special permissions, e.g., 9843ff40c12SJohn Marinoto control the network connection. Traditionally this has been achieved 9853ff40c12SJohn Marinoby running wpa_supplicant as a privileged process with effective user id 9863ff40c12SJohn Marino0 (root). Linux capabilities can be used to provide restricted set of 9873ff40c12SJohn Marinocapabilities to match the functions needed by wpa_supplicant. The 9883ff40c12SJohn Marinominimum set of capabilities needed for the operations is CAP_NET_ADMIN 9893ff40c12SJohn Marinoand CAP_NET_RAW. 9903ff40c12SJohn Marino 9913ff40c12SJohn Marinosetcap(8) can be used to set file capabilities. For example: 9923ff40c12SJohn Marino 9933ff40c12SJohn Marinosudo setcap cap_net_raw,cap_net_admin+ep wpa_supplicant 9943ff40c12SJohn Marino 9953ff40c12SJohn MarinoPlease note that this would give anyone being able to run that 9963ff40c12SJohn Marinowpa_supplicant binary access to the additional capabilities. This can 9973ff40c12SJohn Marinofurther be limited by file owner/group and mode bits. For example: 9983ff40c12SJohn Marino 9993ff40c12SJohn Marinosudo chown wpas wpa_supplicant 10003ff40c12SJohn Marinosudo chmod 0100 wpa_supplicant 10013ff40c12SJohn Marino 10023ff40c12SJohn MarinoThis combination of setcap, chown, and chmod commands would allow wpas 10033ff40c12SJohn Marinouser to execute wpa_supplicant with additional network admin/raw 10043ff40c12SJohn Marinocapabilities. 10053ff40c12SJohn Marino 10063ff40c12SJohn MarinoCommon way style of creating a control interface socket in 10073ff40c12SJohn Marino/var/run/wpa_supplicant could not be done by this user, but this 10083ff40c12SJohn Marinodirectory could be created before starting the wpa_supplicant and set to 10093ff40c12SJohn Marinosuitable mode to allow wpa_supplicant to create sockets 10103ff40c12SJohn Marinothere. Alternatively, other directory or abstract socket namespace could 10113ff40c12SJohn Marinobe used for the control interface. 10123ff40c12SJohn Marino 10133ff40c12SJohn Marino 10143ff40c12SJohn MarinoExternal requests for radio control 10153ff40c12SJohn Marino----------------------------------- 10163ff40c12SJohn Marino 10173ff40c12SJohn MarinoExternal programs can request wpa_supplicant to not start offchannel 10183ff40c12SJohn Marinooperations during other tasks that may need exclusive control of the 10193ff40c12SJohn Marinoradio. The RADIO_WORK control interface command can be used for this. 10203ff40c12SJohn Marino 10213ff40c12SJohn Marino"RADIO_WORK add <name> [freq=<MHz>] [timeout=<seconds>]" command can be 10223ff40c12SJohn Marinoused to reserve a slot for radio access. If freq is specified, other 10233ff40c12SJohn Marinoradio work items on the same channel may be completed in 10243ff40c12SJohn Marinoparallel. Otherwise, all other radio work items are blocked during 10253ff40c12SJohn Marinoexecution. Timeout is set to 10 seconds by default to avoid blocking 10263ff40c12SJohn Marinowpa_supplicant operations for excessive time. If a longer (or shorter) 10273ff40c12SJohn Marinosafety timeout is needed, that can be specified with the optional 10283ff40c12SJohn Marinotimeout parameter. This command returns an identifier for the radio work 10293ff40c12SJohn Marinoitem. 10303ff40c12SJohn Marino 10313ff40c12SJohn MarinoOnce the radio work item has been started, "EXT-RADIO-WORK-START <id>" 10323ff40c12SJohn Marinoevent message is indicated that the external processing can start. Once 10333ff40c12SJohn Marinothe operation has been completed, "RADIO_WORK done <id>" is used to 10343ff40c12SJohn Marinoindicate that to wpa_supplicant. This allows other radio works to be 10353ff40c12SJohn Marinoperformed. If this command is forgotten (e.g., due to the external 1036*a1157835SDaniel Fojtprogram terminating), wpa_supplicant will time out the radio work item 1037*a1157835SDaniel Fojtand send "EXT-RADIO-WORK-TIMEOUT <id>" event to indicate that this has 10383ff40c12SJohn Marinohappened. "RADIO_WORK done <id>" can also be used to cancel items that 10393ff40c12SJohn Marinohave not yet been started. 10403ff40c12SJohn Marino 10413ff40c12SJohn MarinoFor example, in wpa_cli interactive mode: 10423ff40c12SJohn Marino 10433ff40c12SJohn Marino> radio_work add test 10443ff40c12SJohn Marino1 10453ff40c12SJohn Marino<3>EXT-RADIO-WORK-START 1 10463ff40c12SJohn Marino> radio_work show 10473ff40c12SJohn Marinoext:test@wlan0:0:1:2.487797 10483ff40c12SJohn Marino> radio_work done 1 10493ff40c12SJohn MarinoOK 10503ff40c12SJohn Marino> radio_work show 10513ff40c12SJohn Marino 10523ff40c12SJohn Marino 10533ff40c12SJohn Marino> radio_work done 3 10543ff40c12SJohn MarinoOK 10553ff40c12SJohn Marino> radio_work show 10563ff40c12SJohn Marinoext:test freq=2412 timeout=30@wlan0:2412:1:28.583483 10573ff40c12SJohn Marino<3>EXT-RADIO-WORK-TIMEOUT 2 10583ff40c12SJohn Marino 10593ff40c12SJohn Marino 10603ff40c12SJohn Marino> radio_work add test2 freq=2412 timeout=60 10613ff40c12SJohn Marino5 10623ff40c12SJohn Marino<3>EXT-RADIO-WORK-START 5 10633ff40c12SJohn Marino> radio_work add test3 10643ff40c12SJohn Marino6 10653ff40c12SJohn Marino> radio_work add test4 10663ff40c12SJohn Marino7 10673ff40c12SJohn Marino> radio_work show 10683ff40c12SJohn Marinoext:test2 freq=2412 timeout=60@wlan0:2412:1:9.751844 10693ff40c12SJohn Marinoext:test3@wlan0:0:0:5.071812 10703ff40c12SJohn Marinoext:test4@wlan0:0:0:3.143870 10713ff40c12SJohn Marino> radio_work done 6 10723ff40c12SJohn MarinoOK 10733ff40c12SJohn Marino> radio_work show 10743ff40c12SJohn Marinoext:test2 freq=2412 timeout=60@wlan0:2412:1:16.287869 10753ff40c12SJohn Marinoext:test4@wlan0:0:0:9.679895 10763ff40c12SJohn Marino> radio_work done 5 10773ff40c12SJohn MarinoOK 10783ff40c12SJohn Marino<3>EXT-RADIO-WORK-START 7 10793ff40c12SJohn Marino<3>EXT-RADIO-WORK-TIMEOUT 7 1080