NameDateSize

..23-Apr-20199

android.config23-Apr-201919.5 KiB

Android.mk22-Aug-201936.8 KiB

ap.c22-Aug-201943.6 KiB

ap.h22-Aug-20194.4 KiB

autoscan.c09-Dec-20183.5 KiB

autoscan.h12-Jul-20181.4 KiB

autoscan_exponential.c05-Jul-20132 KiB

autoscan_periodic.c05-Jul-20131.6 KiB

bgscan.c09-Dec-20182.4 KiB

bgscan.h12-Jul-20182.1 KiB

bgscan_learn.c09-Dec-201814.4 KiB

bgscan_simple.c09-Dec-20188 KiB

binder/12-Jul-201815

blacklist.c05-Jul-20133.4 KiB

blacklist.h05-Jul-2013660

bss.c22-Aug-201935.6 KiB

bss.h23-Apr-20195.8 KiB

ChangeLog22-Aug-2019127.2 KiB

config.c22-Aug-2019119.5 KiB

config.h22-Aug-201950.2 KiB

config_file.c22-Aug-201942.5 KiB

config_none.c21-Apr-20151.3 KiB

config_ssid.h22-Aug-201926.9 KiB

ctrl_iface.c22-Aug-2019274.9 KiB

ctrl_iface.h21-Apr-20155.3 KiB

ctrl_iface_named_pipe.c09-Dec-201819.6 KiB

ctrl_iface_udp.c09-Dec-201820 KiB

ctrl_iface_unix.c23-Apr-201934.5 KiB

dbus/22-Aug-201920

defconfig22-Aug-201921.7 KiB

dpp_supplicant.c22-Aug-201964.3 KiB

dpp_supplicant.h22-Aug-20191.3 KiB

driver_i.h22-Aug-201928.8 KiB

eap_proxy_dummy.mak21-Apr-20150

eap_proxy_dummy.mk21-Apr-20150

eap_register.c22-Aug-20195.2 KiB

eap_testing.txt06-Nov-201214.4 KiB

eapol_test.c22-Aug-201939.5 KiB

eapol_test.py23-Apr-20194.4 KiB

events.c22-Aug-2019135.1 KiB

examples/23-Apr-201922

gas_query.c23-Apr-201924.2 KiB

gas_query.h23-Apr-20191.5 KiB

hs20_supplicant.c23-Apr-201933.2 KiB

hs20_supplicant.h23-Apr-20192.2 KiB

ibss_rsn.c22-Aug-201923.3 KiB

ibss_rsn.h12-Jul-20181.7 KiB

interworking.c22-Aug-201981.6 KiB

interworking.h09-Dec-20181.3 KiB

libwpa_test.c12-Jul-2018611

main.c16-May-201910.2 KiB

main_none.c21-Apr-2015844

mbo.c23-Apr-201914.9 KiB

mesh.c22-Aug-201918.9 KiB

mesh.h12-Jul-20181.4 KiB

mesh_mpm.c22-Aug-201936.4 KiB

mesh_mpm.h12-Jul-20181.5 KiB

mesh_rsn.c23-Apr-201920.7 KiB

mesh_rsn.h12-Jul-20181.4 KiB

nfc_pw_token.c05-Jul-20131.7 KiB

nmake.mak06-Nov-20126.6 KiB

notify.c22-Aug-201920.8 KiB

notify.h22-Aug-20197.2 KiB

offchannel.c09-Dec-201816.1 KiB

offchannel.h05-Jul-20131.4 KiB

op_classes.c22-Aug-20199.3 KiB

p2p_supplicant.c22-Aug-2019270.4 KiB

p2p_supplicant.h23-Apr-201912.8 KiB

p2p_supplicant_sd.c12-Jul-201830.8 KiB

preauth_test.c22-Aug-20198.6 KiB

README23-Apr-201939.2 KiB

README-DPP22-Aug-20195.2 KiB

README-HS2009-Dec-201821.8 KiB

README-P2P23-Apr-201933 KiB

README-Windows.txt12-Jul-201812.1 KiB

README-WPS21-Apr-201515.9 KiB

rrm.c22-Aug-201941 KiB

scan.c23-Apr-201980 KiB

scan.h12-Jul-20182.8 KiB

sme.c22-Aug-201974.5 KiB

sme.h23-Apr-20193.7 KiB

systemd/23-Apr-20196

todo.txt21-Apr-20154.4 KiB

utils/23-Apr-20193

vs2005/12-Jul-20189

wifi_display.c09-Dec-201810.4 KiB

wifi_display.h21-Apr-2015904

wmm_ac.c23-Apr-201923.6 KiB

wmm_ac.h12-Jul-20184.8 KiB

wnm_sta.c22-Aug-201950.5 KiB

wnm_sta.h09-Dec-20182.5 KiB

wpa_cli.c22-Aug-2019121.3 KiB

wpa_passphrase.c09-Dec-20181.5 KiB

wpa_priv.c09-Dec-201830 KiB

wpa_supplicant.c22-Aug-2019205.7 KiB

wpa_supplicant.conf22-Aug-201974.9 KiB

wpa_supplicant_conf.mk05-Jul-20131.3 KiB

wpa_supplicant_conf.sh05-Jul-2013458

wpa_supplicant_i.h22-Aug-201946.1 KiB

wpa_supplicant_template.conf09-Dec-2018136

wpas_glue.c22-Aug-201933.6 KiB

wpas_glue.h19-Oct-2015888

wpas_kay.c23-Apr-20199.9 KiB

wpas_kay.h09-Dec-20181.1 KiB

wpas_module_tests.c12-Jul-20182.5 KiB

wps_supplicant.c23-Apr-201979.2 KiB

wps_supplicant.h23-Apr-20195.1 KiB

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 fo 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 capabilies
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 allows enrolling of interface-less devices
13in a secure Wi-Fi network using many methods like QR code based
14authentication( detailed below ), PKEX based authentication etc. In DPP
15a Configurator is used to provide network credentials to the devices.
16The three phases of DPP connection are authentication, configuration and
17network introduction.
18
19Build config setup
20------------------
21
22The following changes must go in the config file used to compile hostapd
23and wpa_supplicant.
24
25wpa_supplicant build config
26---------------------------
27
28Enable DPP and protected management frame in wpa_supplicant build config
29file
30
31CONFIG_IEEE80211W=y
32CONFIG_DPP=y
33
34hostapd build config
35--------------------
36
37Enable DPP and protected management frame in hostapd build config file
38
39CONFIG_IEEE80211W=y
40CONFIG_DPP=y
41
42Configurator build config
43-------------------------
44
45Any STA or AP device can act as a Configurator. Enable DPP and protected
46managment frames in build config. For an AP to act as Configurator,
47Interworking needs to be enabled. For wpa_supplicant it is not required.
48
49CONFIG_INTERWORKING=y
50
51
52Sample supplicant config file before provisioning
53-------------------------------------------------
54
55ctrl_interface=DIR=/var/run/wpa_supplicant
56ctrl_interface_group=0
57update_config=1
58pmf=2
59dpp_config_processing=2
60
61Sample hostapd config file before provisioning
62----------------------------------------------
63
64interface=wlan0
65driver=nl80211
66ctrl_interface=/var/run/hostapd
67ssid=test
68channel=1
69wpa=2
70wpa_key_mgmt=DPP
71ieee80211w=1
72wpa_pairwise=CCMP
73rsn_pairwise=CCMP
74
75
76Pre-requisites
77--------------
78
79It is assumed that an AP and client station are up by running hostapd
80and wpa_supplicant using respective config files.
81
82
83Creating Configurator
84---------------------
85
86Add a Configurator over the control interface (wpa_cli/hostapd_cli)
87
88> dpp_configurator_add
89(returns id)
90
91To get key of Configurator
92> dpp_configurator_get_key <id>
93
94
95How to configure an enrollee using Configurator
96-----------------------------------------------
97
98On enrollee side:
99
100Generate QR code for the device. Store the qr code id returned by the
101command.
102
103> dpp_bootstrap_gen type=qrcode mac=<mac-address-of-device> chan=<operating-class/operating-channel> key=<key of the device>
104(returns bootstrapping info id)
105
106Get QR Code of device using the bootstrap info id.
107> dpp_bootstrap_get_uri <bootstrap-id>
108
109Make device listen to DPP request (The central frequency of channel 1 is
1102412) in case if enrollee is a client device.
111
112> dpp_listen <frequency>
113
114On Configurator side:
115
116Enter the QR Code in the Configurator.
117> dpp_qr_code "<QR-Code-read-from-enrollee>"
118
119On successfully adding QR Code, a bootstrapping info id is returned.
120
121Send provisioning request to enrollee. (conf is ap-dpp if enrollee is an
122AP. conf is sta-dpp if enrollee is a client)
123> dpp_auth_init peer=<qr-code-id> conf=<ap-dpp|sta-dpp> configurator=<configurator-id>
124
125The DPP values will be printed in the console. Save this values into the
126config file. If the enrollee is an AP, we need to manually write these
127values to the hostapd config file. If the enrollee is a client device,
128these details can be automatically saved to config file using the
129following command.
130
131> save_config
132
133To set values in runtime for AP enrollees
134
135> set dpp_connector <Connector-value-printed-on-console>
136> set dpp_csign <csign-value-on-console>
137> set dpp_netaccesskey <netaccess-value-on-console>
138
139To set values in runtime for client enrollees, set dpp_config_processing
140to 2 in wpa_supplicant conf file.
141
142Once the values are set in run-time (if not set in run-time, but saved
143in config files, they are taken up in next restart), the client device
144will automatically connect to the already provisioned AP and connection
145will be established.
146
147
148Self-configuring a device
149-------------------------
150
151It is possible for a device to configure itself if it is the
152Configurator for the network.
153
154Create a Configurator in the device and use the dpp_configurator_sign
155command to get DPP credentials.
156
157> dpp_configurator_add
158(returns configurator id)
159> dpp_configurator_sign conf=<ap-dpp|sta-dpp> configurator=<configurator-id>
160
161
162Sample AP configuration files after provisioning
163------------------------------------------------
164
165interface=wlan0
166driver=nl80211
167ctrl_interface=/var/run/hostapd
168ssid=test
169channel=1
170wpa=2
171wpa_key_mgmt=DPP
172ieee80211w=1
173wpa_pairwise=CCMP
174rsn_pairwise=CCMP
175dpp_connector=<Connector value provided by Configurator>
176dpp_csign=<C-Sign-Key value provided by Configurator>
177dpp_netaccesskey=<Net access key provided by Configurator>
178
179
180Sample station configuration file after provisioning
181----------------------------------------------------
182
183ctrl_interface=DIR=/var/run/wpa_supplicant
184ctrl_interface_group=0
185update_config=1
186pmf=2
187dpp_config_processing=2
188network={
189	ssid="test"
190	key_mgmt=DPP
191	ieee80211w=2
192	dpp_connector="<Connector value provided by Configurator>"
193	dpp_netaccesskey=<Net access key provided by Configurator>
194	dpp_csign=<C-sign-key value provided by Configurator>
195}
196

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# Homogenous 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-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

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