• Home
  • History
  • Annotate
  • only in /external/wpa_supplicant_8/wpa_supplicant/
NameDateSize

..05-Nov-20144 KiB

.gitignore05-Nov-201410

android.config05-Nov-201417.4 KiB

Android.mk05-Nov-201433.8 KiB

ap.c05-Nov-201431 KiB

ap.h05-Nov-20143.3 KiB

autoscan.c05-Nov-20143 KiB

autoscan.h05-Nov-20141.1 KiB

autoscan_exponential.c05-Nov-20142 KiB

autoscan_periodic.c05-Nov-20141.6 KiB

bgscan.c05-Nov-20142.7 KiB

bgscan.h05-Nov-20141.8 KiB

bgscan_learn.c05-Nov-201414.4 KiB

bgscan_simple.c05-Nov-20148.2 KiB

blacklist.c05-Nov-20143.4 KiB

blacklist.h05-Nov-2014660

bss.c05-Nov-201431.2 KiB

bss.h05-Nov-20144.5 KiB

ChangeLog05-Nov-2014102.1 KiB

config.c05-Nov-201493.1 KiB

config.h05-Nov-201435.6 KiB

config_file.c05-Nov-201431.1 KiB

config_none.c05-Nov-20141.3 KiB

config_ssid.h05-Nov-201417.7 KiB

config_winreg.c05-Nov-201424 KiB

ctrl_iface.c05-Nov-2014177.2 KiB

ctrl_iface.h05-Nov-20145.3 KiB

ctrl_iface_named_pipe.c05-Nov-201419.7 KiB

ctrl_iface_udp.c05-Nov-201417.3 KiB

ctrl_iface_unix.c05-Nov-201427 KiB

dbus/05-Nov-20144 KiB

defconfig05-Nov-201417.9 KiB

doc/05-Nov-20144 KiB

driver_i.h05-Nov-201421.8 KiB

eap_proxy_dummy.mk05-Nov-20140

eap_register.c05-Nov-20145.1 KiB

eap_testing.txt05-Nov-201414.4 KiB

eapol_test.c05-Nov-201436.8 KiB

events.c05-Nov-201492.9 KiB

examples/05-Nov-20144 KiB

gas_query.c05-Nov-201418.9 KiB

gas_query.h05-Nov-20141.4 KiB

hs20_supplicant.c05-Nov-201422.7 KiB

hs20_supplicant.h05-Nov-20141.6 KiB

ibss_rsn.c05-Nov-201422.6 KiB

ibss_rsn.h05-Nov-20141.7 KiB

interworking.c05-Nov-201474.2 KiB

interworking.h05-Nov-20141.3 KiB

main.c05-Nov-20148.6 KiB

main_none.c05-Nov-2014838

main_winmain.c05-Nov-20141.7 KiB

main_winsvc.c05-Nov-201411.1 KiB

Makefile05-Nov-201437.7 KiB

nfc_pw_token.c05-Nov-20141.7 KiB

nmake.mak05-Nov-20146.6 KiB

notify.c05-Nov-201415.1 KiB

notify.h05-Nov-20145.6 KiB

offchannel.c05-Nov-201413.7 KiB

offchannel.h05-Nov-20141.4 KiB

p2p_supplicant.c05-Nov-2014218.2 KiB

p2p_supplicant.h05-Nov-201410.8 KiB

preauth_test.c05-Nov-20148.4 KiB

README05-Nov-201438.1 KiB

README-HS2005-Nov-201419.1 KiB

README-P2P05-Nov-201421.9 KiB

README-Windows.txt05-Nov-201412.1 KiB

README-WPS05-Nov-201415.9 KiB

scan.c05-Nov-201454.7 KiB

scan.h05-Nov-20142.3 KiB

sme.c05-Nov-201440.2 KiB

sme.h05-Nov-20143 KiB

src/05-Nov-20144 KiB

systemd/05-Nov-20144 KiB

tests/05-Nov-20144 KiB

todo.txt05-Nov-20145 KiB

utils/05-Nov-20144 KiB

wifi_display.c05-Nov-20147.9 KiB

wifi_display.h05-Nov-2014742

win_if_list.c05-Nov-20143.7 KiB

wnm_sta.c05-Nov-201425.8 KiB

wnm_sta.h05-Nov-20141.7 KiB

wpa_cli.c05-Nov-201493.9 KiB

wpa_gui-qt4/05-Nov-20144 KiB

wpa_passphrase.c05-Nov-20141.3 KiB

wpa_priv.c05-Nov-201423 KiB

wpa_supplicant.c05-Nov-2014129.1 KiB

wpa_supplicant.conf05-Nov-201453.5 KiB

wpa_supplicant_conf.mk05-Nov-20141.3 KiB

wpa_supplicant_conf.sh05-Nov-2014458

wpa_supplicant_i.h05-Nov-201429.7 KiB

wpa_supplicant_template.conf05-Nov-2014117

wpas_glue.c05-Nov-201425.2 KiB

wpas_glue.h05-Nov-2014765

wpas_kay.c05-Nov-20148.8 KiB

wpas_kay.h05-Nov-2014922

wpas_module_tests.c05-Nov-20142.5 KiB

wps_supplicant.c05-Nov-201472.9 KiB

wps_supplicant.h05-Nov-20144.8 KiB

README

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

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 SubjetName 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# eap: Pre-configured EAP method
201#	This optional field can be used to specify which EAP method will be
202#	used with this credential. If not set, the EAP method is selected
203#	automatically based on ANQP information (e.g., NAI Realm).
204#
205# phase1: Pre-configure Phase 1 (outer authentication) parameters
206#	This optional field is used with like the 'eap' parameter.
207#
208# phase2: Pre-configure Phase 2 (inner authentication) parameters
209#	This optional field is used with like the 'eap' parameter.
210#
211# excluded_ssid: Excluded SSID
212#	This optional field can be used to excluded specific SSID(s) from
213#	matching with the network. Multiple entries can be used to specify more
214#	than one SSID.
215#
216# roaming_partner: Roaming partner information
217#	This optional field can be used to configure preferences between roaming
218#	partners. The field is a string in following format:
219#	<FQDN>,<0/1 exact match>,<priority>,<* or country code>
220#	(non-exact match means any subdomain matches the entry; priority is in
221#	0..255 range with 0 being the highest priority)
222#
223# update_identifier: PPS MO ID
224#	(Hotspot 2.0 PerProviderSubscription/UpdateIdentifier)
225#
226# provisioning_sp: FQDN of the SP that provisioned the credential
227#	This optional field can be used to keep track of the SP that provisioned
228#	the credential to find the PPS MO (./Wi-Fi/<provisioning_sp>).
229#
230# sp_priority: Credential priority within a provisioning SP
231#	This is the priority of the credential among all credentials
232#	provisionined by the same SP (i.e., for entries that have identical
233#	provisioning_sp value). The range of this priority is 0-255 with 0
234#	being the highest and 255 the lower priority.
235#
236# Minimum backhaul threshold (PPS/<X+>/Policy/MinBackhauldThreshold/*)
237#	These fields can be used to specify minimum download/upload backhaul
238#	bandwidth that is preferred for the credential. This constraint is
239#	ignored if the AP does not advertise WAN Metrics information or if the
240#	limit would prevent any connection. Values are in kilobits per second.
241# min_dl_bandwidth_home
242# min_ul_bandwidth_home
243# min_dl_bandwidth_roaming
244# min_ul_bandwidth_roaming
245#
246# max_bss_load: Maximum BSS Load Channel Utilization (1..255)
247#	(PPS/<X+>/Policy/MaximumBSSLoadValue)
248#	This value is used as the maximum channel utilization for network
249#	selection purposes for home networks. If the AP does not advertise
250#	BSS Load or if the limit would prevent any connection, this constraint
251#	will be ignored.
252#
253# req_conn_capab: Required connection capability
254#	(PPS/<X+>/Policy/RequiredProtoPortTuple)
255#	This value is used to configure set of required protocol/port pairs that
256#	a roaming network shall support (include explicitly in Connection
257#	Capability ANQP element). This constraint is ignored if the AP does not
258#	advertise Connection Capability or if this constraint would prevent any
259#	network connection. This policy is not used in home networks.
260#	Format: <protocol>[:<comma-separated list of ports]
261#	Multiple entries can be used to list multiple requirements.
262#	For example, number of common TCP protocols:
263#	req_conn_capab=6:22,80,443
264#	For example, IPSec/IKE:
265#	req_conn_capab=17:500
266#	req_conn_capab=50
267#
268# ocsp: Whether to use/require OCSP to check server certificate
269#	0 = do not use OCSP stapling (TLS certificate status extension)
270#	1 = try to use OCSP stapling, but not require response
271#	2 = require valid OCSP stapling response
272#
273# sim_num: Identifier for which SIM to use in multi-SIM devices
274#
275# for example:
276#
277#cred={
278#	realm="example.com"
279#	username="user@example.com"
280#	password="password"
281#	ca_cert="/etc/wpa_supplicant/ca.pem"
282#	domain="example.com"
283#	domain_suffix_match="example.com"
284#}
285#
286#cred={
287#	imsi="310026-000000000"
288#	milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82"
289#}
290#
291#cred={
292#	realm="example.com"
293#	username="user"
294#	password="password"
295#	ca_cert="/etc/wpa_supplicant/ca.pem"
296#	domain="example.com"
297#	roaming_consortium=223344
298#	eap=TTLS
299#	phase2="auth=MSCHAPV2"
300#}
301
302
303Control interface
304-----------------
305
306wpa_supplicant provides a control interface that can be used from
307external programs to manage various operations. The included command
308line tool, wpa_cli, can be used for manual testing with this interface.
309
310Following wpa_cli interactive mode commands show some examples of manual
311operations related to Hotspot 2.0:
312
313Remove configured networks and credentials:
314
315> remove_network all
316OK
317> remove_cred all
318OK
319
320
321Add a username/password credential:
322
323> add_cred
3240
325> set_cred 0 realm "mail.example.com"
326OK
327> set_cred 0 username "username"
328OK
329> set_cred 0 password "password"
330OK
331> set_cred 0 priority 1
332OK
333> set_cred 0 temporary 1
334OK
335
336Add a SIM credential using a simulated SIM/USIM card for testing:
337
338> add_cred
3391
340> set_cred 1 imsi "23456-0000000000"
341OK
342> set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123"
343OK
344> set_cred 1 priority 1
345OK
346
347Note: the return value of add_cred is used as the first argument to
348the following set_cred commands.
349
350Add a SIM credential using a external SIM/USIM processing:
351
352> set external_sim 1
353OK
354> add_cred
3551
356> set_cred 1 imsi "23456-0000000000"
357OK
358> set_cred 1 eap SIM
359OK
360
361
362Add a WPA2-Enterprise network:
363
364> add_network
3650
366> set_network 0 key_mgmt WPA-EAP
367OK
368> set_network 0 ssid "enterprise"
369OK
370> set_network 0 eap TTLS
371OK
372> set_network 0 anonymous_identity "anonymous"
373OK
374> set_network 0 identity "user"
375OK
376> set_network 0 password "password"
377OK
378> set_network 0 priority 0
379OK
380> enable_network 0 no-connect
381OK
382
383
384Add an open network:
385
386> add_network
3873
388> set_network 3 key_mgmt NONE
389OK
390> set_network 3 ssid "coffee-shop"
391OK
392> select_network 3
393OK
394
395Note: the return value of add_network is used as the first argument to
396the following set_network commands.
397
398The preferred credentials/networks can be indicated with the priority
399parameter (1 is higher priority than 0).
400
401
402Interworking network selection can be started with interworking_select
403command. This instructs wpa_supplicant to run a network scan and iterate
404through the discovered APs to request ANQP information from the APs that
405advertise support for Interworking/Hotspot 2.0:
406
407> interworking_select
408OK
409<3>Starting ANQP fetch for 02:00:00:00:01:00
410<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
411<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
412<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
413<3>ANQP fetch completed
414<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
415
416
417INTERWORKING-AP event messages indicate the APs that support network
418selection and for which there is a matching
419credential. interworking_connect command can be used to select a network
420to connect with:
421
422
423> interworking_connect 02:00:00:00:01:00
424OK
425<3>CTRL-EVENT-SCAN-RESULTS
426<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
427<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
428<3>Associated with 02:00:00:00:01:00
429<3>CTRL-EVENT-EAP-STARTED EAP authentication started
430<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
431<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
432<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
433<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
434<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=]
435
436
437wpa_supplicant creates a temporary network block for the selected
438network based on the configured credential and ANQP information from the
439AP:
440
441> list_networks
442network id / ssid / bssid / flags
4430	Example Network	any	[CURRENT]
444> get_network 0 key_mgmt
445WPA-EAP
446> get_network 0 eap
447TTLS
448
449
450Alternatively to using an external program to select the network,
451"interworking_select auto" command can be used to request wpa_supplicant
452to select which network to use based on configured priorities:
453
454
455> remove_network all
456OK
457<3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1
458> interworking_select auto
459OK
460<3>Starting ANQP fetch for 02:00:00:00:01:00
461<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
462<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
463<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
464<3>ANQP fetch completed
465<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
466<3>CTRL-EVENT-SCAN-RESULTS
467<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
468<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
469<3>Associated with 02:00:00:00:01:00
470<3>CTRL-EVENT-EAP-STARTED EAP authentication started
471<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
472<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
473<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
474<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
475<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=]
476
477
478The connection status can be shown with the status command:
479
480> status
481bssid=02:00:00:00:01:00
482ssid=Example Network
483id=0
484mode=station
485pairwise_cipher=CCMP       <--- link layer security indication
486group_cipher=CCMP
487key_mgmt=WPA2/IEEE 802.1X/EAP
488wpa_state=COMPLETED
489p2p_device_address=02:00:00:00:00:00
490address=02:00:00:00:00:00
491hs20=1      <--- HS 2.0 indication
492Supplicant PAE state=AUTHENTICATED
493suppPortStatus=Authorized
494EAP state=SUCCESS
495selectedMethod=21 (EAP-TTLS)
496EAP TLS cipher=AES-128-SHA
497EAP-TTLSv0 Phase2 method=PAP
498
499
500> status
501bssid=02:00:00:00:02:00
502ssid=coffee-shop
503id=3
504mode=station
505pairwise_cipher=NONE
506group_cipher=NONE
507key_mgmt=NONE
508wpa_state=COMPLETED
509p2p_device_address=02:00:00:00:00:00
510address=02:00:00:00:00:00
511
512
513Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status
514command output. Link layer security is indicated with the
515pairwise_cipher (CCMP = secure, NONE = no encryption used).
516
517
518Also the scan results include the Hotspot 2.0 indication:
519
520> scan_results
521bssid / frequency / signal level / flags / ssid
52202:00:00:00:01:00	2412	-30	[WPA2-EAP-CCMP][ESS][HS20]	Example Network
523
524
525ANQP information for the BSS can be fetched using the BSS command:
526
527> bss 02:00:00:00:01:00
528id=1
529bssid=02:00:00:00:01:00
530freq=2412
531beacon_int=100
532capabilities=0x0411
533qual=0
534noise=-92
535level=-30
536tsf=1345573286517276
537age=105
538ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000
539flags=[WPA2-EAP-CCMP][ESS][HS20]
540ssid=Example Network
541anqp_roaming_consortium=031122330510203040500601020304050603fedcba
542
543
544ANQP queries can also be requested with the anqp_get and hs20_anqp_get
545commands:
546
547> anqp_get 02:00:00:00:01:00 261
548OK
549<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
550> hs20_anqp_get 02:00:00:00:01:00 2
551OK
552<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
553
554In addition, fetch_anqp command can be used to request similar set of
555ANQP queries to be done as is run as part of interworking_select:
556
557> scan
558OK
559<3>CTRL-EVENT-SCAN-RESULTS
560> fetch_anqp
561OK
562<3>Starting ANQP fetch for 02:00:00:00:01:00
563<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
564<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
565<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
566<3>ANQP fetch completed
567

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>]
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.
85
86The optional dev_id option can be used to specify a single P2P peer to
87search for. The optional delay parameter can be used to request an extra
88delay to be used between search iterations (e.g., to free up radio
89resources for concurrent operations).
90
91The optional dev_type option can be used to specify a single device type
92(primary or secondary) to search for, e.g.,
93"p2p_find dev_type=1-0050F204-1".
94
95p2p_listen [timeout in seconds]
96
97Start Listen-only state (become discoverable without searching for
98other devices). Optional parameter can be used to specify the duration
99for the Listen operation in seconds. This command may not be of that
100much use during normal operations and is mainly designed for
101testing. It can also be used to keep the device discoverable without
102having to maintain a group.
103
104p2p_stop_find
105
106Stop ongoing P2P device discovery or other operation (connect, listen
107mode).
108
109p2p_flush
110
111Flush P2P peer table and state.
112
113Group Formation
114
115p2p_prov_disc <peer device address> <display|keypad|pbc> [join|auto]
116
117Send P2P provision discovery request to the specified peer. The
118parameters for this command are the P2P device address of the peer and
119the desired configuration method. For example, "p2p_prov_disc
12002:01:02:03:04:05 display" would request the peer to display a PIN for
121us and "p2p_prov_disc 02:01:02:03:04:05 keypad" would request the peer
122to enter a PIN that we display.
123
124The optional "join" parameter can be used to indicate that this command
125is requesting an already running GO to prepare for a new client. This is
126mainly used with "display" to request it to display a PIN. The "auto"
127parameter can be used to request wpa_supplicant to automatically figure
128out whether the peer device is operating as a GO and if so, use
129join-a-group style PD instead of GO Negotiation style PD.
130
131p2p_connect <peer device address> <pbc|pin|PIN#> [display|keypad]
132	[persistent|persistent=<network id>] [join|auth]
133	[go_intent=<0..15>] [freq=<in MHz>] [ht40] [vht] [provdisc]
134
135Start P2P group formation with a discovered P2P peer. This includes
136optional group owner negotiation, group interface setup, provisioning,
137and establishing data connection.
138
139The <pbc|pin|PIN#> parameter specifies the WPS provisioning
140method. "pbc" string starts pushbutton method, "pin" string start PIN
141method using an automatically generated PIN (which will be returned as
142the command return code), PIN# means that a pre-selected PIN can be
143used (e.g., 12345670). [display|keypad] is used with PIN method
144to specify which PIN is used (display=dynamically generated random PIN
145from local display, keypad=PIN entered from peer display). "persistent"
146parameter can be used to request a persistent group to be formed. The
147"persistent=<network id>" alternative can be used to pre-populate
148SSID/passphrase configuration based on a previously used persistent
149group where this device was the GO. The previously used parameters will
150then be used if the local end becomes the GO in GO Negotiation (which
151can be forced with go_intent=15).
152
153"join" indicates that this is a command to join an existing group as a
154client. It skips the GO Negotiation part. This will send a Provision
155Discovery Request message to the target GO before associating for WPS
156provisioning.
157
158"auth" indicates that the WPS parameters are authorized for the peer
159device without actually starting GO Negotiation (i.e., the peer is
160expected to initiate GO Negotiation). This is mainly for testing
161purposes.
162
163"go_intent" can be used to override the default GO Intent for this GO
164Negotiation.
165
166"freq" can be used to set a forced operating channel (e.g., freq=2412
167to select 2.4 GHz channel 1).
168
169"provdisc" can be used to request a Provision Discovery exchange to be
170used prior to starting GO Negotiation as a workaround with some deployed
171P2P implementations that require this to allow the user to accept the
172connection.
173
174p2p_group_add [persistent|persistent=<network id>] [freq=<freq in MHz>]
175	[ht40] [vht]
176
177Set up a P2P group owner manually (i.e., without group owner
178negotiation with a specific peer). This is also known as autonomous
179GO. Optional persistent=<network id> can be used to specify restart of
180a persistent group. Optional freq=<freq in MHz> can be used to force
181the GO to be started on a specific frequency. Special freq=2 or freq=5
182options can be used to request the best 2.4 GHz or 5 GHz band channel
183to be selected automatically.
184
185p2p_reject <peer device address>
186
187Reject connection attempt from a peer (specified with a device
188address). This is a mechanism to reject a pending GO Negotiation with
189a peer and request to automatically block any further connection or
190discovery of the peer.
191
192p2p_group_remove <group interface>
193
194Terminate a P2P group. If a new virtual network interface was used for
195the group, it will also be removed. The network interface name of the
196group interface is used as a parameter for this command.
197
198p2p_cancel
199
200Cancel an ongoing P2P group formation and joining-a-group related
201operation. This operations unauthorizes the specific peer device (if any
202had been authorized to start group formation), stops P2P find (if in
203progress), stops pending operations for join-a-group, and removes the
204P2P group interface (if one was used) that is in the WPS provisioning
205step. If the WPS provisioning step has been completed, the group is not
206terminated.
207
208p2p_remove_client <peer's P2P Device Address|iface=<interface address>>
209
210This command can be used to remove the specified client from all groups
211(operating and persistent) from the local GO. Note that the peer device
212can rejoin the group if it is in possession of a valid key. See p2p_set
213per_sta_psk command below for more details on how the peer can be
214removed securely.
215
216Service Discovery
217
218p2p_serv_disc_req
219
220Schedule a P2P service discovery request. The parameters for this
221command are the device address of the peer device (or 00:00:00:00:00:00
222for wildcard query that is sent to every discovered P2P peer that
223supports service discovery) and P2P Service Query TLV(s) as hexdump. For
224example,
225
226p2p_serv_disc_req 00:00:00:00:00:00 02000001
227
228schedules a request for listing all available services of all service
229discovery protocols and requests this to be sent to all discovered
230peers (note: this can result in long response frames). The pending
231requests are sent during device discovery (see p2p_find).
232
233There can be multiple pending peer device specific queries (each will be
234sent in sequence whenever the peer is found).
235
236This command returns an identifier for the pending query (e.g.,
237"1f77628") that can be used to cancel the request. Directed requests
238will be automatically removed when the specified peer has replied to
239it.
240
241Service Query TLV has following format:
242Length (2 octets, little endian) - length of following data
243Service Protocol Type (1 octet) - see the table below
244Service Transaction ID (1 octet) - nonzero identifier for the TLV
245Query Data (Length - 2 octets of data) - service protocol specific data
246
247Service Protocol Types:
2480 = All service protocols
2491 = Bonjour
2502 = UPnP
2513 = WS-Discovery
2524 = Wi-Fi Display
253
254For UPnP, an alternative command format can be used to specify a
255single query TLV (i.e., a service discovery for a specific UPnP
256service):
257
258p2p_serv_disc_req 00:00:00:00:00:00 upnp <version hex> <ST: from M-SEARCH>
259
260For example:
261
262p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1
263
264Additional examples for queries:
265
266# list of all Bonjour services
267p2p_serv_disc_req 00:00:00:00:00:00 02000101
268
269# list of all UPnP services
270p2p_serv_disc_req 00:00:00:00:00:00 02000201
271
272# list of all WS-Discovery services
273p2p_serv_disc_req 00:00:00:00:00:00 02000301
274
275# list of all Bonjour and UPnP services
276p2p_serv_disc_req 00:00:00:00:00:00 0200010102000202
277
278# Apple File Sharing over TCP
279p2p_serv_disc_req 00:00:00:00:00:00 130001010b5f6166706f766572746370c00c000c01
280
281# Bonjour SSTH (supported service type hash)
282p2p_serv_disc_req 00:00:00:00:00:00 05000101000000
283
284# UPnP examples
285p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 ssdp:all
286p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 upnp:rootdevice
287p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:service:ContentDirectory:2
288p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 uuid:6859dede-8574-59ab-9332-123456789012
289p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1
290
291# Wi-Fi Display examples
292# format: wifi-display <list of roles> <list of subelements>
293p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source] 2,3,4,5
294p2p_serv_disc_req 02:01:02:03:04:05 wifi-display [pri-sink] 3
295p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [sec-source] 2
296p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source+sink] 2,3,4,5
297p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source][pri-sink] 2,3,4,5
298
299p2p_serv_disc_cancel_req <query identifier>
300
301Cancel a pending P2P service discovery request. This command takes a
302single parameter: identifier for the pending query (the value returned
303by p2p_serv_disc_req, e.g., "p2p_serv_disc_cancel_req 1f77628".
304
305p2p_serv_disc_resp
306
307Reply to a service discovery query. This command takes following
308parameters: frequency in MHz, destination address, dialog token,
309response TLV(s). The first three parameters are copied from the
310request event. For example, "p2p_serv_disc_resp 2437 02:40:61:c2:f3:b7
3111 0300000101". This command is used only if external program is used
312to process the request (see p2p_serv_disc_external).
313
314p2p_service_update
315
316Indicate that local services have changed. This is used to increment
317the P2P service indicator value so that peers know when previously
318cached information may have changed. This is only needed when external
319service discovery processing is enabled since the commands to
320pre-configure services for internal processing will increment the
321indicator automatically.
322
323p2p_serv_disc_external <0|1>
324
325Configure external processing of P2P service requests: 0 (default) =
326no external processing of requests (i.e., internal code will process
327each request based on pre-configured services), 1 = external
328processing of requests (external program is responsible for replying
329to service discovery requests with p2p_serv_disc_resp). Please note
330that there is quite strict limit on how quickly the response needs to
331be transmitted, so use of the internal processing is strongly
332recommended.
333
334p2p_service_add bonjour <query hexdump> <RDATA hexdump>
335
336Add a local Bonjour service for internal SD query processing.
337
338Examples:
339
340# AFP Over TCP (PTR)
341p2p_service_add bonjour 0b5f6166706f766572746370c00c000c01 074578616d706c65c027
342# AFP Over TCP (TXT) (RDATA=null)
343p2p_service_add bonjour 076578616d706c650b5f6166706f766572746370c00c001001 00
344
345# IP Printing over TCP (PTR) (RDATA=MyPrinter._ipp._tcp.local.)
346p2p_service_add bonjour 045f697070c00c000c01 094d795072696e746572c027
347# IP Printing over TCP (TXT) (RDATA=txtvers=1,pdl=application/postscript)
348p2p_service_add bonjour 096d797072696e746572045f697070c00c001001 09747874766572733d311a70646c3d6170706c69636174696f6e2f706f7374736372797074
349
350# Supported Service Type Hash (SSTH)
351p2p_service_add bonjour 000000 <32-byte bitfield as hexdump>
352(note: see P2P spec Annex E.4 for information on how to construct the bitfield)
353
354p2p_service_del bonjour <query hexdump>
355
356Remove a local Bonjour service from internal SD query processing.
357
358p2p_service_add upnp <version hex> <service>
359
360Add a local UPnP service for internal SD query processing.
361
362Examples:
363
364p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::upnp:rootdevice
365p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::upnp:rootdevice
366p2p_service_add upnp 10 uuid:1122de4e-8574-59ab-9322-333456789044::urn:schemas-upnp-org:service:ContentDirectory:2
367p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::urn:schemas-upnp-org:service:ContentDirectory:2
368p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::urn:schemas-upnp-org:device:InternetGatewayDevice:1
369
370p2p_service_del upnp <version hex> <service>
371
372Remove a local UPnP service from internal SD query processing.
373
374p2p_service_flush
375
376Remove all local services from internal SD query processing.
377
378Invitation
379
380p2p_invite [persistent=<network id>|group=<group ifname>] [peer=address]
381	[go_dev_addr=address] [freq=<freq in MHz>] [ht40] [vht]
382	[pref=<MHz>]
383
384Invite a peer to join a group (e.g., group=wlan1) or to reinvoke a
385persistent group (e.g., persistent=4). If the peer device is the GO of
386the persistent group, the peer parameter is not needed. Otherwise it is
387used to specify which device to invite. go_dev_addr parameter can be
388used to override the GO device address for Invitation Request should
389it be not known for some reason (this should not be needed in most
390cases). When reinvoking a persistent group, the GO device can specify
391the frequency for the group with the freq parameter. When reinvoking a
392persistent group, the P2P client device can use freq parameter to force
393a specific operating channel (or invitation failure if GO rejects that)
394or pref parameter to request a specific channel (while allowing GO to
395select to use another channel, if needed).
396
397Group Operations
398
399(These are used on the group interface.)
400
401wps_pin <any|address> <PIN>
402
403Start WPS PIN method. This allows a single WPS Enrollee to connect to
404the AP/GO. This is used on the GO when a P2P client joins an existing
405group. The second parameter is the address of the Enrollee or a string
406"any" to allow any station to use the entered PIN (which will restrict
407the PIN for one-time-use). PIN is the Enrollee PIN read either from a
408label or display on the P2P Client/WPS Enrollee.
409
410wps_pbc
411
412Start WPS PBC method (i.e., push the button). This allows a single WPS
413Enrollee to connect to the AP/GO. This is used on the GO when a P2P
414client joins an existing group.
415
416p2p_get_passphrase
417
418Get the passphrase for a group (only available when acting as a GO).
419
420p2p_presence_req [<duration> <interval>] [<duration> <interval>]
421
422Send a P2P Presence Request to the GO (this is only available when
423acting as a P2P client). If no duration/interval pairs are given, the
424request indicates that this client has no special needs for GO
425presence. The first parameter pair gives the preferred duration and
426interval values in microseconds. If the second pair is included, that
427indicates which value would be acceptable. This command returns OK
428immediately and the response from the GO is indicated in a
429P2P-PRESENCE-RESPONSE event message.
430
431Parameters
432
433p2p_ext_listen [<period> <interval>]
434
435Configure Extended Listen Timing. If the parameters are omitted, this
436feature is disabled. If the parameters are included, Listen State will
437be entered every interval msec for at least period msec. Both values
438have acceptable range of 1-65535 (with interval obviously having to be
439larger than or equal to duration). If the P2P module is not idle at
440the time the Extended Listen Timing timeout occurs, the Listen State
441operation will be skipped.
442
443The configured values will also be advertised to other P2P Devices. The
444received values are available in the p2p_peer command output:
445
446ext_listen_period=100 ext_listen_interval=5000
447
448p2p_set <field> <value>
449
450Change dynamic P2P parameters
451
452p2p_set discoverability <0/1>
453
454Disable/enable advertisement of client discoverability. This is
455enabled by default and this parameter is mainly used to allow testing
456of device discoverability.
457
458p2p_set managed <0/1>
459
460Disable/enable managed P2P Device operations. This is disabled by
461default.
462
463p2p_set listen_channel <1/6/11>
464
465Set P2P Listen channel. This is mainly meant for testing purposes and
466changing the Listen channel during normal operations can result in
467protocol failures.
468
469p2p_set ssid_postfix <postfix>
470
471Set postfix string to be added to the automatically generated P2P SSID
472(DIRECT-<two random characters>). For example, postfix of "-testing"
473could result in the SSID becoming DIRECT-ab-testing.
474
475p2p_set per_sta_psk <0/1>
476
477Disabled(default)/enables use of per-client PSK in the P2P groups. This
478can be used to request GO to assign a unique PSK for each client during
479WPS provisioning. When enabled, this allow clients to be removed from
480the group securily with p2p_remove_client command since that client's
481PSK is removed at the same time to prevent it from connecting back using
482the old PSK. When per-client PSK is not used, the client can still be
483disconnected, but it will be able to re-join the group since the PSK it
484learned previously is still valid. It should be noted that the default
485passphrase on the GO that is normally used to allow legacy stations to
486connect through manual configuration does not change here, so if that is
487shared, devices with knowledge of that passphrase can still connect.
488
489set <field> <value>
490
491Set global configuration parameters which may also affect P2P
492operations. The format on these parameters is same as is used in
493wpa_supplicant.conf. Only the parameters listen here should be
494changed. Modifying other parameters may result in incorrect behavior
495since not all existing users of the parameters are updated.
496
497set uuid <UUID>
498
499Set WPS UUID (by default, this is generated based on the MAC address).
500
501set device_name <device name>
502
503Set WPS Device Name (also included in some P2P messages).
504
505set manufacturer <manufacturer>
506
507Set WPS Manufacturer.
508
509set model_name <model name>
510
511Set WPS Model Name.
512
513set model_number <model number>
514
515Set WPS Model Number.
516
517set serial_number <serial number>
518
519Set WPS Serial Number.
520
521set device_type <device type>
522
523Set WPS Device Type.
524
525set os_version <OS version>
526
527Set WPS OS Version.
528
529set config_methods <config methods>
530
531Set WPS Configuration Methods.
532
533set sec_device_type <device type>
534
535Add a new Secondary Device Type.
536
537set p2p_go_intent <GO intent>
538
539Set the default P2P GO Intent. Note: This value can be overridden in
540p2p_connect command and as such, there should be no need to change the
541default value here during normal operations.
542
543set p2p_ssid_postfix <P2P SSID postfix>
544
545Set P2P SSID postfix.
546
547set persistent_reconnect <0/1>
548
549Disable/enabled persistent reconnect for reinvocation of persistent
550groups. If enabled, invitations to reinvoke a persistent group will be
551accepted without separate authorization (e.g., user interaction).
552
553set country <two character country code>
554
555Set country code (this is included in some P2P messages).
556
557set p2p_search_delay <delay>
558
559Set p2p_search_delay which adds extra delay in milliseconds between
560concurrent search iterations to make p2p_find friendlier to concurrent
561operations by avoiding it from taking 100% of radio resources. The
562default value is 500 ms.
563
564Status
565
566p2p_peers [discovered]
567
568List P2P Device Addresses of all the P2P peers we know. The optional
569"discovered" parameter filters out the peers that we have not fully
570discovered, i.e., which we have only seen in a received Probe Request
571frame.
572
573p2p_peer <P2P Device Address>
574
575Fetch information about a known P2P peer.
576
577Group Status
578
579(These are used on the group interface.)
580
581status
582
583Show status information (connection state, role, use encryption
584parameters, IP address, etc.).
585
586sta
587
588Show information about an associated station (when acting in AP/GO role).
589
590all_sta
591
592Lists the currently associated stations.
593
594Configuration data
595
596list_networks
597
598Lists the configured networks, including stored information for
599persistent groups. The identifier in this list is used with
600p2p_group_add and p2p_invite to indicate which persistent group is to
601be reinvoked.
602
603remove_network <network id>
604
605Remove a network entry from configuration. 
606
607
608wpa_cli action script
609---------------------
610
611See examples/p2p-action.sh
612
613TODO: describe DHCP/DNS setup
614TODO: cross-connection
615

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