10e0f9c4cywpa_supplicant
2c164510sam==============
3c164510sam
40e0f9c4cyCopyright (c) 2003-2019, Jouni Malinen <j@w1.fi> and contributors
5c164510samAll Rights Reserved.
6c164510sam
75e9e13erpauloThis program is licensed under the BSD license (the one with
85e9e13erpauloadvertisement clause removed).
95e9e13erpaulo
105e9e13erpauloIf you are submitting changes to the project, please see CONTRIBUTIONS
115e9e13erpaulofile for more instructions.
12c164510sam
13c164510sam
14c164510sam
15c164510samLicense
16c164510sam-------
17c164510sam
185e9e13erpauloThis software may be distributed, used, and modified under the terms of
195e9e13erpauloBSD license:
20c164510sam
21c164510samRedistribution and use in source and binary forms, with or without
22c164510sammodification, are permitted provided that the following conditions are
23c164510sammet:
24c164510sam
25c164510sam1. Redistributions of source code must retain the above copyright
26c164510sam   notice, this list of conditions and the following disclaimer.
27c164510sam
28c164510sam2. Redistributions in binary form must reproduce the above copyright
29c164510sam   notice, this list of conditions and the following disclaimer in the
30c164510sam   documentation and/or other materials provided with the distribution.
31c164510sam
32c164510sam3. Neither the name(s) of the above-listed copyright holder(s) nor the
33c164510sam   names of its contributors may be used to endorse or promote products
34c164510sam   derived from this software without specific prior written permission.
35c164510sam
36c164510samTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
37c164510sam"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
38c164510samLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
39c164510samA PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
40c164510samOWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41c164510samSPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42c164510samLIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
43c164510samDATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
44c164510samTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
45c164510sam(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
46c164510samOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
47c164510sam
48c164510sam
49c164510sam
50c164510samFeatures
51c164510sam--------
52c164510sam
53c164510samSupported WPA/IEEE 802.11i features:
54c164510sam- WPA-PSK ("WPA-Personal")
55c164510sam- WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise")
56c164510sam  Following authentication methods are supported with an integrate IEEE 802.1X
57c164510sam  Supplicant:
58c164510sam  * EAP-TLS
59c164510sam  * EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)
60c164510sam  * EAP-PEAP/TLS (both PEAPv0 and PEAPv1)
61c164510sam  * EAP-PEAP/GTC (both PEAPv0 and PEAPv1)
62c164510sam  * EAP-PEAP/OTP (both PEAPv0 and PEAPv1)
63c164510sam  * EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)
64c164510sam  * EAP-TTLS/EAP-MD5-Challenge
65c164510sam  * EAP-TTLS/EAP-GTC
66c164510sam  * EAP-TTLS/EAP-OTP
67c164510sam  * EAP-TTLS/EAP-MSCHAPv2
68c164510sam  * EAP-TTLS/EAP-TLS
69c164510sam  * EAP-TTLS/MSCHAPv2
70c164510sam  * EAP-TTLS/MSCHAP
71c164510sam  * EAP-TTLS/PAP
72c164510sam  * EAP-TTLS/CHAP
73c164510sam  * EAP-SIM
74c164510sam  * EAP-AKA
7522c9018cy  * EAP-AKA'
76c164510sam  * EAP-PSK
77c164510sam  * EAP-PAX
78c164510sam  * EAP-SAKE
79c164510sam  * EAP-IKEv2
80c164510sam  * EAP-GPSK
8122c9018cy  * EAP-pwd
82c164510sam  * LEAP (note: requires special support from the driver for IEEE 802.11
83c164510sam	  authentication)
84c164510sam  (following methods are supported, but since they do not generate keying
85c164510sam   material, they cannot be used with WPA or IEEE 802.1X WEP keying)
868d61b8dcy  * EAP-MD5-Challenge
87c164510sam  * EAP-MSCHAPv2
88c164510sam  * EAP-GTC
89c164510sam  * EAP-OTP
90c164510sam- key management for CCMP, TKIP, WEP104, WEP40
91c164510sam- RSN/WPA2 (IEEE 802.11i)
92c164510sam  * pre-authentication
93c164510sam  * PMKSA caching
94c164510sam
95c164510samSupported TLS/crypto libraries:
96c164510sam- OpenSSL (default)
97c164510sam- GnuTLS
98c164510sam
99c164510samInternal TLS/crypto implementation (optional):
100c164510sam- can be used in place of an external TLS/crypto library
101c164510sam- TLSv1
102c164510sam- X.509 certificate processing
103c164510sam- PKCS #1
104c164510sam- ASN.1
105c164510sam- RSA
106c164510sam- bignum
107c164510sam- minimal size (ca. 50 kB binary, parts of which are already needed for WPA;
108c164510sam  TLSv1/X.509/ASN.1/RSA/bignum parts are about 25 kB on x86)
109c164510sam
110c164510sam
111c164510samRequirements
112c164510sam------------
113c164510sam
114c164510samCurrent hardware/software requirements:
115c164510sam- Linux kernel 2.4.x or 2.6.x with Linux Wireless Extensions v15 or newer
116c164510sam- FreeBSD 6-CURRENT
117c164510sam- NetBSD-current
118c164510sam- Microsoft Windows with WinPcap (at least WinXP, may work with other versions)
119c164510sam- drivers:
12030dc5aerpaulo	Linux drivers that support cfg80211/nl80211. Even though there are
121c164510sam	number of driver specific interface included in wpa_supplicant, please
12230dc5aerpaulo	note that Linux drivers are moving to use generic wireless configuration
12330dc5aerpaulo	interface driver_nl80211 (-Dnl80211 on wpa_supplicant command line)
12430dc5aerpaulo	should be the default option to start with before falling back to driver
12530dc5aerpaulo	specific interface.
12630dc5aerpaulo
12730dc5aerpaulo	Linux drivers that support WPA/WPA2 configuration with the generic
12830dc5aerpaulo	Linux wireless extensions (WE-18 or newer). Obsoleted by nl80211.
129c164510sam
130c164510sam	In theory, any driver that supports Linux wireless extensions can be
131c164510sam	used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in
132c164510sam	configuration file.
133c164510sam
134c164510sam	Wired Ethernet drivers (with ap_scan=0)
135c164510sam
136c164510sam	BSD net80211 layer (e.g., Atheros driver)
137c164510sam	At the moment, this is for FreeBSD 6-CURRENT branch and NetBSD-current.
138c164510sam
139c164510sam	Windows NDIS
140c164510sam	The current Windows port requires WinPcap (http://winpcap.polito.it/).
141c164510sam	See README-Windows.txt for more information.
142c164510sam
143c164510samwpa_supplicant was designed to be portable for different drivers and
144c164510samoperating systems. Hopefully, support for more wlan cards and OSes will be
145c164510samadded in the future. See developer's documentation
146c164510sam(http://hostap.epitest.fi/wpa_supplicant/devel/) for more information about the
147c164510samdesign of wpa_supplicant and porting to other drivers. One main goal
148c164510samis to add full WPA/WPA2 support to Linux wireless extensions to allow
149c164510samnew drivers to be supported without having to implement new
150c164510samdriver-specific interface code in wpa_supplicant.
151c164510sam
152c164510samOptional libraries for layer2 packet processing:
153c164510sam- libpcap (tested with 0.7.2, most relatively recent versions assumed to work,
154c164510sam	this is likely to be available with most distributions,
155c164510sam	http://tcpdump.org/)
156c164510sam- libdnet (tested with v1.4, most versions assumed to work,
157c164510sam	http://libdnet.sourceforge.net/)
158c164510sam
159c164510samThese libraries are _not_ used in the default Linux build. Instead,
160c164510saminternal Linux specific implementation is used. libpcap/libdnet are
161c164510sammore portable and they can be used by adding CONFIG_L2_PACKET=pcap into
162c164510sam.config. They may also be selected automatically for other operating
163c164510samsystems. In case of Windows builds, WinPcap is used by default
164c164510sam(CONFIG_L2_PACKET=winpcap).
165c164510sam
166c164510sam
167c164510samOptional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS:
16822c9018cy- OpenSSL (tested with 1.0.1 and 1.0.2 versions; assumed to
169c164510sam  work with most relatively recent versions; this is likely to be
170c164510sam  available with most distributions, http://www.openssl.org/)
171c164510sam- GnuTLS
172c164510sam- internal TLSv1 implementation
173c164510sam
174c164510samOne of these libraries is needed when EAP-TLS, EAP-PEAP, EAP-TTLS, or
175c164510samEAP-FAST support is enabled. WPA-PSK mode does not require this or EAPOL/EAP
176c164510samimplementation. A configuration file, .config, for compilation is
177c164510samneeded to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5,
178c164510samEAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so
179c164510samthey should only be enabled if testing the EAPOL/EAP state
180c164510sammachines. However, there can be used as inner authentication
181c164510samalgorithms with EAP-PEAP and EAP-TTLS.
182c164510sam
183c164510samSee Building and installing section below for more detailed
184c164510saminformation about the wpa_supplicant build time configuration.
185c164510sam
186c164510sam
187c164510sam
188c164510samWPA
189c164510sam---
190c164510sam
191c164510samThe original security mechanism of IEEE 802.11 standard was not
192c164510samdesigned to be strong and has proven to be insufficient for most
193c164510samnetworks that require some kind of security. Task group I (Security)
194c164510samof IEEE 802.11 working group (http://www.ieee802.org/11/) has worked
195c164510samto address the flaws of the base standard and has in practice
196c164510samcompleted its work in May 2004. The IEEE 802.11i amendment to the IEEE
197c164510sam802.11 standard was approved in June 2004 and published in July 2004.
198c164510sam
199c164510samWi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the
200c164510samIEEE 802.11i work (draft 3.0) to define a subset of the security
201c164510samenhancements that can be implemented with existing wlan hardware. This
202c164510samis called Wi-Fi Protected Access<TM> (WPA). This has now become a
203c164510sammandatory component of interoperability testing and certification done
204c164510samby Wi-Fi Alliance. Wi-Fi provides information about WPA at its web
205c164510samsite (http://www.wi-fi.org/OpenSection/protected_access.asp).
206c164510sam
207c164510samIEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm
208c164510samfor protecting wireless networks. WEP uses RC4 with 40-bit keys,
209c164510sam24-bit initialization vector (IV), and CRC32 to protect against packet
210c164510samforgery. All these choices have proven to be insufficient: key space is
211c164510samtoo small against current attacks, RC4 key scheduling is insufficient
212c164510sam(beginning of the pseudorandom stream should be skipped), IV space is
213c164510samtoo small and IV reuse makes attacks easier, there is no replay
214c164510samprotection, and non-keyed authentication does not protect against bit
215c164510samflipping packet data.
216c164510sam
217c164510samWPA is an intermediate solution for the security issues. It uses
218c164510samTemporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a
219c164510samcompromise on strong security and possibility to use existing
220c164510samhardware. It still uses RC4 for the encryption like WEP, but with
221c164510samper-packet RC4 keys. In addition, it implements replay protection,
222c164510samkeyed packet authentication mechanism (Michael MIC).
223c164510sam
224c164510samKeys can be managed using two different mechanisms. WPA can either use
225c164510saman external authentication server (e.g., RADIUS) and EAP just like
226c164510samIEEE 802.1X is using or pre-shared keys without need for additional
227c164510samservers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",
228c164510samrespectively. Both mechanisms will generate a master session key for
229c164510samthe Authenticator (AP) and Supplicant (client station).
230c164510sam
231c164510samWPA implements a new key handshake (4-Way Handshake and Group Key
232c164510samHandshake) for generating and exchanging data encryption keys between
233c164510samthe Authenticator and Supplicant. This handshake is also used to
234c164510samverify that both Authenticator and Supplicant know the master session
235c164510samkey. These handshakes are identical regardless of the selected key
236c164510sammanagement mechanism (only the method for generating master session
237c164510samkey changes).
238c164510sam
239c164510sam
240c164510sam
241c164510samIEEE 802.11i / WPA2
242c164510sam-------------------
243c164510sam
244c164510samThe design for parts of IEEE 802.11i that were not included in WPA has
245c164510samfinished (May 2004) and this amendment to IEEE 802.11 was approved in
246c164510samJune 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new
247c164510samversion of WPA called WPA2. This includes, e.g., support for more
248c164510samrobust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
249c164510samto replace TKIP and optimizations for handoff (reduced number of
250c164510sammessages in initial key handshake, pre-authentication, and PMKSA caching).
251c164510sam
252c164510sam
253c164510sam
254c164510samwpa_supplicant
255c164510sam--------------
256c164510sam
257c164510samwpa_supplicant is an implementation of the WPA Supplicant component,
258c164510sami.e., the part that runs in the client stations. It implements WPA key
259c164510samnegotiation with a WPA Authenticator and EAP authentication with
260c164510samAuthentication Server. In addition, it controls the roaming and IEEE
261c164510sam802.11 authentication/association of the wlan driver.
262c164510sam
263c164510samwpa_supplicant is designed to be a "daemon" program that runs in the
264c164510sambackground and acts as the backend component controlling the wireless
265c164510samconnection. wpa_supplicant supports separate frontend programs and an
266c164510samexample text-based frontend, wpa_cli, is included with wpa_supplicant.
267c164510sam
268c164510samFollowing steps are used when associating with an AP using WPA:
269c164510sam
270c164510sam- wpa_supplicant requests the kernel driver to scan neighboring BSSes
271c164510sam- wpa_supplicant selects a BSS based on its configuration
272c164510sam- wpa_supplicant requests the kernel driver to associate with the chosen
273c164510sam  BSS
274c164510sam- If WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP
275c164510sam  authentication with the authentication server (proxied by the
276c164510sam  Authenticator in the AP)
277c164510sam- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant
278c164510sam- If WPA-PSK: wpa_supplicant uses PSK as the master session key
279c164510sam- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake
280c164510sam  with the Authenticator (AP)
281c164510sam- wpa_supplicant configures encryption keys for unicast and broadcast
282c164510sam- normal data packets can be transmitted and received
283c164510sam
284c164510sam
285c164510sam
286c164510samBuilding and installing
287c164510sam-----------------------
288c164510sam
289c164510samIn order to be able to build wpa_supplicant, you will first need to
290c164510samselect which parts of it will be included. This is done by creating a
291c164510sambuild time configuration file, .config, in the wpa_supplicant root
292c164510samdirectory. Configuration options are text lines using following
293c164510samformat: CONFIG_<option>=y. Lines starting with # are considered
294c164510samcomments and are ignored. See defconfig file for an example configuration
295c164510samand a list of available options and additional notes.
296c164510sam
297c164510samThe build time configuration can be used to select only the needed
298c164510samfeatures and limit the binary size and requirements for external
299c164510samlibraries. The main configuration parts are the selection of which
3005e9e13erpaulodriver interfaces (e.g., nl80211, wext, ..) and which authentication
301c164510sammethods (e.g., EAP-TLS, EAP-PEAP, ..) are included.
302c164510sam
303c164510samFollowing build time configuration options are used to control IEEE
304c164510sam802.1X/EAPOL and EAP state machines and all EAP methods. Including
305c164510samTLS, PEAP, or TTLS will require linking wpa_supplicant with OpenSSL
306c164510samlibrary for TLS implementation. Alternatively, GnuTLS or the internal
30722c9018cyTLSv1 implementation can be used for TLS functionality.
308c164510sam
309c164510samCONFIG_IEEE8021X_EAPOL=y
310c164510samCONFIG_EAP_MD5=y
311c164510samCONFIG_EAP_MSCHAPV2=y
312c164510samCONFIG_EAP_TLS=y
313c164510samCONFIG_EAP_PEAP=y
314c164510samCONFIG_EAP_TTLS=y
315c164510samCONFIG_EAP_GTC=y
316c164510samCONFIG_EAP_OTP=y
317c164510samCONFIG_EAP_SIM=y
318c164510samCONFIG_EAP_AKA=y
31922c9018cyCONFIG_EAP_AKA_PRIME=y
320c164510samCONFIG_EAP_PSK=y
321c164510samCONFIG_EAP_SAKE=y
322c164510samCONFIG_EAP_GPSK=y
323c164510samCONFIG_EAP_PAX=y
324c164510samCONFIG_EAP_LEAP=y
325c164510samCONFIG_EAP_IKEV2=y
32622c9018cyCONFIG_EAP_PWD=y
327c164510sam
328c164510samFollowing option can be used to include GSM SIM/USIM interface for GSM/UMTS
32922c9018cyauthentication algorithm (for EAP-SIM/EAP-AKA/EAP-AKA'). This requires pcsc-lite
330c164510sam(http://www.linuxnet.com/) for smart card access.
331c164510sam
332c164510samCONFIG_PCSC=y
333c164510sam
334c164510samFollowing options can be added to .config to select which driver
3355e9e13erpaulointerfaces are included.
336c164510sam
3375e9e13erpauloCONFIG_DRIVER_NL80211=y
338c164510samCONFIG_DRIVER_WEXT=y
339c164510samCONFIG_DRIVER_BSD=y
340c164510samCONFIG_DRIVER_NDIS=y
341c164510sam
3425e9e13erpauloFollowing example includes some more features and driver interfaces that
3435e9e13erpauloare included in the wpa_supplicant package:
344c164510sam
3455e9e13erpauloCONFIG_DRIVER_NL80211=y
346c164510samCONFIG_DRIVER_WEXT=y
347c164510samCONFIG_DRIVER_BSD=y
348c164510samCONFIG_DRIVER_NDIS=y
349c164510samCONFIG_IEEE8021X_EAPOL=y
350c164510samCONFIG_EAP_MD5=y
351c164510samCONFIG_EAP_MSCHAPV2=y
352c164510samCONFIG_EAP_TLS=y
353c164510samCONFIG_EAP_PEAP=y
354c164510samCONFIG_EAP_TTLS=y
355c164510samCONFIG_EAP_GTC=y
356c164510samCONFIG_EAP_OTP=y
357c164510samCONFIG_EAP_SIM=y
358c164510samCONFIG_EAP_AKA=y
359c164510samCONFIG_EAP_PSK=y
360c164510samCONFIG_EAP_SAKE=y
361c164510samCONFIG_EAP_GPSK=y
362c164510samCONFIG_EAP_PAX=y
363c164510samCONFIG_EAP_LEAP=y
364c164510samCONFIG_EAP_IKEV2=y
365c164510samCONFIG_PCSC=y
366c164510sam
367c164510samEAP-PEAP and EAP-TTLS will automatically include configured EAP
368c164510sammethods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection.
369c164510sam
370c164510sam
371c164510samAfter you have created a configuration file, you can build
372c164510samwpa_supplicant and wpa_cli with 'make' command. You may then install
373c164510samthe binaries to a suitable system directory, e.g., /usr/local/bin.
374c164510sam
375c164510samExample commands:
376c164510sam
377c164510sam# build wpa_supplicant and wpa_cli
378c164510sammake
379c164510sam# install binaries (this may need root privileges)
380c164510samcp wpa_cli wpa_supplicant /usr/local/bin
381c164510sam
382c164510sam
383c164510samYou will need to make a configuration file, e.g.,
384c164510sam/etc/wpa_supplicant.conf, with network configuration for the networks
385c164510samyou are going to use. Configuration file section below includes
386c164510samexplanation fo the configuration file format and includes various
387c164510samexamples. Once the configuration is ready, you can test whether the
388c164510samconfiguration work by first running wpa_supplicant with following
389c164510samcommand to start it on foreground with debugging enabled:
390c164510sam
391c164510samwpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
392c164510sam
393c164510samAssuming everything goes fine, you can start using following command
394c164510samto start wpa_supplicant on background without debugging:
395c164510sam
396c164510samwpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
397c164510sam
398c164510samPlease note that if you included more than one driver interface in the
399c164510sambuild time configuration (.config), you may need to specify which
400c164510saminterface to use by including -D<driver name> option on the command
401c164510samline. See following section for more details on command line options
402c164510samfor wpa_supplicant.
403c164510sam
404c164510sam
405c164510sam
406c164510samCommand line options
407c164510sam--------------------
408c164510sam
409c164510samusage:
41022c9018cy  wpa_supplicant [-BddfhKLqqtuvW] [-P<pid file>] [-g<global ctrl>] \
41130dc5aerpaulo        [-G<group>] \
412c164510sam        -i<ifname> -c<config file> [-C<ctrl>] [-D<driver>] [-p<driver_param>] \
41322c9018cy        [-b<br_ifname> [-MN -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] \
41430dc5aerpaulo        [-p<driver_param>] [-b<br_ifname>] [-m<P2P Device config file>] ...
415c164510sam
416c164510samoptions:
417c164510sam  -b = optional bridge interface name
418c164510sam  -B = run daemon in the background
419c164510sam  -c = Configuration file
420c164510sam  -C = ctrl_interface parameter (only used if -c is not)
421c164510sam  -i = interface name
422c164510sam  -d = increase debugging verbosity (-dd even more)
4234dc7b76rpaulo  -D = driver name (can be multiple drivers: nl80211,wext)
424c164510sam  -f = Log output to default log location (normally /tmp)
425c164510sam  -g = global ctrl_interface
42630dc5aerpaulo  -G = global ctrl_interface group
427c164510sam  -K = include keys (passwords, etc.) in debug output
428c164510sam  -t = include timestamp in debug messages
429c164510sam  -h = show this help text
4305e9e13erpaulo  -L = show license (BSD)
431c164510sam  -p = driver parameters
432c164510sam  -P = PID file
433c164510sam  -q = decrease debugging verbosity (-qq even less)
434c164510sam  -u = enable DBus control interface
435c164510sam  -v = show version
436c164510sam  -W = wait for a control interface monitor before starting
43722c9018cy  -M = start describing matching interface
438c164510sam  -N = start describing new interface
43930dc5aerpaulo  -m = Configuration file for the P2P Device
440c164510sam
441c164510samdrivers:
44230dc5aerpaulo  nl80211 = Linux nl80211/cfg80211
443c164510sam  wext = Linux wireless extensions (generic)
444c164510sam  wired = wpa_supplicant wired Ethernet driver
445c164510sam  roboswitch = wpa_supplicant Broadcom switch driver
446c164510sam  bsd = BSD 802.11 support (Atheros, etc.)
447c164510sam  ndis = Windows NDIS driver
448c164510sam
449c164510samIn most common cases, wpa_supplicant is started with
450c164510sam
451c164510samwpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0
452c164510sam
453c164510samThis makes the process fork into background.
454c164510sam
455c164510samThe easiest way to debug problems, and to get debug log for bug
456c164510samreports, is to start wpa_supplicant on foreground with debugging
457c164510samenabled:
458c164510sam
459c164510samwpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
460c164510sam
4614dc7b76rpauloIf the specific driver wrapper is not known beforehand, it is possible
4624dc7b76rpauloto specify multiple comma separated driver wrappers on the command
4634dc7b76rpauloline. wpa_supplicant will use the first driver wrapper that is able to
4644dc7b76rpauloinitialize the interface.
4654dc7b76rpaulo
4664dc7b76rpaulowpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0
4674dc7b76rpaulo
468c164510sam
469c164510samwpa_supplicant can control multiple interfaces (radios) either by
470c164510samrunning one process for each interface separately or by running just
471c164510samone process and list of options at command line. Each interface is
472c164510samseparated with -N argument. As an example, following command would
473c164510samstart wpa_supplicant for two interfaces:
474c164510sam
475c164510samwpa_supplicant \
4765e9e13erpaulo	-c wpa1.conf -i wlan0 -D nl80211 -N \
4775e9e13erpaulo	-c wpa2.conf -i wlan1 -D wext
478c164510sam
479c164510sam
48022c9018cyIf the interfaces on which wpa_supplicant is to run are not known or do
48122c9018cynot exist, wpa_supplicant can match an interface when it arrives. Each
48222c9018cymatched interface is separated with -M argument and the -i argument now
48322c9018cyallows for pattern matching.
48422c9018cy
48522c9018cyAs an example, the following command would start wpa_supplicant for a
48622c9018cyspecific wired interface called lan0, any interface starting with wlan
48722c9018cyand lastly any other interface. Each match has its own configuration
48822c9018cyfile, and for the wired interface a specific driver has also been given.
48922c9018cy
49022c9018cywpa_supplicant \
49122c9018cy	-M -c wpa_wired.conf -ilan0 -D wired \
49222c9018cy	-M -c wpa1.conf -iwlan* \
49322c9018cy	-M -c wpa2.conf
49422c9018cy
49522c9018cy
496c164510samIf the interface is added in a Linux bridge (e.g., br0), the bridge
497c164510saminterface needs to be configured to wpa_supplicant in addition to the
498c164510sammain interface:
499c164510sam
50030dc5aerpaulowpa_supplicant -cw.conf -Dnl80211 -iwlan0 -bbr0
501c164510sam
502c164510sam
503c164510samConfiguration file
504c164510sam------------------
505c164510sam
506c164510samwpa_supplicant is configured using a text file that lists all accepted
507c164510samnetworks and security policies, including pre-shared keys. See
508c164510samexample configuration file, wpa_supplicant.conf, for detailed
509c164510saminformation about the configuration format and supported fields.
510c164510sam
511c164510samChanges to configuration file can be reloaded be sending SIGHUP signal
512c164510samto wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly,
513c164510samreloading can be triggered with 'wpa_cli reconfigure' command.
514c164510sam
515c164510samConfiguration file can include one or more network blocks, e.g., one
516c164510samfor each used SSID. wpa_supplicant will automatically select the best
51722c9018cynetwork based on the order of network blocks in the configuration
518c164510samfile, network security level (WPA/WPA2 is preferred), and signal
519c164510samstrength.
520c164510sam
521c164510samExample configuration files for some common configurations:
522c164510sam
523c164510sam1) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work
524c164510sam   network
525c164510sam
526c164510sam# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
527c164510samctrl_interface=/var/run/wpa_supplicant
528c164510samctrl_interface_group=wheel
529c164510sam#
530c164510sam# home network; allow all valid ciphers
531c164510samnetwork={
532c164510sam	ssid="home"
533c164510sam	scan_ssid=1
534c164510sam	key_mgmt=WPA-PSK
535c164510sam	psk="very secret passphrase"
536c164510sam}
537c164510sam#
538c164510sam# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
539c164510samnetwork={
540c164510sam	ssid="work"
541c164510sam	scan_ssid=1
542c164510sam	key_mgmt=WPA-EAP
543c164510sam	pairwise=CCMP TKIP
544c164510sam	group=CCMP TKIP
545c164510sam	eap=TLS
546c164510sam	identity="user@example.com"
547c164510sam	ca_cert="/etc/cert/ca.pem"
548c164510sam	client_cert="/etc/cert/user.pem"
549c164510sam	private_key="/etc/cert/user.prv"
550c164510sam	private_key_passwd="password"
551c164510sam}
552c164510sam
553c164510sam
554c164510sam2) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
555c164510sam   (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series)
556c164510sam
557c164510samctrl_interface=/var/run/wpa_supplicant
558c164510samctrl_interface_group=wheel
559c164510samnetwork={
560c164510sam	ssid="example"
561c164510sam	scan_ssid=1
562c164510sam	key_mgmt=WPA-EAP
563c164510sam	eap=PEAP
564c164510sam	identity="user@example.com"
565c164510sam	password="foobar"
566c164510sam	ca_cert="/etc/cert/ca.pem"
567c164510sam	phase1="peaplabel=0"
568c164510sam	phase2="auth=MSCHAPV2"
569c164510sam}
570c164510sam
571c164510sam
572c164510sam3) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
573c164510sam   unencrypted use. Real identity is sent only within an encrypted TLS tunnel.
574c164510sam
575c164510samctrl_interface=/var/run/wpa_supplicant
576c164510samctrl_interface_group=wheel
577c164510samnetwork={
578c164510sam	ssid="example"
579c164510sam	scan_ssid=1
580c164510sam	key_mgmt=WPA-EAP
581c164510sam	eap=TTLS
582c164510sam	identity="user@example.com"
583c164510sam	anonymous_identity="anonymous@example.com"
584c164510sam	password="foobar"
585c164510sam	ca_cert="/etc/cert/ca.pem"
586c164510sam	phase2="auth=MD5"
587c164510sam}
588c164510sam
589c164510sam
590c164510sam4) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and
591c164510sam   broadcast); use EAP-TLS for authentication
592c164510sam
593c164510samctrl_interface=/var/run/wpa_supplicant
594c164510samctrl_interface_group=wheel
595c164510samnetwork={
596c164510sam	ssid="1x-test"
597c164510sam	scan_ssid=1
598c164510sam	key_mgmt=IEEE8021X
599c164510sam	eap=TLS
600c164510sam	identity="user@example.com"
601c164510sam	ca_cert="/etc/cert/ca.pem"
602c164510sam	client_cert="/etc/cert/user.pem"
603c164510sam	private_key="/etc/cert/user.prv"
604c164510sam	private_key_passwd="password"
605c164510sam	eapol_flags=3
606c164510sam}
607c164510sam
608c164510sam
609c164510sam5) Catch all example that allows more or less all configuration modes. The
610c164510sam   configuration options are used based on what security policy is used in the
611c164510sam   selected SSID. This is mostly for testing and is not recommended for normal
612c164510sam   use.
613c164510sam
614c164510samctrl_interface=/var/run/wpa_supplicant
615c164510samctrl_interface_group=wheel
616c164510samnetwork={
617c164510sam	ssid="example"
618c164510sam	scan_ssid=1
619c164510sam	key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
620c164510sam	pairwise=CCMP TKIP
621c164510sam	group=CCMP TKIP WEP104 WEP40
622c164510sam	psk="very secret passphrase"
623c164510sam	eap=TTLS PEAP TLS
624c164510sam	identity="user@example.com"
625c164510sam	password="foobar"
626c164510sam	ca_cert="/etc/cert/ca.pem"
627c164510sam	client_cert="/etc/cert/user.pem"
628c164510sam	private_key="/etc/cert/user.prv"
629c164510sam	private_key_passwd="password"
630c164510sam	phase1="peaplabel=0"
631c164510sam	ca_cert2="/etc/cert/ca2.pem"
632c164510sam	client_cert2="/etc/cer/user.pem"
633c164510sam	private_key2="/etc/cer/user.prv"
634c164510sam	private_key2_passwd="password"
635c164510sam}
636c164510sam
637c164510sam
638c164510sam6) Authentication for wired Ethernet. This can be used with 'wired' or
639c164510sam   'roboswitch' interface (-Dwired or -Droboswitch on command line).
640c164510sam
641c164510samctrl_interface=/var/run/wpa_supplicant
642c164510samctrl_interface_group=wheel
643c164510samap_scan=0
644c164510samnetwork={
645c164510sam	key_mgmt=IEEE8021X
646c164510sam	eap=MD5
647c164510sam	identity="user"
648c164510sam	password="password"
649c164510sam	eapol_flags=0
650c164510sam}
651c164510sam
652c164510sam
653c164510sam
654c164510samCertificates
655c164510sam------------
656c164510sam
657c164510samSome EAP authentication methods require use of certificates. EAP-TLS
658c164510samuses both server side and client certificates whereas EAP-PEAP and
659c164510samEAP-TTLS only require the server side certificate. When client
660c164510samcertificate is used, a matching private key file has to also be
661c164510samincluded in configuration. If the private key uses a passphrase, this
662c164510samhas to be configured in wpa_supplicant.conf ("private_key_passwd").
663c164510sam
664c164510samwpa_supplicant supports X.509 certificates in PEM and DER
665c164510samformats. User certificate and private key can be included in the same
666c164510samfile.
667c164510sam
668c164510samIf the user certificate and private key is received in PKCS#12/PFX
669c164510samformat, they need to be converted to suitable PEM/DER format for
670c164510samwpa_supplicant. This can be done, e.g., with following commands:
671c164510sam
672c164510sam# convert client certificate and private key to PEM format
673c164510samopenssl pkcs12 -in example.pfx -out user.pem -clcerts
674c164510sam# convert CA certificate (if included in PFX file) to PEM format
675c164510samopenssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
676c164510sam
677c164510sam
678c164510sam
679c164510samwpa_cli
680c164510sam-------
681c164510sam
682c164510samwpa_cli is a text-based frontend program for interacting with
683c164510samwpa_supplicant. It is used to query current status, change
684c164510samconfiguration, trigger events, and request interactive user input.
685c164510sam
686c164510samwpa_cli can show the current authentication status, selected security
687c164510sammode, dot11 and dot1x MIBs, etc. In addition, it can configure some
688c164510samvariables like EAPOL state machine parameters and trigger events like
689c164510samreassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user
690c164510saminterface to request authentication information, like username and
691c164510sampassword, if these are not included in the configuration. This can be
692c164510samused to implement, e.g., one-time-passwords or generic token card
693c164510samauthentication where the authentication is based on a
694c164510samchallenge-response that uses an external device for generating the
695c164510samresponse.
696c164510sam
697c164510samThe control interface of wpa_supplicant can be configured to allow
698c164510samnon-root user access (ctrl_interface_group in the configuration
699c164510samfile). This makes it possible to run wpa_cli with a normal user
700c164510samaccount.
701c164510sam
702c164510samwpa_cli supports two modes: interactive and command line. Both modes
703c164510samshare the same command set and the main difference is in interactive
704c164510sammode providing access to unsolicited messages (event messages,
705c164510samusername/password requests).
706c164510sam
707c164510samInteractive mode is started when wpa_cli is executed without including
708c164510samthe command as a command line parameter. Commands are then entered on
709c164510samthe wpa_cli prompt. In command line mode, the same commands are
710c164510samentered as command line arguments for wpa_cli.
711c164510sam
712c164510sam
713c164510samInteractive authentication parameters request
714c164510sam
715c164510samWhen wpa_supplicant need authentication parameters, like username and
716c164510sampassword, which are not present in the configuration file, it sends a
717c164510samrequest message to all attached frontend programs, e.g., wpa_cli in
718c164510saminteractive mode. wpa_cli shows these requests with
719c164510sam"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or
720c164510samOTP (one-time-password). <id> is a unique identifier for the current
721c164510samnetwork. <text> is description of the request. In case of OTP request,
722c164510samit includes the challenge from the authentication server.
723c164510sam
724c164510samThe reply to these requests can be given with 'identity', 'password',
725c164510samand 'otp' commands. <id> needs to be copied from the the matching
726c164510samrequest. 'password' and 'otp' commands can be used regardless of
727c164510samwhether the request was for PASSWORD or OTP. The main difference
728c164510sambetween these two commands is that values given with 'password' are
729c164510samremembered as long as wpa_supplicant is running whereas values given
730c164510samwith 'otp' are used only once and then forgotten, i.e., wpa_supplicant
731c164510samwill ask frontend for a new value for every use. This can be used to
732c164510samimplement one-time-password lists and generic token card -based
733c164510samauthentication.
734c164510sam
735c164510samExample request for password and a matching reply:
736c164510sam
737c164510samCTRL-REQ-PASSWORD-1:Password needed for SSID foobar
738c164510sam> password 1 mysecretpassword
739c164510sam
740c164510samExample request for generic token card challenge-response:
741c164510sam
742c164510samCTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
743c164510sam> otp 2 9876
744c164510sam
745c164510sam
746c164510samwpa_cli commands
747c164510sam
748c164510sam  status = get current WPA/EAPOL/EAP status
749c164510sam  mib = get MIB variables (dot1x, dot11)
750c164510sam  help = show this usage help
751c164510sam  interface [ifname] = show interfaces/select interface
752c164510sam  level <debug level> = change debug level
753c164510sam  license = show full wpa_cli license
754c164510sam  logoff = IEEE 802.1X EAPOL state machine logoff
755c164510sam  logon = IEEE 802.1X EAPOL state machine logon
756c164510sam  set = set variables (shows list of variables when run without arguments)
757c164510sam  pmksa = show PMKSA cache
758c164510sam  reassociate = force reassociation
759c164510sam  reconfigure = force wpa_supplicant to re-read its configuration file
760c164510sam  preauthenticate <BSSID> = force preauthentication
761c164510sam  identity <network id> <identity> = configure identity for an SSID
762c164510sam  password <network id> <password> = configure password for an SSID
763c164510sam  pin <network id> <pin> = configure pin for an SSID
764c164510sam  otp <network id> <password> = configure one-time-password for an SSID
765c164510sam  passphrase <network id> <passphrase> = configure private key passphrase
766c164510sam    for an SSID
767c164510sam  bssid <network id> <BSSID> = set preferred BSSID for an SSID
768c164510sam  list_networks = list configured networks
769c164510sam  select_network <network id> = select a network (disable others)
770c164510sam  enable_network <network id> = enable a network
771c164510sam  disable_network <network id> = disable a network
772c164510sam  add_network = add a network
773c164510sam  remove_network <network id> = remove a network
774c164510sam  set_network <network id> <variable> <value> = set network variables (shows
775c164510sam    list of variables when run without arguments)
776c164510sam  get_network <network id> <variable> = get network variables
777c164510sam  save_config = save the current configuration
778c164510sam  disconnect = disconnect and wait for reassociate command before connecting
779c164510sam  scan = request new BSS scan
780c164510sam  scan_results = get latest scan results
781c164510sam  get_capability <eap/pairwise/group/key_mgmt/proto/auth_alg> = get capabilies
782c164510sam  terminate = terminate wpa_supplicant
783c164510sam  quit = exit wpa_cli
784c164510sam
785c164510sam
786c164510samwpa_cli command line options
787c164510sam
788c164510samwpa_cli [-p<path to ctrl sockets>] [-i<ifname>] [-hvB] [-a<action file>] \
789c164510sam        [-P<pid file>] [-g<global ctrl>]  [command..]
790c164510sam  -h = help (show this usage text)
791c164510sam  -v = shown version information
792c164510sam  -a = run in daemon mode executing the action file based on events from
793c164510sam       wpa_supplicant
794c164510sam  -B = run a daemon in the background
795c164510sam  default path: /var/run/wpa_supplicant
796c164510sam  default interface: first interface found in socket path
797c164510sam
798c164510sam
799c164510samUsing wpa_cli to run external program on connect/disconnect
800c164510sam-----------------------------------------------------------
801c164510sam
802c164510samwpa_cli can used to run external programs whenever wpa_supplicant
803c164510samconnects or disconnects from a network. This can be used, e.g., to
804c164510samupdate network configuration and/or trigget DHCP client to update IP
805c164510samaddresses, etc.
806c164510sam
807c164510samOne wpa_cli process in "action" mode needs to be started for each
808c164510saminterface. For example, the following command starts wpa_cli for the
80922c9018cydefault interface (-i can be used to select the interface in case of
810c164510sammore than one interface being used at the same time):
811c164510sam
812c164510samwpa_cli -a/sbin/wpa_action.sh -B
813c164510sam
814c164510samThe action file (-a option, /sbin/wpa_action.sh in this example) will
815c164510sambe executed whenever wpa_supplicant completes authentication (connect
816c164510samevent) or detects disconnection). The action script will be called
817c164510samwith two command line arguments: interface name and event (CONNECTED
818c164510samor DISCONNECTED). If the action script needs to get more information
819c164510samabout the current network, it can use 'wpa_cli status' to query
820c164510samwpa_supplicant for more information.
821c164510sam
822c164510samFollowing example can be used as a simple template for an action
823c164510samscript:
824c164510sam
825c164510sam#!/bin/sh
826c164510sam
827c164510samIFNAME=$1
828c164510samCMD=$2
829c164510sam
8305e9e13erpauloif [ "$CMD" = "CONNECTED" ]; then
831c164510sam    SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=`
832c164510sam    # configure network, signal DHCP client, etc.
833c164510samfi
834c164510sam
8355e9e13erpauloif [ "$CMD" = "DISCONNECTED" ]; then
836c164510sam    # remove network configuration, if needed
8375e9e13erpaulo    SSID=
838c164510samfi
839c164510sam
840c164510sam
841c164510sam
842c164510samIntegrating with pcmcia-cs/cardmgr scripts
843c164510sam------------------------------------------
844c164510sam
845c164510samwpa_supplicant needs to be running when using a wireless network with
846c164510samWPA. It can be started either from system startup scripts or from
847c164510sampcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be
848c164510samcompleted before data frames can be exchanged, so wpa_supplicant
849c164510samshould be started before DHCP client.
850c164510sam
851c164510samFor example, following small changes to pcmcia-cs scripts can be used
852c164510samto enable WPA support:
853c164510sam
854c164510samAdd MODE="Managed" and WPA="y" to the network scheme in
855c164510sam/etc/pcmcia/wireless.opts.
856c164510sam
857c164510samAdd the following block to the end of 'start' action handler in
858c164510sam/etc/pcmcia/wireless:
859c164510sam
860c164510sam    if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
861c164510sam	/usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf \
862c164510sam		-i$DEVICE
863c164510sam    fi
864c164510sam
865c164510samAdd the following block to the end of 'stop' action handler (may need
866c164510samto be separated from other actions) in /etc/pcmcia/wireless:
867c164510sam
868c164510sam    if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
869c164510sam	killall wpa_supplicant
870c164510sam    fi
871c164510sam
872c164510samThis will make cardmgr start wpa_supplicant when the card is plugged
873c164510samin.
874c164510sam
875c164510sam
876c164510sam
877c164510samDynamic interface add and operation without configuration files
878c164510sam---------------------------------------------------------------
879c164510sam
880c164510samwpa_supplicant can be started without any configuration files or
881c164510samnetwork interfaces. When used in this way, a global (i.e., per
882c164510samwpa_supplicant process) control interface is used to add and remove
883c164510samnetwork interfaces. Each network interface can then be configured
884c164510samthrough a per-network interface control interface. For example,
885c164510samfollowing commands show how to start wpa_supplicant without any
886c164510samnetwork interfaces and then add a network interface and configure a
887c164510samnetwork (SSID):
888c164510sam
889c164510sam# Start wpa_supplicant in the background
890c164510samwpa_supplicant -g/var/run/wpa_supplicant-global -B
891c164510sam
89230dc5aerpaulo# Add a new interface (wlan0, no configuration file, driver=nl80211, and
893c164510sam# enable control interface)
894c164510samwpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \
89530dc5aerpaulo	"" nl80211 /var/run/wpa_supplicant
896c164510sam
897c164510sam# Configure a network using the newly added network interface:
898c164510samwpa_cli -iwlan0 add_network
899c164510samwpa_cli -iwlan0 set_network 0 ssid '"test"'
900c164510samwpa_cli -iwlan0 set_network 0 key_mgmt WPA-PSK
901c164510samwpa_cli -iwlan0 set_network 0 psk '"12345678"'
902c164510samwpa_cli -iwlan0 set_network 0 pairwise TKIP
903c164510samwpa_cli -iwlan0 set_network 0 group TKIP
904c164510samwpa_cli -iwlan0 set_network 0 proto WPA
905c164510samwpa_cli -iwlan0 enable_network 0
906c164510sam
907c164510sam# At this point, the new network interface should start trying to associate
908c164510sam# with the WPA-PSK network using SSID test.
909c164510sam
910c164510sam# Remove network interface
911c164510samwpa_cli -g/var/run/wpa_supplicant-global interface_remove wlan0
912c164510sam
913c164510sam
914c164510samPrivilege separation
915c164510sam--------------------
916c164510sam
917c164510samTo minimize the size of code that needs to be run with root privileges
918c164510sam(e.g., to control wireless interface operation), wpa_supplicant
919c164510samsupports optional privilege separation. If enabled, this separates the
920c164510samprivileged operations into a separate process (wpa_priv) while leaving
921c164510samrest of the code (e.g., EAP authentication and WPA handshakes) into an
922c164510samunprivileged process (wpa_supplicant) that can be run as non-root
923c164510samuser. Privilege separation restricts the effects of potential software
924c164510samerrors by containing the majority of the code in an unprivileged
925c164510samprocess to avoid full system compromise.
926c164510sam
927c164510samPrivilege separation is not enabled by default and it can be enabled
928c164510samby adding CONFIG_PRIVSEP=y to the build configuration (.config). When
929c164510samenabled, the privileged operations (driver wrapper and l2_packet) are
930c164510samlinked into a separate daemon program, wpa_priv. The unprivileged
931c164510samprogram, wpa_supplicant, will be built with a special driver/l2_packet
932c164510samwrappers that communicate with the privileged wpa_priv process to
933c164510samperform the needed operations. wpa_priv can control what privileged
934c164510samare allowed.
935c164510sam
936c164510samwpa_priv needs to be run with network admin privileges (usually, root
937c164510samuser). It opens a UNIX domain socket for each interface that is
938c164510samincluded on the command line; any other interface will be off limits
939c164510samfor wpa_supplicant in this kind of configuration. After this,
940c164510samwpa_supplicant can be run as a non-root user (e.g., all standard users
941c164510samon a laptop or as a special non-privileged user account created just
942c164510samfor this purpose to limit access to user files even further).
943c164510sam
944c164510sam
945c164510samExample configuration:
946c164510sam- create user group for users that are allowed to use wpa_supplicant
947c164510sam  ('wpapriv' in this example) and assign users that should be able to
948c164510sam  use wpa_supplicant into that group
949c164510sam- create /var/run/wpa_priv directory for UNIX domain sockets and control
950c164510sam  user access by setting it accessible only for the wpapriv group:
951c164510sam  mkdir /var/run/wpa_priv
952c164510sam  chown root:wpapriv /var/run/wpa_priv
953c164510sam  chmod 0750 /var/run/wpa_priv
954c164510sam- start wpa_priv as root (e.g., from system startup scripts) with the
955c164510sam  enabled interfaces configured on the command line:
95630dc5aerpaulo  wpa_priv -B -P /var/run/wpa_priv.pid nl80211:wlan0
957c164510sam- run wpa_supplicant as non-root with a user that is in wpapriv group:
958c164510sam  wpa_supplicant -i ath0 -c wpa_supplicant.conf
959c164510sam
960c164510samwpa_priv does not use the network interface before wpa_supplicant is
961c164510samstarted, so it is fine to include network interfaces that are not
962c164510samavailable at the time wpa_priv is started. As an alternative, wpa_priv
963c164510samcan be started when an interface is added (hotplug/udev/etc. scripts).
964c164510samwpa_priv can control multiple interface with one process, but it is
965c164510samalso possible to run multiple wpa_priv processes at the same time, if
966c164510samdesired.
96730dc5aerpaulo
9688d61b8dcyIt should be noted that the interface used between wpa_supplicant and
9698d61b8dcywpa_priv does not include all the capabilities of the wpa_supplicant
9708d61b8dcydriver interface and at times, this interface lacks update especially
9718d61b8dcyfor recent addition. Consequently, use of wpa_priv does come with the
9728d61b8dcyprice of somewhat reduced available functionality. The next section
9738d61b8dcydescribing how wpa_supplicant can be used with reduced privileges
9748d61b8dcywithout having to handle the complexity of separate wpa_priv. While that
9758d61b8dcyapprove does not provide separation for network admin capabilities, it
9768d61b8dcydoes allow other root privileges to be dropped without the drawbacks of
9778d61b8dcythe wpa_priv process.
9788d61b8dcy
97930dc5aerpaulo
98030dc5aerpauloLinux capabilities instead of privileged process
98130dc5aerpaulo------------------------------------------------
98230dc5aerpaulo
98330dc5aerpaulowpa_supplicant performs operations that need special permissions, e.g.,
98430dc5aerpauloto control the network connection. Traditionally this has been achieved
98530dc5aerpauloby running wpa_supplicant as a privileged process with effective user id
98630dc5aerpaulo0 (root). Linux capabilities can be used to provide restricted set of
98730dc5aerpaulocapabilities to match the functions needed by wpa_supplicant. The
98830dc5aerpaulominimum set of capabilities needed for the operations is CAP_NET_ADMIN
98930dc5aerpauloand CAP_NET_RAW.
99030dc5aerpaulo
99130dc5aerpaulosetcap(8) can be used to set file capabilities. For example:
99230dc5aerpaulo
99330dc5aerpaulosudo setcap cap_net_raw,cap_net_admin+ep wpa_supplicant
99430dc5aerpaulo
99530dc5aerpauloPlease note that this would give anyone being able to run that
99630dc5aerpaulowpa_supplicant binary access to the additional capabilities. This can
99730dc5aerpaulofurther be limited by file owner/group and mode bits. For example:
99830dc5aerpaulo
99930dc5aerpaulosudo chown wpas wpa_supplicant
100030dc5aerpaulosudo chmod 0100 wpa_supplicant
100130dc5aerpaulo
100230dc5aerpauloThis combination of setcap, chown, and chmod commands would allow wpas
100330dc5aerpaulouser to execute wpa_supplicant with additional network admin/raw
100430dc5aerpaulocapabilities.
100530dc5aerpaulo
100630dc5aerpauloCommon way style of creating a control interface socket in
100730dc5aerpaulo/var/run/wpa_supplicant could not be done by this user, but this
100830dc5aerpaulodirectory could be created before starting the wpa_supplicant and set to
100930dc5aerpaulosuitable mode to allow wpa_supplicant to create sockets
101030dc5aerpaulothere. Alternatively, other directory or abstract socket namespace could
101130dc5aerpaulobe used for the control interface.
101230dc5aerpaulo
101330dc5aerpaulo
101430dc5aerpauloExternal requests for radio control
101530dc5aerpaulo-----------------------------------
101630dc5aerpaulo
101730dc5aerpauloExternal programs can request wpa_supplicant to not start offchannel
101830dc5aerpaulooperations during other tasks that may need exclusive control of the
101930dc5aerpauloradio. The RADIO_WORK control interface command can be used for this.
102030dc5aerpaulo
102130dc5aerpaulo"RADIO_WORK add <name> [freq=<MHz>] [timeout=<seconds>]" command can be
102230dc5aerpauloused to reserve a slot for radio access. If freq is specified, other
102330dc5aerpauloradio work items on the same channel may be completed in
102430dc5aerpauloparallel. Otherwise, all other radio work items are blocked during
102530dc5aerpauloexecution. Timeout is set to 10 seconds by default to avoid blocking
102630dc5aerpaulowpa_supplicant operations for excessive time. If a longer (or shorter)
102730dc5aerpaulosafety timeout is needed, that can be specified with the optional
102830dc5aerpaulotimeout parameter. This command returns an identifier for the radio work
102930dc5aerpauloitem.
103030dc5aerpaulo
103130dc5aerpauloOnce the radio work item has been started, "EXT-RADIO-WORK-START <id>"
103230dc5aerpauloevent message is indicated that the external processing can start. Once
103330dc5aerpaulothe operation has been completed, "RADIO_WORK done <id>" is used to
103430dc5aerpauloindicate that to wpa_supplicant. This allows other radio works to be
103530dc5aerpauloperformed. If this command is forgotten (e.g., due to the external
103622c9018cyprogram terminating), wpa_supplicant will time out the radio work item
103722c9018cyand send "EXT-RADIO-WORK-TIMEOUT <id>" event to indicate that this has
103830dc5aerpaulohappened. "RADIO_WORK done <id>" can also be used to cancel items that
103930dc5aerpaulohave not yet been started.
104030dc5aerpaulo
104130dc5aerpauloFor example, in wpa_cli interactive mode:
104230dc5aerpaulo
104330dc5aerpaulo> radio_work add test
104430dc5aerpaulo1
104530dc5aerpaulo<3>EXT-RADIO-WORK-START 1
104630dc5aerpaulo> radio_work show
104730dc5aerpauloext:test@wlan0:0:1:2.487797
104830dc5aerpaulo> radio_work done 1
104930dc5aerpauloOK
105030dc5aerpaulo> radio_work show
105130dc5aerpaulo
105230dc5aerpaulo
105330dc5aerpaulo> radio_work done 3
105430dc5aerpauloOK
105530dc5aerpaulo> radio_work show
105630dc5aerpauloext:test freq=2412 timeout=30@wlan0:2412:1:28.583483
105730dc5aerpaulo<3>EXT-RADIO-WORK-TIMEOUT 2
105830dc5aerpaulo
105930dc5aerpaulo
106030dc5aerpaulo> radio_work add test2 freq=2412 timeout=60
106130dc5aerpaulo5
106230dc5aerpaulo<3>EXT-RADIO-WORK-START 5
106330dc5aerpaulo> radio_work add test3
106430dc5aerpaulo6
106530dc5aerpaulo> radio_work add test4
106630dc5aerpaulo7
106730dc5aerpaulo> radio_work show
106830dc5aerpauloext:test2 freq=2412 timeout=60@wlan0:2412:1:9.751844
106930dc5aerpauloext:test3@wlan0:0:0:5.071812
107030dc5aerpauloext:test4@wlan0:0:0:3.143870
107130dc5aerpaulo> radio_work done 6
107230dc5aerpauloOK
107330dc5aerpaulo> radio_work show
107430dc5aerpauloext:test2 freq=2412 timeout=60@wlan0:2412:1:16.287869
107530dc5aerpauloext:test4@wlan0:0:0:9.679895
107630dc5aerpaulo> radio_work done 5
107730dc5aerpauloOK
107830dc5aerpaulo<3>EXT-RADIO-WORK-START 7
107930dc5aerpaulo<3>EXT-RADIO-WORK-TIMEOUT 7
1080