Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 1 | WPA Supplicant |
| 2 | ============== |
| 3 | |
Dmitry Shmidt | fb79edc | 2014-01-10 10:45:54 -0800 | [diff] [blame] | 4 | Copyright (c) 2003-2014, Jouni Malinen <j@w1.fi> and contributors |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 5 | All Rights Reserved. |
| 6 | |
Dmitry Shmidt | c5ec7f5 | 2012-03-06 16:33:24 -0800 | [diff] [blame] | 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. |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 12 | |
| 13 | |
| 14 | |
| 15 | License |
| 16 | ------- |
| 17 | |
Dmitry Shmidt | c5ec7f5 | 2012-03-06 16:33:24 -0800 | [diff] [blame] | 18 | This software may be distributed, used, and modified under the terms of |
| 19 | BSD license: |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 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: |
Dmitry Shmidt | 4b06059 | 2013-04-29 16:42:49 -0700 | [diff] [blame] | 118 | Linux drivers that support cfg80211/nl80211. Even though there are |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 119 | number of driver specific interface included in wpa_supplicant, please |
Dmitry Shmidt | 4b06059 | 2013-04-29 16:42:49 -0700 | [diff] [blame] | 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. |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 127 | |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 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 |
Dmitry Shmidt | 1f69aa5 | 2012-01-24 16:10:04 -0800 | [diff] [blame] | 304 | driver interfaces (e.g., nl80211, wext, ..) and which authentication |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 305 | methods (e.g., EAP-TLS, EAP-PEAP, ..) are included. |
| 306 | |
| 307 | Following build time configuration options are used to control IEEE |
| 308 | 802.1X/EAPOL and EAP state machines and all EAP methods. Including |
| 309 | TLS, PEAP, or TTLS will require linking wpa_supplicant with OpenSSL |
| 310 | library for TLS implementation. Alternatively, GnuTLS or the internal |
| 311 | TLSv1 implementation can be used for TLS functionaly. |
| 312 | |
| 313 | CONFIG_IEEE8021X_EAPOL=y |
| 314 | CONFIG_EAP_MD5=y |
| 315 | CONFIG_EAP_MSCHAPV2=y |
| 316 | CONFIG_EAP_TLS=y |
| 317 | CONFIG_EAP_PEAP=y |
| 318 | CONFIG_EAP_TTLS=y |
| 319 | CONFIG_EAP_GTC=y |
| 320 | CONFIG_EAP_OTP=y |
| 321 | CONFIG_EAP_SIM=y |
| 322 | CONFIG_EAP_AKA=y |
| 323 | CONFIG_EAP_PSK=y |
| 324 | CONFIG_EAP_SAKE=y |
| 325 | CONFIG_EAP_GPSK=y |
| 326 | CONFIG_EAP_PAX=y |
| 327 | CONFIG_EAP_LEAP=y |
| 328 | CONFIG_EAP_IKEV2=y |
| 329 | |
| 330 | Following option can be used to include GSM SIM/USIM interface for GSM/UMTS |
| 331 | authentication algorithm (for EAP-SIM/EAP-AKA). This requires pcsc-lite |
| 332 | (http://www.linuxnet.com/) for smart card access. |
| 333 | |
| 334 | CONFIG_PCSC=y |
| 335 | |
| 336 | Following options can be added to .config to select which driver |
| 337 | interfaces are included. |
| 338 | |
Dmitry Shmidt | 1f69aa5 | 2012-01-24 16:10:04 -0800 | [diff] [blame] | 339 | CONFIG_DRIVER_NL80211=y |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 340 | CONFIG_DRIVER_WEXT=y |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 341 | CONFIG_DRIVER_BSD=y |
| 342 | CONFIG_DRIVER_NDIS=y |
| 343 | |
Dmitry Shmidt | 1f69aa5 | 2012-01-24 16:10:04 -0800 | [diff] [blame] | 344 | Following example includes some more features and driver interfaces that |
| 345 | are included in the wpa_supplicant package: |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 346 | |
Dmitry Shmidt | 1f69aa5 | 2012-01-24 16:10:04 -0800 | [diff] [blame] | 347 | CONFIG_DRIVER_NL80211=y |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 348 | CONFIG_DRIVER_WEXT=y |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 349 | CONFIG_DRIVER_BSD=y |
| 350 | CONFIG_DRIVER_NDIS=y |
| 351 | CONFIG_IEEE8021X_EAPOL=y |
| 352 | CONFIG_EAP_MD5=y |
| 353 | CONFIG_EAP_MSCHAPV2=y |
| 354 | CONFIG_EAP_TLS=y |
| 355 | CONFIG_EAP_PEAP=y |
| 356 | CONFIG_EAP_TTLS=y |
| 357 | CONFIG_EAP_GTC=y |
| 358 | CONFIG_EAP_OTP=y |
| 359 | CONFIG_EAP_SIM=y |
| 360 | CONFIG_EAP_AKA=y |
| 361 | CONFIG_EAP_PSK=y |
| 362 | CONFIG_EAP_SAKE=y |
| 363 | CONFIG_EAP_GPSK=y |
| 364 | CONFIG_EAP_PAX=y |
| 365 | CONFIG_EAP_LEAP=y |
| 366 | CONFIG_EAP_IKEV2=y |
| 367 | CONFIG_PCSC=y |
| 368 | |
| 369 | EAP-PEAP and EAP-TTLS will automatically include configured EAP |
| 370 | methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection. |
| 371 | |
| 372 | |
| 373 | After you have created a configuration file, you can build |
| 374 | wpa_supplicant and wpa_cli with 'make' command. You may then install |
| 375 | the binaries to a suitable system directory, e.g., /usr/local/bin. |
| 376 | |
| 377 | Example commands: |
| 378 | |
| 379 | # build wpa_supplicant and wpa_cli |
| 380 | make |
| 381 | # install binaries (this may need root privileges) |
| 382 | cp wpa_cli wpa_supplicant /usr/local/bin |
| 383 | |
| 384 | |
| 385 | You will need to make a configuration file, e.g., |
| 386 | /etc/wpa_supplicant.conf, with network configuration for the networks |
| 387 | you are going to use. Configuration file section below includes |
| 388 | explanation fo the configuration file format and includes various |
| 389 | examples. Once the configuration is ready, you can test whether the |
| 390 | configuration work by first running wpa_supplicant with following |
| 391 | command to start it on foreground with debugging enabled: |
| 392 | |
| 393 | wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d |
| 394 | |
| 395 | Assuming everything goes fine, you can start using following command |
| 396 | to start wpa_supplicant on background without debugging: |
| 397 | |
| 398 | wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B |
| 399 | |
| 400 | Please note that if you included more than one driver interface in the |
| 401 | build time configuration (.config), you may need to specify which |
| 402 | interface to use by including -D<driver name> option on the command |
| 403 | line. See following section for more details on command line options |
| 404 | for wpa_supplicant. |
| 405 | |
| 406 | |
| 407 | |
| 408 | Command line options |
| 409 | -------------------- |
| 410 | |
| 411 | usage: |
| 412 | wpa_supplicant [-BddfhKLqqtuvwW] [-P<pid file>] [-g<global ctrl>] \ |
Dmitry Shmidt | b6e9aaf | 2013-05-20 14:49:44 -0700 | [diff] [blame] | 413 | [-G<group>] \ |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 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>] \ |
Dmitry Shmidt | 2ac5f60 | 2014-03-07 10:08:21 -0800 | [diff] [blame] | 416 | [-p<driver_param>] [-b<br_ifname>] [-m<P2P Device config file>] ... |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 417 | |
| 418 | options: |
| 419 | -b = optional bridge interface name |
| 420 | -B = run daemon in the background |
| 421 | -c = Configuration file |
| 422 | -C = ctrl_interface parameter (only used if -c is not) |
| 423 | -i = interface name |
| 424 | -d = increase debugging verbosity (-dd even more) |
| 425 | -D = driver name (can be multiple drivers: nl80211,wext) |
| 426 | -f = Log output to default log location (normally /tmp) |
| 427 | -g = global ctrl_interface |
Dmitry Shmidt | b6e9aaf | 2013-05-20 14:49:44 -0700 | [diff] [blame] | 428 | -G = global ctrl_interface group |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 429 | -K = include keys (passwords, etc.) in debug output |
| 430 | -t = include timestamp in debug messages |
| 431 | -h = show this help text |
Dmitry Shmidt | 0494959 | 2012-07-19 12:16:46 -0700 | [diff] [blame] | 432 | -L = show license (BSD) |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 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 |
Dmitry Shmidt | 2ac5f60 | 2014-03-07 10:08:21 -0800 | [diff] [blame] | 441 | -m = Configuration file for the P2P Device |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 442 | |
| 443 | drivers: |
Dmitry Shmidt | 4b06059 | 2013-04-29 16:42:49 -0700 | [diff] [blame] | 444 | nl80211 = Linux nl80211/cfg80211 |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 445 | wext = Linux wireless extensions (generic) |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 446 | wired = wpa_supplicant wired Ethernet driver |
| 447 | roboswitch = wpa_supplicant Broadcom switch driver |
| 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 | |
| 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 | |
| 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 \ |
Dmitry Shmidt | 1f69aa5 | 2012-01-24 16:10:04 -0800 | [diff] [blame] | 478 | -c wpa1.conf -i wlan0 -D nl80211 -N \ |
| 479 | -c wpa2.conf -i wlan1 -D wext |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 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 | |
Dmitry Shmidt | 4b06059 | 2013-04-29 16:42:49 -0700 | [diff] [blame] | 486 | wpa_supplicant -cw.conf -Dnl80211 -iwlan0 -bbr0 |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 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 | |
| 624 | 6) Authentication for wired Ethernet. This can be used with 'wired' or |
| 625 | 'roboswitch' interface (-Dwired or -Droboswitch on command line). |
| 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 | |
| 816 | if [ "$CMD" = "CONNECTED" ]; then |
| 817 | SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=` |
| 818 | # configure network, signal DHCP client, etc. |
| 819 | fi |
| 820 | |
| 821 | if [ "$CMD" = "DISCONNECTED" ]; then |
| 822 | # remove network configuration, if needed |
| 823 | SSID= |
| 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 | |
Dmitry Shmidt | 4b06059 | 2013-04-29 16:42:49 -0700 | [diff] [blame] | 878 | # Add a new interface (wlan0, no configuration file, driver=nl80211, and |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 879 | # enable control interface) |
| 880 | wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \ |
Dmitry Shmidt | 4b06059 | 2013-04-29 16:42:49 -0700 | [diff] [blame] | 881 | "" nl80211 /var/run/wpa_supplicant |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 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: |
Dmitry Shmidt | 4b06059 | 2013-04-29 16:42:49 -0700 | [diff] [blame] | 942 | wpa_priv -B -P /var/run/wpa_priv.pid nl80211:wlan0 |
Dmitry Shmidt | 8d520ff | 2011-05-09 14:06:53 -0700 | [diff] [blame] | 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. |
Dmitry Shmidt | 5605286 | 2013-10-04 10:23:25 -0700 | [diff] [blame] | 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. |
Dmitry Shmidt | fb79edc | 2014-01-10 10:45:54 -0800 | [diff] [blame] | 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 |