Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
dbus/ | 03-May-2024 | - | 18,769 | 13,253 | ||
doc/docbook/ | 03-May-2024 | - | 2,061 | 1,726 | ||
examples/ | 03-May-2024 | - | 5,169 | 4,002 | ||
hidl/ | 03-May-2024 | - | 13,615 | 11,230 | ||
src/ | 03-May-2024 | - | ||||
systemd/ | 03-May-2024 | - | 62 | 47 | ||
utils/ | 03-May-2024 | - | 55 | 37 | ||
wpa_client_include/libwpa_client/ | 03-May-2024 | - | 11,307 | 3,172 | ||
wpa_gui-qt4/ | 03-May-2024 | - | 12,469 | 11,169 | ||
.gitignore | D | 03-May-2024 | 20 | 3 | 2 | |
Android.mk | D | 03-May-2024 | 40 KiB | 1,879 | 1,585 | |
ChangeLog | D | 03-May-2024 | 127.3 KiB | 2,447 | 2,396 | |
CleanSpec.mk | D | 03-May-2024 | 2.5 KiB | 55 | 4 | |
Makefile | D | 03-May-2024 | 43.1 KiB | 2,040 | 1,778 | |
README | D | 03-May-2024 | 39.2 KiB | 1,080 | 867 | |
README-DPP | D | 03-May-2024 | 5.9 KiB | 205 | 147 | |
README-HS20 | D | 03-May-2024 | 21.8 KiB | 649 | 555 | |
README-P2P | D | 03-May-2024 | 33 KiB | 857 | 629 | |
README-WPS | D | 03-May-2024 | 15.9 KiB | 400 | 291 | |
README-Windows.txt | D | 03-May-2024 | 12.1 KiB | 300 | 228 | |
android.config | D | 03-May-2024 | 20 KiB | 564 | 455 | |
ap.c | D | 03-May-2024 | 47.6 KiB | 1,827 | 1,448 | |
ap.h | D | 03-May-2024 | 4.4 KiB | 106 | 88 | |
autoscan.c | D | 03-May-2024 | 3.5 KiB | 163 | 113 | |
autoscan.h | D | 03-May-2024 | 1.4 KiB | 60 | 35 | |
autoscan_exponential.c | D | 03-May-2024 | 2 KiB | 105 | 69 | |
autoscan_periodic.c | D | 03-May-2024 | 1.6 KiB | 86 | 52 | |
bgscan.c | D | 03-May-2024 | 2.4 KiB | 110 | 82 | |
bgscan.h | D | 03-May-2024 | 2.1 KiB | 83 | 57 | |
bgscan_learn.c | D | 03-May-2024 | 14.4 KiB | 615 | 479 | |
bgscan_simple.c | D | 03-May-2024 | 8 KiB | 276 | 191 | |
bss.c | D | 03-May-2024 | 36.5 KiB | 1,386 | 934 | |
bss.h | D | 03-May-2024 | 6.5 KiB | 201 | 139 | |
bssid_ignore.c | D | 03-May-2024 | 5.4 KiB | 222 | 142 | |
bssid_ignore.h | D | 03-May-2024 | 1 KiB | 34 | 17 | |
config.c | D | 03-May-2024 | 131.2 KiB | 5,378 | 4,320 | |
config.h | D | 03-May-2024 | 54.8 KiB | 1,766 | 346 | |
config_file.c | D | 03-May-2024 | 42.8 KiB | 1,632 | 1,418 | |
config_none.c | D | 03-May-2024 | 1.3 KiB | 57 | 28 | |
config_ssid.h | D | 03-May-2024 | 31 KiB | 1,161 | 237 | |
config_winreg.c | D | 03-May-2024 | 24.9 KiB | 1,062 | 853 | |
ctrl_iface.c | D | 03-May-2024 | 295 KiB | 12,184 | 10,220 | |
ctrl_iface.h | D | 03-May-2024 | 5.6 KiB | 167 | 53 | |
ctrl_iface_named_pipe.c | D | 03-May-2024 | 19.7 KiB | 832 | 644 | |
ctrl_iface_udp.c | D | 03-May-2024 | 21 KiB | 832 | 682 | |
ctrl_iface_unix.c | D | 03-May-2024 | 36.1 KiB | 1,432 | 1,145 | |
defconfig | D | 03-May-2024 | 22.8 KiB | 637 | 517 | |
dpp_supplicant.c | D | 03-May-2024 | 108.6 KiB | 3,978 | 3,320 | |
dpp_supplicant.h | D | 03-May-2024 | 2.1 KiB | 46 | 33 | |
driver_i.h | D | 03-May-2024 | 29.9 KiB | 1,121 | 979 | |
eap_proxy_dummy.mak | D | 03-May-2024 | 0 | |||
eap_proxy_dummy.mk | D | 03-May-2024 | 0 | 1 | 0 | |
eap_proxy_qmi_oc.mak | D | 03-May-2024 | 530 | 20 | 14 | |
eap_proxy_qmi_oc.mk | D | 03-May-2024 | 1.1 KiB | 38 | 24 | |
eap_register.c | D | 03-May-2024 | 5.2 KiB | 272 | 204 | |
eap_testing.txt | D | 03-May-2024 | 14.4 KiB | 393 | 363 | |
eapol_test.c | D | 03-May-2024 | 39.5 KiB | 1,555 | 1,303 | |
eapol_test.py | D | 03-May-2024 | 4.4 KiB | 143 | 117 | |
events.c | D | 03-May-2024 | 154.9 KiB | 5,635 | 4,566 | |
gas_query.c | D | 03-May-2024 | 25.3 KiB | 908 | 694 | |
gas_query.h | D | 03-May-2024 | 1.5 KiB | 61 | 37 | |
hs20_supplicant.c | D | 03-May-2024 | 33.8 KiB | 1,375 | 1,147 | |
hs20_supplicant.h | D | 03-May-2024 | 2.2 KiB | 53 | 40 | |
ibss_rsn.c | D | 03-May-2024 | 23.9 KiB | 955 | 713 | |
ibss_rsn.h | D | 03-May-2024 | 1.7 KiB | 66 | 39 | |
interworking.c | D | 03-May-2024 | 82.3 KiB | 3,276 | 2,732 | |
interworking.h | D | 03-May-2024 | 1.3 KiB | 38 | 26 | |
libwpa_test.c | D | 03-May-2024 | 611 | 33 | 19 | |
main.c | D | 03-May-2024 | 10.1 KiB | 410 | 360 | |
main_none.c | D | 03-May-2024 | 844 | 41 | 22 | |
main_winmain.c | D | 03-May-2024 | 1.7 KiB | 79 | 55 | |
main_winsvc.c | D | 03-May-2024 | 11.2 KiB | 459 | 352 | |
mbo.c | D | 03-May-2024 | 16.2 KiB | 671 | 493 | |
mesh.c | D | 03-May-2024 | 22.9 KiB | 856 | 659 | |
mesh.h | D | 03-May-2024 | 1.5 KiB | 50 | 33 | |
mesh_mpm.c | D | 03-May-2024 | 36.5 KiB | 1,395 | 1,124 | |
mesh_mpm.h | D | 03-May-2024 | 1.5 KiB | 47 | 29 | |
mesh_rsn.c | D | 03-May-2024 | 20.6 KiB | 797 | 598 | |
mesh_rsn.h | D | 03-May-2024 | 1.4 KiB | 46 | 34 | |
nfc_pw_token.c | D | 03-May-2024 | 1.7 KiB | 84 | 57 | |
nmake.mak | D | 03-May-2024 | 6.6 KiB | 241 | 200 | |
notify.c | D | 03-May-2024 | 28.1 KiB | 1,250 | 893 | |
notify.h | D | 03-May-2024 | 9.6 KiB | 206 | 189 | |
offchannel.c | D | 03-May-2024 | 16.1 KiB | 489 | 325 | |
offchannel.h | D | 03-May-2024 | 1.4 KiB | 36 | 24 | |
op_classes.c | D | 03-May-2024 | 13.4 KiB | 531 | 380 | |
p2p_supplicant.c | D | 03-May-2024 | 280.2 KiB | 9,909 | 7,772 | |
p2p_supplicant.h | D | 03-May-2024 | 13 KiB | 351 | 307 | |
p2p_supplicant_sd.c | D | 03-May-2024 | 31 KiB | 1,283 | 970 | |
pasn_supplicant.c | D | 03-May-2024 | 36.7 KiB | 1,510 | 1,126 | |
preauth_test.c | D | 03-May-2024 | 8.8 KiB | 372 | 279 | |
robust_av.c | D | 03-May-2024 | 4.3 KiB | 156 | 110 | |
rrm.c | D | 03-May-2024 | 41.7 KiB | 1,595 | 1,170 | |
scan.c | D | 03-May-2024 | 83.1 KiB | 3,129 | 2,296 | |
scan.h | D | 03-May-2024 | 4 KiB | 95 | 65 | |
sme.c | D | 03-May-2024 | 83.8 KiB | 2,931 | 2,411 | |
sme.h | D | 03-May-2024 | 3.8 KiB | 140 | 107 | |
todo.txt | D | 03-May-2024 | 4.4 KiB | 79 | 78 | |
wifi_display.c | D | 03-May-2024 | 10.4 KiB | 432 | 302 | |
wifi_display.h | D | 03-May-2024 | 904 | 25 | 13 | |
win_if_list.c | D | 03-May-2024 | 3.7 KiB | 174 | 128 | |
wmm_ac.c | D | 03-May-2024 | 23.6 KiB | 988 | 739 | |
wmm_ac.h | D | 03-May-2024 | 4.8 KiB | 177 | 57 | |
wnm_sta.c | D | 03-May-2024 | 51.5 KiB | 1,983 | 1,611 | |
wnm_sta.h | D | 03-May-2024 | 2.5 KiB | 94 | 69 | |
wpa_cli.c | D | 03-May-2024 | 128.2 KiB | 5,004 | 4,142 | |
wpa_passphrase.c | D | 03-May-2024 | 1.5 KiB | 74 | 55 | |
wpa_priv.c | D | 03-May-2024 | 30.2 KiB | 1,293 | 1,062 | |
wpa_supplicant.c | D | 03-May-2024 | 230.8 KiB | 8,419 | 6,431 | |
wpa_supplicant.conf | D | 03-May-2024 | 82.4 KiB | 2,075 | 298 | |
wpa_supplicant_conf.mk | D | 03-May-2024 | 1.5 KiB | 38 | 20 | |
wpa_supplicant_conf.sh | D | 03-May-2024 | 458 | 17 | 6 | |
wpa_supplicant_i.h | D | 03-May-2024 | 52 KiB | 1,756 | 1,188 | |
wpa_supplicant_template.conf | D | 03-May-2024 | 152 | 10 | 8 | |
wpas_glue.c | D | 03-May-2024 | 39.8 KiB | 1,501 | 1,165 | |
wpas_glue.h | D | 03-May-2024 | 888 | 29 | 14 | |
wpas_kay.c | D | 03-May-2024 | 9.9 KiB | 441 | 325 | |
wpas_kay.h | D | 03-May-2024 | 1.1 KiB | 52 | 33 | |
wpas_module_tests.c | D | 03-May-2024 | 3.2 KiB | 115 | 81 | |
wps_supplicant.c | D | 03-May-2024 | 80.5 KiB | 3,009 | 2,434 | |
wps_supplicant.h | D | 03-May-2024 | 5.3 KiB | 167 | 136 |
README
1wpa_supplicant 2============== 3 4Copyright (c) 2003-2019, Jouni Malinen <j@w1.fi> and contributors 5All Rights Reserved. 6 7This program is licensed under the BSD license (the one with 8advertisement clause removed). 9 10If you are submitting changes to the project, please see CONTRIBUTIONS 11file for more instructions. 12 13 14 15License 16------- 17 18This software may be distributed, used, and modified under the terms of 19BSD license: 20 21Redistribution and use in source and binary forms, with or without 22modification, are permitted provided that the following conditions are 23met: 24 251. Redistributions of source code must retain the above copyright 26 notice, this list of conditions and the following disclaimer. 27 282. 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 323. 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 36THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 37"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 38LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 39A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 40OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 41SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 42LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 43DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 44THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 45(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 46OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 47 48 49 50Features 51-------- 52 53Supported 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-AKA' 76 * EAP-PSK 77 * EAP-PAX 78 * EAP-SAKE 79 * EAP-IKEv2 80 * EAP-GPSK 81 * EAP-pwd 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) 86 * EAP-MD5-Challenge 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 95Supported TLS/crypto libraries: 96- OpenSSL (default) 97- GnuTLS 98 99Internal 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 111Requirements 112------------ 113 114Current 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: 120 Linux drivers that support cfg80211/nl80211. Even though there are 121 number of driver specific interface included in wpa_supplicant, please 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. 129 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 143wpa_supplicant was designed to be portable for different drivers and 144operating systems. Hopefully, support for more wlan cards and OSes will be 145added in the future. See developer's documentation 146(http://hostap.epitest.fi/wpa_supplicant/devel/) for more information about the 147design of wpa_supplicant and porting to other drivers. One main goal 148is to add full WPA/WPA2 support to Linux wireless extensions to allow 149new drivers to be supported without having to implement new 150driver-specific interface code in wpa_supplicant. 151 152Optional 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 159These libraries are _not_ used in the default Linux build. Instead, 160internal Linux specific implementation is used. libpcap/libdnet are 161more portable and they can be used by adding CONFIG_L2_PACKET=pcap into 162.config. They may also be selected automatically for other operating 163systems. In case of Windows builds, WinPcap is used by default 164(CONFIG_L2_PACKET=winpcap). 165 166 167Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS: 168- OpenSSL (tested with 1.0.1 and 1.0.2 versions; assumed to 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 174One of these libraries is needed when EAP-TLS, EAP-PEAP, EAP-TTLS, or 175EAP-FAST support is enabled. WPA-PSK mode does not require this or EAPOL/EAP 176implementation. A configuration file, .config, for compilation is 177needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5, 178EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so 179they should only be enabled if testing the EAPOL/EAP state 180machines. However, there can be used as inner authentication 181algorithms with EAP-PEAP and EAP-TTLS. 182 183See Building and installing section below for more detailed 184information about the wpa_supplicant build time configuration. 185 186 187 188WPA 189--- 190 191The original security mechanism of IEEE 802.11 standard was not 192designed to be strong and has proven to be insufficient for most 193networks that require some kind of security. Task group I (Security) 194of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked 195to address the flaws of the base standard and has in practice 196completed its work in May 2004. The IEEE 802.11i amendment to the IEEE 197802.11 standard was approved in June 2004 and published in July 2004. 198 199Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the 200IEEE 802.11i work (draft 3.0) to define a subset of the security 201enhancements that can be implemented with existing wlan hardware. This 202is called Wi-Fi Protected Access<TM> (WPA). This has now become a 203mandatory component of interoperability testing and certification done 204by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web 205site (http://www.wi-fi.org/OpenSection/protected_access.asp). 206 207IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm 208for protecting wireless networks. WEP uses RC4 with 40-bit keys, 20924-bit initialization vector (IV), and CRC32 to protect against packet 210forgery. All these choices have proven to be insufficient: key space is 211too small against current attacks, RC4 key scheduling is insufficient 212(beginning of the pseudorandom stream should be skipped), IV space is 213too small and IV reuse makes attacks easier, there is no replay 214protection, and non-keyed authentication does not protect against bit 215flipping packet data. 216 217WPA is an intermediate solution for the security issues. It uses 218Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a 219compromise on strong security and possibility to use existing 220hardware. It still uses RC4 for the encryption like WEP, but with 221per-packet RC4 keys. In addition, it implements replay protection, 222keyed packet authentication mechanism (Michael MIC). 223 224Keys can be managed using two different mechanisms. WPA can either use 225an external authentication server (e.g., RADIUS) and EAP just like 226IEEE 802.1X is using or pre-shared keys without need for additional 227servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal", 228respectively. Both mechanisms will generate a master session key for 229the Authenticator (AP) and Supplicant (client station). 230 231WPA implements a new key handshake (4-Way Handshake and Group Key 232Handshake) for generating and exchanging data encryption keys between 233the Authenticator and Supplicant. This handshake is also used to 234verify that both Authenticator and Supplicant know the master session 235key. These handshakes are identical regardless of the selected key 236management mechanism (only the method for generating master session 237key changes). 238 239 240 241IEEE 802.11i / WPA2 242------------------- 243 244The design for parts of IEEE 802.11i that were not included in WPA has 245finished (May 2004) and this amendment to IEEE 802.11 was approved in 246June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new 247version of WPA called WPA2. This includes, e.g., support for more 248robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC) 249to replace TKIP and optimizations for handoff (reduced number of 250messages in initial key handshake, pre-authentication, and PMKSA caching). 251 252 253 254wpa_supplicant 255-------------- 256 257wpa_supplicant is an implementation of the WPA Supplicant component, 258i.e., the part that runs in the client stations. It implements WPA key 259negotiation with a WPA Authenticator and EAP authentication with 260Authentication Server. In addition, it controls the roaming and IEEE 261802.11 authentication/association of the wlan driver. 262 263wpa_supplicant is designed to be a "daemon" program that runs in the 264background and acts as the backend component controlling the wireless 265connection. wpa_supplicant supports separate frontend programs and an 266example text-based frontend, wpa_cli, is included with wpa_supplicant. 267 268Following 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 286Building and installing 287----------------------- 288 289In order to be able to build wpa_supplicant, you will first need to 290select which parts of it will be included. This is done by creating a 291build time configuration file, .config, in the wpa_supplicant root 292directory. Configuration options are text lines using following 293format: CONFIG_<option>=y. Lines starting with # are considered 294comments and are ignored. See defconfig file for an example configuration 295and a list of available options and additional notes. 296 297The build time configuration can be used to select only the needed 298features and limit the binary size and requirements for external 299libraries. The main configuration parts are the selection of which 300driver interfaces (e.g., nl80211, wext, ..) and which authentication 301methods (e.g., EAP-TLS, EAP-PEAP, ..) are included. 302 303Following build time configuration options are used to control IEEE 304802.1X/EAPOL and EAP state machines and all EAP methods. Including 305TLS, PEAP, or TTLS will require linking wpa_supplicant with OpenSSL 306library for TLS implementation. Alternatively, GnuTLS or the internal 307TLSv1 implementation can be used for TLS functionality. 308 309CONFIG_IEEE8021X_EAPOL=y 310CONFIG_EAP_MD5=y 311CONFIG_EAP_MSCHAPV2=y 312CONFIG_EAP_TLS=y 313CONFIG_EAP_PEAP=y 314CONFIG_EAP_TTLS=y 315CONFIG_EAP_GTC=y 316CONFIG_EAP_OTP=y 317CONFIG_EAP_SIM=y 318CONFIG_EAP_AKA=y 319CONFIG_EAP_AKA_PRIME=y 320CONFIG_EAP_PSK=y 321CONFIG_EAP_SAKE=y 322CONFIG_EAP_GPSK=y 323CONFIG_EAP_PAX=y 324CONFIG_EAP_LEAP=y 325CONFIG_EAP_IKEV2=y 326CONFIG_EAP_PWD=y 327 328Following option can be used to include GSM SIM/USIM interface for GSM/UMTS 329authentication algorithm (for EAP-SIM/EAP-AKA/EAP-AKA'). This requires pcsc-lite 330(http://www.linuxnet.com/) for smart card access. 331 332CONFIG_PCSC=y 333 334Following options can be added to .config to select which driver 335interfaces are included. 336 337CONFIG_DRIVER_NL80211=y 338CONFIG_DRIVER_WEXT=y 339CONFIG_DRIVER_BSD=y 340CONFIG_DRIVER_NDIS=y 341 342Following example includes some more features and driver interfaces that 343are included in the wpa_supplicant package: 344 345CONFIG_DRIVER_NL80211=y 346CONFIG_DRIVER_WEXT=y 347CONFIG_DRIVER_BSD=y 348CONFIG_DRIVER_NDIS=y 349CONFIG_IEEE8021X_EAPOL=y 350CONFIG_EAP_MD5=y 351CONFIG_EAP_MSCHAPV2=y 352CONFIG_EAP_TLS=y 353CONFIG_EAP_PEAP=y 354CONFIG_EAP_TTLS=y 355CONFIG_EAP_GTC=y 356CONFIG_EAP_OTP=y 357CONFIG_EAP_SIM=y 358CONFIG_EAP_AKA=y 359CONFIG_EAP_PSK=y 360CONFIG_EAP_SAKE=y 361CONFIG_EAP_GPSK=y 362CONFIG_EAP_PAX=y 363CONFIG_EAP_LEAP=y 364CONFIG_EAP_IKEV2=y 365CONFIG_PCSC=y 366 367EAP-PEAP and EAP-TTLS will automatically include configured EAP 368methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection. 369 370 371After you have created a configuration file, you can build 372wpa_supplicant and wpa_cli with 'make' command. You may then install 373the binaries to a suitable system directory, e.g., /usr/local/bin. 374 375Example commands: 376 377# build wpa_supplicant and wpa_cli 378make 379# install binaries (this may need root privileges) 380cp wpa_cli wpa_supplicant /usr/local/bin 381 382 383You will need to make a configuration file, e.g., 384/etc/wpa_supplicant.conf, with network configuration for the networks 385you are going to use. Configuration file section below includes 386explanation of the configuration file format and includes various 387examples. Once the configuration is ready, you can test whether the 388configuration work by first running wpa_supplicant with following 389command to start it on foreground with debugging enabled: 390 391wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d 392 393Assuming everything goes fine, you can start using following command 394to start wpa_supplicant on background without debugging: 395 396wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B 397 398Please note that if you included more than one driver interface in the 399build time configuration (.config), you may need to specify which 400interface to use by including -D<driver name> option on the command 401line. See following section for more details on command line options 402for wpa_supplicant. 403 404 405 406Command line options 407-------------------- 408 409usage: 410 wpa_supplicant [-BddfhKLqqtuvW] [-P<pid file>] [-g<global ctrl>] \ 411 [-G<group>] \ 412 -i<ifname> -c<config file> [-C<ctrl>] [-D<driver>] [-p<driver_param>] \ 413 [-b<br_ifname> [-MN -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] \ 414 [-p<driver_param>] [-b<br_ifname>] [-m<P2P Device config file>] ... 415 416options: 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 426 -G = global ctrl_interface group 427 -K = include keys (passwords, etc.) in debug output 428 -t = include timestamp in debug messages 429 -h = show this help text 430 -L = show license (BSD) 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 436 -W = wait for a control interface monitor before starting 437 -M = start describing matching interface 438 -N = start describing new interface 439 -m = Configuration file for the P2P Device 440 441drivers: 442 nl80211 = Linux nl80211/cfg80211 443 wext = Linux wireless extensions (generic) 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 449In most common cases, wpa_supplicant is started with 450 451wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0 452 453This makes the process fork into background. 454 455The easiest way to debug problems, and to get debug log for bug 456reports, is to start wpa_supplicant on foreground with debugging 457enabled: 458 459wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d 460 461If the specific driver wrapper is not known beforehand, it is possible 462to specify multiple comma separated driver wrappers on the command 463line. wpa_supplicant will use the first driver wrapper that is able to 464initialize the interface. 465 466wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0 467 468 469wpa_supplicant can control multiple interfaces (radios) either by 470running one process for each interface separately or by running just 471one process and list of options at command line. Each interface is 472separated with -N argument. As an example, following command would 473start wpa_supplicant for two interfaces: 474 475wpa_supplicant \ 476 -c wpa1.conf -i wlan0 -D nl80211 -N \ 477 -c wpa2.conf -i wlan1 -D wext 478 479 480If the interfaces on which wpa_supplicant is to run are not known or do 481not exist, wpa_supplicant can match an interface when it arrives. Each 482matched interface is separated with -M argument and the -i argument now 483allows for pattern matching. 484 485As an example, the following command would start wpa_supplicant for a 486specific wired interface called lan0, any interface starting with wlan 487and lastly any other interface. Each match has its own configuration 488file, and for the wired interface a specific driver has also been given. 489 490wpa_supplicant \ 491 -M -c wpa_wired.conf -ilan0 -D wired \ 492 -M -c wpa1.conf -iwlan* \ 493 -M -c wpa2.conf 494 495 496If the interface is added in a Linux bridge (e.g., br0), the bridge 497interface needs to be configured to wpa_supplicant in addition to the 498main interface: 499 500wpa_supplicant -cw.conf -Dnl80211 -iwlan0 -bbr0 501 502 503Configuration file 504------------------ 505 506wpa_supplicant is configured using a text file that lists all accepted 507networks and security policies, including pre-shared keys. See 508example configuration file, wpa_supplicant.conf, for detailed 509information about the configuration format and supported fields. 510 511Changes to configuration file can be reloaded be sending SIGHUP signal 512to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly, 513reloading can be triggered with 'wpa_cli reconfigure' command. 514 515Configuration file can include one or more network blocks, e.g., one 516for each used SSID. wpa_supplicant will automatically select the best 517network based on the order of network blocks in the configuration 518file, network security level (WPA/WPA2 is preferred), and signal 519strength. 520 521Example configuration files for some common configurations: 522 5231) 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 527ctrl_interface=/var/run/wpa_supplicant 528ctrl_interface_group=wheel 529# 530# home network; allow all valid ciphers 531network={ 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 539network={ 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 5542) 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 557ctrl_interface=/var/run/wpa_supplicant 558ctrl_interface_group=wheel 559network={ 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 5723) 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 575ctrl_interface=/var/run/wpa_supplicant 576ctrl_interface_group=wheel 577network={ 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 5904) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and 591 broadcast); use EAP-TLS for authentication 592 593ctrl_interface=/var/run/wpa_supplicant 594ctrl_interface_group=wheel 595network={ 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 6095) 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 614ctrl_interface=/var/run/wpa_supplicant 615ctrl_interface_group=wheel 616network={ 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 6386) Authentication for wired Ethernet. This can be used with 'wired' or 639 'roboswitch' interface (-Dwired or -Droboswitch on command line). 640 641ctrl_interface=/var/run/wpa_supplicant 642ctrl_interface_group=wheel 643ap_scan=0 644network={ 645 key_mgmt=IEEE8021X 646 eap=MD5 647 identity="user" 648 password="password" 649 eapol_flags=0 650} 651 652 653 654Certificates 655------------ 656 657Some EAP authentication methods require use of certificates. EAP-TLS 658uses both server side and client certificates whereas EAP-PEAP and 659EAP-TTLS only require the server side certificate. When client 660certificate is used, a matching private key file has to also be 661included in configuration. If the private key uses a passphrase, this 662has to be configured in wpa_supplicant.conf ("private_key_passwd"). 663 664wpa_supplicant supports X.509 certificates in PEM and DER 665formats. User certificate and private key can be included in the same 666file. 667 668If the user certificate and private key is received in PKCS#12/PFX 669format, they need to be converted to suitable PEM/DER format for 670wpa_supplicant. This can be done, e.g., with following commands: 671 672# convert client certificate and private key to PEM format 673openssl pkcs12 -in example.pfx -out user.pem -clcerts 674# convert CA certificate (if included in PFX file) to PEM format 675openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys 676 677 678 679wpa_cli 680------- 681 682wpa_cli is a text-based frontend program for interacting with 683wpa_supplicant. It is used to query current status, change 684configuration, trigger events, and request interactive user input. 685 686wpa_cli can show the current authentication status, selected security 687mode, dot11 and dot1x MIBs, etc. In addition, it can configure some 688variables like EAPOL state machine parameters and trigger events like 689reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user 690interface to request authentication information, like username and 691password, if these are not included in the configuration. This can be 692used to implement, e.g., one-time-passwords or generic token card 693authentication where the authentication is based on a 694challenge-response that uses an external device for generating the 695response. 696 697The control interface of wpa_supplicant can be configured to allow 698non-root user access (ctrl_interface_group in the configuration 699file). This makes it possible to run wpa_cli with a normal user 700account. 701 702wpa_cli supports two modes: interactive and command line. Both modes 703share the same command set and the main difference is in interactive 704mode providing access to unsolicited messages (event messages, 705username/password requests). 706 707Interactive mode is started when wpa_cli is executed without including 708the command as a command line parameter. Commands are then entered on 709the wpa_cli prompt. In command line mode, the same commands are 710entered as command line arguments for wpa_cli. 711 712 713Interactive authentication parameters request 714 715When wpa_supplicant need authentication parameters, like username and 716password, which are not present in the configuration file, it sends a 717request message to all attached frontend programs, e.g., wpa_cli in 718interactive mode. wpa_cli shows these requests with 719"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or 720OTP (one-time-password). <id> is a unique identifier for the current 721network. <text> is description of the request. In case of OTP request, 722it includes the challenge from the authentication server. 723 724The reply to these requests can be given with 'identity', 'password', 725and 'otp' commands. <id> needs to be copied from the the matching 726request. 'password' and 'otp' commands can be used regardless of 727whether the request was for PASSWORD or OTP. The main difference 728between these two commands is that values given with 'password' are 729remembered as long as wpa_supplicant is running whereas values given 730with 'otp' are used only once and then forgotten, i.e., wpa_supplicant 731will ask frontend for a new value for every use. This can be used to 732implement one-time-password lists and generic token card -based 733authentication. 734 735Example request for password and a matching reply: 736 737CTRL-REQ-PASSWORD-1:Password needed for SSID foobar 738> password 1 mysecretpassword 739 740Example request for generic token card challenge-response: 741 742CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 743> otp 2 9876 744 745 746wpa_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 capabilities 782 terminate = terminate wpa_supplicant 783 quit = exit wpa_cli 784 785 786wpa_cli command line options 787 788wpa_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 799Using wpa_cli to run external program on connect/disconnect 800----------------------------------------------------------- 801 802wpa_cli can used to run external programs whenever wpa_supplicant 803connects or disconnects from a network. This can be used, e.g., to 804update network configuration and/or trigget DHCP client to update IP 805addresses, etc. 806 807One wpa_cli process in "action" mode needs to be started for each 808interface. For example, the following command starts wpa_cli for the 809default interface (-i can be used to select the interface in case of 810more than one interface being used at the same time): 811 812wpa_cli -a/sbin/wpa_action.sh -B 813 814The action file (-a option, /sbin/wpa_action.sh in this example) will 815be executed whenever wpa_supplicant completes authentication (connect 816event) or detects disconnection). The action script will be called 817with two command line arguments: interface name and event (CONNECTED 818or DISCONNECTED). If the action script needs to get more information 819about the current network, it can use 'wpa_cli status' to query 820wpa_supplicant for more information. 821 822Following example can be used as a simple template for an action 823script: 824 825#!/bin/sh 826 827IFNAME=$1 828CMD=$2 829 830if [ "$CMD" = "CONNECTED" ]; then 831 SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=` 832 # configure network, signal DHCP client, etc. 833fi 834 835if [ "$CMD" = "DISCONNECTED" ]; then 836 # remove network configuration, if needed 837 SSID= 838fi 839 840 841 842Integrating with pcmcia-cs/cardmgr scripts 843------------------------------------------ 844 845wpa_supplicant needs to be running when using a wireless network with 846WPA. It can be started either from system startup scripts or from 847pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be 848completed before data frames can be exchanged, so wpa_supplicant 849should be started before DHCP client. 850 851For example, following small changes to pcmcia-cs scripts can be used 852to enable WPA support: 853 854Add MODE="Managed" and WPA="y" to the network scheme in 855/etc/pcmcia/wireless.opts. 856 857Add 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 865Add the following block to the end of 'stop' action handler (may need 866to 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 872This will make cardmgr start wpa_supplicant when the card is plugged 873in. 874 875 876 877Dynamic interface add and operation without configuration files 878--------------------------------------------------------------- 879 880wpa_supplicant can be started without any configuration files or 881network interfaces. When used in this way, a global (i.e., per 882wpa_supplicant process) control interface is used to add and remove 883network interfaces. Each network interface can then be configured 884through a per-network interface control interface. For example, 885following commands show how to start wpa_supplicant without any 886network interfaces and then add a network interface and configure a 887network (SSID): 888 889# Start wpa_supplicant in the background 890wpa_supplicant -g/var/run/wpa_supplicant-global -B 891 892# Add a new interface (wlan0, no configuration file, driver=nl80211, and 893# enable control interface) 894wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \ 895 "" nl80211 /var/run/wpa_supplicant 896 897# Configure a network using the newly added network interface: 898wpa_cli -iwlan0 add_network 899wpa_cli -iwlan0 set_network 0 ssid '"test"' 900wpa_cli -iwlan0 set_network 0 key_mgmt WPA-PSK 901wpa_cli -iwlan0 set_network 0 psk '"12345678"' 902wpa_cli -iwlan0 set_network 0 pairwise TKIP 903wpa_cli -iwlan0 set_network 0 group TKIP 904wpa_cli -iwlan0 set_network 0 proto WPA 905wpa_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 911wpa_cli -g/var/run/wpa_supplicant-global interface_remove wlan0 912 913 914Privilege separation 915-------------------- 916 917To minimize the size of code that needs to be run with root privileges 918(e.g., to control wireless interface operation), wpa_supplicant 919supports optional privilege separation. If enabled, this separates the 920privileged operations into a separate process (wpa_priv) while leaving 921rest of the code (e.g., EAP authentication and WPA handshakes) into an 922unprivileged process (wpa_supplicant) that can be run as non-root 923user. Privilege separation restricts the effects of potential software 924errors by containing the majority of the code in an unprivileged 925process to avoid full system compromise. 926 927Privilege separation is not enabled by default and it can be enabled 928by adding CONFIG_PRIVSEP=y to the build configuration (.config). When 929enabled, the privileged operations (driver wrapper and l2_packet) are 930linked into a separate daemon program, wpa_priv. The unprivileged 931program, wpa_supplicant, will be built with a special driver/l2_packet 932wrappers that communicate with the privileged wpa_priv process to 933perform the needed operations. wpa_priv can control what privileged 934are allowed. 935 936wpa_priv needs to be run with network admin privileges (usually, root 937user). It opens a UNIX domain socket for each interface that is 938included on the command line; any other interface will be off limits 939for wpa_supplicant in this kind of configuration. After this, 940wpa_supplicant can be run as a non-root user (e.g., all standard users 941on a laptop or as a special non-privileged user account created just 942for this purpose to limit access to user files even further). 943 944 945Example 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: 956 wpa_priv -B -P /var/run/wpa_priv.pid nl80211:wlan0 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 960wpa_priv does not use the network interface before wpa_supplicant is 961started, so it is fine to include network interfaces that are not 962available at the time wpa_priv is started. As an alternative, wpa_priv 963can be started when an interface is added (hotplug/udev/etc. scripts). 964wpa_priv can control multiple interface with one process, but it is 965also possible to run multiple wpa_priv processes at the same time, if 966desired. 967 968It should be noted that the interface used between wpa_supplicant and 969wpa_priv does not include all the capabilities of the wpa_supplicant 970driver interface and at times, this interface lacks update especially 971for recent addition. Consequently, use of wpa_priv does come with the 972price of somewhat reduced available functionality. The next section 973describing how wpa_supplicant can be used with reduced privileges 974without having to handle the complexity of separate wpa_priv. While that 975approve does not provide separation for network admin capabilities, it 976does allow other root privileges to be dropped without the drawbacks of 977the wpa_priv process. 978 979 980Linux capabilities instead of privileged process 981------------------------------------------------ 982 983wpa_supplicant performs operations that need special permissions, e.g., 984to control the network connection. Traditionally this has been achieved 985by running wpa_supplicant as a privileged process with effective user id 9860 (root). Linux capabilities can be used to provide restricted set of 987capabilities to match the functions needed by wpa_supplicant. The 988minimum set of capabilities needed for the operations is CAP_NET_ADMIN 989and CAP_NET_RAW. 990 991setcap(8) can be used to set file capabilities. For example: 992 993sudo setcap cap_net_raw,cap_net_admin+ep wpa_supplicant 994 995Please note that this would give anyone being able to run that 996wpa_supplicant binary access to the additional capabilities. This can 997further be limited by file owner/group and mode bits. For example: 998 999sudo chown wpas wpa_supplicant 1000sudo chmod 0100 wpa_supplicant 1001 1002This combination of setcap, chown, and chmod commands would allow wpas 1003user to execute wpa_supplicant with additional network admin/raw 1004capabilities. 1005 1006Common way style of creating a control interface socket in 1007/var/run/wpa_supplicant could not be done by this user, but this 1008directory could be created before starting the wpa_supplicant and set to 1009suitable mode to allow wpa_supplicant to create sockets 1010there. Alternatively, other directory or abstract socket namespace could 1011be used for the control interface. 1012 1013 1014External requests for radio control 1015----------------------------------- 1016 1017External programs can request wpa_supplicant to not start offchannel 1018operations during other tasks that may need exclusive control of the 1019radio. The RADIO_WORK control interface command can be used for this. 1020 1021"RADIO_WORK add <name> [freq=<MHz>] [timeout=<seconds>]" command can be 1022used to reserve a slot for radio access. If freq is specified, other 1023radio work items on the same channel may be completed in 1024parallel. Otherwise, all other radio work items are blocked during 1025execution. Timeout is set to 10 seconds by default to avoid blocking 1026wpa_supplicant operations for excessive time. If a longer (or shorter) 1027safety timeout is needed, that can be specified with the optional 1028timeout parameter. This command returns an identifier for the radio work 1029item. 1030 1031Once the radio work item has been started, "EXT-RADIO-WORK-START <id>" 1032event message is indicated that the external processing can start. Once 1033the operation has been completed, "RADIO_WORK done <id>" is used to 1034indicate that to wpa_supplicant. This allows other radio works to be 1035performed. If this command is forgotten (e.g., due to the external 1036program terminating), wpa_supplicant will time out the radio work item 1037and send "EXT-RADIO-WORK-TIMEOUT <id>" event to indicate that this has 1038happened. "RADIO_WORK done <id>" can also be used to cancel items that 1039have not yet been started. 1040 1041For example, in wpa_cli interactive mode: 1042 1043> radio_work add test 10441 1045<3>EXT-RADIO-WORK-START 1 1046> radio_work show 1047ext:test@wlan0:0:1:2.487797 1048> radio_work done 1 1049OK 1050> radio_work show 1051 1052 1053> radio_work done 3 1054OK 1055> radio_work show 1056ext: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 10615 1062<3>EXT-RADIO-WORK-START 5 1063> radio_work add test3 10646 1065> radio_work add test4 10667 1067> radio_work show 1068ext:test2 freq=2412 timeout=60@wlan0:2412:1:9.751844 1069ext:test3@wlan0:0:0:5.071812 1070ext:test4@wlan0:0:0:3.143870 1071> radio_work done 6 1072OK 1073> radio_work show 1074ext:test2 freq=2412 timeout=60@wlan0:2412:1:16.287869 1075ext:test4@wlan0:0:0:9.679895 1076> radio_work done 5 1077OK 1078<3>EXT-RADIO-WORK-START 7 1079<3>EXT-RADIO-WORK-TIMEOUT 7 1080
README-DPP
1Device Provisioning Protocol (DPP) 2================================== 3 4This document describes how the Device Provisioning Protocol (DPP) 5implementation in wpa_supplicant and hostapd can be configured and how 6the STA device and AP can be configured to connect each other using DPP 7Connector mechanism. 8 9Introduction to DPP 10------------------- 11 12Device Provisioning Protocol (also known as Wi-Fi Easy Connect) allows 13enrolling of interface-less devices in a secure Wi-Fi network using many 14methods like QR code based authentication (detailed below), PKEX based 15authentication (password with in-band provisioning), etc. In DPP a 16Configurator is used to provide network credentials to the devices. The 17three phases of DPP connection are authentication, configuration and 18network introduction. 19 20More information about Wi-Fi Easy Connect is available from this Wi-Fi 21Alliance web page: 22https://www.wi-fi.org/discover-wi-fi/wi-fi-easy-connect 23 24Build config setup 25------------------ 26 27The following parameters must be included in the config file used to 28compile hostapd and wpa_supplicant. 29 30wpa_supplicant build config 31--------------------------- 32 33Enable DPP in wpa_supplicant build config file 34 35CONFIG_DPP=y 36 37hostapd build config 38-------------------- 39 40Enable DPP in hostapd build config file 41 42CONFIG_DPP=y 43 44Configurator build config 45------------------------- 46 47Any STA or AP device can act as a Configurator. Enable DPP in build 48config. For an AP to act as a Configurator, Interworking needs to be 49enabled for GAS. For wpa_supplicant it is not required. 50 51CONFIG_INTERWORKING=y 52 53 54Sample supplicant config file before provisioning 55------------------------------------------------- 56 57ctrl_interface=DIR=/var/run/wpa_supplicant 58ctrl_interface_group=0 59update_config=1 60pmf=2 61dpp_config_processing=2 62 63Sample hostapd config file before provisioning 64---------------------------------------------- 65 66interface=wlan0 67driver=nl80211 68ctrl_interface=/var/run/hostapd 69ssid=test 70channel=1 71wpa=2 72wpa_key_mgmt=DPP 73ieee80211w=1 74wpa_pairwise=CCMP 75rsn_pairwise=CCMP 76 77 78Pre-requisites 79-------------- 80 81It is assumed that an AP and client station are up by running hostapd 82and wpa_supplicant using respective config files. 83 84 85Creating Configurator 86--------------------- 87 88Add a Configurator over the control interface (wpa_cli/hostapd_cli) 89 90> dpp_configurator_add 91(returns id) 92 93To get key of Configurator 94> dpp_configurator_get_key <id> 95 96 97How to configure an Enrollee using Configurator 98----------------------------------------------- 99 100On Enrollee side: 101 102Generate QR code for the device. Store the QR code id returned by the 103command. 104 105> dpp_bootstrap_gen type=qrcode mac=<mac-address-of-device> chan=<operating-class/channel> key=<key of the device> 106(Returns bootstrapping info id. If the key parameter is not included, a new key 107is generated automatically. The MAC address is specified without octet 108separating colons. The channel list includes the possible channels on which the 109device is waiting. This uses global operating classes; e.g., 81/1 is the 2.4 110GHz channel 1 on 2412 MHz.) 111 112Get URI for the QR Code of device using the bootstrap info id. 113> dpp_bootstrap_get_uri <bootstrap-id> 114 115Make device listen to DPP request. The central frequency of the 2.4 GHz 116band channel 1 is 2412 MHz) in case the Enrollee is a client device. An 117AP as an Enrollee is listening on its operating channel. 118 119> dpp_listen <frequency> 120 121On Configurator side: 122 123Enter the QR Code in the Configurator. 124> dpp_qr_code "<URI-from-QR-Code-read-from-enrollee>" 125 126On successfully adding QR Code, a bootstrapping info id is returned. 127 128Send provisioning request to Enrollee. (conf is ap-dpp if Enrollee is an 129AP. conf is sta-dpp if Enrollee is a client) 130> dpp_auth_init peer=<qr-code-id> conf=<ap-dpp|sta-dpp> ssid=<SSID hexdump> configurator=<configurator-id> 131or for legacy (PSK/SAE) provisioning for a station Enrollee: 132> dpp_auth_init peer=<qr-code-id> conf=sta-psk ssid=<SSID hexdump> pass=<passphrase hexdump> 133 134The DPP values will be printed in the console. Save these values into the 135config file. If the Enrollee is an AP, we need to manually write these 136values to the hostapd config file. If the Enrollee is a client device, 137these details can be automatically saved to config file using the 138following command. 139 140> save_config 141 142To set values in runtime for AP enrollees 143 144> set dpp_connector <Connector-value-printed-on-console> 145> set dpp_csign <csign-value-on-console> 146> set dpp_netaccesskey <netaccess-value-on-console> 147 148To set values in runtime for client enrollees, set dpp_config_processing 149to 2 in wpa_supplicant conf file. 150 151Once the values are set in run-time (if not set in run-time, but saved 152in config files, they are taken up in next restart), the client device 153will automatically connect to the already provisioned AP and connection 154will be established. 155 156 157Self-configuring a device 158------------------------- 159 160It is possible for a device to configure itself if it is the 161Configurator for the network. 162 163Create a Configurator in the device and use the dpp_configurator_sign 164command to get DPP credentials. 165 166> dpp_configurator_add 167(returns configurator id) 168> dpp_configurator_sign conf=<ap-dpp|sta-dpp> configurator=<configurator-id> ssid=<SSID hexdump> 169 170 171Sample AP configuration files after provisioning 172------------------------------------------------ 173 174interface=wlan0 175driver=nl80211 176ctrl_interface=/var/run/hostapd 177ssid=test 178channel=1 179wpa=2 180wpa_key_mgmt=DPP 181ieee80211w=1 182wpa_pairwise=CCMP 183rsn_pairwise=CCMP 184dpp_connector=<Connector value provided by Configurator> 185dpp_csign=<C-Sign-Key value provided by Configurator> 186dpp_netaccesskey=<Net access key provided by Configurator> 187 188 189Sample station configuration file after provisioning 190---------------------------------------------------- 191 192ctrl_interface=DIR=/var/run/wpa_supplicant 193ctrl_interface_group=0 194update_config=1 195pmf=2 196dpp_config_processing=2 197network={ 198 ssid="test" 199 key_mgmt=DPP 200 ieee80211w=2 201 dpp_connector="<Connector value provided by Configurator>" 202 dpp_netaccesskey=<Net access key provided by Configurator> 203 dpp_csign=<C-sign-key value provided by Configurator> 204} 205
README-HS20
1wpa_supplicant and Hotspot 2.0 2============================== 3 4This document describe how the IEEE 802.11u Interworking and Wi-Fi 5Hotspot 2.0 (Release 1) implementation in wpa_supplicant can be 6configured and how an external component on the client e.g., management 7GUI or Wi-Fi framework) is used to manage this functionality. 8 9 10Introduction to Wi-Fi Hotspot 2.0 11--------------------------------- 12 13Hotspot 2.0 is the name of the Wi-Fi Alliance specification that is used 14in the Wi-Fi CERTIFIED Passpoint<TM> program. More information about 15this is available in this white paper: 16 17http://www.wi-fi.org/knowledge-center/white-papers/wi-fi-certified-passpoint%E2%84%A2-new-program-wi-fi-alliance%C2%AE-enable-seamless 18 19The Hotspot 2.0 specification is also available from WFA: 20https://www.wi-fi.org/knowledge-center/published-specifications 21 22The core Interworking functionality (network selection, GAS/ANQP) were 23standardized in IEEE Std 802.11u-2011 which is now part of the IEEE Std 24802.11-2012. 25 26 27wpa_supplicant network selection 28-------------------------------- 29 30Interworking support added option for configuring credentials that can 31work with multiple networks as an alternative to configuration of 32network blocks (e.g., per-SSID parameters). When requested to perform 33network selection, wpa_supplicant picks the highest priority enabled 34network block or credential. If a credential is picked (based on ANQP 35information from APs), a temporary network block is created 36automatically for the matching network. This temporary network block is 37used similarly to the network blocks that can be configured by the user, 38but it is not stored into the configuration file and is meant to be used 39only for temporary period of time since a new one can be created 40whenever needed based on ANQP information and the credential. 41 42By default, wpa_supplicant is not using automatic network selection 43unless requested explicitly with the interworking_select command. This 44can be changed with the auto_interworking=1 parameter to perform network 45selection automatically whenever trying to find a network for connection 46and none of the enabled network blocks match with the scan results. This 47case works similarly to "interworking_select auto", i.e., wpa_supplicant 48will internally determine which network or credential is going to be 49used based on configured priorities, scan results, and ANQP information. 50 51 52wpa_supplicant configuration 53---------------------------- 54 55Interworking and Hotspot 2.0 functionality are optional components that 56need to be enabled in the wpa_supplicant build configuration 57(.config). This is done by adding following parameters into that file: 58 59CONFIG_INTERWORKING=y 60CONFIG_HS20=y 61 62It should be noted that this functionality requires a driver that 63supports GAS/ANQP operations. This uses the same design as P2P, i.e., 64Action frame processing and building in user space within 65wpa_supplicant. The Linux nl80211 driver interface provides the needed 66functionality for this. 67 68 69There are number of run-time configuration parameters (e.g., in 70wpa_supplicant.conf when using the configuration file) that can be used 71to control Hotspot 2.0 operations. 72 73# Enable Interworking 74interworking=1 75 76# Enable Hotspot 2.0 77hs20=1 78 79# Parameters for controlling scanning 80 81# Homogeneous ESS identifier 82# If this is set, scans will be used to request response only from BSSes 83# belonging to the specified Homogeneous ESS. This is used only if interworking 84# is enabled. 85#hessid=00:11:22:33:44:55 86 87# Access Network Type 88# When Interworking is enabled, scans can be limited to APs that advertise the 89# specified Access Network Type (0..15; with 15 indicating wildcard match). 90# This value controls the Access Network Type value in Probe Request frames. 91#access_network_type=15 92 93# Automatic network selection behavior 94# 0 = do not automatically go through Interworking network selection 95# (i.e., require explicit interworking_select command for this; default) 96# 1 = perform Interworking network selection if one or more 97# credentials have been configured and scan did not find a 98# matching network block 99#auto_interworking=0 100 101 102Credentials can be pre-configured for automatic network selection: 103 104# credential block 105# 106# Each credential used for automatic network selection is configured as a set 107# of parameters that are compared to the information advertised by the APs when 108# interworking_select and interworking_connect commands are used. 109# 110# credential fields: 111# 112# temporary: Whether this credential is temporary and not to be saved 113# 114# priority: Priority group 115# By default, all networks and credentials get the same priority group 116# (0). This field can be used to give higher priority for credentials 117# (and similarly in struct wpa_ssid for network blocks) to change the 118# Interworking automatic networking selection behavior. The matching 119# network (based on either an enabled network block or a credential) 120# with the highest priority value will be selected. 121# 122# pcsc: Use PC/SC and SIM/USIM card 123# 124# realm: Home Realm for Interworking 125# 126# username: Username for Interworking network selection 127# 128# password: Password for Interworking network selection 129# 130# ca_cert: CA certificate for Interworking network selection 131# 132# client_cert: File path to client certificate file (PEM/DER) 133# This field is used with Interworking networking selection for a case 134# where client certificate/private key is used for authentication 135# (EAP-TLS). Full path to the file should be used since working 136# directory may change when wpa_supplicant is run in the background. 137# 138# Alternatively, a named configuration blob can be used by setting 139# this to blob://blob_name. 140# 141# private_key: File path to client private key file (PEM/DER/PFX) 142# When PKCS#12/PFX file (.p12/.pfx) is used, client_cert should be 143# commented out. Both the private key and certificate will be read 144# from the PKCS#12 file in this case. Full path to the file should be 145# used since working directory may change when wpa_supplicant is run 146# in the background. 147# 148# Windows certificate store can be used by leaving client_cert out and 149# configuring private_key in one of the following formats: 150# 151# cert://substring_to_match 152# 153# hash://certificate_thumbprint_in_hex 154# 155# For example: private_key="hash://63093aa9c47f56ae88334c7b65a4" 156# 157# Note that when running wpa_supplicant as an application, the user 158# certificate store (My user account) is used, whereas computer store 159# (Computer account) is used when running wpasvc as a service. 160# 161# Alternatively, a named configuration blob can be used by setting 162# this to blob://blob_name. 163# 164# private_key_passwd: Password for private key file 165# 166# imsi: IMSI in <MCC> | <MNC> | '-' | <MSIN> format 167# 168# milenage: Milenage parameters for SIM/USIM simulator in <Ki>:<OPc>:<SQN> 169# format 170# 171# domain_suffix_match: Constraint for server domain name 172# If set, this FQDN is used as a suffix match requirement for the AAA 173# server certificate in SubjectAltName dNSName element(s). If a 174# matching dNSName is found, this constraint is met. If no dNSName 175# values are present, this constraint is matched against SubjectName CN 176# using same suffix match comparison. Suffix match here means that the 177# host/domain name is compared one label at a time starting from the 178# top-level domain and all the labels in @domain_suffix_match shall be 179# included in the certificate. The certificate may include additional 180# sub-level labels in addition to the required labels. 181# 182# For example, domain_suffix_match=example.com would match 183# test.example.com but would not match test-example.com. 184# 185# domain: Home service provider FQDN(s) 186# This is used to compare against the Domain Name List to figure out 187# whether the AP is operated by the Home SP. Multiple domain entries can 188# be used to configure alternative FQDNs that will be considered home 189# networks. 190# 191# roaming_consortium: Roaming Consortium OI 192# If roaming_consortium_len is non-zero, this field contains the 193# Roaming Consortium OI that can be used to determine which access 194# points support authentication with this credential. This is an 195# alternative to the use of the realm parameter. When using Roaming 196# Consortium to match the network, the EAP parameters need to be 197# pre-configured with the credential since the NAI Realm information 198# may not be available or fetched. 199# 200# required_roaming_consortium: Required Roaming Consortium OI 201# If required_roaming_consortium_len is non-zero, this field contains the 202# Roaming Consortium OI that is required to be advertised by the AP for 203# the credential to be considered matching. 204# 205# roaming_consortiums: Roaming Consortium OI(s) memberships 206# This string field contains one or more comma delimited OIs (hexdump) 207# identifying the roaming consortiums of which the provider is a member. 208# The list is sorted from the most preferred one to the least preferred 209# one. A match between the Roaming Consortium OIs advertised by an AP and 210# the OIs in this list indicates that successful authentication is 211# possible. 212# (Hotspot 2.0 PerProviderSubscription/<X+>/HomeSP/RoamingConsortiumOI) 213# 214# eap: Pre-configured EAP method 215# This optional field can be used to specify which EAP method will be 216# used with this credential. If not set, the EAP method is selected 217# automatically based on ANQP information (e.g., NAI Realm). 218# 219# phase1: Pre-configure Phase 1 (outer authentication) parameters 220# This optional field is used with like the 'eap' parameter. 221# 222# phase2: Pre-configure Phase 2 (inner authentication) parameters 223# This optional field is used with like the 'eap' parameter. 224# 225# excluded_ssid: Excluded SSID 226# This optional field can be used to excluded specific SSID(s) from 227# matching with the network. Multiple entries can be used to specify more 228# than one SSID. 229# 230# roaming_partner: Roaming partner information 231# This optional field can be used to configure preferences between roaming 232# partners. The field is a string in following format: 233# <FQDN>,<0/1 exact match>,<priority>,<* or country code> 234# (non-exact match means any subdomain matches the entry; priority is in 235# 0..255 range with 0 being the highest priority) 236# 237# update_identifier: PPS MO ID 238# (Hotspot 2.0 PerProviderSubscription/UpdateIdentifier) 239# 240# provisioning_sp: FQDN of the SP that provisioned the credential 241# This optional field can be used to keep track of the SP that provisioned 242# the credential to find the PPS MO (./Wi-Fi/<provisioning_sp>). 243# 244# sp_priority: Credential priority within a provisioning SP 245# This is the priority of the credential among all credentials 246# provisioned by the same SP (i.e., for entries that have identical 247# provisioning_sp value). The range of this priority is 0-255 with 0 248# being the highest and 255 the lower priority. 249# 250# Minimum backhaul threshold (PPS/<X+>/Policy/MinBackhauldThreshold/*) 251# These fields can be used to specify minimum download/upload backhaul 252# bandwidth that is preferred for the credential. This constraint is 253# ignored if the AP does not advertise WAN Metrics information or if the 254# limit would prevent any connection. Values are in kilobits per second. 255# min_dl_bandwidth_home 256# min_ul_bandwidth_home 257# min_dl_bandwidth_roaming 258# min_ul_bandwidth_roaming 259# 260# max_bss_load: Maximum BSS Load Channel Utilization (1..255) 261# (PPS/<X+>/Policy/MaximumBSSLoadValue) 262# This value is used as the maximum channel utilization for network 263# selection purposes for home networks. If the AP does not advertise 264# BSS Load or if the limit would prevent any connection, this constraint 265# will be ignored. 266# 267# req_conn_capab: Required connection capability 268# (PPS/<X+>/Policy/RequiredProtoPortTuple) 269# This value is used to configure set of required protocol/port pairs that 270# a roaming network shall support (include explicitly in Connection 271# Capability ANQP element). This constraint is ignored if the AP does not 272# advertise Connection Capability or if this constraint would prevent any 273# network connection. This policy is not used in home networks. 274# Format: <protocol>[:<comma-separated list of ports] 275# Multiple entries can be used to list multiple requirements. 276# For example, number of common TCP protocols: 277# req_conn_capab=6:22,80,443 278# For example, IPSec/IKE: 279# req_conn_capab=17:500 280# req_conn_capab=50 281# 282# ocsp: Whether to use/require OCSP to check server certificate 283# 0 = do not use OCSP stapling (TLS certificate status extension) 284# 1 = try to use OCSP stapling, but not require response 285# 2 = require valid OCSP stapling response 286# 287# sim_num: Identifier for which SIM to use in multi-SIM devices 288# 289# for example: 290# 291#cred={ 292# realm="example.com" 293# username="user@example.com" 294# password="password" 295# ca_cert="/etc/wpa_supplicant/ca.pem" 296# domain="example.com" 297# domain_suffix_match="example.com" 298#} 299# 300#cred={ 301# imsi="310026-000000000" 302# milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82" 303#} 304# 305#cred={ 306# realm="example.com" 307# username="user" 308# password="password" 309# ca_cert="/etc/wpa_supplicant/ca.pem" 310# domain="example.com" 311# roaming_consortium=223344 312# roaming_consortiums="112233,4455667788,aabbcc" 313# eap=TTLS 314# phase2="auth=MSCHAPV2" 315#} 316 317 318Control interface 319----------------- 320 321wpa_supplicant provides a control interface that can be used from 322external programs to manage various operations. The included command 323line tool, wpa_cli, can be used for manual testing with this interface. 324 325Following wpa_cli interactive mode commands show some examples of manual 326operations related to Hotspot 2.0: 327 328Remove configured networks and credentials: 329 330> remove_network all 331OK 332> remove_cred all 333OK 334 335 336Add a username/password credential: 337 338> add_cred 3390 340> set_cred 0 realm "mail.example.com" 341OK 342> set_cred 0 username "username" 343OK 344> set_cred 0 password "password" 345OK 346> set_cred 0 priority 1 347OK 348> set_cred 0 temporary 1 349OK 350 351Add a SIM credential using a simulated SIM/USIM card for testing: 352 353> add_cred 3541 355> set_cred 1 imsi "23456-0000000000" 356OK 357> set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123" 358OK 359> set_cred 1 priority 1 360OK 361 362Note: the return value of add_cred is used as the first argument to 363the following set_cred commands. 364 365Add a SIM credential using a external SIM/USIM processing: 366 367> set external_sim 1 368OK 369> add_cred 3701 371> set_cred 1 imsi "23456-0000000000" 372OK 373> set_cred 1 eap SIM 374OK 375 376 377Add a WPA2-Enterprise network: 378 379> add_network 3800 381> set_network 0 key_mgmt WPA-EAP 382OK 383> set_network 0 ssid "enterprise" 384OK 385> set_network 0 eap TTLS 386OK 387> set_network 0 anonymous_identity "anonymous" 388OK 389> set_network 0 identity "user" 390OK 391> set_network 0 password "password" 392OK 393> set_network 0 priority 0 394OK 395> enable_network 0 no-connect 396OK 397 398 399Add an open network: 400 401> add_network 4023 403> set_network 3 key_mgmt NONE 404OK 405> set_network 3 ssid "coffee-shop" 406OK 407> select_network 3 408OK 409 410Note: the return value of add_network is used as the first argument to 411the following set_network commands. 412 413The preferred credentials/networks can be indicated with the priority 414parameter (1 is higher priority than 0). 415 416 417Interworking network selection can be started with interworking_select 418command. This instructs wpa_supplicant to run a network scan and iterate 419through the discovered APs to request ANQP information from the APs that 420advertise support for Interworking/Hotspot 2.0: 421 422> interworking_select 423OK 424<3>Starting ANQP fetch for 02:00:00:00:01:00 425<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 426<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 427<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 428<3>ANQP fetch completed 429<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 430 431 432INTERWORKING-AP event messages indicate the APs that support network 433selection and for which there is a matching 434credential. interworking_connect command can be used to select a network 435to connect with: 436 437 438> interworking_connect 02:00:00:00:01:00 439OK 440<3>CTRL-EVENT-SCAN-RESULTS 441<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 442<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 443<3>Associated with 02:00:00:00:01:00 444<3>CTRL-EVENT-EAP-STARTED EAP authentication started 445<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 446<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 447<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 448<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 449<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=] 450 451 452wpa_supplicant creates a temporary network block for the selected 453network based on the configured credential and ANQP information from the 454AP: 455 456> list_networks 457network id / ssid / bssid / flags 4580 Example Network any [CURRENT] 459> get_network 0 key_mgmt 460WPA-EAP 461> get_network 0 eap 462TTLS 463 464 465Alternatively to using an external program to select the network, 466"interworking_select auto" command can be used to request wpa_supplicant 467to select which network to use based on configured priorities: 468 469 470> remove_network all 471OK 472<3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1 473> interworking_select auto 474OK 475<3>Starting ANQP fetch for 02:00:00:00:01:00 476<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 477<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 478<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 479<3>ANQP fetch completed 480<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 481<3>CTRL-EVENT-SCAN-RESULTS 482<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 483<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 484<3>Associated with 02:00:00:00:01:00 485<3>CTRL-EVENT-EAP-STARTED EAP authentication started 486<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 487<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 488<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 489<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 490<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=] 491 492 493The connection status can be shown with the status command: 494 495> status 496bssid=02:00:00:00:01:00 497ssid=Example Network 498id=0 499mode=station 500pairwise_cipher=CCMP <--- link layer security indication 501group_cipher=CCMP 502key_mgmt=WPA2/IEEE 802.1X/EAP 503wpa_state=COMPLETED 504p2p_device_address=02:00:00:00:00:00 505address=02:00:00:00:00:00 506hs20=1 <--- HS 2.0 indication 507Supplicant PAE state=AUTHENTICATED 508suppPortStatus=Authorized 509EAP state=SUCCESS 510selectedMethod=21 (EAP-TTLS) 511EAP TLS cipher=AES-128-SHA 512EAP-TTLSv0 Phase2 method=PAP 513 514 515> status 516bssid=02:00:00:00:02:00 517ssid=coffee-shop 518id=3 519mode=station 520pairwise_cipher=NONE 521group_cipher=NONE 522key_mgmt=NONE 523wpa_state=COMPLETED 524p2p_device_address=02:00:00:00:00:00 525address=02:00:00:00:00:00 526 527 528Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status 529command output. Link layer security is indicated with the 530pairwise_cipher (CCMP = secure, NONE = no encryption used). 531 532 533Also the scan results include the Hotspot 2.0 indication: 534 535> scan_results 536bssid / frequency / signal level / flags / ssid 53702:00:00:00:01:00 2412 -30 [WPA2-EAP-CCMP][ESS][HS20] Example Network 538 539 540ANQP information for the BSS can be fetched using the BSS command: 541 542> bss 02:00:00:00:01:00 543id=1 544bssid=02:00:00:00:01:00 545freq=2412 546beacon_int=100 547capabilities=0x0411 548qual=0 549noise=-92 550level=-30 551tsf=1345573286517276 552age=105 553ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000 554flags=[WPA2-EAP-CCMP][ESS][HS20] 555ssid=Example Network 556anqp_roaming_consortium=031122330510203040500601020304050603fedcba 557 558 559ANQP queries can also be requested with the anqp_get and hs20_anqp_get 560commands: 561 562> anqp_get 02:00:00:00:01:00 261 563OK 564<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 565> hs20_anqp_get 02:00:00:00:01:00 2 566OK 567<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 568 569In addition, fetch_anqp command can be used to request similar set of 570ANQP queries to be done as is run as part of interworking_select: 571 572> scan 573OK 574<3>CTRL-EVENT-SCAN-RESULTS 575> fetch_anqp 576OK 577<3>Starting ANQP fetch for 02:00:00:00:01:00 578<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 579<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 580<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 581<3>ANQP fetch completed 582 583 584Hotspot 2.0 Rel 2 online signup and OSEN 585---------------------------------------- 586 587Following parameters can be used to create a network profile for 588link-layer protected Hotspot 2.0 online signup connection with 589OSEN. Note that ssid and identify (NAI) values need to be set based on 590the information for the selected provider in the OSU Providers list 591ANQP-element. 592 593network={ 594 ssid="HS 2.0 OSU" 595 proto=OSEN 596 key_mgmt=OSEN 597 pairwise=CCMP 598 group=GTK_NOT_USED 599 eap=WFA-UNAUTH-TLS 600 identity="anonymous@example.com" 601 ca_cert="osu-ca.pem" 602 ocsp=2 603} 604 605 606Hotspot 2.0 connection with external network selection 607------------------------------------------------------ 608 609When a component controlling wpa_supplicant takes care of Interworking 610network selection, following configuration and network profile 611parameters can be used to configure a temporary network profile for a 612Hotspot 2.0 connection (e.g., with SET, ADD_NETWORK, SET_NETWORK, and 613SELECT_NETWORK control interface commands): 614 615interworking=1 616hs20=1 617auto_interworking=0 618 619network={ 620 ssid="test-hs20" 621 proto=RSN 622 key_mgmt=WPA-EAP 623 pairwise=CCMP 624 anonymous_identity="anonymous@example.com" 625 identity="hs20-test@example.com" 626 password="password" 627 ca_cert="ca.pem" 628 eap=TTLS 629 phase2="auth=MSCHAPV2" 630 update_identifier=54321 631 roaming_consortium_selection=112233 632 #ocsp=2 633} 634 635 636These parameters are set based on the PPS MO credential and/or NAI Realm 637list ANQP-element: 638 639anonymous_identity: Credential/UsernamePassword/Username with username part 640 replaced with "anonymous" 641identity: Credential/UsernamePassword/Username 642password: Credential/UsernamePassword/Password 643update_identifier: PPS/UpdateIdentifier 644ca_cert: from the downloaded trust root based on PPS information 645eap: Credential/UsernamePassword/EAPMethod or NAI Realm list 646phase2: Credential/UsernamePassword/EAPMethod or NAI Realm list 647roaming_consortium_selection: Matching OI from HomeSP/RoamingConsortiumOI 648ocsp: Credential/CheckAAAServerCertStatus 649
README-P2P
1wpa_supplicant and Wi-Fi P2P 2============================ 3 4This document describes how the Wi-Fi P2P implementation in 5wpa_supplicant can be configured and how an external component on the 6client (e.g., management GUI) is used to enable WPS enrollment and 7registrar registration. 8 9 10Introduction to Wi-Fi P2P 11------------------------- 12 13TODO 14 15More information about Wi-Fi P2P is available from Wi-Fi Alliance: 16http://www.wi-fi.org/Wi-Fi_Direct.php 17 18 19wpa_supplicant implementation 20----------------------------- 21 22TODO 23 24 25wpa_supplicant configuration 26---------------------------- 27 28Wi-Fi P2P is an optional component that needs to be enabled in the 29wpa_supplicant build configuration (.config). Here is an example 30configuration that includes Wi-Fi P2P support and Linux nl80211 31-based driver interface: 32 33CONFIG_DRIVER_NL80211=y 34CONFIG_CTRL_IFACE=y 35CONFIG_P2P=y 36CONFIG_AP=y 37CONFIG_WPS=y 38 39 40In run-time configuration file (wpa_supplicant.conf), some parameters 41for P2P may be set. In order to make the devices easier to recognize, 42device_name and device_type should be specified. For example, 43something like this should be included: 44 45ctrl_interface=/var/run/wpa_supplicant 46device_name=My P2P Device 47device_type=1-0050F204-1 48 49 50wpa_cli 51------- 52 53Actual Wi-Fi P2P operations are requested during runtime. These can be 54done for example using wpa_cli (which is described below) or a GUI 55like wpa_gui-qt4. 56 57 58wpa_cli starts in interactive mode if no command string is included on 59the command line. By default, it will select the first network interface 60that it can find (and that wpa_supplicant controls). If more than one 61interface is in use, it may be necessary to select one of the explicitly 62by adding -i argument on the command line (e.g., 'wpa_cli -i wlan1'). 63 64Most of the P2P operations are done on the main interface (e.g., the 65interface that is automatically added when the driver is loaded, e.g., 66wlan0). When using a separate virtual interface for group operations 67(e.g., wlan1), the control interface for that group interface may need 68to be used for some operations (mainly WPS activation in GO). This may 69change in the future so that all the needed operations could be done 70over the main control interface. 71 72Device Discovery 73 74p2p_find [timeout in seconds] [type=<social|progressive>] \ 75 [dev_id=<addr>] [dev_type=<device type>] \ 76 [delay=<search delay in ms>] [seek=<service name>] [freq=<MHz>] 77 78The default behavior is to run a single full scan in the beginning and 79then scan only social channels. type=social will scan only social 80channels, i.e., it skips the initial full scan. type=progressive is 81like the default behavior, but it will scan through all the channels 82progressively one channel at the time in the Search state rounds. This 83will help in finding new groups or groups missed during the initial 84full scan. When the type parameter is not included (i.e., full scan), the 85optional freq parameter can be used to override the first scan to use only 86the specified channel after which only social channels are scanned. 87 88The optional dev_id option can be used to specify a single P2P peer to 89search for. The optional delay parameter can be used to request an extra 90delay to be used between search iterations (e.g., to free up radio 91resources for concurrent operations). 92 93The optional dev_type option can be used to specify a single device type 94(primary or secondary) to search for, e.g., 95"p2p_find dev_type=1-0050F204-1". 96 97 98With one or more seek arguments, the command sends Probe Request frames 99for a P2PS service. For example, 100p2p_find 5 dev_id=11:22:33:44:55:66 seek=alt.example.chat seek=alt.example.video 101 102Parameters description: 103 Timeout - Optional ASCII base-10-encoded u16. If missing, request will not 104 time out and must be canceled manually 105 dev_id - Optional to request responses from a single known remote device 106 Service Name - Mandatory UTF-8 string for ASP seeks 107 Service name must match the remote service being advertised exactly 108 (no prefix matching). 109 Service name may be empty, in which case all ASP services will be 110 returned, and may be filtered with p2p_serv_disc_req settings, and 111 p2p_serv_asp_resp results. 112 Multiple service names may be requested, but if it exceeds internal 113 limit, it will automatically revert to requesting all ASP services. 114 115p2p_listen [timeout in seconds] 116 117Start Listen-only state (become discoverable without searching for 118other devices). Optional parameter can be used to specify the duration 119for the Listen operation in seconds. This command may not be of that 120much use during normal operations and is mainly designed for 121testing. It can also be used to keep the device discoverable without 122having to maintain a group. 123 124p2p_stop_find 125 126Stop ongoing P2P device discovery or other operation (connect, listen 127mode). 128 129p2p_flush 130 131Flush P2P peer table and state. 132 133Group Formation 134 135p2p_prov_disc <peer device address> <display|keypad|pbc> [join|auto] 136 137Send P2P provision discovery request to the specified peer. The 138parameters for this command are the P2P device address of the peer and 139the desired configuration method. For example, "p2p_prov_disc 14002:01:02:03:04:05 display" would request the peer to display a PIN for 141us and "p2p_prov_disc 02:01:02:03:04:05 keypad" would request the peer 142to enter a PIN that we display. 143 144The optional "join" parameter can be used to indicate that this command 145is requesting an already running GO to prepare for a new client. This is 146mainly used with "display" to request it to display a PIN. The "auto" 147parameter can be used to request wpa_supplicant to automatically figure 148out whether the peer device is operating as a GO and if so, use 149join-a-group style PD instead of GO Negotiation style PD. 150 151p2p_connect <peer device address> <pbc|pin|PIN#|p2ps> [display|keypad|p2ps] 152 [persistent|persistent=<network id>] [join|auth] 153 [go_intent=<0..15>] [freq=<in MHz>] [ht40] [vht] [he] [provdisc] [auto] 154 [ssid=<hexdump>] 155 156Start P2P group formation with a discovered P2P peer. This includes 157optional group owner negotiation, group interface setup, provisioning, 158and establishing data connection. 159 160The <pbc|pin|PIN#> parameter specifies the WPS provisioning 161method. "pbc" string starts pushbutton method, "pin" string start PIN 162method using an automatically generated PIN (which will be returned as 163the command return code), PIN# means that a pre-selected PIN can be 164used (e.g., 12345670). [display|keypad] is used with PIN method 165to specify which PIN is used (display=dynamically generated random PIN 166from local display, keypad=PIN entered from peer display). "persistent" 167parameter can be used to request a persistent group to be formed. The 168"persistent=<network id>" alternative can be used to pre-populate 169SSID/passphrase configuration based on a previously used persistent 170group where this device was the GO. The previously used parameters will 171then be used if the local end becomes the GO in GO Negotiation (which 172can be forced with go_intent=15). 173 174"join" indicates that this is a command to join an existing group as a 175client. It skips the GO Negotiation part. This will send a Provision 176Discovery Request message to the target GO before associating for WPS 177provisioning. 178 179"auth" indicates that the WPS parameters are authorized for the peer 180device without actually starting GO Negotiation (i.e., the peer is 181expected to initiate GO Negotiation). This is mainly for testing 182purposes. 183 184"go_intent" can be used to override the default GO Intent for this GO 185Negotiation. 186 187"freq" can be used to set a forced operating channel (e.g., freq=2412 188to select 2.4 GHz channel 1). 189 190"provdisc" can be used to request a Provision Discovery exchange to be 191used prior to starting GO Negotiation as a workaround with some deployed 192P2P implementations that require this to allow the user to accept the 193connection. 194 195"auto" can be used to request wpa_supplicant to automatically figure 196out whether the peer device is operating as a GO and if so, use 197join-a-group operation rather than GO Negotiation. 198 199"ssid=<hexdump>" can be used to specify the Group SSID for join 200operations. This allows the P2P Client interface to filter scan results 201based on SSID to avoid selecting an incorrect BSS entry in case the same 202P2P Device or Interface address have been used in multiple groups 203recently. 204 205P2PS attribute changes to p2p_connect command: 206 207P2PS supports two WPS provisioning methods namely PIN method and P2PS default. 208The remaining parameters hold same role as in legacy P2P. In case of P2PS 209default config method "p2ps" keyword is added in p2p_connect command. 210 211For example: 212p2p_connect 02:0a:f5:85:11:00 12345670 p2ps persistent join 213 (WPS Method = P2PS default) 214 215p2p_connect 02:0a:f5:85:11:00 45629034 keypad persistent 216 (WPS Method = PIN) 217 218p2p_asp_provision <peer MAC address> <adv_id=peer adv id> 219 <adv_mac=peer MAC address> [role=2|4|1] <session=session id> 220 <session_mac=initiator mac address> 221 [info='service info'] <method=Default|keypad|Display> 222 223This command starts provision discovery with the P2PS enabled peer device. 224 225For example, 226p2p_asp_provision 00:11:22:33:44:55 adv_id=4d6fc7 adv_mac=00:55:44:33:22:11 role=1 session=12ab34 session_mac=00:11:22:33:44:55 info='name=john' method=1000 227 228Parameter description: 229 MAC address - Mandatory 230 adv_id - Mandatory remote Advertising ID of service connection is being 231 established for 232 adv_mac - Mandatory MAC address that owns/registered the service 233 role - Optional 234 2 (group client only) or 4 (group owner only) 235 if not present (or 1) role is negotiated by the two peers. 236 session - Mandatory Session ID of the first session to be established 237 session_mac - Mandatory MAC address that owns/initiated the session 238 method - Optional method to request for provisioning (1000 - P2PS Default, 239 100 - Keypad(PIN), 8 - Display(PIN)) 240 info - Optional UTF-8 string. Hint for service to indicate possible usage 241 parameters - Escape single quote & backslash: 242 with a backslash 0x27 == ' == \', and 0x5c == \ == \\ 243 244p2p_asp_provision_resp <peer mac address> <adv_id= local adv id> 245 <adv_mac=local MAC address> <role=1|2|4> <status=0> 246 <session=session id> <session_mac=peer MAC address> 247 248This command sends a provision discovery response from responder side. 249 250For example, 251p2p_asp_provision_resp 00:55:44:33:22:11 adv_id=4d6fc7 adv_mac=00:55:44:33:22:11 role=1 status=0 session=12ab34 session_mac=00:11:22:33:44:55 252 253Parameters definition: 254 MAC address - Mandatory 255 adv_id - Mandatory local Advertising ID of service connection is being 256 established for 257 adv_mac - Mandatory MAC address that owns/registered the service 258 role - Optional 2 (group client only) or 4 (group owner only) 259 if not present (or 1) role is negotiated by the two peers. 260 status - Mandatory Acceptance/Rejection code of Provisioning 261 session - Mandatory Session ID of the first session to be established 262 session_mac - Mandatory MAC address that owns/initiated the session 263 264p2p_group_add [persistent|persistent=<network id>] [freq=<freq in MHz>] 265 [ht40] [vht] [he] 266 267Set up a P2P group owner manually (i.e., without group owner 268negotiation with a specific peer). This is also known as autonomous 269GO. Optional persistent=<network id> can be used to specify restart of 270a persistent group. Optional freq=<freq in MHz> can be used to force 271the GO to be started on a specific frequency. Special freq=2 or freq=5 272options can be used to request the best 2.4 GHz or 5 GHz band channel 273to be selected automatically. 274 275p2p_reject <peer device address> 276 277Reject connection attempt from a peer (specified with a device 278address). This is a mechanism to reject a pending GO Negotiation with 279a peer and request to automatically block any further connection or 280discovery of the peer. 281 282p2p_group_remove <group interface> 283 284Terminate a P2P group. If a new virtual network interface was used for 285the group, it will also be removed. The network interface name of the 286group interface is used as a parameter for this command. 287 288p2p_cancel 289 290Cancel an ongoing P2P group formation and joining-a-group related 291operation. This operation unauthorizes the specific peer device (if any 292had been authorized to start group formation), stops P2P find (if in 293progress), stops pending operations for join-a-group, and removes the 294P2P group interface (if one was used) that is in the WPS provisioning 295step. If the WPS provisioning step has been completed, the group is not 296terminated. 297 298p2p_remove_client <peer's P2P Device Address|iface=<interface address>> 299 300This command can be used to remove the specified client from all groups 301(operating and persistent) from the local GO. Note that the peer device 302can rejoin the group if it is in possession of a valid key. See p2p_set 303per_sta_psk command below for more details on how the peer can be 304removed securely. 305 306Service Discovery 307 308p2p_service_add asp <auto accept> <adv id> <status 0/1> <Config Methods> 309 <Service name> [Service Information] [Response Info] 310 311This command can be used to search for a P2PS service which includes 312Play, Send, Display, and Print service. The parameters for this command 313are "asp" to identify the command as P2PS one, auto accept value, 314advertisement id which uniquely identifies the service requests, state 315of the service whether the service is available or not, config methods 316which can be either P2PS method or PIN method, service name followed by 317two optional parameters service information, and response info. 318 319For example, 320p2p_service_add asp 1 4d6fc7 0 1108 alt.example.chat svc_info='name=john' rsp_info='enter PIN 1234' 321 322Parameters definition: 323 asp - Mandatory for ASP service registration 324 auto accept - Mandatory ASCII hex-encoded boolean (0 == no auto-accept, 325 1 == auto-accept ANY role, 2 == auto-accept CLIENT role, 326 4 == auto-accept GO role) 327 Advertisement ID - Mandatory non-zero ASCII hex-encoded u32 328 (Must be unique/not yet exist in svc db) 329 State - Mandatory ASCII hex-encoded u8 (0 -- Svc not available, 330 1 -- Svc available, 2-0xff Application defined) 331 Config Methods - Mandatory ASCII hex-encoded u16 (bitmask of WSC config 332 methods) 333 Service Name - Mandatory UTF-8 string 334 Service Information - Optional UTF-8 string 335 Escape single quote & backslash with a backslash: 336 0x27 == ' == \', and 0x5c == \ == \\ 337 Session response information - Optional (used only if auto accept is TRUE) 338 UTF-8 string 339 Escape single quote & backslash with a backslash: 340 0x27 == ' == \', and 0x5c == \ == \\ 341 342p2p_service_rep asp <auto accept> <adv id> <status 0/1> <Config Methods> 343 <Service name> [Service Information] [Response Info] 344 345This command can be used to replace the existing service request 346attributes from the initiator side. The replacement is only allowed if 347the advertisement id issued in the command matches with any one entry in 348the list of existing SD queries. If advertisement id doesn't match the 349command returns a failure. 350 351For example, 352p2p_service_rep asp 1 4d6fc7 1 1108 alt.example.chat svc_info='name=john' rsp_info='enter PIN 1234' 353 354Parameters definition: 355 asp - Mandatory for ASP service registration 356 auto accept - Mandatory ASCII hex-encoded boolean (1 == true, 0 == false) 357 Advertisement ID - Mandatory non-zero ASCII hex-encoded u32 358 (Must already exist in svc db) 359 State - Mandatory ASCII hex-encoded u8 (can be used to indicate svc 360 available or not available for instance) 361 Config Methods - Mandatory ASCII hex-encoded u16 (bitmask of WSC config 362 methods) 363 Service Name - Mandatory UTF-8 string (Must match existing string in svc db) 364 Service Information - Optional UTF-8 string 365 Escape single quote & backslash with a backslash: 366 0x27 == ' == \', and 0x5c == \ == \\ 367 Session response information - Optional (used only if auto accept is TRUE) 368 UTF-8 string 369 Escape single quote & backslash with a backslash: 370 0x27 == ' == \', and 0x5c == \ == \\ 371 372p2p_serv_disc_req 373 374Schedule a P2P service discovery request. The parameters for this 375command are the device address of the peer device (or 00:00:00:00:00:00 376for wildcard query that is sent to every discovered P2P peer that 377supports service discovery) and P2P Service Query TLV(s) as hexdump. For 378example, 379 380p2p_serv_disc_req 00:00:00:00:00:00 02000001 381 382schedules a request for listing all available services of all service 383discovery protocols and requests this to be sent to all discovered 384peers (note: this can result in long response frames). The pending 385requests are sent during device discovery (see p2p_find). 386 387There can be multiple pending peer device specific queries (each will be 388sent in sequence whenever the peer is found). 389 390This command returns an identifier for the pending query (e.g., 391"1f77628") that can be used to cancel the request. Directed requests 392will be automatically removed when the specified peer has replied to 393it. 394 395Service Query TLV has following format: 396Length (2 octets, little endian) - length of following data 397Service Protocol Type (1 octet) - see the table below 398Service Transaction ID (1 octet) - nonzero identifier for the TLV 399Query Data (Length - 2 octets of data) - service protocol specific data 400 401Service Protocol Types: 4020 = All service protocols 4031 = Bonjour 4042 = UPnP 4053 = WS-Discovery 4064 = Wi-Fi Display 407 408For UPnP, an alternative command format can be used to specify a 409single query TLV (i.e., a service discovery for a specific UPnP 410service): 411 412p2p_serv_disc_req 00:00:00:00:00:00 upnp <version hex> <ST: from M-SEARCH> 413 414For example: 415 416p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 417 418Additional examples for queries: 419 420# list of all Bonjour services 421p2p_serv_disc_req 00:00:00:00:00:00 02000101 422 423# list of all UPnP services 424p2p_serv_disc_req 00:00:00:00:00:00 02000201 425 426# list of all WS-Discovery services 427p2p_serv_disc_req 00:00:00:00:00:00 02000301 428 429# list of all Bonjour and UPnP services 430p2p_serv_disc_req 00:00:00:00:00:00 0200010102000202 431 432# Apple File Sharing over TCP 433p2p_serv_disc_req 00:00:00:00:00:00 130001010b5f6166706f766572746370c00c000c01 434 435# Bonjour SSTH (supported service type hash) 436p2p_serv_disc_req 00:00:00:00:00:00 05000101000000 437 438# UPnP examples 439p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 ssdp:all 440p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 upnp:rootdevice 441p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:service:ContentDirectory:2 442p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 uuid:6859dede-8574-59ab-9332-123456789012 443p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 444 445# Wi-Fi Display examples 446# format: wifi-display <list of roles> <list of subelements> 447p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source] 2,3,4,5 448p2p_serv_disc_req 02:01:02:03:04:05 wifi-display [pri-sink] 3 449p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [sec-source] 2 450p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source+sink] 2,3,4,5 451p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source][pri-sink] 2,3,4,5 452 453p2p_serv_disc_req <Unicast|Broadcast mac address> asp <Transaction ID> 454 <Service Name> [Service Information] 455 456The command can be used for service discovery for P2PS enabled devices. 457 458For example: p2p_serv_disc_req 00:00:00:00:00:00 asp a1 alt.example 'john' 459 460Parameters definition: 461 MAC address - Mandatory Existing 462 asp - Mandatory for ASP queries 463 Transaction ID - Mandatory non-zero ASCII hex-encoded u8 for GAS 464 Service Name Prefix - Mandatory UTF-8 string. 465 Will match from beginning of remote Service Name 466 Service Information Substring - Optional UTF-8 string 467 If Service Information Substring is not included, all services matching 468 Service Name Prefix will be returned. 469 If Service Information Substring is included, both the Substring and the 470 Service Name Prefix must match for service to be returned. 471 If remote service has no Service Information, all Substring searches 472 will fail. 473 474p2p_serv_disc_cancel_req <query identifier> 475 476Cancel a pending P2P service discovery request. This command takes a 477single parameter: identifier for the pending query (the value returned 478by p2p_serv_disc_req, e.g., "p2p_serv_disc_cancel_req 1f77628". 479 480p2p_serv_disc_resp 481 482Reply to a service discovery query. This command takes following 483parameters: frequency in MHz, destination address, dialog token, 484response TLV(s). The first three parameters are copied from the 485request event. For example, "p2p_serv_disc_resp 2437 02:40:61:c2:f3:b7 4861 0300000101". This command is used only if external program is used 487to process the request (see p2p_serv_disc_external). 488 489p2p_service_update 490 491Indicate that local services have changed. This is used to increment 492the P2P service indicator value so that peers know when previously 493cached information may have changed. This is only needed when external 494service discovery processing is enabled since the commands to 495pre-configure services for internal processing will increment the 496indicator automatically. 497 498p2p_serv_disc_external <0|1> 499 500Configure external processing of P2P service requests: 0 (default) = 501no external processing of requests (i.e., internal code will process 502each request based on pre-configured services), 1 = external 503processing of requests (external program is responsible for replying 504to service discovery requests with p2p_serv_disc_resp). Please note 505that there is quite strict limit on how quickly the response needs to 506be transmitted, so use of the internal processing is strongly 507recommended. 508 509p2p_service_add bonjour <query hexdump> <RDATA hexdump> 510 511Add a local Bonjour service for internal SD query processing. 512 513Examples: 514 515# AFP Over TCP (PTR) 516p2p_service_add bonjour 0b5f6166706f766572746370c00c000c01 074578616d706c65c027 517# AFP Over TCP (TXT) (RDATA=null) 518p2p_service_add bonjour 076578616d706c650b5f6166706f766572746370c00c001001 00 519 520# IP Printing over TCP (PTR) (RDATA=MyPrinter._ipp._tcp.local.) 521p2p_service_add bonjour 045f697070c00c000c01 094d795072696e746572c027 522# IP Printing over TCP (TXT) (RDATA=txtvers=1,pdl=application/postscript) 523p2p_service_add bonjour 096d797072696e746572045f697070c00c001001 09747874766572733d311a70646c3d6170706c69636174696f6e2f706f7374736372797074 524 525# Supported Service Type Hash (SSTH) 526p2p_service_add bonjour 000000 <32-byte bitfield as hexdump> 527(note: see P2P spec Annex E.4 for information on how to construct the bitfield) 528 529p2p_service_del bonjour <query hexdump> 530 531Remove a local Bonjour service from internal SD query processing. 532 533p2p_service_add upnp <version hex> <service> 534 535Add a local UPnP service for internal SD query processing. 536 537Examples: 538 539p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::upnp:rootdevice 540p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::upnp:rootdevice 541p2p_service_add upnp 10 uuid:1122de4e-8574-59ab-9322-333456789044::urn:schemas-upnp-org:service:ContentDirectory:2 542p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::urn:schemas-upnp-org:service:ContentDirectory:2 543p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::urn:schemas-upnp-org:device:InternetGatewayDevice:1 544 545p2p_service_del upnp <version hex> <service> 546 547Remove a local UPnP service from internal SD query processing. 548 549p2p_service_del asp <adv id> 550 551Removes the local asp service from internal SD query list. 552For example: p2p_service_del asp 4d6fc7 553 554p2p_service_flush 555 556Remove all local services from internal SD query processing. 557 558Invitation 559 560p2p_invite [persistent=<network id>|group=<group ifname>] [peer=address] 561 [go_dev_addr=address] [freq=<freq in MHz>] [ht40] [vht] [he] 562 [pref=<MHz>] 563 564Invite a peer to join a group (e.g., group=wlan1) or to reinvoke a 565persistent group (e.g., persistent=4). If the peer device is the GO of 566the persistent group, the peer parameter is not needed. Otherwise it is 567used to specify which device to invite. go_dev_addr parameter can be 568used to override the GO device address for Invitation Request should 569it be not known for some reason (this should not be needed in most 570cases). When reinvoking a persistent group, the GO device can specify 571the frequency for the group with the freq parameter. When reinvoking a 572persistent group, the P2P client device can use freq parameter to force 573a specific operating channel (or invitation failure if GO rejects that) 574or pref parameter to request a specific channel (while allowing GO to 575select to use another channel, if needed). 576 577Group Operations 578 579(These are used on the group interface.) 580 581wps_pin <any|address> <PIN> 582 583Start WPS PIN method. This allows a single WPS Enrollee to connect to 584the AP/GO. This is used on the GO when a P2P client joins an existing 585group. The second parameter is the address of the Enrollee or a string 586"any" to allow any station to use the entered PIN (which will restrict 587the PIN for one-time-use). PIN is the Enrollee PIN read either from a 588label or display on the P2P Client/WPS Enrollee. 589 590wps_pbc 591 592Start WPS PBC method (i.e., push the button). This allows a single WPS 593Enrollee to connect to the AP/GO. This is used on the GO when a P2P 594client joins an existing group. 595 596p2p_get_passphrase 597 598Get the passphrase for a group (only available when acting as a GO). 599 600p2p_presence_req [<duration> <interval>] [<duration> <interval>] 601 602Send a P2P Presence Request to the GO (this is only available when 603acting as a P2P client). If no duration/interval pairs are given, the 604request indicates that this client has no special needs for GO 605presence. The first parameter pair gives the preferred duration and 606interval values in microseconds. If the second pair is included, that 607indicates which value would be acceptable. This command returns OK 608immediately and the response from the GO is indicated in a 609P2P-PRESENCE-RESPONSE event message. 610 611Parameters 612 613p2p_ext_listen [<period> <interval>] 614 615Configure Extended Listen Timing. If the parameters are omitted, this 616feature is disabled. If the parameters are included, Listen State will 617be entered every interval msec for at least period msec. Both values 618have acceptable range of 1-65535 (with interval obviously having to be 619larger than or equal to duration). If the P2P module is not idle at 620the time the Extended Listen Timing timeout occurs, the Listen State 621operation will be skipped. 622 623The configured values will also be advertised to other P2P Devices. The 624received values are available in the p2p_peer command output: 625 626ext_listen_period=100 ext_listen_interval=5000 627 628p2p_set <field> <value> 629 630Change dynamic P2P parameters 631 632p2p_set discoverability <0/1> 633 634Disable/enable advertisement of client discoverability. This is 635enabled by default and this parameter is mainly used to allow testing 636of device discoverability. 637 638p2p_set managed <0/1> 639 640Disable/enable managed P2P Device operations. This is disabled by 641default. 642 643p2p_set listen_channel <channel> [<op_class>] 644 645Set P2P Listen channel. This is mainly meant for testing purposes and 646changing the Listen channel during normal operations can result in 647protocol failures. 648 649When specifying a social channel on the 2.4 GHz band (1/6/11) there is 650no need to specify the operating class since it defaults to 81. When 651specifying a social channel on the 60 GHz band (2), specify the 60 GHz 652operating class (180). 653 654p2p_set ssid_postfix <postfix> 655 656Set postfix string to be added to the automatically generated P2P SSID 657(DIRECT-<two random characters>). For example, postfix of "-testing" 658could result in the SSID becoming DIRECT-ab-testing. 659 660p2p_set per_sta_psk <0/1> 661 662Disabled(default)/enables use of per-client PSK in the P2P groups. This 663can be used to request GO to assign a unique PSK for each client during 664WPS provisioning. When enabled, this allow clients to be removed from 665the group securely with p2p_remove_client command since that client's 666PSK is removed at the same time to prevent it from connecting back using 667the old PSK. When per-client PSK is not used, the client can still be 668disconnected, but it will be able to re-join the group since the PSK it 669learned previously is still valid. It should be noted that the default 670passphrase on the GO that is normally used to allow legacy stations to 671connect through manual configuration does not change here, so if that is 672shared, devices with knowledge of that passphrase can still connect. 673 674set <field> <value> 675 676Set global configuration parameters which may also affect P2P 677operations. The format on these parameters is same as is used in 678wpa_supplicant.conf. Only the parameters listen here should be 679changed. Modifying other parameters may result in incorrect behavior 680since not all existing users of the parameters are updated. 681 682set uuid <UUID> 683 684Set WPS UUID (by default, this is generated based on the MAC address). 685 686set device_name <device name> 687 688Set WPS Device Name (also included in some P2P messages). 689 690set manufacturer <manufacturer> 691 692Set WPS Manufacturer. 693 694set model_name <model name> 695 696Set WPS Model Name. 697 698set model_number <model number> 699 700Set WPS Model Number. 701 702set serial_number <serial number> 703 704Set WPS Serial Number. 705 706set device_type <device type> 707 708Set WPS Device Type. 709 710set os_version <OS version> 711 712Set WPS OS Version. 713 714set config_methods <config methods> 715 716Set WPS Configuration Methods. 717 718set sec_device_type <device type> 719 720Add a new Secondary Device Type. 721 722set p2p_go_intent <GO intent> 723 724Set the default P2P GO Intent. Note: This value can be overridden in 725p2p_connect command and as such, there should be no need to change the 726default value here during normal operations. 727 728set p2p_ssid_postfix <P2P SSID postfix> 729 730Set P2P SSID postfix. 731 732set persistent_reconnect <0/1> 733 734Disable/enabled persistent reconnect for reinvocation of persistent 735groups. If enabled, invitations to reinvoke a persistent group will be 736accepted without separate authorization (e.g., user interaction). 737 738set country <two character country code> 739 740Set country code (this is included in some P2P messages). 741 742set p2p_search_delay <delay> 743 744Set p2p_search_delay which adds extra delay in milliseconds between 745concurrent search iterations to make p2p_find friendlier to concurrent 746operations by avoiding it from taking 100% of radio resources. The 747default value is 500 ms. 748 749Status 750 751p2p_peers [discovered] 752 753List P2P Device Addresses of all the P2P peers we know. The optional 754"discovered" parameter filters out the peers that we have not fully 755discovered, i.e., which we have only seen in a received Probe Request 756frame. 757 758p2p_peer <P2P Device Address> 759 760Fetch information about a known P2P peer. 761 762Group Status 763 764(These are used on the group interface.) 765 766status 767 768Show status information (connection state, role, use encryption 769parameters, IP address, etc.). 770 771sta 772 773Show information about an associated station (when acting in AP/GO role). 774 775all_sta 776 777Lists the currently associated stations. 778 779Configuration data 780 781list_networks 782 783Lists the configured networks, including stored information for 784persistent groups. The identifier in this list is used with 785p2p_group_add and p2p_invite to indicate which persistent group is to 786be reinvoked. 787 788remove_network <network id> 789 790Remove a network entry from configuration. 791 792 793P2PS Events/Responses: 794 795P2PS-PROV-START: This events gets triggered when provisioning is issued for 796either seeker or advertiser. 797 798For example, 799P2PS-PROV-START 00:55:44:33:22:11 adv_id=111 adv_mac=00:55:44:33:22:11 conncap=1 session=1234567 session_mac=00:11:22:33:44:55 info='xxxx' 800 801Parameters definition: 802 MAC address - always 803 adv_id - always ASCII hex-encoded u32 804 adv_mac - always MAC address that owns/registered the service 805 conncap - always mask of 0x01 (new), 0x02 (group client), 0x04 (group owner) 806 bits 807 session - always Session ID of the first session to be established 808 session_mac - always MAC address that owns/initiated the session 809 info - if available, UTF-8 string 810 Escaped single quote & backslash with a backslash: 811 \' == 0x27 == ', and \\ == 0x5c == \ 812 813P2PS-PROV-DONE: When provisioning is completed then this event gets triggered. 814 815For example, 816P2PS-PROV-DONE 00:11:22:33:44:55 status=0 adv_id=111 adv_mac=00:55:44:33:22:11 conncap=1 session=1234567 session_mac=00:11:22:33:44:55 [dev_passwd_id=8 | go=p2p-wlan0-0 | join=11:22:33:44:55:66 | persist=0] 817 818Parameters definition: 819 MAC address - always main device address of peer. May be different from MAC 820 ultimately connected to. 821 status - always ascii hex-encoded u8 (0 == success, 12 == deferred success) 822 adv_id - always ascii hex-encoded u32 823 adv_mac - always MAC address that owns/registered the service 824 conncap - always One of: 1 (new), 2 (group client), 4 (group owner) bits 825 session - always Session ID of the first session to be established 826 session_mac - always MAC address that owns/initiated the session 827 dev_passwd_id - only if conncap value == 1 (New GO negotiation) 828 8 - "p2ps" password must be passed in p2p_connect command 829 1 - "display" password must be passed in p2p_connect command 830 5 - "keypad" password must be passed in p2p_connect command 831 join only - if conncap value == 2 (Client Only). Display password and "join" 832 must be passed in p2p_connect and address must be the MAC specified 833 go only - if conncap value == 4 (GO Only). Interface name must be set with a 834 password 835 persist - only if previous persistent group existed between peers and shall 836 be re-used. Group is restarted by sending "p2p_group_add persistent=0" 837 where value is taken from P2P-PROV-DONE 838 839Extended Events/Response 840 841P2P-DEVICE-FOUND 00:11:22:33:44:55 p2p_dev_addr=00:11:22:33:44:55 pri_dev_type=0-00000000-0 name='' config_methods=0x108 dev_capab=0x21 group_capab=0x0 adv_id=111 asp_svc=alt.example.chat 842 843Parameters definition: 844 adv_id - if ASP ASCII hex-encoded u32. If it is reporting the 845 "wildcard service", this value will be 0 846 asp_svc - if ASP this is the service string. If it is reporting the 847 "wildcard service", this value will be org.wi-fi.wfds 848 849 850wpa_cli action script 851--------------------- 852 853See examples/p2p-action.sh 854 855TODO: describe DHCP/DNS setup 856TODO: cross-connection 857
README-WPS
1wpa_supplicant and Wi-Fi Protected Setup (WPS) 2============================================== 3 4This document describes how the WPS implementation in wpa_supplicant 5can be configured and how an external component on the client (e.g., 6management GUI) is used to enable WPS enrollment and registrar 7registration. 8 9 10Introduction to WPS 11------------------- 12 13Wi-Fi Protected Setup (WPS) is a mechanism for easy configuration of a 14wireless network. It allows automated generation of random keys (WPA 15passphrase/PSK) and configuration of an access point and client 16devices. WPS includes number of methods for setting up connections 17with PIN method and push-button configuration (PBC) being the most 18commonly deployed options. 19 20While WPS can enable more home networks to use encryption in the 21wireless network, it should be noted that the use of the PIN and 22especially PBC mechanisms for authenticating the initial key setup is 23not very secure. As such, use of WPS may not be suitable for 24environments that require secure network access without chance for 25allowing outsiders to gain access during the setup phase. 26 27WPS uses following terms to describe the entities participating in the 28network setup: 29- access point: the WLAN access point 30- Registrar: a device that control a network and can authorize 31 addition of new devices); this may be either in the AP ("internal 32 Registrar") or in an external device, e.g., a laptop, ("external 33 Registrar") 34- Enrollee: a device that is being authorized to use the network 35 36It should also be noted that the AP and a client device may change 37roles (i.e., AP acts as an Enrollee and client device as a Registrar) 38when WPS is used to configure the access point. 39 40 41More information about WPS is available from Wi-Fi Alliance: 42http://www.wi-fi.org/wifi-protected-setup 43 44 45wpa_supplicant implementation 46----------------------------- 47 48wpa_supplicant includes an optional WPS component that can be used as 49an Enrollee to enroll new network credential or as a Registrar to 50configure an AP. 51 52 53wpa_supplicant configuration 54---------------------------- 55 56WPS is an optional component that needs to be enabled in 57wpa_supplicant build configuration (.config). Here is an example 58configuration that includes WPS support and Linux nl80211 -based 59driver interface: 60 61CONFIG_DRIVER_NL80211=y 62CONFIG_WPS=y 63 64If you want to enable WPS external registrar (ER) functionality, you 65will also need to add following line: 66 67CONFIG_WPS_ER=y 68 69Following parameter can be used to enable support for NFC config method: 70 71CONFIG_WPS_NFC=y 72 73 74WPS needs the Universally Unique IDentifier (UUID; see RFC 4122) for 75the device. This is configured in the runtime configuration for 76wpa_supplicant (if not set, UUID will be generated based on local MAC 77address): 78 79# example UUID for WPS 80uuid=12345678-9abc-def0-1234-56789abcdef0 81 82The network configuration blocks needed for WPS are added 83automatically based on control interface commands, so they do not need 84to be added explicitly in the configuration file. 85 86WPS registration will generate new network blocks for the acquired 87credentials. If these are to be stored for future use (after 88restarting wpa_supplicant), wpa_supplicant will need to be configured 89to allow configuration file updates: 90 91update_config=1 92 93 94 95External operations 96------------------- 97 98WPS requires either a device PIN code (usually, 8-digit number) or a 99pushbutton event (for PBC) to allow a new WPS Enrollee to join the 100network. wpa_supplicant uses the control interface as an input channel 101for these events. 102 103The PIN value used in the commands must be processed by an UI to 104remove non-digit characters and potentially, to verify the checksum 105digit. "wpa_cli wps_check_pin <PIN>" can be used to do such processing. 106It returns FAIL if the PIN is invalid, or FAIL-CHECKSUM if the checksum 107digit is incorrect, or the processed PIN (non-digit characters removed) 108if the PIN is valid. 109 110If the client device has a display, a random PIN has to be generated 111for each WPS registration session. wpa_supplicant can do this with a 112control interface request, e.g., by calling wpa_cli: 113 114wpa_cli wps_pin any 115 116This will return the generated 8-digit PIN which will then need to be 117entered at the Registrar to complete WPS registration. At that point, 118the client will be enrolled with credentials needed to connect to the 119AP to access the network. 120 121 122If the client device does not have a display that could show the 123random PIN, a hardcoded PIN that is printed on a label can be 124used. wpa_supplicant is notified this with a control interface 125request, e.g., by calling wpa_cli: 126 127wpa_cli wps_pin any 12345670 128 129This starts the WPS negotiation in the same way as above with the 130generated PIN. 131 132When the wps_pin command is issued for an AP (including P2P GO) mode 133interface, an optional timeout parameter can be used to specify 134expiration timeout for the PIN in seconds. For example: 135 136wpa_cli wps_pin any 12345670 300 137 138 139If a random PIN is needed for a user interface, "wpa_cli wps_pin get" 140can be used to generate a new PIN without starting WPS negotiation. 141This random PIN can then be passed as an argument to another wps_pin 142call when the actual operation should be started. 143 144If the client design wants to support optional WPS PBC mode, this can 145be enabled by either a physical button in the client device or a 146virtual button in the user interface. The PBC operation requires that 147a button is also pressed at the AP/Registrar at about the same time (2 148minute window). wpa_supplicant is notified of the local button event 149over the control interface, e.g., by calling wpa_cli: 150 151wpa_cli wps_pbc 152 153At this point, the AP/Registrar has two minutes to complete WPS 154negotiation which will generate a new WPA PSK in the same way as the 155PIN method described above. 156 157 158If the client wants to operate in the Registrar role to learn the 159current AP configuration and optionally, to configure an AP, 160wpa_supplicant is notified over the control interface, e.g., with 161wpa_cli: 162 163wpa_cli wps_reg <AP BSSID> <AP PIN> 164(example: wpa_cli wps_reg 02:34:56:78:9a:bc 12345670) 165 166This is used to fetch the current AP settings instead of actually 167changing them. The main difference with the wps_pin command is that 168wps_reg uses the AP PIN (e.g., from a label on the AP) instead of a 169PIN generated at the client. 170 171In order to change the AP configuration, the new configuration 172parameters are given to the wps_reg command: 173 174wpa_cli wps_reg <AP BSSID> <AP PIN> <new SSID> <auth> <encr> <new key> 175examples: 176 wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 testing WPA2PSK CCMP 12345678 177 wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 clear OPEN NONE "" 178 179<auth> must be one of the following: OPEN WPAPSK WPA2PSK 180<encr> must be one of the following: NONE WEP TKIP CCMP 181 182 183Scanning 184-------- 185 186Scan results ('wpa_cli scan_results' or 'wpa_cli bss <idx>') include a 187flags field that is used to indicate whether the BSS support WPS. If 188the AP support WPS, but has not recently activated a Registrar, [WPS] 189flag will be included. If PIN method has been recently selected, 190[WPS-PIN] is shown instead. Similarly, [WPS-PBC] is shown if PBC mode 191is in progress. GUI programs can use these as triggers for suggesting 192a guided WPS configuration to the user. In addition, control interface 193monitor events WPS-AP-AVAILABLE{,-PBC,-PIN} can be used to find out if 194there are WPS enabled APs in scan results without having to go through 195all the details in the GUI. These notification could be used, e.g., to 196suggest possible WPS connection to the user. 197 198 199wpa_gui 200------- 201 202wpa_gui-qt4 directory contains a sample GUI that shows an example of 203how WPS support can be integrated into the GUI. Its main window has a 204WPS tab that guides user through WPS registration with automatic AP 205selection. In addition, it shows how WPS can be started manually by 206selecting an AP from scan results. 207 208 209Credential processing 210--------------------- 211 212By default, wpa_supplicant processes received credentials and updates 213its configuration internally. However, it is possible to 214control these operations from external programs, if desired. 215 216This internal processing can be disabled with wps_cred_processing=1 217option. When this is used, an external program is responsible for 218processing the credential attributes and updating wpa_supplicant 219configuration based on them. 220 221Following control interface messages are sent out for external programs: 222 223WPS-CRED-RECEIVED <hexdump of Credential attribute(s)> 224For example: 225<2>WPS-CRED-RECEIVED 100e006f10260001011045000c6a6b6d2d7770732d74657374100300020020100f000200081027004030653462303435366332363666653064333961643135353461316634626637313234333761636664623766333939653534663166316230323061643434386235102000060266a0ee1727 226 227 228wpa_supplicant as WPS External Registrar (ER) 229--------------------------------------------- 230 231wpa_supplicant can be used as a WPS ER to configure an AP or enroll 232new Enrollee to join the network. This functionality uses UPnP and 233requires that a working IP connectivity is available with the AP (this 234can be either over a wired or wireless connection). 235 236Separate wpa_supplicant process can be started for WPS ER 237operations. A special "none" driver can be used in such a case to 238indicate that no local network interface is actually controlled. For 239example, following command could be used to start the ER: 240 241wpa_supplicant -Dnone -c er.conf -ieth0 242 243Sample er.conf: 244 245ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=admin 246device_name=WPS External Registrar 247 248 249wpa_cli commands for ER functionality: 250 251wps_er_start [IP address] 252- start WPS ER functionality 253- the optional IP address parameter can be used to filter operations only 254 to include a single AP 255- if run again while ER is active, the stored information (discovered APs 256 and Enrollees) are shown again 257 258wps_er_stop 259- stop WPS ER functionality 260 261wps_er_learn <UUID|BSSID> <AP PIN> 262- learn AP configuration 263 264wps_er_set_config <UUID|BSSID> <network id> 265- use AP configuration from a locally configured network (e.g., from 266 wps_reg command); this does not change the AP's configuration, but 267 only prepares a configuration to be used when enrolling a new device 268 to the AP 269 270wps_er_config <UUID|BSSID> <AP PIN> <new SSID> <auth> <encr> <new key> 271- examples: 272 wps_er_config 87654321-9abc-def0-1234-56789abc0002 12345670 testing WPA2PSK CCMP 12345678 273 wpa_er_config 87654321-9abc-def0-1234-56789abc0002 12345670 clear OPEN NONE "" 274 275<auth> must be one of the following: OPEN WPAPSK WPA2PSK 276<encr> must be one of the following: NONE WEP TKIP CCMP 277 278 279wps_er_pbc <Enrollee UUID|MAC address> 280- accept an Enrollee PBC using External Registrar 281 282wps_er_pin <Enrollee UUID|"any"|MAC address> <PIN> [Enrollee MAC address] 283- add an Enrollee PIN to External Registrar 284- if Enrollee UUID is not known, "any" can be used to add a wildcard PIN 285- if the MAC address of the enrollee is known, it should be configured 286 to allow the AP to advertise list of authorized enrollees 287 288 289WPS ER events: 290 291WPS_EVENT_ER_AP_ADD 292- WPS ER discovered an AP 293 294WPS-ER-AP-ADD 87654321-9abc-def0-1234-56789abc0002 02:11:22:33:44:55 pri_dev_type=6-0050F204-1 wps_state=1 |Very friendly name|Company|Long description of the model|WAP|http://w1.fi/|http://w1.fi/hostapd/ 295 296WPS_EVENT_ER_AP_REMOVE 297- WPS ER removed an AP entry 298 299WPS-ER-AP-REMOVE 87654321-9abc-def0-1234-56789abc0002 300 301WPS_EVENT_ER_ENROLLEE_ADD 302- WPS ER discovered a new Enrollee 303 304WPS-ER-ENROLLEE-ADD 2b7093f1-d6fb-5108-adbb-bea66bb87333 02:66:a0:ee:17:27 M1=1 config_methods=0x14d dev_passwd_id=0 pri_dev_type=1-0050F204-1 |Wireless Client|Company|cmodel|123|12345| 305 306WPS_EVENT_ER_ENROLLEE_REMOVE 307- WPS ER removed an Enrollee entry 308 309WPS-ER-ENROLLEE-REMOVE 2b7093f1-d6fb-5108-adbb-bea66bb87333 02:66:a0:ee:17:27 310 311WPS-ER-AP-SETTINGS 312- WPS ER learned AP settings 313 314WPS-ER-AP-SETTINGS uuid=fd91b4ec-e3fa-5891-a57d-8c59efeed1d2 ssid=test-wps auth_type=0x0020 encr_type=0x0008 key=12345678 315 316 317WPS with NFC 318------------ 319 320WPS can be used with NFC-based configuration method. An NFC tag 321containing a password token from the Enrollee can be used to 322authenticate the connection instead of the PIN. In addition, an NFC tag 323with a configuration token can be used to transfer AP settings without 324going through the WPS protocol. 325 326When the station acts as an Enrollee, a local NFC tag with a password 327token can be used by touching the NFC interface of a Registrar. 328 329"wps_nfc [BSSID]" command starts WPS protocol run with the local end as 330the Enrollee using the NFC password token that is either pre-configured 331in the configuration file (wps_nfc_dev_pw_id, wps_nfc_dh_pubkey, 332wps_nfc_dh_privkey, wps_nfc_dev_pw) or generated dynamically with 333"wps_nfc_token <WPS|NDEF>" command. The included nfc_pw_token tool 334(build with "make nfc_pw_token") can be used to generate NFC password 335tokens during manufacturing (each station needs to have its own random 336keys). 337 338The "wps_nfc_config_token <WPS/NDEF>" command can be used to build an 339NFC configuration token when wpa_supplicant is controlling an AP 340interface (AP or P2P GO). The output value from this command is a 341hexdump of the current AP configuration (WPS parameter requests this to 342include only the WPS attributes; NDEF parameter requests additional NDEF 343encapsulation to be included). This data needs to be written to an NFC 344tag with an external program. Once written, the NFC configuration token 345can be used to touch an NFC interface on a station to provision the 346credentials needed to access the network. 347 348The "wps_nfc_config_token <WPS/NDEF> <network id>" command can be used 349to build an NFC configuration token based on a locally configured 350network. 351 352If the station includes NFC interface and reads an NFC tag with a MIME 353media type "application/vnd.wfa.wsc", the NDEF message payload (with or 354without NDEF encapsulation) can be delivered to wpa_supplicant using the 355following wpa_cli command: 356 357wps_nfc_tag_read <hexdump of payload> 358 359If the NFC tag contains a configuration token, the network is added to 360wpa_supplicant configuration. If the NFC tag contains a password token, 361the token is added to the WPS Registrar component. This information can 362then be used with wps_reg command (when the NFC password token was from 363an AP) using a special value "nfc-pw" in place of the PIN parameter. If 364the ER functionality has been started (wps_er_start), the NFC password 365token is used to enable enrollment of a new station (that was the source 366of the NFC password token). 367 368"nfc_get_handover_req <NDEF> <WPS-CR>" command can be used to build the 369WPS carrier record for a Handover Request Message for connection 370handover. The first argument selects the format of the output data and 371the second argument selects which type of connection handover is 372requested (WPS-CR = Wi-Fi handover as specified in WSC 2.0). 373 374"nfc_get_handover_sel <NDEF> <WPS> [UUID|BSSID]" command can be used to 375build the contents of a Handover Select Message for connection handover 376when this does not depend on the contents of the Handover Request 377Message. The first argument selects the format of the output data and 378the second argument selects which type of connection handover is 379requested (WPS = Wi-Fi handover as specified in WSC 2.0). If the options 380UUID|BSSID argument is included, this is a request to build the handover 381message for the specified AP when wpa_supplicant is operating as a WPS 382ER. 383 384"nfc_report_handover <INIT/RESP> WPS <carrier from handover request> 385<carrier from handover select>" can be used as an alternative way for 386reporting completed NFC connection handover. The first parameter 387indicates whether the local device initiated or responded to the 388connection handover and the carrier records are the selected carrier 389from the handover request and select messages as a hexdump. 390 391The "wps_er_nfc_config_token <WPS/NDEF> <UUID|BSSID>" command can be 392used to build an NFC configuration token for the specified AP when 393wpa_supplicant is operating as a WPS ER. The output value from this 394command is a hexdump of the selected AP configuration (WPS parameter 395requests this to include only the WPS attributes; NDEF parameter 396requests additional NDEF encapsulation to be included). This data needs 397to be written to an NFC tag with an external program. Once written, the 398NFC configuration token can be used to touch an NFC interface on a 399station to provision the credentials needed to access the network. 400
README-Windows.txt
1wpa_supplicant for Windows 2========================== 3 4Copyright (c) 2003-2009, Jouni Malinen <j@w1.fi> and contributors 5All Rights Reserved. 6 7This program is licensed under the BSD license (the one with 8advertisement clause removed). 9 10 11wpa_supplicant has support for being used as a WPA/WPA2/IEEE 802.1X 12Supplicant on Windows. The current port requires that WinPcap 13(http://winpcap.polito.it/) is installed for accessing packets and the 14driver interface. Both release versions 3.0 and 3.1 are supported. 15 16The current port is still somewhat experimental. It has been tested 17mainly on Windows XP (SP2) with limited set of NDIS drivers. In 18addition, the current version has been reported to work with Windows 192000. 20 21All security modes have been verified to work (at least complete 22authentication and successfully ping a wired host): 23- plaintext 24- static WEP / open system authentication 25- static WEP / shared key authentication 26- IEEE 802.1X with dynamic WEP keys 27- WPA-PSK, TKIP, CCMP, TKIP+CCMP 28- WPA-EAP, TKIP, CCMP, TKIP+CCMP 29- WPA2-PSK, TKIP, CCMP, TKIP+CCMP 30- WPA2-EAP, TKIP, CCMP, TKIP+CCMP 31 32 33Building wpa_supplicant with mingw 34---------------------------------- 35 36The default build setup for wpa_supplicant is to use MinGW and 37cross-compiling from Linux to MinGW/Windows. It should also be 38possible to build this under Windows using the MinGW tools, but that 39is not tested nor supported and is likely to require some changes to 40the Makefile unless cygwin is used. 41 42 43Building wpa_supplicant with MSVC 44--------------------------------- 45 46wpa_supplicant can be built with Microsoft Visual C++ compiler. This 47has been tested with Microsoft Visual C++ Toolkit 2003 and Visual 48Studio 2005 using the included nmake.mak as a Makefile for nmake. IDE 49can also be used by creating a project that includes the files and 50defines mentioned in nmake.mak. Example VS2005 solution and project 51files are included in vs2005 subdirectory. This can be used as a 52starting point for building the programs with VS2005 IDE. Visual Studio 532008 Express Edition is also able to use these project files. 54 55WinPcap development package is needed for the build and this can be 56downloaded from http://www.winpcap.org/install/bin/WpdPack_4_0_2.zip. The 57default nmake.mak expects this to be unpacked into C:\dev\WpdPack so 58that Include and Lib directories are in this directory. The files can be 59stored elsewhere as long as the WINPCAPDIR in nmake.mak is updated to 60match with the selected directory. In case a project file in the IDE is 61used, these Include and Lib directories need to be added to project 62properties as additional include/library directories. 63 64OpenSSL source package can be downloaded from 65http://www.openssl.org/source/openssl-0.9.8i.tar.gz and built and 66installed following instructions in INSTALL.W32. Note that if EAP-FAST 67support will be included in the wpa_supplicant, OpenSSL needs to be 68patched to# support it openssl-0.9.8i-tls-extensions.patch. The example 69nmake.mak file expects OpenSSL to be installed into C:\dev\openssl, but 70this directory can be modified by changing OPENSSLDIR variable in 71nmake.mak. 72 73If you do not need EAP-FAST support, you may also be able to use Win32 74binary installation package of OpenSSL from 75http://www.slproweb.com/products/Win32OpenSSL.html instead of building 76the library yourself. In this case, you will need to copy Include and 77Lib directories in suitable directory, e.g., C:\dev\openssl for the 78default nmake.mak. Copy {Win32OpenSSLRoot}\include into 79C:\dev\openssl\include and make C:\dev\openssl\lib subdirectory with 80files from {Win32OpenSSLRoot}\VC (i.e., libeay*.lib and ssleay*.lib). 81This will end up using dynamically linked OpenSSL (i.e., .dll files are 82needed) for it. Alternative, you can copy files from 83{Win32OpenSSLRoot}\VC\static to create a static build (no OpenSSL .dll 84files needed). 85 86 87Building wpa_supplicant for cygwin 88---------------------------------- 89 90wpa_supplicant can be built for cygwin by installing the needed 91development packages for cygwin. This includes things like compiler, 92make, openssl development package, etc. In addition, developer's pack 93for WinPcap (WPdpack.zip) from 94http://winpcap.polito.it/install/default.htm is needed. 95 96.config file should enable only one driver interface, 97CONFIG_DRIVER_NDIS. In addition, include directories may need to be 98added to match the system. An example configuration is available in 99defconfig. The library and include files for WinPcap will either need 100to be installed in compiler/linker default directories or their 101location will need to be adding to .config when building 102wpa_supplicant. 103 104Othen than this, the build should be more or less identical to Linux 105version, i.e., just run make after having created .config file. An 106additional tool, win_if_list.exe, can be built by running "make 107win_if_list". 108 109 110Building wpa_gui 111---------------- 112 113wpa_gui uses Qt application framework from Trolltech. It can be built 114with the open source version of Qt4 and MinGW. Following commands can 115be used to build the binary in the Qt 4 Command Prompt: 116 117# go to the root directory of wpa_supplicant source code 118cd wpa_gui-qt4 119qmake -o Makefile wpa_gui.pro 120make 121# the wpa_gui.exe binary is created into 'release' subdirectory 122 123 124Using wpa_supplicant for Windows 125-------------------------------- 126 127wpa_supplicant, wpa_cli, and wpa_gui behave more or less identically to 128Linux version, so instructions in README and example wpa_supplicant.conf 129should be applicable for most parts. In addition, there is another 130version of wpa_supplicant, wpasvc.exe, which can be used as a Windows 131service and which reads its configuration from registry instead of 132text file. 133 134When using access points in "hidden SSID" mode, ap_scan=2 mode need to 135be used (see wpa_supplicant.conf for more information). 136 137Windows NDIS/WinPcap uses quite long interface names, so some care 138will be needed when starting wpa_supplicant. Alternatively, the 139adapter description can be used as the interface name which may be 140easier since it is usually in more human-readable 141format. win_if_list.exe can be used to find out the proper interface 142name. 143 144Example steps in starting up wpa_supplicant: 145 146# win_if_list.exe 147ifname: \Device\NPF_GenericNdisWanAdapter 148description: Generic NdisWan adapter 149 150ifname: \Device\NPF_{769E012B-FD17-4935-A5E3-8090C38E25D2} 151description: Atheros Wireless Network Adapter (Microsoft's Packet Scheduler) 152 153ifname: \Device\NPF_{732546E7-E26C-48E3-9871-7537B020A211} 154description: Intel 8255x-based Integrated Fast Ethernet (Microsoft's Packet Scheduler) 155 156 157Since the example configuration used Atheros WLAN card, the middle one 158is the correct interface in this case. The interface name for -i 159command line option is the full string following "ifname:" (the 160"\Device\NPF_" prefix can be removed). In other words, wpa_supplicant 161would be started with the following command: 162 163# wpa_supplicant.exe -i'{769E012B-FD17-4935-A5E3-8090C38E25D2}' -c wpa_supplicant.conf -d 164 165-d optional enables some more debugging (use -dd for even more, if 166needed). It can be left out if debugging information is not needed. 167 168With the alternative mechanism for selecting the interface, this 169command has identical results in this case: 170 171# wpa_supplicant.exe -iAtheros -c wpa_supplicant.conf -d 172 173 174Simple configuration example for WPA-PSK: 175 176#ap_scan=2 177ctrl_interface= 178network={ 179 ssid="test" 180 key_mgmt=WPA-PSK 181 proto=WPA 182 pairwise=TKIP 183 psk="secret passphrase" 184} 185 186(remove '#' from the comment out ap_scan line to enable mode in which 187wpa_supplicant tries to associate with the SSID without doing 188scanning; this allows APs with hidden SSIDs to be used) 189 190 191wpa_cli.exe and wpa_gui.exe can be used to interact with the 192wpa_supplicant.exe program in the same way as with Linux. Note that 193ctrl_interface is using UNIX domain sockets when built for cygwin, but 194the native build for Windows uses named pipes and the contents of the 195ctrl_interface configuration item is used to control access to the 196interface. Anyway, this variable has to be included in the configuration 197to enable the control interface. 198 199 200Example SDDL string formats: 201 202(local admins group has permission, but nobody else): 203 204ctrl_interface=SDDL=D:(A;;GA;;;BA) 205 206("A" == "access allowed", "GA" == GENERIC_ALL == all permissions, and 207"BA" == "builtin administrators" == the local admins. The empty fields 208are for flags and object GUIDs, none of which should be required in this 209case.) 210 211(local admins and the local "power users" group have permissions, 212but nobody else): 213 214ctrl_interface=SDDL=D:(A;;GA;;;BA)(A;;GA;;;PU) 215 216(One ACCESS_ALLOWED ACE for GENERIC_ALL for builtin administrators, and 217one ACCESS_ALLOWED ACE for GENERIC_ALL for power users.) 218 219(close to wide open, but you have to be a valid user on 220the machine): 221 222ctrl_interface=SDDL=D:(A;;GA;;;AU) 223 224(One ACCESS_ALLOWED ACE for GENERIC_ALL for the "authenticated users" 225group.) 226 227This one would allow absolutely everyone (including anonymous 228users) -- this is *not* recommended, since named pipes can be attached 229to from anywhere on the network (i.e. there's no "this machine only" 230like there is with 127.0.0.1 sockets): 231 232ctrl_interface=SDDL=D:(A;;GA;;;BU)(A;;GA;;;AN) 233 234(BU == "builtin users", "AN" == "anonymous") 235 236See also [1] for the format of ACEs, and [2] for the possible strings 237that can be used for principal names. 238 239[1] 240http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/ace_strings.asp 241[2] 242http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/sid_strings.asp 243 244 245Starting wpa_supplicant as a Windows service (wpasvc.exe) 246--------------------------------------------------------- 247 248wpa_supplicant can be started as a Windows service by using wpasvc.exe 249program that is alternative build of wpa_supplicant.exe. Most of the 250core functionality of wpasvc.exe is identical to wpa_supplicant.exe, 251but it is using Windows registry for configuration information instead 252of a text file and command line parameters. In addition, it can be 253registered as a service that can be started automatically or manually 254like any other Windows service. 255 256The root of wpa_supplicant configuration in registry is 257HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant. This level includes global 258parameters and a 'interfaces' subkey with all the interface configuration 259(adapter to confname mapping). Each such mapping is a subkey that has 260'adapter', 'config', and 'ctrl_interface' values. 261 262This program can be run either as a normal command line application, 263e.g., for debugging, with 'wpasvc.exe app' or as a Windows service. 264Service need to be registered with 'wpasvc.exe reg <full path to 265wpasvc.exe>'. Alternatively, 'wpasvc.exe reg' can be used to register 266the service with the current location of wpasvc.exe. After this, wpasvc 267can be started like any other Windows service (e.g., 'net start wpasvc') 268or it can be configured to start automatically through the Services tool 269in administrative tasks. The service can be unregistered with 270'wpasvc.exe unreg'. 271 272If the service is set to start during system bootup to make the 273network connection available before any user has logged in, there may 274be a long (half a minute or so) delay in starting up wpa_supplicant 275due to WinPcap needing a driver called "Network Monitor Driver" which 276is started by default on demand. 277 278To speed up wpa_supplicant start during system bootup, "Network 279Monitor Driver" can be configured to be started sooner by setting its 280startup type to System instead of the default Demand. To do this, open 281up Device Manager, select Show Hidden Devices, expand the "Non 282Plug-and-Play devices" branch, double click "Network Monitor Driver", 283go to the Driver tab, and change the Demand setting to System instead. 284 285Configuration data is in HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs 286key. Each configuration profile has its own key under this. In terms of text 287files, each profile would map to a separate text file with possibly multiple 288networks. Under each profile, there is a networks key that lists all 289networks as a subkey. Each network has set of values in the same way as 290network block in the configuration file. In addition, blobs subkey has 291possible blobs as values. 292 293HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs\test\networks\0000 294 ssid="example" 295 key_mgmt=WPA-PSK 296 297See win_example.reg for an example on how to setup wpasvc.exe 298parameters in registry. It can also be imported to registry as a 299starting point for the configuration. 300