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