]>
Commit | Line | Data |
---|---|---|
6fc6879b JM |
1 | WPA Supplicant |
2 | ============== | |
3 | ||
57d38ddf | 4 | Copyright (c) 2003-2012, 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: | |
118 | Linux drivers that support WPA/WPA2 configuration with the generic | |
119 | Linux wireless extensions (WE-18 or newer). Even though there are | |
120 | number of driver specific interface included in wpa_supplicant, please | |
121 | note that Linux drivers are moving to use generic wireless extensions | |
122 | and driver_wext (-Dwext on wpa_supplicant command line) should be the | |
123 | default option to start with before falling back to driver specific | |
124 | interface. | |
125 | ||
6fc6879b JM |
126 | In theory, any driver that supports Linux wireless extensions can be |
127 | used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in | |
128 | configuration file. | |
129 | ||
130 | Wired Ethernet drivers (with ap_scan=0) | |
131 | ||
132 | BSD net80211 layer (e.g., Atheros driver) | |
133 | At the moment, this is for FreeBSD 6-CURRENT branch and NetBSD-current. | |
134 | ||
135 | Windows NDIS | |
136 | The current Windows port requires WinPcap (http://winpcap.polito.it/). | |
137 | See README-Windows.txt for more information. | |
138 | ||
139 | wpa_supplicant was designed to be portable for different drivers and | |
140 | operating systems. Hopefully, support for more wlan cards and OSes will be | |
141 | added in the future. See developer's documentation | |
142 | (http://hostap.epitest.fi/wpa_supplicant/devel/) for more information about the | |
143 | design of wpa_supplicant and porting to other drivers. One main goal | |
144 | is to add full WPA/WPA2 support to Linux wireless extensions to allow | |
145 | new drivers to be supported without having to implement new | |
146 | driver-specific interface code in wpa_supplicant. | |
147 | ||
148 | Optional libraries for layer2 packet processing: | |
149 | - libpcap (tested with 0.7.2, most relatively recent versions assumed to work, | |
150 | this is likely to be available with most distributions, | |
151 | http://tcpdump.org/) | |
152 | - libdnet (tested with v1.4, most versions assumed to work, | |
153 | http://libdnet.sourceforge.net/) | |
154 | ||
155 | These libraries are _not_ used in the default Linux build. Instead, | |
156 | internal Linux specific implementation is used. libpcap/libdnet are | |
157 | more portable and they can be used by adding CONFIG_L2_PACKET=pcap into | |
158 | .config. They may also be selected automatically for other operating | |
159 | systems. In case of Windows builds, WinPcap is used by default | |
160 | (CONFIG_L2_PACKET=winpcap). | |
161 | ||
162 | ||
163 | Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS: | |
164 | - OpenSSL (tested with 0.9.7c and 0.9.7d, and 0.9.8 versions; assumed to | |
165 | work with most relatively recent versions; this is likely to be | |
166 | available with most distributions, http://www.openssl.org/) | |
167 | - GnuTLS | |
168 | - internal TLSv1 implementation | |
169 | ||
170 | TLS options for EAP-FAST: | |
171 | - OpenSSL 0.9.8d _with_ openssl-0.9.8d-tls-extensions.patch applied | |
172 | (i.e., the default OpenSSL package does not include support for | |
173 | extensions needed for EAP-FAST) | |
174 | - internal TLSv1 implementation | |
175 | ||
176 | One of these libraries is needed when EAP-TLS, EAP-PEAP, EAP-TTLS, or | |
177 | EAP-FAST support is enabled. WPA-PSK mode does not require this or EAPOL/EAP | |
178 | implementation. A configuration file, .config, for compilation is | |
179 | needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5, | |
180 | EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so | |
181 | they should only be enabled if testing the EAPOL/EAP state | |
182 | machines. However, there can be used as inner authentication | |
183 | algorithms with EAP-PEAP and EAP-TTLS. | |
184 | ||
185 | See Building and installing section below for more detailed | |
186 | information about the wpa_supplicant build time configuration. | |
187 | ||
188 | ||
189 | ||
190 | WPA | |
191 | --- | |
192 | ||
193 | The original security mechanism of IEEE 802.11 standard was not | |
194 | designed to be strong and has proven to be insufficient for most | |
195 | networks that require some kind of security. Task group I (Security) | |
196 | of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked | |
197 | to address the flaws of the base standard and has in practice | |
198 | completed its work in May 2004. The IEEE 802.11i amendment to the IEEE | |
199 | 802.11 standard was approved in June 2004 and published in July 2004. | |
200 | ||
201 | Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the | |
202 | IEEE 802.11i work (draft 3.0) to define a subset of the security | |
203 | enhancements that can be implemented with existing wlan hardware. This | |
204 | is called Wi-Fi Protected Access<TM> (WPA). This has now become a | |
205 | mandatory component of interoperability testing and certification done | |
206 | by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web | |
207 | site (http://www.wi-fi.org/OpenSection/protected_access.asp). | |
208 | ||
209 | IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm | |
210 | for protecting wireless networks. WEP uses RC4 with 40-bit keys, | |
211 | 24-bit initialization vector (IV), and CRC32 to protect against packet | |
212 | forgery. All these choices have proven to be insufficient: key space is | |
213 | too small against current attacks, RC4 key scheduling is insufficient | |
214 | (beginning of the pseudorandom stream should be skipped), IV space is | |
215 | too small and IV reuse makes attacks easier, there is no replay | |
216 | protection, and non-keyed authentication does not protect against bit | |
217 | flipping packet data. | |
218 | ||
219 | WPA is an intermediate solution for the security issues. It uses | |
220 | Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a | |
221 | compromise on strong security and possibility to use existing | |
222 | hardware. It still uses RC4 for the encryption like WEP, but with | |
223 | per-packet RC4 keys. In addition, it implements replay protection, | |
224 | keyed packet authentication mechanism (Michael MIC). | |
225 | ||
226 | Keys can be managed using two different mechanisms. WPA can either use | |
227 | an external authentication server (e.g., RADIUS) and EAP just like | |
228 | IEEE 802.1X is using or pre-shared keys without need for additional | |
229 | servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal", | |
230 | respectively. Both mechanisms will generate a master session key for | |
231 | the Authenticator (AP) and Supplicant (client station). | |
232 | ||
233 | WPA implements a new key handshake (4-Way Handshake and Group Key | |
234 | Handshake) for generating and exchanging data encryption keys between | |
235 | the Authenticator and Supplicant. This handshake is also used to | |
236 | verify that both Authenticator and Supplicant know the master session | |
237 | key. These handshakes are identical regardless of the selected key | |
238 | management mechanism (only the method for generating master session | |
239 | key changes). | |
240 | ||
241 | ||
242 | ||
243 | IEEE 802.11i / WPA2 | |
244 | ------------------- | |
245 | ||
246 | The design for parts of IEEE 802.11i that were not included in WPA has | |
247 | finished (May 2004) and this amendment to IEEE 802.11 was approved in | |
248 | June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new | |
249 | version of WPA called WPA2. This includes, e.g., support for more | |
250 | robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC) | |
251 | to replace TKIP and optimizations for handoff (reduced number of | |
252 | messages in initial key handshake, pre-authentication, and PMKSA caching). | |
253 | ||
254 | ||
255 | ||
256 | wpa_supplicant | |
257 | -------------- | |
258 | ||
259 | wpa_supplicant is an implementation of the WPA Supplicant component, | |
260 | i.e., the part that runs in the client stations. It implements WPA key | |
261 | negotiation with a WPA Authenticator and EAP authentication with | |
262 | Authentication Server. In addition, it controls the roaming and IEEE | |
263 | 802.11 authentication/association of the wlan driver. | |
264 | ||
265 | wpa_supplicant is designed to be a "daemon" program that runs in the | |
266 | background and acts as the backend component controlling the wireless | |
267 | connection. wpa_supplicant supports separate frontend programs and an | |
268 | example text-based frontend, wpa_cli, is included with wpa_supplicant. | |
269 | ||
270 | Following steps are used when associating with an AP using WPA: | |
271 | ||
272 | - wpa_supplicant requests the kernel driver to scan neighboring BSSes | |
273 | - wpa_supplicant selects a BSS based on its configuration | |
274 | - wpa_supplicant requests the kernel driver to associate with the chosen | |
275 | BSS | |
276 | - If WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP | |
277 | authentication with the authentication server (proxied by the | |
278 | Authenticator in the AP) | |
279 | - If WPA-EAP: master key is received from the IEEE 802.1X Supplicant | |
280 | - If WPA-PSK: wpa_supplicant uses PSK as the master session key | |
281 | - wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake | |
282 | with the Authenticator (AP) | |
283 | - wpa_supplicant configures encryption keys for unicast and broadcast | |
284 | - normal data packets can be transmitted and received | |
285 | ||
286 | ||
287 | ||
288 | Building and installing | |
289 | ----------------------- | |
290 | ||
291 | In order to be able to build wpa_supplicant, you will first need to | |
292 | select which parts of it will be included. This is done by creating a | |
293 | build time configuration file, .config, in the wpa_supplicant root | |
294 | directory. Configuration options are text lines using following | |
295 | format: CONFIG_<option>=y. Lines starting with # are considered | |
296 | comments and are ignored. See defconfig file for an example configuration | |
297 | and a list of available options and additional notes. | |
298 | ||
299 | The build time configuration can be used to select only the needed | |
300 | features and limit the binary size and requirements for external | |
301 | libraries. The main configuration parts are the selection of which | |
b6c8df69 | 302 | driver interfaces (e.g., nl80211, wext, ..) and which authentication |
6fc6879b JM |
303 | methods (e.g., EAP-TLS, EAP-PEAP, ..) are included. |
304 | ||
305 | Following build time configuration options are used to control IEEE | |
306 | 802.1X/EAPOL and EAP state machines and all EAP methods. Including | |
307 | TLS, PEAP, or TTLS will require linking wpa_supplicant with OpenSSL | |
308 | library for TLS implementation. Alternatively, GnuTLS or the internal | |
309 | TLSv1 implementation can be used for TLS functionaly. | |
310 | ||
311 | CONFIG_IEEE8021X_EAPOL=y | |
312 | CONFIG_EAP_MD5=y | |
313 | CONFIG_EAP_MSCHAPV2=y | |
314 | CONFIG_EAP_TLS=y | |
315 | CONFIG_EAP_PEAP=y | |
316 | CONFIG_EAP_TTLS=y | |
317 | CONFIG_EAP_GTC=y | |
318 | CONFIG_EAP_OTP=y | |
319 | CONFIG_EAP_SIM=y | |
320 | CONFIG_EAP_AKA=y | |
321 | CONFIG_EAP_PSK=y | |
322 | CONFIG_EAP_SAKE=y | |
323 | CONFIG_EAP_GPSK=y | |
324 | CONFIG_EAP_PAX=y | |
325 | CONFIG_EAP_LEAP=y | |
326 | CONFIG_EAP_IKEV2=y | |
327 | ||
328 | Following option can be used to include GSM SIM/USIM interface for GSM/UMTS | |
329 | authentication algorithm (for EAP-SIM/EAP-AKA). This requires pcsc-lite | |
330 | (http://www.linuxnet.com/) for smart card access. | |
331 | ||
332 | CONFIG_PCSC=y | |
333 | ||
334 | Following options can be added to .config to select which driver | |
df077c62 | 335 | interfaces are included. |
6fc6879b | 336 | |
b6c8df69 | 337 | CONFIG_DRIVER_NL80211=y |
6fc6879b | 338 | CONFIG_DRIVER_WEXT=y |
6fc6879b JM |
339 | CONFIG_DRIVER_BSD=y |
340 | CONFIG_DRIVER_NDIS=y | |
341 | ||
b6c8df69 JM |
342 | Following example includes some more features and driver interfaces that |
343 | are included in the wpa_supplicant package: | |
6fc6879b | 344 | |
b6c8df69 | 345 | CONFIG_DRIVER_NL80211=y |
6fc6879b | 346 | CONFIG_DRIVER_WEXT=y |
6fc6879b JM |
347 | CONFIG_DRIVER_BSD=y |
348 | CONFIG_DRIVER_NDIS=y | |
6fc6879b JM |
349 | CONFIG_IEEE8021X_EAPOL=y |
350 | CONFIG_EAP_MD5=y | |
351 | CONFIG_EAP_MSCHAPV2=y | |
352 | CONFIG_EAP_TLS=y | |
353 | CONFIG_EAP_PEAP=y | |
354 | CONFIG_EAP_TTLS=y | |
355 | CONFIG_EAP_GTC=y | |
356 | CONFIG_EAP_OTP=y | |
357 | CONFIG_EAP_SIM=y | |
358 | CONFIG_EAP_AKA=y | |
359 | CONFIG_EAP_PSK=y | |
360 | CONFIG_EAP_SAKE=y | |
361 | CONFIG_EAP_GPSK=y | |
362 | CONFIG_EAP_PAX=y | |
363 | CONFIG_EAP_LEAP=y | |
364 | CONFIG_EAP_IKEV2=y | |
365 | CONFIG_PCSC=y | |
366 | ||
367 | EAP-PEAP and EAP-TTLS will automatically include configured EAP | |
368 | methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection. | |
369 | ||
370 | ||
371 | After you have created a configuration file, you can build | |
372 | wpa_supplicant and wpa_cli with 'make' command. You may then install | |
373 | the binaries to a suitable system directory, e.g., /usr/local/bin. | |
374 | ||
375 | Example commands: | |
376 | ||
377 | # build wpa_supplicant and wpa_cli | |
378 | make | |
379 | # install binaries (this may need root privileges) | |
380 | cp wpa_cli wpa_supplicant /usr/local/bin | |
381 | ||
382 | ||
383 | You will need to make a configuration file, e.g., | |
384 | /etc/wpa_supplicant.conf, with network configuration for the networks | |
385 | you are going to use. Configuration file section below includes | |
386 | explanation fo the configuration file format and includes various | |
387 | examples. Once the configuration is ready, you can test whether the | |
388 | configuration work by first running wpa_supplicant with following | |
389 | command to start it on foreground with debugging enabled: | |
390 | ||
391 | wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d | |
392 | ||
393 | Assuming everything goes fine, you can start using following command | |
394 | to start wpa_supplicant on background without debugging: | |
395 | ||
396 | wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B | |
397 | ||
398 | Please note that if you included more than one driver interface in the | |
399 | build time configuration (.config), you may need to specify which | |
400 | interface to use by including -D<driver name> option on the command | |
401 | line. See following section for more details on command line options | |
402 | for wpa_supplicant. | |
403 | ||
404 | ||
405 | ||
406 | Command line options | |
407 | -------------------- | |
408 | ||
409 | usage: | |
410 | wpa_supplicant [-BddfhKLqqtuvwW] [-P<pid file>] [-g<global ctrl>] \ | |
411 | -i<ifname> -c<config file> [-C<ctrl>] [-D<driver>] [-p<driver_param>] \ | |
412 | [-b<br_ifname> [-N -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] \ | |
413 | [-p<driver_param>] [-b<br_ifname>] ...] | |
414 | ||
415 | options: | |
416 | -b = optional bridge interface name | |
417 | -B = run daemon in the background | |
418 | -c = Configuration file | |
419 | -C = ctrl_interface parameter (only used if -c is not) | |
420 | -i = interface name | |
421 | -d = increase debugging verbosity (-dd even more) | |
362f781e | 422 | -D = driver name (can be multiple drivers: nl80211,wext) |
6fc6879b JM |
423 | -f = Log output to default log location (normally /tmp) |
424 | -g = global ctrl_interface | |
425 | -K = include keys (passwords, etc.) in debug output | |
426 | -t = include timestamp in debug messages | |
427 | -h = show this help text | |
d755e01b | 428 | -L = show license (BSD) |
6fc6879b JM |
429 | -p = driver parameters |
430 | -P = PID file | |
431 | -q = decrease debugging verbosity (-qq even less) | |
432 | -u = enable DBus control interface | |
433 | -v = show version | |
434 | -w = wait for interface to be added, if needed | |
435 | -W = wait for a control interface monitor before starting | |
436 | -N = start describing new interface | |
437 | ||
438 | drivers: | |
6fc6879b | 439 | wext = Linux wireless extensions (generic) |
6fc6879b | 440 | wired = wpa_supplicant wired Ethernet driver |
e519314e | 441 | roboswitch = wpa_supplicant Broadcom switch driver |
6fc6879b JM |
442 | bsd = BSD 802.11 support (Atheros, etc.) |
443 | ndis = Windows NDIS driver | |
444 | ||
445 | In most common cases, wpa_supplicant is started with | |
446 | ||
447 | wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0 | |
448 | ||
449 | This makes the process fork into background. | |
450 | ||
451 | The easiest way to debug problems, and to get debug log for bug | |
452 | reports, is to start wpa_supplicant on foreground with debugging | |
453 | enabled: | |
454 | ||
455 | wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d | |
456 | ||
362f781e JM |
457 | If the specific driver wrapper is not known beforehand, it is possible |
458 | to specify multiple comma separated driver wrappers on the command | |
459 | line. wpa_supplicant will use the first driver wrapper that is able to | |
460 | initialize the interface. | |
461 | ||
462 | wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0 | |
463 | ||
6fc6879b JM |
464 | |
465 | wpa_supplicant can control multiple interfaces (radios) either by | |
466 | running one process for each interface separately or by running just | |
467 | one process and list of options at command line. Each interface is | |
468 | separated with -N argument. As an example, following command would | |
469 | start wpa_supplicant for two interfaces: | |
470 | ||
471 | wpa_supplicant \ | |
b6c8df69 JM |
472 | -c wpa1.conf -i wlan0 -D nl80211 -N \ |
473 | -c wpa2.conf -i wlan1 -D wext | |
6fc6879b JM |
474 | |
475 | ||
476 | If the interface is added in a Linux bridge (e.g., br0), the bridge | |
477 | interface needs to be configured to wpa_supplicant in addition to the | |
478 | main interface: | |
479 | ||
b6c8df69 | 480 | wpa_supplicant -cw.conf -Dwext -iwlan0 -bbr0 |
6fc6879b JM |
481 | |
482 | ||
483 | Configuration file | |
484 | ------------------ | |
485 | ||
486 | wpa_supplicant is configured using a text file that lists all accepted | |
487 | networks and security policies, including pre-shared keys. See | |
488 | example configuration file, wpa_supplicant.conf, for detailed | |
489 | information about the configuration format and supported fields. | |
490 | ||
491 | Changes to configuration file can be reloaded be sending SIGHUP signal | |
492 | to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly, | |
493 | reloading can be triggered with 'wpa_cli reconfigure' command. | |
494 | ||
495 | Configuration file can include one or more network blocks, e.g., one | |
496 | for each used SSID. wpa_supplicant will automatically select the best | |
497 | betwork based on the order of network blocks in the configuration | |
498 | file, network security level (WPA/WPA2 is preferred), and signal | |
499 | strength. | |
500 | ||
501 | Example configuration files for some common configurations: | |
502 | ||
503 | 1) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work | |
504 | network | |
505 | ||
506 | # allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group | |
507 | ctrl_interface=/var/run/wpa_supplicant | |
508 | ctrl_interface_group=wheel | |
509 | # | |
510 | # home network; allow all valid ciphers | |
511 | network={ | |
512 | ssid="home" | |
513 | scan_ssid=1 | |
514 | key_mgmt=WPA-PSK | |
515 | psk="very secret passphrase" | |
516 | } | |
517 | # | |
518 | # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers | |
519 | network={ | |
520 | ssid="work" | |
521 | scan_ssid=1 | |
522 | key_mgmt=WPA-EAP | |
523 | pairwise=CCMP TKIP | |
524 | group=CCMP TKIP | |
525 | eap=TLS | |
526 | identity="user@example.com" | |
527 | ca_cert="/etc/cert/ca.pem" | |
528 | client_cert="/etc/cert/user.pem" | |
529 | private_key="/etc/cert/user.prv" | |
530 | private_key_passwd="password" | |
531 | } | |
532 | ||
533 | ||
534 | 2) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel | |
535 | (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series) | |
536 | ||
537 | ctrl_interface=/var/run/wpa_supplicant | |
538 | ctrl_interface_group=wheel | |
539 | network={ | |
540 | ssid="example" | |
541 | scan_ssid=1 | |
542 | key_mgmt=WPA-EAP | |
543 | eap=PEAP | |
544 | identity="user@example.com" | |
545 | password="foobar" | |
546 | ca_cert="/etc/cert/ca.pem" | |
547 | phase1="peaplabel=0" | |
548 | phase2="auth=MSCHAPV2" | |
549 | } | |
550 | ||
551 | ||
552 | 3) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the | |
553 | unencrypted use. Real identity is sent only within an encrypted TLS tunnel. | |
554 | ||
555 | ctrl_interface=/var/run/wpa_supplicant | |
556 | ctrl_interface_group=wheel | |
557 | network={ | |
558 | ssid="example" | |
559 | scan_ssid=1 | |
560 | key_mgmt=WPA-EAP | |
561 | eap=TTLS | |
562 | identity="user@example.com" | |
563 | anonymous_identity="anonymous@example.com" | |
564 | password="foobar" | |
565 | ca_cert="/etc/cert/ca.pem" | |
566 | phase2="auth=MD5" | |
567 | } | |
568 | ||
569 | ||
570 | 4) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and | |
571 | broadcast); use EAP-TLS for authentication | |
572 | ||
573 | ctrl_interface=/var/run/wpa_supplicant | |
574 | ctrl_interface_group=wheel | |
575 | network={ | |
576 | ssid="1x-test" | |
577 | scan_ssid=1 | |
578 | key_mgmt=IEEE8021X | |
579 | eap=TLS | |
580 | identity="user@example.com" | |
581 | ca_cert="/etc/cert/ca.pem" | |
582 | client_cert="/etc/cert/user.pem" | |
583 | private_key="/etc/cert/user.prv" | |
584 | private_key_passwd="password" | |
585 | eapol_flags=3 | |
586 | } | |
587 | ||
588 | ||
589 | 5) Catch all example that allows more or less all configuration modes. The | |
590 | configuration options are used based on what security policy is used in the | |
591 | selected SSID. This is mostly for testing and is not recommended for normal | |
592 | use. | |
593 | ||
594 | ctrl_interface=/var/run/wpa_supplicant | |
595 | ctrl_interface_group=wheel | |
596 | network={ | |
597 | ssid="example" | |
598 | scan_ssid=1 | |
599 | key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE | |
600 | pairwise=CCMP TKIP | |
601 | group=CCMP TKIP WEP104 WEP40 | |
602 | psk="very secret passphrase" | |
603 | eap=TTLS PEAP TLS | |
604 | identity="user@example.com" | |
605 | password="foobar" | |
606 | ca_cert="/etc/cert/ca.pem" | |
607 | client_cert="/etc/cert/user.pem" | |
608 | private_key="/etc/cert/user.prv" | |
609 | private_key_passwd="password" | |
610 | phase1="peaplabel=0" | |
611 | ca_cert2="/etc/cert/ca2.pem" | |
612 | client_cert2="/etc/cer/user.pem" | |
613 | private_key2="/etc/cer/user.prv" | |
614 | private_key2_passwd="password" | |
615 | } | |
616 | ||
617 | ||
e519314e JW |
618 | 6) Authentication for wired Ethernet. This can be used with 'wired' or |
619 | 'roboswitch' interface (-Dwired or -Droboswitch on command line). | |
6fc6879b JM |
620 | |
621 | ctrl_interface=/var/run/wpa_supplicant | |
622 | ctrl_interface_group=wheel | |
623 | ap_scan=0 | |
624 | network={ | |
625 | key_mgmt=IEEE8021X | |
626 | eap=MD5 | |
627 | identity="user" | |
628 | password="password" | |
629 | eapol_flags=0 | |
630 | } | |
631 | ||
632 | ||
633 | ||
634 | Certificates | |
635 | ------------ | |
636 | ||
637 | Some EAP authentication methods require use of certificates. EAP-TLS | |
638 | uses both server side and client certificates whereas EAP-PEAP and | |
639 | EAP-TTLS only require the server side certificate. When client | |
640 | certificate is used, a matching private key file has to also be | |
641 | included in configuration. If the private key uses a passphrase, this | |
642 | has to be configured in wpa_supplicant.conf ("private_key_passwd"). | |
643 | ||
644 | wpa_supplicant supports X.509 certificates in PEM and DER | |
645 | formats. User certificate and private key can be included in the same | |
646 | file. | |
647 | ||
648 | If the user certificate and private key is received in PKCS#12/PFX | |
649 | format, they need to be converted to suitable PEM/DER format for | |
650 | wpa_supplicant. This can be done, e.g., with following commands: | |
651 | ||
652 | # convert client certificate and private key to PEM format | |
653 | openssl pkcs12 -in example.pfx -out user.pem -clcerts | |
654 | # convert CA certificate (if included in PFX file) to PEM format | |
655 | openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys | |
656 | ||
657 | ||
658 | ||
659 | wpa_cli | |
660 | ------- | |
661 | ||
662 | wpa_cli is a text-based frontend program for interacting with | |
663 | wpa_supplicant. It is used to query current status, change | |
664 | configuration, trigger events, and request interactive user input. | |
665 | ||
666 | wpa_cli can show the current authentication status, selected security | |
667 | mode, dot11 and dot1x MIBs, etc. In addition, it can configure some | |
668 | variables like EAPOL state machine parameters and trigger events like | |
669 | reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user | |
670 | interface to request authentication information, like username and | |
671 | password, if these are not included in the configuration. This can be | |
672 | used to implement, e.g., one-time-passwords or generic token card | |
673 | authentication where the authentication is based on a | |
674 | challenge-response that uses an external device for generating the | |
675 | response. | |
676 | ||
677 | The control interface of wpa_supplicant can be configured to allow | |
678 | non-root user access (ctrl_interface_group in the configuration | |
679 | file). This makes it possible to run wpa_cli with a normal user | |
680 | account. | |
681 | ||
682 | wpa_cli supports two modes: interactive and command line. Both modes | |
683 | share the same command set and the main difference is in interactive | |
684 | mode providing access to unsolicited messages (event messages, | |
685 | username/password requests). | |
686 | ||
687 | Interactive mode is started when wpa_cli is executed without including | |
688 | the command as a command line parameter. Commands are then entered on | |
689 | the wpa_cli prompt. In command line mode, the same commands are | |
690 | entered as command line arguments for wpa_cli. | |
691 | ||
692 | ||
693 | Interactive authentication parameters request | |
694 | ||
695 | When wpa_supplicant need authentication parameters, like username and | |
696 | password, which are not present in the configuration file, it sends a | |
697 | request message to all attached frontend programs, e.g., wpa_cli in | |
698 | interactive mode. wpa_cli shows these requests with | |
699 | "CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or | |
700 | OTP (one-time-password). <id> is a unique identifier for the current | |
701 | network. <text> is description of the request. In case of OTP request, | |
702 | it includes the challenge from the authentication server. | |
703 | ||
704 | The reply to these requests can be given with 'identity', 'password', | |
705 | and 'otp' commands. <id> needs to be copied from the the matching | |
706 | request. 'password' and 'otp' commands can be used regardless of | |
707 | whether the request was for PASSWORD or OTP. The main difference | |
708 | between these two commands is that values given with 'password' are | |
709 | remembered as long as wpa_supplicant is running whereas values given | |
710 | with 'otp' are used only once and then forgotten, i.e., wpa_supplicant | |
711 | will ask frontend for a new value for every use. This can be used to | |
712 | implement one-time-password lists and generic token card -based | |
713 | authentication. | |
714 | ||
715 | Example request for password and a matching reply: | |
716 | ||
717 | CTRL-REQ-PASSWORD-1:Password needed for SSID foobar | |
718 | > password 1 mysecretpassword | |
719 | ||
720 | Example request for generic token card challenge-response: | |
721 | ||
722 | CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar | |
723 | > otp 2 9876 | |
724 | ||
725 | ||
726 | wpa_cli commands | |
727 | ||
728 | status = get current WPA/EAPOL/EAP status | |
729 | mib = get MIB variables (dot1x, dot11) | |
730 | help = show this usage help | |
731 | interface [ifname] = show interfaces/select interface | |
732 | level <debug level> = change debug level | |
733 | license = show full wpa_cli license | |
734 | logoff = IEEE 802.1X EAPOL state machine logoff | |
735 | logon = IEEE 802.1X EAPOL state machine logon | |
736 | set = set variables (shows list of variables when run without arguments) | |
737 | pmksa = show PMKSA cache | |
738 | reassociate = force reassociation | |
739 | reconfigure = force wpa_supplicant to re-read its configuration file | |
740 | preauthenticate <BSSID> = force preauthentication | |
741 | identity <network id> <identity> = configure identity for an SSID | |
742 | password <network id> <password> = configure password for an SSID | |
743 | pin <network id> <pin> = configure pin for an SSID | |
744 | otp <network id> <password> = configure one-time-password for an SSID | |
745 | passphrase <network id> <passphrase> = configure private key passphrase | |
746 | for an SSID | |
747 | bssid <network id> <BSSID> = set preferred BSSID for an SSID | |
748 | list_networks = list configured networks | |
749 | select_network <network id> = select a network (disable others) | |
750 | enable_network <network id> = enable a network | |
751 | disable_network <network id> = disable a network | |
752 | add_network = add a network | |
753 | remove_network <network id> = remove a network | |
754 | set_network <network id> <variable> <value> = set network variables (shows | |
755 | list of variables when run without arguments) | |
756 | get_network <network id> <variable> = get network variables | |
757 | save_config = save the current configuration | |
758 | disconnect = disconnect and wait for reassociate command before connecting | |
759 | scan = request new BSS scan | |
760 | scan_results = get latest scan results | |
761 | get_capability <eap/pairwise/group/key_mgmt/proto/auth_alg> = get capabilies | |
762 | terminate = terminate wpa_supplicant | |
763 | quit = exit wpa_cli | |
764 | ||
765 | ||
766 | wpa_cli command line options | |
767 | ||
768 | wpa_cli [-p<path to ctrl sockets>] [-i<ifname>] [-hvB] [-a<action file>] \ | |
769 | [-P<pid file>] [-g<global ctrl>] [command..] | |
770 | -h = help (show this usage text) | |
771 | -v = shown version information | |
772 | -a = run in daemon mode executing the action file based on events from | |
773 | wpa_supplicant | |
774 | -B = run a daemon in the background | |
775 | default path: /var/run/wpa_supplicant | |
776 | default interface: first interface found in socket path | |
777 | ||
778 | ||
779 | Using wpa_cli to run external program on connect/disconnect | |
780 | ----------------------------------------------------------- | |
781 | ||
782 | wpa_cli can used to run external programs whenever wpa_supplicant | |
783 | connects or disconnects from a network. This can be used, e.g., to | |
784 | update network configuration and/or trigget DHCP client to update IP | |
785 | addresses, etc. | |
786 | ||
787 | One wpa_cli process in "action" mode needs to be started for each | |
788 | interface. For example, the following command starts wpa_cli for the | |
789 | default ingterface (-i can be used to select the interface in case of | |
790 | more than one interface being used at the same time): | |
791 | ||
792 | wpa_cli -a/sbin/wpa_action.sh -B | |
793 | ||
794 | The action file (-a option, /sbin/wpa_action.sh in this example) will | |
795 | be executed whenever wpa_supplicant completes authentication (connect | |
796 | event) or detects disconnection). The action script will be called | |
797 | with two command line arguments: interface name and event (CONNECTED | |
798 | or DISCONNECTED). If the action script needs to get more information | |
799 | about the current network, it can use 'wpa_cli status' to query | |
800 | wpa_supplicant for more information. | |
801 | ||
802 | Following example can be used as a simple template for an action | |
803 | script: | |
804 | ||
805 | #!/bin/sh | |
806 | ||
807 | IFNAME=$1 | |
808 | CMD=$2 | |
809 | ||
be5b1e86 | 810 | if [ "$CMD" = "CONNECTED" ]; then |
6fc6879b JM |
811 | SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=` |
812 | # configure network, signal DHCP client, etc. | |
813 | fi | |
814 | ||
be5b1e86 | 815 | if [ "$CMD" = "DISCONNECTED" ]; then |
6fc6879b | 816 | # remove network configuration, if needed |
be5b1e86 | 817 | SSID= |
6fc6879b JM |
818 | fi |
819 | ||
820 | ||
821 | ||
822 | Integrating with pcmcia-cs/cardmgr scripts | |
823 | ------------------------------------------ | |
824 | ||
825 | wpa_supplicant needs to be running when using a wireless network with | |
826 | WPA. It can be started either from system startup scripts or from | |
827 | pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be | |
828 | completed before data frames can be exchanged, so wpa_supplicant | |
829 | should be started before DHCP client. | |
830 | ||
831 | For example, following small changes to pcmcia-cs scripts can be used | |
832 | to enable WPA support: | |
833 | ||
834 | Add MODE="Managed" and WPA="y" to the network scheme in | |
835 | /etc/pcmcia/wireless.opts. | |
836 | ||
837 | Add the following block to the end of 'start' action handler in | |
838 | /etc/pcmcia/wireless: | |
839 | ||
840 | if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then | |
841 | /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf \ | |
842 | -i$DEVICE | |
843 | fi | |
844 | ||
845 | Add the following block to the end of 'stop' action handler (may need | |
846 | to be separated from other actions) in /etc/pcmcia/wireless: | |
847 | ||
848 | if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then | |
849 | killall wpa_supplicant | |
850 | fi | |
851 | ||
852 | This will make cardmgr start wpa_supplicant when the card is plugged | |
853 | in. | |
854 | ||
855 | ||
856 | ||
857 | Dynamic interface add and operation without configuration files | |
858 | --------------------------------------------------------------- | |
859 | ||
860 | wpa_supplicant can be started without any configuration files or | |
861 | network interfaces. When used in this way, a global (i.e., per | |
862 | wpa_supplicant process) control interface is used to add and remove | |
863 | network interfaces. Each network interface can then be configured | |
864 | through a per-network interface control interface. For example, | |
865 | following commands show how to start wpa_supplicant without any | |
866 | network interfaces and then add a network interface and configure a | |
867 | network (SSID): | |
868 | ||
869 | # Start wpa_supplicant in the background | |
870 | wpa_supplicant -g/var/run/wpa_supplicant-global -B | |
871 | ||
872 | # Add a new interface (wlan0, no configuration file, driver=wext, and | |
873 | # enable control interface) | |
874 | wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \ | |
875 | "" wext /var/run/wpa_supplicant | |
876 | ||
877 | # Configure a network using the newly added network interface: | |
878 | wpa_cli -iwlan0 add_network | |
879 | wpa_cli -iwlan0 set_network 0 ssid '"test"' | |
880 | wpa_cli -iwlan0 set_network 0 key_mgmt WPA-PSK | |
881 | wpa_cli -iwlan0 set_network 0 psk '"12345678"' | |
882 | wpa_cli -iwlan0 set_network 0 pairwise TKIP | |
883 | wpa_cli -iwlan0 set_network 0 group TKIP | |
884 | wpa_cli -iwlan0 set_network 0 proto WPA | |
885 | wpa_cli -iwlan0 enable_network 0 | |
886 | ||
887 | # At this point, the new network interface should start trying to associate | |
888 | # with the WPA-PSK network using SSID test. | |
889 | ||
890 | # Remove network interface | |
891 | wpa_cli -g/var/run/wpa_supplicant-global interface_remove wlan0 | |
892 | ||
893 | ||
894 | Privilege separation | |
895 | -------------------- | |
896 | ||
897 | To minimize the size of code that needs to be run with root privileges | |
898 | (e.g., to control wireless interface operation), wpa_supplicant | |
899 | supports optional privilege separation. If enabled, this separates the | |
900 | privileged operations into a separate process (wpa_priv) while leaving | |
901 | rest of the code (e.g., EAP authentication and WPA handshakes) into an | |
902 | unprivileged process (wpa_supplicant) that can be run as non-root | |
903 | user. Privilege separation restricts the effects of potential software | |
904 | errors by containing the majority of the code in an unprivileged | |
905 | process to avoid full system compromise. | |
906 | ||
907 | Privilege separation is not enabled by default and it can be enabled | |
908 | by adding CONFIG_PRIVSEP=y to the build configuration (.config). When | |
909 | enabled, the privileged operations (driver wrapper and l2_packet) are | |
910 | linked into a separate daemon program, wpa_priv. The unprivileged | |
911 | program, wpa_supplicant, will be built with a special driver/l2_packet | |
912 | wrappers that communicate with the privileged wpa_priv process to | |
913 | perform the needed operations. wpa_priv can control what privileged | |
914 | are allowed. | |
915 | ||
916 | wpa_priv needs to be run with network admin privileges (usually, root | |
917 | user). It opens a UNIX domain socket for each interface that is | |
918 | included on the command line; any other interface will be off limits | |
919 | for wpa_supplicant in this kind of configuration. After this, | |
920 | wpa_supplicant can be run as a non-root user (e.g., all standard users | |
921 | on a laptop or as a special non-privileged user account created just | |
922 | for this purpose to limit access to user files even further). | |
923 | ||
924 | ||
925 | Example configuration: | |
926 | - create user group for users that are allowed to use wpa_supplicant | |
927 | ('wpapriv' in this example) and assign users that should be able to | |
928 | use wpa_supplicant into that group | |
929 | - create /var/run/wpa_priv directory for UNIX domain sockets and control | |
930 | user access by setting it accessible only for the wpapriv group: | |
931 | mkdir /var/run/wpa_priv | |
932 | chown root:wpapriv /var/run/wpa_priv | |
933 | chmod 0750 /var/run/wpa_priv | |
934 | - start wpa_priv as root (e.g., from system startup scripts) with the | |
935 | enabled interfaces configured on the command line: | |
936 | wpa_priv -B -P /var/run/wpa_priv.pid wext:ath0 | |
937 | - run wpa_supplicant as non-root with a user that is in wpapriv group: | |
938 | wpa_supplicant -i ath0 -c wpa_supplicant.conf | |
939 | ||
940 | wpa_priv does not use the network interface before wpa_supplicant is | |
941 | started, so it is fine to include network interfaces that are not | |
942 | available at the time wpa_priv is started. As an alternative, wpa_priv | |
943 | can be started when an interface is added (hotplug/udev/etc. scripts). | |
944 | wpa_priv can control multiple interface with one process, but it is | |
945 | also possible to run multiple wpa_priv processes at the same time, if | |
946 | desired. |