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