]>
Commit | Line | Data |
---|---|---|
6fc6879b JM |
1 | WPA Supplicant |
2 | ============== | |
3 | ||
090b8e3d | 4 | Copyright (c) 2003-2014, Jouni Malinen <j@w1.fi> and contributors |
6fc6879b JM |
5 | All Rights Reserved. |
6 | ||
331f89ff JM |
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. | |
6fc6879b JM |
12 | |
13 | ||
14 | ||
15 | License | |
16 | ------- | |
17 | ||
331f89ff JM |
18 | This software may be distributed, used, and modified under the terms of |
19 | BSD license: | |
6fc6879b JM |
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: | |
b57b5600 | 118 | Linux drivers that support cfg80211/nl80211. Even though there are |
6fc6879b | 119 | number of driver specific interface included in wpa_supplicant, please |
b57b5600 JM |
120 | note that Linux drivers are moving to use generic wireless configuration |
121 | interface driver_nl80211 (-Dnl80211 on wpa_supplicant command line) | |
122 | should be the default option to start with before falling back to driver | |
123 | specific interface. | |
124 | ||
125 | Linux drivers that support WPA/WPA2 configuration with the generic | |
126 | Linux wireless extensions (WE-18 or newer). Obsoleted by nl80211. | |
6fc6879b | 127 | |
6fc6879b JM |
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 | |
b6c8df69 | 304 | driver interfaces (e.g., nl80211, wext, ..) and which authentication |
6fc6879b JM |
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 | |
df077c62 | 337 | interfaces are included. |
6fc6879b | 338 | |
b6c8df69 | 339 | CONFIG_DRIVER_NL80211=y |
6fc6879b | 340 | CONFIG_DRIVER_WEXT=y |
6fc6879b JM |
341 | CONFIG_DRIVER_BSD=y |
342 | CONFIG_DRIVER_NDIS=y | |
343 | ||
b6c8df69 JM |
344 | Following example includes some more features and driver interfaces that |
345 | are included in the wpa_supplicant package: | |
6fc6879b | 346 | |
b6c8df69 | 347 | CONFIG_DRIVER_NL80211=y |
6fc6879b | 348 | CONFIG_DRIVER_WEXT=y |
6fc6879b JM |
349 | CONFIG_DRIVER_BSD=y |
350 | CONFIG_DRIVER_NDIS=y | |
6fc6879b JM |
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>] \ | |
29257565 | 413 | [-G<group>] \ |
6fc6879b JM |
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>] \ | |
c16a7590 | 416 | [-p<driver_param>] [-b<br_ifname>] [-m<P2P Device config file>] ... |
6fc6879b JM |
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) | |
362f781e | 425 | -D = driver name (can be multiple drivers: nl80211,wext) |
6fc6879b JM |
426 | -f = Log output to default log location (normally /tmp) |
427 | -g = global ctrl_interface | |
29257565 | 428 | -G = global ctrl_interface group |
6fc6879b JM |
429 | -K = include keys (passwords, etc.) in debug output |
430 | -t = include timestamp in debug messages | |
431 | -h = show this help text | |
d755e01b | 432 | -L = show license (BSD) |
6fc6879b JM |
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 | |
c16a7590 | 441 | -m = Configuration file for the P2P Device |
6fc6879b JM |
442 | |
443 | drivers: | |
b57b5600 | 444 | nl80211 = Linux nl80211/cfg80211 |
6fc6879b | 445 | wext = Linux wireless extensions (generic) |
6fc6879b | 446 | wired = wpa_supplicant wired Ethernet driver |
e519314e | 447 | roboswitch = wpa_supplicant Broadcom switch driver |
6fc6879b JM |
448 | bsd = BSD 802.11 support (Atheros, etc.) |
449 | ndis = Windows NDIS driver | |
450 | ||
451 | In most common cases, wpa_supplicant is started with | |
452 | ||
453 | wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0 | |
454 | ||
455 | This makes the process fork into background. | |
456 | ||
457 | The easiest way to debug problems, and to get debug log for bug | |
458 | reports, is to start wpa_supplicant on foreground with debugging | |
459 | enabled: | |
460 | ||
461 | wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d | |
462 | ||
362f781e JM |
463 | If the specific driver wrapper is not known beforehand, it is possible |
464 | to specify multiple comma separated driver wrappers on the command | |
465 | line. wpa_supplicant will use the first driver wrapper that is able to | |
466 | initialize the interface. | |
467 | ||
468 | wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0 | |
469 | ||
6fc6879b JM |
470 | |
471 | wpa_supplicant can control multiple interfaces (radios) either by | |
472 | running one process for each interface separately or by running just | |
473 | one process and list of options at command line. Each interface is | |
474 | separated with -N argument. As an example, following command would | |
475 | start wpa_supplicant for two interfaces: | |
476 | ||
477 | wpa_supplicant \ | |
b6c8df69 JM |
478 | -c wpa1.conf -i wlan0 -D nl80211 -N \ |
479 | -c wpa2.conf -i wlan1 -D wext | |
6fc6879b JM |
480 | |
481 | ||
482 | If the interface is added in a Linux bridge (e.g., br0), the bridge | |
483 | interface needs to be configured to wpa_supplicant in addition to the | |
484 | main interface: | |
485 | ||
b57b5600 | 486 | wpa_supplicant -cw.conf -Dnl80211 -iwlan0 -bbr0 |
6fc6879b JM |
487 | |
488 | ||
489 | Configuration file | |
490 | ------------------ | |
491 | ||
492 | wpa_supplicant is configured using a text file that lists all accepted | |
493 | networks and security policies, including pre-shared keys. See | |
494 | example configuration file, wpa_supplicant.conf, for detailed | |
495 | information about the configuration format and supported fields. | |
496 | ||
497 | Changes to configuration file can be reloaded be sending SIGHUP signal | |
498 | to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly, | |
499 | reloading can be triggered with 'wpa_cli reconfigure' command. | |
500 | ||
501 | Configuration file can include one or more network blocks, e.g., one | |
502 | for each used SSID. wpa_supplicant will automatically select the best | |
503 | betwork based on the order of network blocks in the configuration | |
504 | file, network security level (WPA/WPA2 is preferred), and signal | |
505 | strength. | |
506 | ||
507 | Example configuration files for some common configurations: | |
508 | ||
509 | 1) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work | |
510 | network | |
511 | ||
512 | # allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group | |
513 | ctrl_interface=/var/run/wpa_supplicant | |
514 | ctrl_interface_group=wheel | |
515 | # | |
516 | # home network; allow all valid ciphers | |
517 | network={ | |
518 | ssid="home" | |
519 | scan_ssid=1 | |
520 | key_mgmt=WPA-PSK | |
521 | psk="very secret passphrase" | |
522 | } | |
523 | # | |
524 | # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers | |
525 | network={ | |
526 | ssid="work" | |
527 | scan_ssid=1 | |
528 | key_mgmt=WPA-EAP | |
529 | pairwise=CCMP TKIP | |
530 | group=CCMP TKIP | |
531 | eap=TLS | |
532 | identity="user@example.com" | |
533 | ca_cert="/etc/cert/ca.pem" | |
534 | client_cert="/etc/cert/user.pem" | |
535 | private_key="/etc/cert/user.prv" | |
536 | private_key_passwd="password" | |
537 | } | |
538 | ||
539 | ||
540 | 2) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel | |
541 | (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series) | |
542 | ||
543 | ctrl_interface=/var/run/wpa_supplicant | |
544 | ctrl_interface_group=wheel | |
545 | network={ | |
546 | ssid="example" | |
547 | scan_ssid=1 | |
548 | key_mgmt=WPA-EAP | |
549 | eap=PEAP | |
550 | identity="user@example.com" | |
551 | password="foobar" | |
552 | ca_cert="/etc/cert/ca.pem" | |
553 | phase1="peaplabel=0" | |
554 | phase2="auth=MSCHAPV2" | |
555 | } | |
556 | ||
557 | ||
558 | 3) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the | |
559 | unencrypted use. Real identity is sent only within an encrypted TLS tunnel. | |
560 | ||
561 | ctrl_interface=/var/run/wpa_supplicant | |
562 | ctrl_interface_group=wheel | |
563 | network={ | |
564 | ssid="example" | |
565 | scan_ssid=1 | |
566 | key_mgmt=WPA-EAP | |
567 | eap=TTLS | |
568 | identity="user@example.com" | |
569 | anonymous_identity="anonymous@example.com" | |
570 | password="foobar" | |
571 | ca_cert="/etc/cert/ca.pem" | |
572 | phase2="auth=MD5" | |
573 | } | |
574 | ||
575 | ||
576 | 4) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and | |
577 | broadcast); use EAP-TLS for authentication | |
578 | ||
579 | ctrl_interface=/var/run/wpa_supplicant | |
580 | ctrl_interface_group=wheel | |
581 | network={ | |
582 | ssid="1x-test" | |
583 | scan_ssid=1 | |
584 | key_mgmt=IEEE8021X | |
585 | eap=TLS | |
586 | identity="user@example.com" | |
587 | ca_cert="/etc/cert/ca.pem" | |
588 | client_cert="/etc/cert/user.pem" | |
589 | private_key="/etc/cert/user.prv" | |
590 | private_key_passwd="password" | |
591 | eapol_flags=3 | |
592 | } | |
593 | ||
594 | ||
595 | 5) Catch all example that allows more or less all configuration modes. The | |
596 | configuration options are used based on what security policy is used in the | |
597 | selected SSID. This is mostly for testing and is not recommended for normal | |
598 | use. | |
599 | ||
600 | ctrl_interface=/var/run/wpa_supplicant | |
601 | ctrl_interface_group=wheel | |
602 | network={ | |
603 | ssid="example" | |
604 | scan_ssid=1 | |
605 | key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE | |
606 | pairwise=CCMP TKIP | |
607 | group=CCMP TKIP WEP104 WEP40 | |
608 | psk="very secret passphrase" | |
609 | eap=TTLS PEAP TLS | |
610 | identity="user@example.com" | |
611 | password="foobar" | |
612 | ca_cert="/etc/cert/ca.pem" | |
613 | client_cert="/etc/cert/user.pem" | |
614 | private_key="/etc/cert/user.prv" | |
615 | private_key_passwd="password" | |
616 | phase1="peaplabel=0" | |
617 | ca_cert2="/etc/cert/ca2.pem" | |
618 | client_cert2="/etc/cer/user.pem" | |
619 | private_key2="/etc/cer/user.prv" | |
620 | private_key2_passwd="password" | |
621 | } | |
622 | ||
623 | ||
e519314e JW |
624 | 6) Authentication for wired Ethernet. This can be used with 'wired' or |
625 | 'roboswitch' interface (-Dwired or -Droboswitch on command line). | |
6fc6879b JM |
626 | |
627 | ctrl_interface=/var/run/wpa_supplicant | |
628 | ctrl_interface_group=wheel | |
629 | ap_scan=0 | |
630 | network={ | |
631 | key_mgmt=IEEE8021X | |
632 | eap=MD5 | |
633 | identity="user" | |
634 | password="password" | |
635 | eapol_flags=0 | |
636 | } | |
637 | ||
638 | ||
639 | ||
640 | Certificates | |
641 | ------------ | |
642 | ||
643 | Some EAP authentication methods require use of certificates. EAP-TLS | |
644 | uses both server side and client certificates whereas EAP-PEAP and | |
645 | EAP-TTLS only require the server side certificate. When client | |
646 | certificate is used, a matching private key file has to also be | |
647 | included in configuration. If the private key uses a passphrase, this | |
648 | has to be configured in wpa_supplicant.conf ("private_key_passwd"). | |
649 | ||
650 | wpa_supplicant supports X.509 certificates in PEM and DER | |
651 | formats. User certificate and private key can be included in the same | |
652 | file. | |
653 | ||
654 | If the user certificate and private key is received in PKCS#12/PFX | |
655 | format, they need to be converted to suitable PEM/DER format for | |
656 | wpa_supplicant. This can be done, e.g., with following commands: | |
657 | ||
658 | # convert client certificate and private key to PEM format | |
659 | openssl pkcs12 -in example.pfx -out user.pem -clcerts | |
660 | # convert CA certificate (if included in PFX file) to PEM format | |
661 | openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys | |
662 | ||
663 | ||
664 | ||
665 | wpa_cli | |
666 | ------- | |
667 | ||
668 | wpa_cli is a text-based frontend program for interacting with | |
669 | wpa_supplicant. It is used to query current status, change | |
670 | configuration, trigger events, and request interactive user input. | |
671 | ||
672 | wpa_cli can show the current authentication status, selected security | |
673 | mode, dot11 and dot1x MIBs, etc. In addition, it can configure some | |
674 | variables like EAPOL state machine parameters and trigger events like | |
675 | reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user | |
676 | interface to request authentication information, like username and | |
677 | password, if these are not included in the configuration. This can be | |
678 | used to implement, e.g., one-time-passwords or generic token card | |
679 | authentication where the authentication is based on a | |
680 | challenge-response that uses an external device for generating the | |
681 | response. | |
682 | ||
683 | The control interface of wpa_supplicant can be configured to allow | |
684 | non-root user access (ctrl_interface_group in the configuration | |
685 | file). This makes it possible to run wpa_cli with a normal user | |
686 | account. | |
687 | ||
688 | wpa_cli supports two modes: interactive and command line. Both modes | |
689 | share the same command set and the main difference is in interactive | |
690 | mode providing access to unsolicited messages (event messages, | |
691 | username/password requests). | |
692 | ||
693 | Interactive mode is started when wpa_cli is executed without including | |
694 | the command as a command line parameter. Commands are then entered on | |
695 | the wpa_cli prompt. In command line mode, the same commands are | |
696 | entered as command line arguments for wpa_cli. | |
697 | ||
698 | ||
699 | Interactive authentication parameters request | |
700 | ||
701 | When wpa_supplicant need authentication parameters, like username and | |
702 | password, which are not present in the configuration file, it sends a | |
703 | request message to all attached frontend programs, e.g., wpa_cli in | |
704 | interactive mode. wpa_cli shows these requests with | |
705 | "CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or | |
706 | OTP (one-time-password). <id> is a unique identifier for the current | |
707 | network. <text> is description of the request. In case of OTP request, | |
708 | it includes the challenge from the authentication server. | |
709 | ||
710 | The reply to these requests can be given with 'identity', 'password', | |
711 | and 'otp' commands. <id> needs to be copied from the the matching | |
712 | request. 'password' and 'otp' commands can be used regardless of | |
713 | whether the request was for PASSWORD or OTP. The main difference | |
714 | between these two commands is that values given with 'password' are | |
715 | remembered as long as wpa_supplicant is running whereas values given | |
716 | with 'otp' are used only once and then forgotten, i.e., wpa_supplicant | |
717 | will ask frontend for a new value for every use. This can be used to | |
718 | implement one-time-password lists and generic token card -based | |
719 | authentication. | |
720 | ||
721 | Example request for password and a matching reply: | |
722 | ||
723 | CTRL-REQ-PASSWORD-1:Password needed for SSID foobar | |
724 | > password 1 mysecretpassword | |
725 | ||
726 | Example request for generic token card challenge-response: | |
727 | ||
728 | CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar | |
729 | > otp 2 9876 | |
730 | ||
731 | ||
732 | wpa_cli commands | |
733 | ||
734 | status = get current WPA/EAPOL/EAP status | |
735 | mib = get MIB variables (dot1x, dot11) | |
736 | help = show this usage help | |
737 | interface [ifname] = show interfaces/select interface | |
738 | level <debug level> = change debug level | |
739 | license = show full wpa_cli license | |
740 | logoff = IEEE 802.1X EAPOL state machine logoff | |
741 | logon = IEEE 802.1X EAPOL state machine logon | |
742 | set = set variables (shows list of variables when run without arguments) | |
743 | pmksa = show PMKSA cache | |
744 | reassociate = force reassociation | |
745 | reconfigure = force wpa_supplicant to re-read its configuration file | |
746 | preauthenticate <BSSID> = force preauthentication | |
747 | identity <network id> <identity> = configure identity for an SSID | |
748 | password <network id> <password> = configure password for an SSID | |
749 | pin <network id> <pin> = configure pin for an SSID | |
750 | otp <network id> <password> = configure one-time-password for an SSID | |
751 | passphrase <network id> <passphrase> = configure private key passphrase | |
752 | for an SSID | |
753 | bssid <network id> <BSSID> = set preferred BSSID for an SSID | |
754 | list_networks = list configured networks | |
755 | select_network <network id> = select a network (disable others) | |
756 | enable_network <network id> = enable a network | |
757 | disable_network <network id> = disable a network | |
758 | add_network = add a network | |
759 | remove_network <network id> = remove a network | |
760 | set_network <network id> <variable> <value> = set network variables (shows | |
761 | list of variables when run without arguments) | |
762 | get_network <network id> <variable> = get network variables | |
763 | save_config = save the current configuration | |
764 | disconnect = disconnect and wait for reassociate command before connecting | |
765 | scan = request new BSS scan | |
766 | scan_results = get latest scan results | |
767 | get_capability <eap/pairwise/group/key_mgmt/proto/auth_alg> = get capabilies | |
768 | terminate = terminate wpa_supplicant | |
769 | quit = exit wpa_cli | |
770 | ||
771 | ||
772 | wpa_cli command line options | |
773 | ||
774 | wpa_cli [-p<path to ctrl sockets>] [-i<ifname>] [-hvB] [-a<action file>] \ | |
775 | [-P<pid file>] [-g<global ctrl>] [command..] | |
776 | -h = help (show this usage text) | |
777 | -v = shown version information | |
778 | -a = run in daemon mode executing the action file based on events from | |
779 | wpa_supplicant | |
780 | -B = run a daemon in the background | |
781 | default path: /var/run/wpa_supplicant | |
782 | default interface: first interface found in socket path | |
783 | ||
784 | ||
785 | Using wpa_cli to run external program on connect/disconnect | |
786 | ----------------------------------------------------------- | |
787 | ||
788 | wpa_cli can used to run external programs whenever wpa_supplicant | |
789 | connects or disconnects from a network. This can be used, e.g., to | |
790 | update network configuration and/or trigget DHCP client to update IP | |
791 | addresses, etc. | |
792 | ||
793 | One wpa_cli process in "action" mode needs to be started for each | |
794 | interface. For example, the following command starts wpa_cli for the | |
795 | default ingterface (-i can be used to select the interface in case of | |
796 | more than one interface being used at the same time): | |
797 | ||
798 | wpa_cli -a/sbin/wpa_action.sh -B | |
799 | ||
800 | The action file (-a option, /sbin/wpa_action.sh in this example) will | |
801 | be executed whenever wpa_supplicant completes authentication (connect | |
802 | event) or detects disconnection). The action script will be called | |
803 | with two command line arguments: interface name and event (CONNECTED | |
804 | or DISCONNECTED). If the action script needs to get more information | |
805 | about the current network, it can use 'wpa_cli status' to query | |
806 | wpa_supplicant for more information. | |
807 | ||
808 | Following example can be used as a simple template for an action | |
809 | script: | |
810 | ||
811 | #!/bin/sh | |
812 | ||
813 | IFNAME=$1 | |
814 | CMD=$2 | |
815 | ||
be5b1e86 | 816 | if [ "$CMD" = "CONNECTED" ]; then |
6fc6879b JM |
817 | SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=` |
818 | # configure network, signal DHCP client, etc. | |
819 | fi | |
820 | ||
be5b1e86 | 821 | if [ "$CMD" = "DISCONNECTED" ]; then |
6fc6879b | 822 | # remove network configuration, if needed |
be5b1e86 | 823 | SSID= |
6fc6879b JM |
824 | fi |
825 | ||
826 | ||
827 | ||
828 | Integrating with pcmcia-cs/cardmgr scripts | |
829 | ------------------------------------------ | |
830 | ||
831 | wpa_supplicant needs to be running when using a wireless network with | |
832 | WPA. It can be started either from system startup scripts or from | |
833 | pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be | |
834 | completed before data frames can be exchanged, so wpa_supplicant | |
835 | should be started before DHCP client. | |
836 | ||
837 | For example, following small changes to pcmcia-cs scripts can be used | |
838 | to enable WPA support: | |
839 | ||
840 | Add MODE="Managed" and WPA="y" to the network scheme in | |
841 | /etc/pcmcia/wireless.opts. | |
842 | ||
843 | Add the following block to the end of 'start' action handler in | |
844 | /etc/pcmcia/wireless: | |
845 | ||
846 | if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then | |
847 | /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf \ | |
848 | -i$DEVICE | |
849 | fi | |
850 | ||
851 | Add the following block to the end of 'stop' action handler (may need | |
852 | to be separated from other actions) in /etc/pcmcia/wireless: | |
853 | ||
854 | if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then | |
855 | killall wpa_supplicant | |
856 | fi | |
857 | ||
858 | This will make cardmgr start wpa_supplicant when the card is plugged | |
859 | in. | |
860 | ||
861 | ||
862 | ||
863 | Dynamic interface add and operation without configuration files | |
864 | --------------------------------------------------------------- | |
865 | ||
866 | wpa_supplicant can be started without any configuration files or | |
867 | network interfaces. When used in this way, a global (i.e., per | |
868 | wpa_supplicant process) control interface is used to add and remove | |
869 | network interfaces. Each network interface can then be configured | |
870 | through a per-network interface control interface. For example, | |
871 | following commands show how to start wpa_supplicant without any | |
872 | network interfaces and then add a network interface and configure a | |
873 | network (SSID): | |
874 | ||
875 | # Start wpa_supplicant in the background | |
876 | wpa_supplicant -g/var/run/wpa_supplicant-global -B | |
877 | ||
b57b5600 | 878 | # Add a new interface (wlan0, no configuration file, driver=nl80211, and |
6fc6879b JM |
879 | # enable control interface) |
880 | wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \ | |
b57b5600 | 881 | "" nl80211 /var/run/wpa_supplicant |
6fc6879b JM |
882 | |
883 | # Configure a network using the newly added network interface: | |
884 | wpa_cli -iwlan0 add_network | |
885 | wpa_cli -iwlan0 set_network 0 ssid '"test"' | |
886 | wpa_cli -iwlan0 set_network 0 key_mgmt WPA-PSK | |
887 | wpa_cli -iwlan0 set_network 0 psk '"12345678"' | |
888 | wpa_cli -iwlan0 set_network 0 pairwise TKIP | |
889 | wpa_cli -iwlan0 set_network 0 group TKIP | |
890 | wpa_cli -iwlan0 set_network 0 proto WPA | |
891 | wpa_cli -iwlan0 enable_network 0 | |
892 | ||
893 | # At this point, the new network interface should start trying to associate | |
894 | # with the WPA-PSK network using SSID test. | |
895 | ||
896 | # Remove network interface | |
897 | wpa_cli -g/var/run/wpa_supplicant-global interface_remove wlan0 | |
898 | ||
899 | ||
900 | Privilege separation | |
901 | -------------------- | |
902 | ||
903 | To minimize the size of code that needs to be run with root privileges | |
904 | (e.g., to control wireless interface operation), wpa_supplicant | |
905 | supports optional privilege separation. If enabled, this separates the | |
906 | privileged operations into a separate process (wpa_priv) while leaving | |
907 | rest of the code (e.g., EAP authentication and WPA handshakes) into an | |
908 | unprivileged process (wpa_supplicant) that can be run as non-root | |
909 | user. Privilege separation restricts the effects of potential software | |
910 | errors by containing the majority of the code in an unprivileged | |
911 | process to avoid full system compromise. | |
912 | ||
913 | Privilege separation is not enabled by default and it can be enabled | |
914 | by adding CONFIG_PRIVSEP=y to the build configuration (.config). When | |
915 | enabled, the privileged operations (driver wrapper and l2_packet) are | |
916 | linked into a separate daemon program, wpa_priv. The unprivileged | |
917 | program, wpa_supplicant, will be built with a special driver/l2_packet | |
918 | wrappers that communicate with the privileged wpa_priv process to | |
919 | perform the needed operations. wpa_priv can control what privileged | |
920 | are allowed. | |
921 | ||
922 | wpa_priv needs to be run with network admin privileges (usually, root | |
923 | user). It opens a UNIX domain socket for each interface that is | |
924 | included on the command line; any other interface will be off limits | |
925 | for wpa_supplicant in this kind of configuration. After this, | |
926 | wpa_supplicant can be run as a non-root user (e.g., all standard users | |
927 | on a laptop or as a special non-privileged user account created just | |
928 | for this purpose to limit access to user files even further). | |
929 | ||
930 | ||
931 | Example configuration: | |
932 | - create user group for users that are allowed to use wpa_supplicant | |
933 | ('wpapriv' in this example) and assign users that should be able to | |
934 | use wpa_supplicant into that group | |
935 | - create /var/run/wpa_priv directory for UNIX domain sockets and control | |
936 | user access by setting it accessible only for the wpapriv group: | |
937 | mkdir /var/run/wpa_priv | |
938 | chown root:wpapriv /var/run/wpa_priv | |
939 | chmod 0750 /var/run/wpa_priv | |
940 | - start wpa_priv as root (e.g., from system startup scripts) with the | |
941 | enabled interfaces configured on the command line: | |
b57b5600 | 942 | wpa_priv -B -P /var/run/wpa_priv.pid nl80211:wlan0 |
6fc6879b JM |
943 | - run wpa_supplicant as non-root with a user that is in wpapriv group: |
944 | wpa_supplicant -i ath0 -c wpa_supplicant.conf | |
945 | ||
946 | wpa_priv does not use the network interface before wpa_supplicant is | |
947 | started, so it is fine to include network interfaces that are not | |
948 | available at the time wpa_priv is started. As an alternative, wpa_priv | |
949 | can be started when an interface is added (hotplug/udev/etc. scripts). | |
950 | wpa_priv can control multiple interface with one process, but it is | |
951 | also possible to run multiple wpa_priv processes at the same time, if | |
952 | desired. | |
5388dc97 JM |
953 | |
954 | ||
955 | Linux capabilities instead of privileged process | |
956 | ------------------------------------------------ | |
957 | ||
958 | wpa_supplicant performs operations that need special permissions, e.g., | |
959 | to control the network connection. Traditionally this has been achieved | |
960 | by running wpa_supplicant as a privileged process with effective user id | |
961 | 0 (root). Linux capabilities can be used to provide restricted set of | |
962 | capabilities to match the functions needed by wpa_supplicant. The | |
963 | minimum set of capabilities needed for the operations is CAP_NET_ADMIN | |
964 | and CAP_NET_RAW. | |
965 | ||
966 | setcap(8) can be used to set file capabilities. For example: | |
967 | ||
968 | sudo setcap cap_net_raw,cap_net_admin+ep wpa_supplicant | |
969 | ||
970 | Please note that this would give anyone being able to run that | |
971 | wpa_supplicant binary access to the additional capabilities. This can | |
972 | further be limited by file owner/group and mode bits. For example: | |
973 | ||
974 | sudo chown wpas wpa_supplicant | |
975 | sudo chmod 0100 wpa_supplicant | |
976 | ||
977 | This combination of setcap, chown, and chmod commands would allow wpas | |
978 | user to execute wpa_supplicant with additional network admin/raw | |
979 | capabilities. | |
980 | ||
981 | Common way style of creating a control interface socket in | |
982 | /var/run/wpa_supplicant could not be done by this user, but this | |
983 | directory could be created before starting the wpa_supplicant and set to | |
984 | suitable mode to allow wpa_supplicant to create sockets | |
985 | there. Alternatively, other directory or abstract socket namespace could | |
986 | be used for the control interface. | |
1f965e62 JM |
987 | |
988 | ||
989 | External requests for radio control | |
990 | ----------------------------------- | |
991 | ||
992 | External programs can request wpa_supplicant to not start offchannel | |
993 | operations during other tasks that may need exclusive control of the | |
994 | radio. The RADIO_WORK control interface command can be used for this. | |
995 | ||
996 | "RADIO_WORK add <name> [freq=<MHz>] [timeout=<seconds>]" command can be | |
997 | used to reserve a slot for radio access. If freq is specified, other | |
998 | radio work items on the same channel may be completed in | |
999 | parallel. Otherwise, all other radio work items are blocked during | |
1000 | execution. Timeout is set to 10 seconds by default to avoid blocking | |
1001 | wpa_supplicant operations for excessive time. If a longer (or shorter) | |
1002 | safety timeout is needed, that can be specified with the optional | |
1003 | timeout parameter. This command returns an identifier for the radio work | |
1004 | item. | |
1005 | ||
1006 | Once the radio work item has been started, "EXT-RADIO-WORK-START <id>" | |
1007 | event message is indicated that the external processing can start. Once | |
1008 | the operation has been completed, "RADIO_WORK done <id>" is used to | |
1009 | indicate that to wpa_supplicant. This allows other radio works to be | |
1010 | performed. If this command is forgotten (e.g., due to the external | |
1011 | program terminating), wpa_supplicant will time out the radio owrk item | |
1012 | and send "EXT-RADIO-WORK-TIMEOUT <id>" event ot indicate that this has | |
1013 | happened. "RADIO_WORK done <id>" can also be used to cancel items that | |
1014 | have not yet been started. | |
1015 | ||
1016 | For example, in wpa_cli interactive mode: | |
1017 | ||
1018 | > radio_work add test | |
1019 | 1 | |
1020 | <3>EXT-RADIO-WORK-START 1 | |
1021 | > radio_work show | |
1022 | ext:test@wlan0:0:1:2.487797 | |
1023 | > radio_work done 1 | |
1024 | OK | |
1025 | > radio_work show | |
1026 | ||
1027 | ||
1028 | > radio_work done 3 | |
1029 | OK | |
1030 | > radio_work show | |
1031 | ext:test freq=2412 timeout=30@wlan0:2412:1:28.583483 | |
1032 | <3>EXT-RADIO-WORK-TIMEOUT 2 | |
1033 | ||
1034 | ||
1035 | > radio_work add test2 freq=2412 timeout=60 | |
1036 | 5 | |
1037 | <3>EXT-RADIO-WORK-START 5 | |
1038 | > radio_work add test3 | |
1039 | 6 | |
1040 | > radio_work add test4 | |
1041 | 7 | |
1042 | > radio_work show | |
1043 | ext:test2 freq=2412 timeout=60@wlan0:2412:1:9.751844 | |
1044 | ext:test3@wlan0:0:0:5.071812 | |
1045 | ext:test4@wlan0:0:0:3.143870 | |
1046 | > radio_work done 6 | |
1047 | OK | |
1048 | > radio_work show | |
1049 | ext:test2 freq=2412 timeout=60@wlan0:2412:1:16.287869 | |
1050 | ext:test4@wlan0:0:0:9.679895 | |
1051 | > radio_work done 5 | |
1052 | OK | |
1053 | <3>EXT-RADIO-WORK-START 7 | |
1054 | <3>EXT-RADIO-WORK-TIMEOUT 7 |