|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | - | - |
| dbus/ | | 03-May-2024 | - | 16,428 | 11,248 |
| doc/docbook/ | | 03-May-2024 | - | 1,826 | 1,544 |
| examples/ | | 03-May-2024 | - | 1,067 | 740 |
| src/ | | 03-May-2024 | - | | |
| tests/ | | 03-May-2024 | - | 506 | 360 |
| wpa_gui-qt4/ | | 03-May-2024 | - | 12,218 | 10,976 |
| .gitignore | D | 03-May-2024 | 10 | 2 | 1 |
| Android.mk | D | 03-May-2024 | 30.7 KiB | 1,463 | 1,240 |
| ChangeLog | D | 03-May-2024 | 69.4 KiB | 1,296 | 1,256 |
| Makefile | D | 03-May-2024 | 32.9 KiB | 1,527 | 1,315 |
| README | D | 03-May-2024 | 34.3 KiB | 947 | 759 |
| README-P2P | D | 03-May-2024 | 17.5 KiB | 526 | 353 |
| README-WPS | D | 03-May-2024 | 11.2 KiB | 306 | 215 |
| README-Windows.txt | D | 03-May-2024 | 18.9 KiB | 451 | 362 |
| android.config | D | 03-May-2024 | 13.9 KiB | 408 | 325 |
| ap.c | D | 03-May-2024 | 25.2 KiB | 972 | 771 |
| ap.h | D | 03-May-2024 | 2.2 KiB | 50 | 38 |
| bgscan.c | D | 03-May-2024 | 2.7 KiB | 118 | 90 |
| bgscan.h | D | 03-May-2024 | 1.8 KiB | 73 | 50 |
| bgscan_learn.c | D | 03-May-2024 | 13.9 KiB | 605 | 471 |
| bgscan_simple.c | D | 03-May-2024 | 8.2 KiB | 284 | 193 |
| blacklist.c | D | 03-May-2024 | 3.1 KiB | 128 | 72 |
| blacklist.h | D | 03-May-2024 | 660 | 25 | 13 |
| bss.c | D | 03-May-2024 | 16 KiB | 682 | 525 |
| bss.h | D | 03-May-2024 | 4.1 KiB | 120 | 80 |
| config.c | D | 03-May-2024 | 64.1 KiB | 2,690 | 2,072 |
| config.h | D | 03-May-2024 | 18.5 KiB | 571 | 134 |
| config_file.c | D | 03-May-2024 | 19.1 KiB | 788 | 644 |
| config_none.c | D | 03-May-2024 | 1.2 KiB | 52 | 23 |
| config_ssid.h | D | 03-May-2024 | 13 KiB | 476 | 89 |
| config_winreg.c | D | 03-May-2024 | 23.5 KiB | 1,018 | 812 |
| ctrl_iface.c | D | 03-May-2024 | 100.6 KiB | 4,218 | 3,587 |
| ctrl_iface.h | D | 03-May-2024 | 5.7 KiB | 169 | 49 |
| ctrl_iface_named_pipe.c | D | 03-May-2024 | 19.7 KiB | 830 | 642 |
| ctrl_iface_udp.c | D | 03-May-2024 | 12.8 KiB | 556 | 426 |
| ctrl_iface_unix.c | D | 03-May-2024 | 18.4 KiB | 758 | 631 |
| defconfig | D | 03-May-2024 | 17.4 KiB | 480 | 391 |
| driver_i.h | D | 03-May-2024 | 17.7 KiB | 680 | 596 |
| eap_register.c | D | 03-May-2024 | 4.6 KiB | 240 | 178 |
| eap_testing.txt | D | 03-May-2024 | 14.4 KiB | 393 | 363 |
| eapol_test.c | D | 03-May-2024 | 32.5 KiB | 1,278 | 1,062 |
| events.c | D | 03-May-2024 | 72.6 KiB | 2,678 | 2,184 |
| gas_query.c | D | 03-May-2024 | 12.3 KiB | 476 | 371 |
| gas_query.h | D | 03-May-2024 | 1.3 KiB | 56 | 35 |
| ibss_rsn.c | D | 03-May-2024 | 15.3 KiB | 657 | 492 |
| ibss_rsn.h | D | 03-May-2024 | 1 KiB | 45 | 27 |
| interworking.c | D | 03-May-2024 | 26.2 KiB | 1,133 | 935 |
| interworking.h | D | 03-May-2024 | 839 | 26 | 14 |
| main.c | D | 03-May-2024 | 6.9 KiB | 285 | 246 |
| main_none.c | D | 03-May-2024 | 838 | 41 | 22 |
| main_symbian.cpp | D | 03-May-2024 | 851 | 43 | 24 |
| main_winmain.c | D | 03-May-2024 | 1.7 KiB | 79 | 55 |
| main_winsvc.c | D | 03-May-2024 | 11.1 KiB | 459 | 352 |
| nmake.mak | D | 03-May-2024 | 6.6 KiB | 241 | 200 |
| notify.c | D | 03-May-2024 | 14.3 KiB | 609 | 413 |
| notify.h | D | 03-May-2024 | 5.3 KiB | 126 | 109 |
| offchannel.c | D | 03-May-2024 | 9.3 KiB | 309 | 235 |
| offchannel.h | D | 03-May-2024 | 1.2 KiB | 34 | 22 |
| p2p_supplicant.c | D | 03-May-2024 | 123.2 KiB | 4,518 | 3,556 |
| p2p_supplicant.h | D | 03-May-2024 | 6.7 KiB | 140 | 128 |
| preauth_test.c | D | 03-May-2024 | 8.6 KiB | 371 | 277 |
| scan.c | D | 03-May-2024 | 32.4 KiB | 1,298 | 971 |
| scan.h | D | 03-May-2024 | 1.4 KiB | 37 | 26 |
| sme.c | D | 03-May-2024 | 22.1 KiB | 765 | 615 |
| sme.h | D | 03-May-2024 | 2.7 KiB | 101 | 75 |
| todo.txt | D | 03-May-2024 | 5 KiB | 86 | 85 |
| win_if_list.c | D | 03-May-2024 | 3.7 KiB | 174 | 128 |
| wpa_cli.c | D | 03-May-2024 | 90.3 KiB | 3,833 | 3,194 |
| wpa_passphrase.c | D | 03-May-2024 | 1.3 KiB | 68 | 49 |
| wpa_priv.c | D | 03-May-2024 | 23.2 KiB | 1,035 | 835 |
| wpa_supplicant.c | D | 03-May-2024 | 88.3 KiB | 3,143 | 2,295 |
| wpa_supplicant.conf | D | 03-May-2024 | 34.9 KiB | 922 | 244 |
| wpa_supplicant_conf.mk | D | 03-May-2024 | 1.3 KiB | 35 | 17 |
| wpa_supplicant_conf.sh | D | 03-May-2024 | 458 | 17 | 6 |
| wpa_supplicant_i.h | D | 03-May-2024 | 18.2 KiB | 638 | 380 |
| wpa_supplicant_template.conf | D | 03-May-2024 | 132 | 7 | 5 |
| wpas_glue.c | D | 03-May-2024 | 21.9 KiB | 853 | 644 |
| wpas_glue.h | D | 03-May-2024 | 765 | 26 | 12 |
| wps_supplicant.c | D | 03-May-2024 | 47.2 KiB | 1,736 | 1,445 |
| wps_supplicant.h | D | 03-May-2024 | 3.5 KiB | 120 | 93 |
README
1WPA Supplicant
2==============
3
4Copyright (c) 2003-2012, 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 WPA/WPA2 configuration with the generic
119 Linux wireless extensions (WE-18 or newer). Even though there are
120 number of driver specific interface included in wpa_supplicant, please
121 note that Linux drivers are moving to use generic wireless extensions
122 and driver_wext (-Dwext on wpa_supplicant command line) should be the
123 default option to start with before falling back to driver specific
124 interface.
125
126 In theory, any driver that supports Linux wireless extensions can be
127 used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in
128 configuration file.
129
130 Wired Ethernet drivers (with ap_scan=0)
131
132 BSD net80211 layer (e.g., Atheros driver)
133 At the moment, this is for FreeBSD 6-CURRENT branch and NetBSD-current.
134
135 Windows NDIS
136 The current Windows port requires WinPcap (http://winpcap.polito.it/).
137 See README-Windows.txt for more information.
138
139wpa_supplicant was designed to be portable for different drivers and
140operating systems. Hopefully, support for more wlan cards and OSes will be
141added in the future. See developer's documentation
142(http://hostap.epitest.fi/wpa_supplicant/devel/) for more information about the
143design of wpa_supplicant and porting to other drivers. One main goal
144is to add full WPA/WPA2 support to Linux wireless extensions to allow
145new drivers to be supported without having to implement new
146driver-specific interface code in wpa_supplicant.
147
148Optional libraries for layer2 packet processing:
149- libpcap (tested with 0.7.2, most relatively recent versions assumed to work,
150 this is likely to be available with most distributions,
151 http://tcpdump.org/)
152- libdnet (tested with v1.4, most versions assumed to work,
153 http://libdnet.sourceforge.net/)
154
155These libraries are _not_ used in the default Linux build. Instead,
156internal Linux specific implementation is used. libpcap/libdnet are
157more portable and they can be used by adding CONFIG_L2_PACKET=pcap into
158.config. They may also be selected automatically for other operating
159systems. In case of Windows builds, WinPcap is used by default
160(CONFIG_L2_PACKET=winpcap).
161
162
163Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS:
164- OpenSSL (tested with 0.9.7c and 0.9.7d, and 0.9.8 versions; assumed to
165 work with most relatively recent versions; this is likely to be
166 available with most distributions, http://www.openssl.org/)
167- GnuTLS
168- internal TLSv1 implementation
169
170TLS options for EAP-FAST:
171- OpenSSL 0.9.8d _with_ openssl-0.9.8d-tls-extensions.patch applied
172 (i.e., the default OpenSSL package does not include support for
173 extensions needed for EAP-FAST)
174- internal TLSv1 implementation
175
176One of these libraries is needed when EAP-TLS, EAP-PEAP, EAP-TTLS, or
177EAP-FAST support is enabled. WPA-PSK mode does not require this or EAPOL/EAP
178implementation. A configuration file, .config, for compilation is
179needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5,
180EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so
181they should only be enabled if testing the EAPOL/EAP state
182machines. However, there can be used as inner authentication
183algorithms with EAP-PEAP and EAP-TTLS.
184
185See Building and installing section below for more detailed
186information about the wpa_supplicant build time configuration.
187
188
189
190WPA
191---
192
193The original security mechanism of IEEE 802.11 standard was not
194designed to be strong and has proven to be insufficient for most
195networks that require some kind of security. Task group I (Security)
196of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked
197to address the flaws of the base standard and has in practice
198completed its work in May 2004. The IEEE 802.11i amendment to the IEEE
199802.11 standard was approved in June 2004 and published in July 2004.
200
201Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the
202IEEE 802.11i work (draft 3.0) to define a subset of the security
203enhancements that can be implemented with existing wlan hardware. This
204is called Wi-Fi Protected Access<TM> (WPA). This has now become a
205mandatory component of interoperability testing and certification done
206by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web
207site (http://www.wi-fi.org/OpenSection/protected_access.asp).
208
209IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm
210for protecting wireless networks. WEP uses RC4 with 40-bit keys,
21124-bit initialization vector (IV), and CRC32 to protect against packet
212forgery. All these choices have proven to be insufficient: key space is
213too small against current attacks, RC4 key scheduling is insufficient
214(beginning of the pseudorandom stream should be skipped), IV space is
215too small and IV reuse makes attacks easier, there is no replay
216protection, and non-keyed authentication does not protect against bit
217flipping packet data.
218
219WPA is an intermediate solution for the security issues. It uses
220Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a
221compromise on strong security and possibility to use existing
222hardware. It still uses RC4 for the encryption like WEP, but with
223per-packet RC4 keys. In addition, it implements replay protection,
224keyed packet authentication mechanism (Michael MIC).
225
226Keys can be managed using two different mechanisms. WPA can either use
227an external authentication server (e.g., RADIUS) and EAP just like
228IEEE 802.1X is using or pre-shared keys without need for additional
229servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",
230respectively. Both mechanisms will generate a master session key for
231the Authenticator (AP) and Supplicant (client station).
232
233WPA implements a new key handshake (4-Way Handshake and Group Key
234Handshake) for generating and exchanging data encryption keys between
235the Authenticator and Supplicant. This handshake is also used to
236verify that both Authenticator and Supplicant know the master session
237key. These handshakes are identical regardless of the selected key
238management mechanism (only the method for generating master session
239key changes).
240
241
242
243IEEE 802.11i / WPA2
244-------------------
245
246The design for parts of IEEE 802.11i that were not included in WPA has
247finished (May 2004) and this amendment to IEEE 802.11 was approved in
248June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new
249version of WPA called WPA2. This includes, e.g., support for more
250robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
251to replace TKIP and optimizations for handoff (reduced number of
252messages in initial key handshake, pre-authentication, and PMKSA caching).
253
254
255
256wpa_supplicant
257--------------
258
259wpa_supplicant is an implementation of the WPA Supplicant component,
260i.e., the part that runs in the client stations. It implements WPA key
261negotiation with a WPA Authenticator and EAP authentication with
262Authentication Server. In addition, it controls the roaming and IEEE
263802.11 authentication/association of the wlan driver.
264
265wpa_supplicant is designed to be a "daemon" program that runs in the
266background and acts as the backend component controlling the wireless
267connection. wpa_supplicant supports separate frontend programs and an
268example text-based frontend, wpa_cli, is included with wpa_supplicant.
269
270Following steps are used when associating with an AP using WPA:
271
272- wpa_supplicant requests the kernel driver to scan neighboring BSSes
273- wpa_supplicant selects a BSS based on its configuration
274- wpa_supplicant requests the kernel driver to associate with the chosen
275 BSS
276- If WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP
277 authentication with the authentication server (proxied by the
278 Authenticator in the AP)
279- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant
280- If WPA-PSK: wpa_supplicant uses PSK as the master session key
281- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake
282 with the Authenticator (AP)
283- wpa_supplicant configures encryption keys for unicast and broadcast
284- normal data packets can be transmitted and received
285
286
287
288Building and installing
289-----------------------
290
291In order to be able to build wpa_supplicant, you will first need to
292select which parts of it will be included. This is done by creating a
293build time configuration file, .config, in the wpa_supplicant root
294directory. Configuration options are text lines using following
295format: CONFIG_<option>=y. Lines starting with # are considered
296comments and are ignored. See defconfig file for an example configuration
297and a list of available options and additional notes.
298
299The build time configuration can be used to select only the needed
300features and limit the binary size and requirements for external
301libraries. The main configuration parts are the selection of which
302driver interfaces (e.g., nl80211, wext, ..) and which authentication
303methods (e.g., EAP-TLS, EAP-PEAP, ..) are included.
304
305Following build time configuration options are used to control IEEE
306802.1X/EAPOL and EAP state machines and all EAP methods. Including
307TLS, PEAP, or TTLS will require linking wpa_supplicant with OpenSSL
308library for TLS implementation. Alternatively, GnuTLS or the internal
309TLSv1 implementation can be used for TLS functionaly.
310
311CONFIG_IEEE8021X_EAPOL=y
312CONFIG_EAP_MD5=y
313CONFIG_EAP_MSCHAPV2=y
314CONFIG_EAP_TLS=y
315CONFIG_EAP_PEAP=y
316CONFIG_EAP_TTLS=y
317CONFIG_EAP_GTC=y
318CONFIG_EAP_OTP=y
319CONFIG_EAP_SIM=y
320CONFIG_EAP_AKA=y
321CONFIG_EAP_PSK=y
322CONFIG_EAP_SAKE=y
323CONFIG_EAP_GPSK=y
324CONFIG_EAP_PAX=y
325CONFIG_EAP_LEAP=y
326CONFIG_EAP_IKEV2=y
327
328Following option can be used to include GSM SIM/USIM interface for GSM/UMTS
329authentication algorithm (for EAP-SIM/EAP-AKA). This requires pcsc-lite
330(http://www.linuxnet.com/) for smart card access.
331
332CONFIG_PCSC=y
333
334Following options can be added to .config to select which driver
335interfaces are included.
336
337CONFIG_DRIVER_NL80211=y
338CONFIG_DRIVER_WEXT=y
339CONFIG_DRIVER_BSD=y
340CONFIG_DRIVER_NDIS=y
341
342Following example includes some more features and driver interfaces that
343are included in the wpa_supplicant package:
344
345CONFIG_DRIVER_NL80211=y
346CONFIG_DRIVER_WEXT=y
347CONFIG_DRIVER_BSD=y
348CONFIG_DRIVER_NDIS=y
349CONFIG_IEEE8021X_EAPOL=y
350CONFIG_EAP_MD5=y
351CONFIG_EAP_MSCHAPV2=y
352CONFIG_EAP_TLS=y
353CONFIG_EAP_PEAP=y
354CONFIG_EAP_TTLS=y
355CONFIG_EAP_GTC=y
356CONFIG_EAP_OTP=y
357CONFIG_EAP_SIM=y
358CONFIG_EAP_AKA=y
359CONFIG_EAP_PSK=y
360CONFIG_EAP_SAKE=y
361CONFIG_EAP_GPSK=y
362CONFIG_EAP_PAX=y
363CONFIG_EAP_LEAP=y
364CONFIG_EAP_IKEV2=y
365CONFIG_PCSC=y
366
367EAP-PEAP and EAP-TTLS will automatically include configured EAP
368methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection.
369
370
371After you have created a configuration file, you can build
372wpa_supplicant and wpa_cli with 'make' command. You may then install
373the binaries to a suitable system directory, e.g., /usr/local/bin.
374
375Example commands:
376
377# build wpa_supplicant and wpa_cli
378make
379# install binaries (this may need root privileges)
380cp wpa_cli wpa_supplicant /usr/local/bin
381
382
383You will need to make a configuration file, e.g.,
384/etc/wpa_supplicant.conf, with network configuration for the networks
385you are going to use. Configuration file section below includes
386explanation fo the configuration file format and includes various
387examples. Once the configuration is ready, you can test whether the
388configuration work by first running wpa_supplicant with following
389command to start it on foreground with debugging enabled:
390
391wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
392
393Assuming everything goes fine, you can start using following command
394to start wpa_supplicant on background without debugging:
395
396wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
397
398Please note that if you included more than one driver interface in the
399build time configuration (.config), you may need to specify which
400interface to use by including -D<driver name> option on the command
401line. See following section for more details on command line options
402for wpa_supplicant.
403
404
405
406Command line options
407--------------------
408
409usage:
410 wpa_supplicant [-BddfhKLqqtuvwW] [-P<pid file>] [-g<global ctrl>] \
411 -i<ifname> -c<config file> [-C<ctrl>] [-D<driver>] [-p<driver_param>] \
412 [-b<br_ifname> [-N -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] \
413 [-p<driver_param>] [-b<br_ifname>] ...]
414
415options:
416 -b = optional bridge interface name
417 -B = run daemon in the background
418 -c = Configuration file
419 -C = ctrl_interface parameter (only used if -c is not)
420 -i = interface name
421 -d = increase debugging verbosity (-dd even more)
422 -D = driver name (can be multiple drivers: nl80211,wext)
423 -f = Log output to default log location (normally /tmp)
424 -g = global ctrl_interface
425 -K = include keys (passwords, etc.) in debug output
426 -t = include timestamp in debug messages
427 -h = show this help text
428 -L = show license (GPL and BSD)
429 -p = driver parameters
430 -P = PID file
431 -q = decrease debugging verbosity (-qq even less)
432 -u = enable DBus control interface
433 -v = show version
434 -w = wait for interface to be added, if needed
435 -W = wait for a control interface monitor before starting
436 -N = start describing new interface
437
438drivers:
439 wext = Linux wireless extensions (generic)
440 wired = wpa_supplicant wired Ethernet driver
441 roboswitch = wpa_supplicant Broadcom switch driver
442 bsd = BSD 802.11 support (Atheros, etc.)
443 ndis = Windows NDIS driver
444
445In most common cases, wpa_supplicant is started with
446
447wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0
448
449This makes the process fork into background.
450
451The easiest way to debug problems, and to get debug log for bug
452reports, is to start wpa_supplicant on foreground with debugging
453enabled:
454
455wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
456
457If the specific driver wrapper is not known beforehand, it is possible
458to specify multiple comma separated driver wrappers on the command
459line. wpa_supplicant will use the first driver wrapper that is able to
460initialize the interface.
461
462wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0
463
464
465wpa_supplicant can control multiple interfaces (radios) either by
466running one process for each interface separately or by running just
467one process and list of options at command line. Each interface is
468separated with -N argument. As an example, following command would
469start wpa_supplicant for two interfaces:
470
471wpa_supplicant \
472 -c wpa1.conf -i wlan0 -D nl80211 -N \
473 -c wpa2.conf -i wlan1 -D wext
474
475
476If the interface is added in a Linux bridge (e.g., br0), the bridge
477interface needs to be configured to wpa_supplicant in addition to the
478main interface:
479
480wpa_supplicant -cw.conf -Dwext -iwlan0 -bbr0
481
482
483Configuration file
484------------------
485
486wpa_supplicant is configured using a text file that lists all accepted
487networks and security policies, including pre-shared keys. See
488example configuration file, wpa_supplicant.conf, for detailed
489information about the configuration format and supported fields.
490
491Changes to configuration file can be reloaded be sending SIGHUP signal
492to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly,
493reloading can be triggered with 'wpa_cli reconfigure' command.
494
495Configuration file can include one or more network blocks, e.g., one
496for each used SSID. wpa_supplicant will automatically select the best
497betwork based on the order of network blocks in the configuration
498file, network security level (WPA/WPA2 is preferred), and signal
499strength.
500
501Example configuration files for some common configurations:
502
5031) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work
504 network
505
506# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
507ctrl_interface=/var/run/wpa_supplicant
508ctrl_interface_group=wheel
509#
510# home network; allow all valid ciphers
511network={
512 ssid="home"
513 scan_ssid=1
514 key_mgmt=WPA-PSK
515 psk="very secret passphrase"
516}
517#
518# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
519network={
520 ssid="work"
521 scan_ssid=1
522 key_mgmt=WPA-EAP
523 pairwise=CCMP TKIP
524 group=CCMP TKIP
525 eap=TLS
526 identity="user@example.com"
527 ca_cert="/etc/cert/ca.pem"
528 client_cert="/etc/cert/user.pem"
529 private_key="/etc/cert/user.prv"
530 private_key_passwd="password"
531}
532
533
5342) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
535 (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series)
536
537ctrl_interface=/var/run/wpa_supplicant
538ctrl_interface_group=wheel
539network={
540 ssid="example"
541 scan_ssid=1
542 key_mgmt=WPA-EAP
543 eap=PEAP
544 identity="user@example.com"
545 password="foobar"
546 ca_cert="/etc/cert/ca.pem"
547 phase1="peaplabel=0"
548 phase2="auth=MSCHAPV2"
549}
550
551
5523) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
553 unencrypted use. Real identity is sent only within an encrypted TLS tunnel.
554
555ctrl_interface=/var/run/wpa_supplicant
556ctrl_interface_group=wheel
557network={
558 ssid="example"
559 scan_ssid=1
560 key_mgmt=WPA-EAP
561 eap=TTLS
562 identity="user@example.com"
563 anonymous_identity="anonymous@example.com"
564 password="foobar"
565 ca_cert="/etc/cert/ca.pem"
566 phase2="auth=MD5"
567}
568
569
5704) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and
571 broadcast); use EAP-TLS for authentication
572
573ctrl_interface=/var/run/wpa_supplicant
574ctrl_interface_group=wheel
575network={
576 ssid="1x-test"
577 scan_ssid=1
578 key_mgmt=IEEE8021X
579 eap=TLS
580 identity="user@example.com"
581 ca_cert="/etc/cert/ca.pem"
582 client_cert="/etc/cert/user.pem"
583 private_key="/etc/cert/user.prv"
584 private_key_passwd="password"
585 eapol_flags=3
586}
587
588
5895) Catch all example that allows more or less all configuration modes. The
590 configuration options are used based on what security policy is used in the
591 selected SSID. This is mostly for testing and is not recommended for normal
592 use.
593
594ctrl_interface=/var/run/wpa_supplicant
595ctrl_interface_group=wheel
596network={
597 ssid="example"
598 scan_ssid=1
599 key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
600 pairwise=CCMP TKIP
601 group=CCMP TKIP WEP104 WEP40
602 psk="very secret passphrase"
603 eap=TTLS PEAP TLS
604 identity="user@example.com"
605 password="foobar"
606 ca_cert="/etc/cert/ca.pem"
607 client_cert="/etc/cert/user.pem"
608 private_key="/etc/cert/user.prv"
609 private_key_passwd="password"
610 phase1="peaplabel=0"
611 ca_cert2="/etc/cert/ca2.pem"
612 client_cert2="/etc/cer/user.pem"
613 private_key2="/etc/cer/user.prv"
614 private_key2_passwd="password"
615}
616
617
6186) Authentication for wired Ethernet. This can be used with 'wired' or
619 'roboswitch' interface (-Dwired or -Droboswitch on command line).
620
621ctrl_interface=/var/run/wpa_supplicant
622ctrl_interface_group=wheel
623ap_scan=0
624network={
625 key_mgmt=IEEE8021X
626 eap=MD5
627 identity="user"
628 password="password"
629 eapol_flags=0
630}
631
632
633
634Certificates
635------------
636
637Some EAP authentication methods require use of certificates. EAP-TLS
638uses both server side and client certificates whereas EAP-PEAP and
639EAP-TTLS only require the server side certificate. When client
640certificate is used, a matching private key file has to also be
641included in configuration. If the private key uses a passphrase, this
642has to be configured in wpa_supplicant.conf ("private_key_passwd").
643
644wpa_supplicant supports X.509 certificates in PEM and DER
645formats. User certificate and private key can be included in the same
646file.
647
648If the user certificate and private key is received in PKCS#12/PFX
649format, they need to be converted to suitable PEM/DER format for
650wpa_supplicant. This can be done, e.g., with following commands:
651
652# convert client certificate and private key to PEM format
653openssl pkcs12 -in example.pfx -out user.pem -clcerts
654# convert CA certificate (if included in PFX file) to PEM format
655openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
656
657
658
659wpa_cli
660-------
661
662wpa_cli is a text-based frontend program for interacting with
663wpa_supplicant. It is used to query current status, change
664configuration, trigger events, and request interactive user input.
665
666wpa_cli can show the current authentication status, selected security
667mode, dot11 and dot1x MIBs, etc. In addition, it can configure some
668variables like EAPOL state machine parameters and trigger events like
669reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user
670interface to request authentication information, like username and
671password, if these are not included in the configuration. This can be
672used to implement, e.g., one-time-passwords or generic token card
673authentication where the authentication is based on a
674challenge-response that uses an external device for generating the
675response.
676
677The control interface of wpa_supplicant can be configured to allow
678non-root user access (ctrl_interface_group in the configuration
679file). This makes it possible to run wpa_cli with a normal user
680account.
681
682wpa_cli supports two modes: interactive and command line. Both modes
683share the same command set and the main difference is in interactive
684mode providing access to unsolicited messages (event messages,
685username/password requests).
686
687Interactive mode is started when wpa_cli is executed without including
688the command as a command line parameter. Commands are then entered on
689the wpa_cli prompt. In command line mode, the same commands are
690entered as command line arguments for wpa_cli.
691
692
693Interactive authentication parameters request
694
695When wpa_supplicant need authentication parameters, like username and
696password, which are not present in the configuration file, it sends a
697request message to all attached frontend programs, e.g., wpa_cli in
698interactive mode. wpa_cli shows these requests with
699"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or
700OTP (one-time-password). <id> is a unique identifier for the current
701network. <text> is description of the request. In case of OTP request,
702it includes the challenge from the authentication server.
703
704The reply to these requests can be given with 'identity', 'password',
705and 'otp' commands. <id> needs to be copied from the the matching
706request. 'password' and 'otp' commands can be used regardless of
707whether the request was for PASSWORD or OTP. The main difference
708between these two commands is that values given with 'password' are
709remembered as long as wpa_supplicant is running whereas values given
710with 'otp' are used only once and then forgotten, i.e., wpa_supplicant
711will ask frontend for a new value for every use. This can be used to
712implement one-time-password lists and generic token card -based
713authentication.
714
715Example request for password and a matching reply:
716
717CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
718> password 1 mysecretpassword
719
720Example request for generic token card challenge-response:
721
722CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
723> otp 2 9876
724
725
726wpa_cli commands
727
728 status = get current WPA/EAPOL/EAP status
729 mib = get MIB variables (dot1x, dot11)
730 help = show this usage help
731 interface [ifname] = show interfaces/select interface
732 level <debug level> = change debug level
733 license = show full wpa_cli license
734 logoff = IEEE 802.1X EAPOL state machine logoff
735 logon = IEEE 802.1X EAPOL state machine logon
736 set = set variables (shows list of variables when run without arguments)
737 pmksa = show PMKSA cache
738 reassociate = force reassociation
739 reconfigure = force wpa_supplicant to re-read its configuration file
740 preauthenticate <BSSID> = force preauthentication
741 identity <network id> <identity> = configure identity for an SSID
742 password <network id> <password> = configure password for an SSID
743 pin <network id> <pin> = configure pin for an SSID
744 otp <network id> <password> = configure one-time-password for an SSID
745 passphrase <network id> <passphrase> = configure private key passphrase
746 for an SSID
747 bssid <network id> <BSSID> = set preferred BSSID for an SSID
748 list_networks = list configured networks
749 select_network <network id> = select a network (disable others)
750 enable_network <network id> = enable a network
751 disable_network <network id> = disable a network
752 add_network = add a network
753 remove_network <network id> = remove a network
754 set_network <network id> <variable> <value> = set network variables (shows
755 list of variables when run without arguments)
756 get_network <network id> <variable> = get network variables
757 save_config = save the current configuration
758 disconnect = disconnect and wait for reassociate command before connecting
759 scan = request new BSS scan
760 scan_results = get latest scan results
761 get_capability <eap/pairwise/group/key_mgmt/proto/auth_alg> = get capabilies
762 terminate = terminate wpa_supplicant
763 quit = exit wpa_cli
764
765
766wpa_cli command line options
767
768wpa_cli [-p<path to ctrl sockets>] [-i<ifname>] [-hvB] [-a<action file>] \
769 [-P<pid file>] [-g<global ctrl>] [command..]
770 -h = help (show this usage text)
771 -v = shown version information
772 -a = run in daemon mode executing the action file based on events from
773 wpa_supplicant
774 -B = run a daemon in the background
775 default path: /var/run/wpa_supplicant
776 default interface: first interface found in socket path
777
778
779Using wpa_cli to run external program on connect/disconnect
780-----------------------------------------------------------
781
782wpa_cli can used to run external programs whenever wpa_supplicant
783connects or disconnects from a network. This can be used, e.g., to
784update network configuration and/or trigget DHCP client to update IP
785addresses, etc.
786
787One wpa_cli process in "action" mode needs to be started for each
788interface. For example, the following command starts wpa_cli for the
789default ingterface (-i can be used to select the interface in case of
790more than one interface being used at the same time):
791
792wpa_cli -a/sbin/wpa_action.sh -B
793
794The action file (-a option, /sbin/wpa_action.sh in this example) will
795be executed whenever wpa_supplicant completes authentication (connect
796event) or detects disconnection). The action script will be called
797with two command line arguments: interface name and event (CONNECTED
798or DISCONNECTED). If the action script needs to get more information
799about the current network, it can use 'wpa_cli status' to query
800wpa_supplicant for more information.
801
802Following example can be used as a simple template for an action
803script:
804
805#!/bin/sh
806
807IFNAME=$1
808CMD=$2
809
810if [ "$CMD" = "CONNECTED" ]; then
811 SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=`
812 # configure network, signal DHCP client, etc.
813fi
814
815if [ "$CMD" = "DISCONNECTED" ]; then
816 # remove network configuration, if needed
817 SSID=
818fi
819
820
821
822Integrating with pcmcia-cs/cardmgr scripts
823------------------------------------------
824
825wpa_supplicant needs to be running when using a wireless network with
826WPA. It can be started either from system startup scripts or from
827pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be
828completed before data frames can be exchanged, so wpa_supplicant
829should be started before DHCP client.
830
831For example, following small changes to pcmcia-cs scripts can be used
832to enable WPA support:
833
834Add MODE="Managed" and WPA="y" to the network scheme in
835/etc/pcmcia/wireless.opts.
836
837Add the following block to the end of 'start' action handler in
838/etc/pcmcia/wireless:
839
840 if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
841 /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf \
842 -i$DEVICE
843 fi
844
845Add the following block to the end of 'stop' action handler (may need
846to be separated from other actions) in /etc/pcmcia/wireless:
847
848 if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
849 killall wpa_supplicant
850 fi
851
852This will make cardmgr start wpa_supplicant when the card is plugged
853in.
854
855
856
857Dynamic interface add and operation without configuration files
858---------------------------------------------------------------
859
860wpa_supplicant can be started without any configuration files or
861network interfaces. When used in this way, a global (i.e., per
862wpa_supplicant process) control interface is used to add and remove
863network interfaces. Each network interface can then be configured
864through a per-network interface control interface. For example,
865following commands show how to start wpa_supplicant without any
866network interfaces and then add a network interface and configure a
867network (SSID):
868
869# Start wpa_supplicant in the background
870wpa_supplicant -g/var/run/wpa_supplicant-global -B
871
872# Add a new interface (wlan0, no configuration file, driver=wext, and
873# enable control interface)
874wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \
875 "" wext /var/run/wpa_supplicant
876
877# Configure a network using the newly added network interface:
878wpa_cli -iwlan0 add_network
879wpa_cli -iwlan0 set_network 0 ssid '"test"'
880wpa_cli -iwlan0 set_network 0 key_mgmt WPA-PSK
881wpa_cli -iwlan0 set_network 0 psk '"12345678"'
882wpa_cli -iwlan0 set_network 0 pairwise TKIP
883wpa_cli -iwlan0 set_network 0 group TKIP
884wpa_cli -iwlan0 set_network 0 proto WPA
885wpa_cli -iwlan0 enable_network 0
886
887# At this point, the new network interface should start trying to associate
888# with the WPA-PSK network using SSID test.
889
890# Remove network interface
891wpa_cli -g/var/run/wpa_supplicant-global interface_remove wlan0
892
893
894Privilege separation
895--------------------
896
897To minimize the size of code that needs to be run with root privileges
898(e.g., to control wireless interface operation), wpa_supplicant
899supports optional privilege separation. If enabled, this separates the
900privileged operations into a separate process (wpa_priv) while leaving
901rest of the code (e.g., EAP authentication and WPA handshakes) into an
902unprivileged process (wpa_supplicant) that can be run as non-root
903user. Privilege separation restricts the effects of potential software
904errors by containing the majority of the code in an unprivileged
905process to avoid full system compromise.
906
907Privilege separation is not enabled by default and it can be enabled
908by adding CONFIG_PRIVSEP=y to the build configuration (.config). When
909enabled, the privileged operations (driver wrapper and l2_packet) are
910linked into a separate daemon program, wpa_priv. The unprivileged
911program, wpa_supplicant, will be built with a special driver/l2_packet
912wrappers that communicate with the privileged wpa_priv process to
913perform the needed operations. wpa_priv can control what privileged
914are allowed.
915
916wpa_priv needs to be run with network admin privileges (usually, root
917user). It opens a UNIX domain socket for each interface that is
918included on the command line; any other interface will be off limits
919for wpa_supplicant in this kind of configuration. After this,
920wpa_supplicant can be run as a non-root user (e.g., all standard users
921on a laptop or as a special non-privileged user account created just
922for this purpose to limit access to user files even further).
923
924
925Example configuration:
926- create user group for users that are allowed to use wpa_supplicant
927 ('wpapriv' in this example) and assign users that should be able to
928 use wpa_supplicant into that group
929- create /var/run/wpa_priv directory for UNIX domain sockets and control
930 user access by setting it accessible only for the wpapriv group:
931 mkdir /var/run/wpa_priv
932 chown root:wpapriv /var/run/wpa_priv
933 chmod 0750 /var/run/wpa_priv
934- start wpa_priv as root (e.g., from system startup scripts) with the
935 enabled interfaces configured on the command line:
936 wpa_priv -B -P /var/run/wpa_priv.pid wext:ath0
937- run wpa_supplicant as non-root with a user that is in wpapriv group:
938 wpa_supplicant -i ath0 -c wpa_supplicant.conf
939
940wpa_priv does not use the network interface before wpa_supplicant is
941started, so it is fine to include network interfaces that are not
942available at the time wpa_priv is started. As an alternative, wpa_priv
943can be started when an interface is added (hotplug/udev/etc. scripts).
944wpa_priv can control multiple interface with one process, but it is
945also possible to run multiple wpa_priv processes at the same time, if
946desired.
947
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
76The default behavior is to run a single full scan in the beginning and
77then scan only social channels. type=social will scan only social
78channels, i.e., it skips the initial full scan. type=progressive is
79like the default behavior, but it will scan through all the channels
80progressively one channel at the time in the Search state rounds. This
81will help in finding new groups or groups missed during the initial
82full scan.
83
84p2p_listen [timeout in seconds]
85
86Start Listen-only state (become discoverable without searching for
87other devices). Optional parameter can be used to specify the duration
88for the Listen operation in seconds. This command may not be of that
89much use during normal operations and is mainly designed for
90testing. It can also be used to keep the device discoverable without
91having to maintain a group.
92
93p2p_stop_find
94
95Stop ongoing P2P device discovery or other operation (connect, listen
96mode).
97
98p2p_flush
99
100Flush P2P peer table and state.
101
102Group Formation
103
104p2p_prov_disc <peer device address> <display|keypad|pbc> [join]
105
106Send P2P provision discovery request to the specified peer. The
107parameters for this command are the P2P device address of the peer and
108the desired configuration method. For example, "p2p_prov_disc
10902:01:02:03:04:05 display" would request the peer to display a PIN for
110us and "p2p_prov_disc 02:01:02:03:04:05 keypad" would request the peer
111to enter a PIN that we display.
112
113The optional "join" parameter can be used to indicate that this command
114is requesting an already running GO to prepare for a new client. This is
115mainly used with "display" to request it to display a PIN.
116
117p2p_connect <peer device address> <pbc|pin|PIN#> [display|keypad]
118 [persistent] [join|auth] [go_intent=<0..15>] [freq=<in MHz>]
119
120Start P2P group formation with a discovered P2P peer. This includes
121optional group owner negotiation, group interface setup, provisioning,
122and establishing data connection.
123
124The <pbc|pin|PIN#> parameter specifies the WPS provisioning
125method. "pbc" string starts pushbutton method, "pin" string start PIN
126method using an automatically generated PIN (which will be returned as
127the command return code), PIN# means that a pre-selected PIN can be
128used (e.g., 12345670). [display|keypad] is used with PIN method
129to specify which PIN is used (display=dynamically generated random PIN
130from local display, keypad=PIN entered from peer display). "persistent"
131parameter can be used to request a persistent group to be formed.
132
133"join" indicates that this is a command to join an existing group as a
134client. It skips the GO Negotiation part. This will send a Provision
135Discovery Request message to the target GO before associating for WPS
136provisioning.
137
138"auth" indicates that the WPS parameters are authorized for the peer
139device without actually starting GO Negotiation (i.e., the peer is
140expected to initiate GO Negotiation). This is mainly for testing
141purposes.
142
143"go_intent" can be used to override the default GO Intent for this GO
144Negotiation.
145
146"freq" can be used to set a forced operating channel (e.g., freq=2412
147to select 2.4 GHz channel 1).
148
149p2p_group_add [persistent|persistent=<network id>] [freq=<freq in MHz>]
150
151Set up a P2P group owner manually (i.e., without group owner
152negotiation with a specific peer). This is also known as autonomous
153GO. Optional persistent=<network id> can be used to specify restart of
154a persistent group. Optional freq=<freq in MHz> can be used to force
155the GO to be started on a specific frequency. Special freq=2 or freq=5
156options can be used to request the best 2.4 GHz or 5 GHz band channel
157to be selected automatically.
158
159p2p_reject <peer device address>
160
161Reject connection attempt from a peer (specified with a device
162address). This is a mechanism to reject a pending GO Negotiation with
163a peer and request to automatically block any further connection or
164discovery of the peer.
165
166p2p_group_remove <group interface>
167
168Terminate a P2P group. If a new virtual network interface was used for
169the group, it will also be removed. The network interface name of the
170group interface is used as a parameter for this command.
171
172p2p_cancel
173
174Cancel an ongoing P2P group formation related operation.
175
176Service Discovery
177
178p2p_serv_disc_req
179
180Schedule a P2P service discovery request. The parameters for this
181command are the device address of the peer device (or 00:00:00:00:00:00
182for wildcard query that is sent to every discovered P2P peer that
183supports service discovery) and P2P Service Query TLV(s) as hexdump. For
184example,
185
186p2p_serv_disc_req 00:00:00:00:00:00 02000001
187
188schedules a request for listing all available services of all service
189discovery protocols and requests this to be sent to all discovered
190peers (note: this can result in long response frames). The pending
191requests are sent during device discovery (see p2p_find).
192
193Only a single pending wildcard query is supported, but there can be
194multiple pending peer device specific queries (each will be sent in
195sequence whenever the peer is found).
196
197This command returns an identifier for the pending query (e.g.,
198"1f77628") that can be used to cancel the request. Directed requests
199will be automatically removed when the specified peer has replied to
200it.
201
202For UPnP, an alternative command format can be used to specify a
203single query TLV (i.e., a service discovery for a specific UPnP
204service):
205
206p2p_serv_disc_req 00:00:00:00:00:00 upnp <version hex> <ST: from M-SEARCH>
207
208For example:
209
210p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1
211
212Additional examples for queries:
213
214# list of all Bonjour services
215p2p_serv_disc_req 00:00:00:00:00:00 02000101
216
217# list of all UPnP services
218p2p_serv_disc_req 00:00:00:00:00:00 02000201
219
220# list of all WS-Discovery services
221p2p_serv_disc_req 00:00:00:00:00:00 02000301
222
223# list of all Bonjour and UPnP services
224p2p_serv_disc_req 00:00:00:00:00:00 0200010102000202
225
226# Apple File Sharing over TCP
227p2p_serv_disc_req 00:00:00:00:00:00 130001010b5f6166706f766572746370c00c000c01
228
229# Bonjour SSTH (supported service type hash)
230p2p_serv_disc_req 00:00:00:00:00:00 05000101000000
231
232# UPnP examples
233p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 ssdp:all
234p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 upnp:rootdevice
235p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:service:ContentDirectory:2
236p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 uuid:6859dede-8574-59ab-9332-123456789012
237p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1
238
239p2p_serv_disc_cancel_req <query identifier>
240
241Cancel a pending P2P service discovery request. This command takes a
242single parameter: identifier for the pending query (the value returned
243by p2p_serv_disc_req, e.g., "p2p_serv_disc_cancel_req 1f77628".
244
245p2p_serv_disc_resp
246
247Reply to a service discovery query. This command takes following
248parameters: frequency in MHz, destination address, dialog token,
249response TLV(s). The first three parameters are copied from the
250request event. For example, "p2p_serv_disc_resp 2437 02:40:61:c2:f3:b7
2511 0300000101". This command is used only if external program is used
252to process the request (see p2p_serv_disc_external).
253
254p2p_service_update
255
256Indicate that local services have changed. This is used to increment
257the P2P service indicator value so that peers know when previously
258cached information may have changed. This is only needed when external
259service discovery processing is enabled since the commands to
260pre-configure services for internal processing will increment the
261indicator automatically.
262
263p2p_serv_disc_external <0|1>
264
265Configure external processing of P2P service requests: 0 (default) =
266no external processing of requests (i.e., internal code will process
267each request based on pre-configured services), 1 = external
268processing of requests (external program is responsible for replying
269to service discovery requests with p2p_serv_disc_resp). Please note
270that there is quite strict limit on how quickly the response needs to
271be transmitted, so use of the internal processing is strongly
272recommended.
273
274p2p_service_add bonjour <query hexdump> <RDATA hexdump>
275
276Add a local Bonjour service for internal SD query processing.
277
278Examples:
279
280# AFP Over TCP (PTR)
281p2p_service_add bonjour 0b5f6166706f766572746370c00c000c01 074578616d706c65c027
282# AFP Over TCP (TXT) (RDATA=null)
283p2p_service_add bonjour 076578616d706c650b5f6166706f766572746370c00c001001 00
284
285# IP Printing over TCP (PTR) (RDATA=MyPrinter._ipp._tcp.local.)
286p2p_service_add bonjour 045f697070c00c000c01 094d795072696e746572c027
287# IP Printing over TCP (TXT) (RDATA=txtvers=1,pdl=application/postscript)
288p2p_service_add bonjour 096d797072696e746572045f697070c00c001001 09747874766572733d311a70646c3d6170706c69636174696f6e2f706f7374736372797074
289
290# Supported Service Type Hash (SSTH)
291p2p_service_add bonjour 000000 <32-byte bitfield as hexdump>
292(note: see P2P spec Annex E.4 for information on how to construct the bitfield)
293
294p2p_service_del bonjour <query hexdump>
295
296Remove a local Bonjour service from internal SD query processing.
297
298p2p_service_add upnp <version hex> <service>
299
300Add a local UPnP service for internal SD query processing.
301
302Examples:
303
304p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::upnp:rootdevice
305p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::upnp:rootdevice
306p2p_service_add upnp 10 uuid:1122de4e-8574-59ab-9322-333456789044::urn:schemas-upnp-org:service:ContentDirectory:2
307p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::urn:schemas-upnp-org:service:ContentDirectory:2
308p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::urn:schemas-upnp-org:device:InternetGatewayDevice:1
309
310p2p_service_del upnp <version hex> <service>
311
312Remove a local UPnP service from internal SD query processing.
313
314p2p_service_flush
315
316Remove all local services from internal SD query processing.
317
318Invitation
319
320p2p_invite [persistent=<network id>|group=<group ifname>] [peer=address]
321 [go_dev_addr=address]
322
323Invite a peer to join a group (e.g., group=wlan1) or to reinvoke a
324persistent group (e.g., persistent=4). If the peer device is the GO of
325the persisten group, the peer parameter is not needed. Otherwise it is
326used to specify which device to invite. go_dev_addr parameter can be
327used to override the GO device address for Invitation Request should
328it be not known for some reason (this should not be needed in most
329cases).
330
331Group Operations
332
333(These are used on the group interface.)
334
335wps_pin <any|address> <PIN>
336
337Start WPS PIN method. This allows a single WPS Enrollee to connect to
338the AP/GO. This is used on the GO when a P2P client joins an existing
339group. The second parameter is the address of the Enrollee or a string
340"any" to allow any station to use the entered PIN (which will restrict
341the PIN for one-time-use). PIN is the Enrollee PIN read either from a
342label or display on the P2P Client/WPS Enrollee.
343
344wps_pbc
345
346Start WPS PBC method (i.e., push the button). This allows a single WPS
347Enrollee to connect to the AP/GO. This is used on the GO when a P2P
348client joins an existing group.
349
350p2p_get_passphrase
351
352Get the passphrase for a group (only available when acting as a GO).
353
354p2p_presence_req [<duration> <interval>] [<duration> <interval>]
355
356Send a P2P Presence Request to the GO (this is only available when
357acting as a P2P client). If no duration/interval pairs are given, the
358request indicates that this client has no special needs for GO
359presence. the first parameter pair gives the preferred duration and
360interval values in microseconds. If the second pair is included, that
361indicates which value would be acceptable.
362
363Parameters
364
365p2p_ext_listen [<period> <interval>]
366
367Configure Extended Listen Timing. If the parameters are omitted, this
368feature is disabled. If the parameters are included, Listen State will
369be entered every interval msec for at least period msec. Both values
370have acceptable range of 1-65535 (with interval obviously having to be
371larger than or equal to duration). If the P2P module is not idle at
372the time the Extended Listen Timing timeout occurs, the Listen State
373operation will be skipped.
374
375The configured values will also be advertised to other P2P Devices. The
376received values are available in the p2p_peer command output:
377
378ext_listen_period=100 ext_listen_interval=5000
379
380p2p_set <field> <value>
381
382Change dynamic P2P parameters
383
384p2p_set discoverability <0/1>
385
386Disable/enable advertisement of client discoverability. This is
387enabled by default and this parameter is mainly used to allow testing
388of device discoverability.
389
390p2p_set managed <0/1>
391
392Disable/enable managed P2P Device operations. This is disabled by
393default.
394
395p2p_set listen_channel <1/6/11>
396
397Set P2P Listen channel. This is mainly meant for testing purposes and
398changing the Listen channel during normal operations can result in
399protocol failures.
400
401p2p_set ssid_postfix <postfix>
402
403Set postfix string to be added to the automatically generated P2P SSID
404(DIRECT-<two random characters>). For example, postfix of "-testing"
405could result in the SSID becoming DIRECT-ab-testing.
406
407set <field> <value>
408
409Set global configuration parameters which may also affect P2P
410operations. The format on these parameters is same as is used in
411wpa_supplicant.conf. Only the parameters listen here should be
412changed. Modifying other parameters may result in incorrect behavior
413since not all existing users of the parameters are updated.
414
415set uuid <UUID>
416
417Set WPS UUID (by default, this is generated based on the MAC address).
418
419set device_name <device name>
420
421Set WPS Device Name (also included in some P2P messages).
422
423set manufacturer <manufacturer>
424
425Set WPS Manufacturer.
426
427set model_name <model name>
428
429Set WPS Model Name.
430
431set model_number <model number>
432
433Set WPS Model Number.
434
435set serial_number <serial number>
436
437Set WPS Serial Number.
438
439set device_type <device type>
440
441Set WPS Device Type.
442
443set os_version <OS version>
444
445Set WPS OS Version.
446
447set config_methods <config methods>
448
449Set WPS Configuration Methods.
450
451set sec_device_type <device type>
452
453Add a new Secondary Device Type.
454
455set p2p_go_intent <GO intent>
456
457Set the default P2P GO Intent. Note: This value can be overridden in
458p2p_connect command and as such, there should be no need to change the
459default value here during normal operations.
460
461set p2p_ssid_postfix <P2P SSID postfix>
462
463Set P2P SSID postfix.
464
465set persistent_reconnect <0/1>
466
467Disable/enabled persistent reconnect for reinvocation of persistent
468groups. If enabled, invitations to reinvoke a persistent group will be
469accepted without separate authorization (e.g., user interaction).
470
471set country <two character country code>
472
473Set country code (this is included in some P2P messages).
474
475Status
476
477p2p_peers [discovered]
478
479List P2P Device Addresses of all the P2P peers we know. The optional
480"discovered" parameter filters out the peers that we have not fully
481discovered, i.e., which we have only seen in a received Probe Request
482frame.
483
484p2p_peer <P2P Device Address>
485
486Fetch information about a known P2P peer.
487
488Group Status
489
490(These are used on the group interface.)
491
492status
493
494Show status information (connection state, role, use encryption
495parameters, IP address, etc.).
496
497sta
498
499Show information about an associated station (when acting in AP/GO role).
500
501all_sta
502
503Lists the currently associated stations.
504
505Configuration data
506
507list_networks
508
509Lists the configured networks, including stored information for
510persistent groups. The identifier in this list is used with
511p2p_group_add and p2p_invite to indicate which persistent group is to
512be reinvoked.
513
514remove_network <network id>
515
516Remove a network entry from configuration.
517
518
519wpa_cli action script
520---------------------
521
522See examples/p2p-action.sh
523
524TODO: describe DHCP/DNS setup
525TODO: cross-connection
526
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
63CONFIG_WPS2=y
64
65If you want to enable WPS external registrar (ER) functionality, you
66will also need to add following line:
67
68CONFIG_WPS_ER=y
69
70
71WPS needs the Universally Unique IDentifier (UUID; see RFC 4122) for
72the device. This is configured in the runtime configuration for
73wpa_supplicant (if not set, UUID will be generated based on local MAC
74address):
75
76# example UUID for WPS
77uuid=12345678-9abc-def0-1234-56789abcdef0
78
79The network configuration blocks needed for WPS are added
80automatically based on control interface commands, so they do not need
81to be added explicitly in the configuration file.
82
83WPS registration will generate new network blocks for the acquired
84credentials. If these are to be stored for future use (after
85restarting wpa_supplicant), wpa_supplicant will need to be configured
86to allow configuration file updates:
87
88update_config=1
89
90
91
92External operations
93-------------------
94
95WPS requires either a device PIN code (usually, 8-digit number) or a
96pushbutton event (for PBC) to allow a new WPS Enrollee to join the
97network. wpa_supplicant uses the control interface as an input channel
98for these events.
99
100The PIN value used in the commands must be processed by an UI to
101remove non-digit characters and potentially, to verify the checksum
102digit. "wpa_cli wps_check_pin <PIN>" can be used to do such processing.
103It returns FAIL if the PIN is invalid, or FAIL-CHECKSUM if the checksum
104digit is incorrect, or the processed PIN (non-digit characters removed)
105if the PIN is valid.
106
107If the client device has a display, a random PIN has to be generated
108for each WPS registration session. wpa_supplicant can do this with a
109control interface request, e.g., by calling wpa_cli:
110
111wpa_cli wps_pin any
112
113This will return the generated 8-digit PIN which will then need to be
114entered at the Registrar to complete WPS registration. At that point,
115the client will be enrolled with credentials needed to connect to the
116AP to access the network.
117
118
119If the client device does not have a display that could show the
120random PIN, a hardcoded PIN that is printed on a label can be
121used. wpa_supplicant is notified this with a control interface
122request, e.g., by calling wpa_cli:
123
124wpa_cli wps_pin any 12345670
125
126This starts the WPS negotiation in the same way as above with the
127generated PIN.
128
129
130If a random PIN is needed for a user interface, "wpa_cli wps_pin get"
131can be used to generate a new PIN without starting WPS negotiation.
132This random PIN can then be passed as an argument to another wps_pin
133call when the actual operation should be started.
134
135If the client design wants to support optional WPS PBC mode, this can
136be enabled by either a physical button in the client device or a
137virtual button in the user interface. The PBC operation requires that
138a button is also pressed at the AP/Registrar at about the same time (2
139minute window). wpa_supplicant is notified of the local button event
140over the control interface, e.g., by calling wpa_cli:
141
142wpa_cli wps_pbc
143
144At this point, the AP/Registrar has two minutes to complete WPS
145negotiation which will generate a new WPA PSK in the same way as the
146PIN method described above.
147
148
149If the client wants to operate in the Registrar role to learn the
150current AP configuration and optionally, to configure an AP,
151wpa_supplicant is notified over the control interface, e.g., with
152wpa_cli:
153
154wpa_cli wps_reg <AP BSSID> <AP PIN>
155(example: wpa_cli wps_reg 02:34:56:78:9a:bc 12345670)
156
157This is used to fetch the current AP settings instead of actually
158changing them. The main difference with the wps_pin command is that
159wps_reg uses the AP PIN (e.g., from a label on the AP) instead of a
160PIN generated at the client.
161
162In order to change the AP configuration, the new configuration
163parameters are given to the wps_reg command:
164
165wpa_cli wps_reg <AP BSSID> <AP PIN> <new SSID> <auth> <encr> <new key>
166examples:
167 wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 testing WPA2PSK CCMP 12345678
168 wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 clear OPEN NONE ""
169
170<auth> must be one of the following: OPEN WPAPSK WPA2PSK
171<encr> must be one of the following: NONE WEP TKIP CCMP
172
173
174Scanning
175--------
176
177Scan results ('wpa_cli scan_results' or 'wpa_cli bss <idx>') include a
178flags field that is used to indicate whether the BSS support WPS. If
179the AP support WPS, but has not recently activated a Registrar, [WPS]
180flag will be included. If PIN method has been recently selected,
181[WPS-PIN] is shown instead. Similarly, [WPS-PBC] is shown if PBC mode
182is in progress. GUI programs can use these as triggers for suggesting
183a guided WPS configuration to the user. In addition, control interface
184monitor events WPS-AP-AVAILABLE{,-PBC,-PIN} can be used to find out if
185there are WPS enabled APs in scan results without having to go through
186all the details in the GUI. These notification could be used, e.g., to
187suggest possible WPS connection to the user.
188
189
190wpa_gui
191-------
192
193wpa_gui-qt4 directory contains a sample GUI that shows an example of
194how WPS support can be integrated into the GUI. Its main window has a
195WPS tab that guides user through WPS registration with automatic AP
196selection. In addition, it shows how WPS can be started manually by
197selecting an AP from scan results.
198
199
200Credential processing
201---------------------
202
203By default, wpa_supplicant processes received credentials and updates
204its configuration internally. However, it is possible to
205control these operations from external programs, if desired.
206
207This internal processing can be disabled with wps_cred_processing=1
208option. When this is used, an external program is responsible for
209processing the credential attributes and updating wpa_supplicant
210configuration based on them.
211
212Following control interface messages are sent out for external programs:
213
214WPS-CRED-RECEIVED <hexdump of Credential attribute(s)>
215For example:
216<2>WPS-CRED-RECEIVED 100e006f10260001011045000c6a6b6d2d7770732d74657374100300020020100f000200081027004030653462303435366332363666653064333961643135353461316634626637313234333761636664623766333939653534663166316230323061643434386235102000060266a0ee1727
217
218
219wpa_supplicant as WPS External Registrar (ER)
220---------------------------------------------
221
222wpa_supplicant can be used as a WPS ER to configure an AP or enroll
223new Enrollee to join the network. This functionality uses UPnP and
224requires that a working IP connectivity is available with the AP (this
225can be either over a wired or wireless connection).
226
227Separate wpa_supplicant process can be started for WPS ER
228operations. A special "none" driver can be used in such a case to
229indicate that no local network interface is actually controlled. For
230example, following command could be used to start the ER:
231
232wpa_supplicant -Dnone -c er.conf -ieth0
233
234Sample er.conf:
235
236ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=admin
237device_name=WPS External Registrar
238
239
240wpa_cli commands for ER functionality:
241
242wps_er_start [IP address]
243- start WPS ER functionality
244- the optional IP address parameter can be used to filter operations only
245 to include a single AP
246- if run again while ER is active, the stored information (discovered APs
247 and Enrollees) are shown again
248
249wps_er_stop
250- stop WPS ER functionality
251
252wps_er_learn <UUID> <AP PIN>
253- learn AP configuration
254
255wps_er_set_config <UUID> <network id>
256- use AP configuration from a locally configured network (e.g., from
257 wps_reg command); this does not change the AP's configuration, but
258 only prepares a configuration to be used when enrolling a new device
259 to the AP
260
261wps_er_config <UUID> <AP PIN> <new SSID> <auth> <encr> <new key>
262- examples:
263 wps_er_config 87654321-9abc-def0-1234-56789abc0002 12345670 testing WPA2PSK CCMP 12345678
264 wpa_er_config 87654321-9abc-def0-1234-56789abc0002 12345670 clear OPEN NONE ""
265
266<auth> must be one of the following: OPEN WPAPSK WPA2PSK
267<encr> must be one of the following: NONE WEP TKIP CCMP
268
269
270wps_er_pbc <Enrollee UUID>
271- accept an Enrollee PBC using External Registrar
272
273wps_er_pin <Enrollee UUID> <PIN> [Enrollee MAC address]
274- add an Enrollee PIN to External Registrar
275- if Enrollee UUID is not known, "any" can be used to add a wildcard PIN
276- if the MAC address of the enrollee is known, it should be configured
277 to allow the AP to advertise list of authorized enrollees
278
279
280WPS ER events:
281
282WPS_EVENT_ER_AP_ADD
283- WPS ER discovered an AP
284
285WPS-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/
286
287WPS_EVENT_ER_AP_REMOVE
288- WPS ER removed an AP entry
289
290WPS-ER-AP-REMOVE 87654321-9abc-def0-1234-56789abc0002
291
292WPS_EVENT_ER_ENROLLEE_ADD
293- WPS ER discovered a new Enrollee
294
295WPS-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|
296
297WPS_EVENT_ER_ENROLLEE_REMOVE
298- WPS ER removed an Enrollee entry
299
300WPS-ER-ENROLLEE-REMOVE 2b7093f1-d6fb-5108-adbb-bea66bb87333 02:66:a0:ee:17:27
301
302WPS-ER-AP-SETTINGS
303- WPS ER learned AP settings
304
305WPS-ER-AP-SETTINGS uuid=fd91b4ec-e3fa-5891-a57d-8c59efeed1d2 ssid=test-wps auth_type=0x0020 encr_type=0x0008 key=12345678
306
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 dual-licensed under both the GPL version 2 and BSD
8license. Either license may be used at your option.
9
10This product includes software developed by the OpenSSL Project
11for use in the OpenSSL Toolkit (http://www.openssl.org/). This
12product includes cryptographic software written by Eric Young
13(eay@cryptsoft.com).
14
15
16wpa_supplicant has support for being used as a WPA/WPA2/IEEE 802.1X
17Supplicant on Windows. The current port requires that WinPcap
18(http://winpcap.polito.it/) is installed for accessing packets and the
19driver interface. Both release versions 3.0 and 3.1 are supported.
20
21The current port is still somewhat experimental. It has been tested
22mainly on Windows XP (SP2) with limited set of NDIS drivers. In
23addition, the current version has been reported to work with Windows
242000.
25
26All security modes have been verified to work (at least complete
27authentication and successfully ping a wired host):
28- plaintext
29- static WEP / open system authentication
30- static WEP / shared key authentication
31- IEEE 802.1X with dynamic WEP keys
32- WPA-PSK, TKIP, CCMP, TKIP+CCMP
33- WPA-EAP, TKIP, CCMP, TKIP+CCMP
34- WPA2-PSK, TKIP, CCMP, TKIP+CCMP
35- WPA2-EAP, TKIP, CCMP, TKIP+CCMP
36
37
38Binary version
39--------------
40
41Compiled binary version of the wpa_supplicant and additional tools is
42available from http://w1.fi/wpa_supplicant/. These binaries can be
43used after installing WinPcap.
44
45wpa_gui uses Qt 4 framework and may need additional dynamic libraries
46(DLLs). These libraries are available from
47http://w1.fi/wpa_supplicant/qt4/wpa_gui-qt433-windows-dll.zip
48You can copy the DLL files from this ZIP package into the same directory
49with wpa_gui.exe to allow wpa_gui to be started.
50
51
52Building wpa_supplicant with mingw
53----------------------------------
54
55The default build setup for wpa_supplicant is to use MinGW and
56cross-compiling from Linux to MinGW/Windows. It should also be
57possible to build this under Windows using the MinGW tools, but that
58is not tested nor supported and is likely to require some changes to
59the Makefile unless cygwin is used.
60
61
62Building wpa_supplicant with MSVC
63---------------------------------
64
65wpa_supplicant can be built with Microsoft Visual C++ compiler. This
66has been tested with Microsoft Visual C++ Toolkit 2003 and Visual
67Studio 2005 using the included nmake.mak as a Makefile for nmake. IDE
68can also be used by creating a project that includes the files and
69defines mentioned in nmake.mak. Example VS2005 solution and project
70files are included in vs2005 subdirectory. This can be used as a
71starting point for building the programs with VS2005 IDE. Visual Studio
722008 Express Edition is also able to use these project files.
73
74WinPcap development package is needed for the build and this can be
75downloaded from http://www.winpcap.org/install/bin/WpdPack_4_0_2.zip. The
76default nmake.mak expects this to be unpacked into C:\dev\WpdPack so
77that Include and Lib directories are in this directory. The files can be
78stored elsewhere as long as the WINPCAPDIR in nmake.mak is updated to
79match with the selected directory. In case a project file in the IDE is
80used, these Include and Lib directories need to be added to project
81properties as additional include/library directories.
82
83OpenSSL source package can be downloaded from
84http://www.openssl.org/source/openssl-0.9.8i.tar.gz and built and
85installed following instructions in INSTALL.W32. Note that if EAP-FAST
86support will be included in the wpa_supplicant, OpenSSL needs to be
87patched to# support it openssl-0.9.8i-tls-extensions.patch. The example
88nmake.mak file expects OpenSSL to be installed into C:\dev\openssl, but
89this directory can be modified by changing OPENSSLDIR variable in
90nmake.mak.
91
92If you do not need EAP-FAST support, you may also be able to use Win32
93binary installation package of OpenSSL from
94http://www.slproweb.com/products/Win32OpenSSL.html instead of building
95the library yourself. In this case, you will need to copy Include and
96Lib directories in suitable directory, e.g., C:\dev\openssl for the
97default nmake.mak. Copy {Win32OpenSSLRoot}\include into
98C:\dev\openssl\include and make C:\dev\openssl\lib subdirectory with
99files from {Win32OpenSSLRoot}\VC (i.e., libeay*.lib and ssleay*.lib).
100This will end up using dynamically linked OpenSSL (i.e., .dll files are
101needed) for it. Alternative, you can copy files from
102{Win32OpenSSLRoot}\VC\static to create a static build (no OpenSSL .dll
103files needed).
104
105
106Building wpa_supplicant for cygwin
107----------------------------------
108
109wpa_supplicant can be built for cygwin by installing the needed
110development packages for cygwin. This includes things like compiler,
111make, openssl development package, etc. In addition, developer's pack
112for WinPcap (WPdpack.zip) from
113http://winpcap.polito.it/install/default.htm is needed.
114
115.config file should enable only one driver interface,
116CONFIG_DRIVER_NDIS. In addition, include directories may need to be
117added to match the system. An example configuration is available in
118defconfig. The library and include files for WinPcap will either need
119to be installed in compiler/linker default directories or their
120location will need to be adding to .config when building
121wpa_supplicant.
122
123Othen than this, the build should be more or less identical to Linux
124version, i.e., just run make after having created .config file. An
125additional tool, win_if_list.exe, can be built by running "make
126win_if_list".
127
128
129Building wpa_gui
130----------------
131
132wpa_gui uses Qt application framework from Trolltech. It can be built
133with the open source version of Qt4 and MinGW. Following commands can
134be used to build the binary in the Qt 4 Command Prompt:
135
136# go to the root directory of wpa_supplicant source code
137cd wpa_gui-qt4
138qmake -o Makefile wpa_gui.pro
139make
140# the wpa_gui.exe binary is created into 'release' subdirectory
141
142
143Using wpa_supplicant for Windows
144--------------------------------
145
146wpa_supplicant, wpa_cli, and wpa_gui behave more or less identically to
147Linux version, so instructions in README and example wpa_supplicant.conf
148should be applicable for most parts. In addition, there is another
149version of wpa_supplicant, wpasvc.exe, which can be used as a Windows
150service and which reads its configuration from registry instead of
151text file.
152
153When using access points in "hidden SSID" mode, ap_scan=2 mode need to
154be used (see wpa_supplicant.conf for more information).
155
156Windows NDIS/WinPcap uses quite long interface names, so some care
157will be needed when starting wpa_supplicant. Alternatively, the
158adapter description can be used as the interface name which may be
159easier since it is usually in more human-readable
160format. win_if_list.exe can be used to find out the proper interface
161name.
162
163Example steps in starting up wpa_supplicant:
164
165# win_if_list.exe
166ifname: \Device\NPF_GenericNdisWanAdapter
167description: Generic NdisWan adapter
168
169ifname: \Device\NPF_{769E012B-FD17-4935-A5E3-8090C38E25D2}
170description: Atheros Wireless Network Adapter (Microsoft's Packet Scheduler)
171
172ifname: \Device\NPF_{732546E7-E26C-48E3-9871-7537B020A211}
173description: Intel 8255x-based Integrated Fast Ethernet (Microsoft's Packet Scheduler)
174
175
176Since the example configuration used Atheros WLAN card, the middle one
177is the correct interface in this case. The interface name for -i
178command line option is the full string following "ifname:" (the
179"\Device\NPF_" prefix can be removed). In other words, wpa_supplicant
180would be started with the following command:
181
182# wpa_supplicant.exe -i'{769E012B-FD17-4935-A5E3-8090C38E25D2}' -c wpa_supplicant.conf -d
183
184-d optional enables some more debugging (use -dd for even more, if
185needed). It can be left out if debugging information is not needed.
186
187With the alternative mechanism for selecting the interface, this
188command has identical results in this case:
189
190# wpa_supplicant.exe -iAtheros -c wpa_supplicant.conf -d
191
192
193Simple configuration example for WPA-PSK:
194
195#ap_scan=2
196ctrl_interface=
197network={
198 ssid="test"
199 key_mgmt=WPA-PSK
200 proto=WPA
201 pairwise=TKIP
202 psk="secret passphrase"
203}
204
205(remove '#' from the comment out ap_scan line to enable mode in which
206wpa_supplicant tries to associate with the SSID without doing
207scanning; this allows APs with hidden SSIDs to be used)
208
209
210wpa_cli.exe and wpa_gui.exe can be used to interact with the
211wpa_supplicant.exe program in the same way as with Linux. Note that
212ctrl_interface is using UNIX domain sockets when built for cygwin, but
213the native build for Windows uses named pipes and the contents of the
214ctrl_interface configuration item is used to control access to the
215interface. Anyway, this variable has to be included in the configuration
216to enable the control interface.
217
218
219Example SDDL string formats:
220
221(local admins group has permission, but nobody else):
222
223ctrl_interface=SDDL=D:(A;;GA;;;BA)
224
225("A" == "access allowed", "GA" == GENERIC_ALL == all permissions, and
226"BA" == "builtin administrators" == the local admins. The empty fields
227are for flags and object GUIDs, none of which should be required in this
228case.)
229
230(local admins and the local "power users" group have permissions,
231but nobody else):
232
233ctrl_interface=SDDL=D:(A;;GA;;;BA)(A;;GA;;;PU)
234
235(One ACCESS_ALLOWED ACE for GENERIC_ALL for builtin administrators, and
236one ACCESS_ALLOWED ACE for GENERIC_ALL for power users.)
237
238(close to wide open, but you have to be a valid user on
239the machine):
240
241ctrl_interface=SDDL=D:(A;;GA;;;AU)
242
243(One ACCESS_ALLOWED ACE for GENERIC_ALL for the "authenticated users"
244group.)
245
246This one would allow absolutely everyone (including anonymous
247users) -- this is *not* recommended, since named pipes can be attached
248to from anywhere on the network (i.e. there's no "this machine only"
249like there is with 127.0.0.1 sockets):
250
251ctrl_interface=SDDL=D:(A;;GA;;;BU)(A;;GA;;;AN)
252
253(BU == "builtin users", "AN" == "anonymous")
254
255See also [1] for the format of ACEs, and [2] for the possible strings
256that can be used for principal names.
257
258[1]
259http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/ace_strings.asp
260[2]
261http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/sid_strings.asp
262
263
264Starting wpa_supplicant as a Windows service (wpasvc.exe)
265---------------------------------------------------------
266
267wpa_supplicant can be started as a Windows service by using wpasvc.exe
268program that is alternative build of wpa_supplicant.exe. Most of the
269core functionality of wpasvc.exe is identical to wpa_supplicant.exe,
270but it is using Windows registry for configuration information instead
271of a text file and command line parameters. In addition, it can be
272registered as a service that can be started automatically or manually
273like any other Windows service.
274
275The root of wpa_supplicant configuration in registry is
276HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant. This level includes global
277parameters and a 'interfaces' subkey with all the interface configuration
278(adapter to confname mapping). Each such mapping is a subkey that has
279'adapter', 'config', and 'ctrl_interface' values.
280
281This program can be run either as a normal command line application,
282e.g., for debugging, with 'wpasvc.exe app' or as a Windows service.
283Service need to be registered with 'wpasvc.exe reg <full path to
284wpasvc.exe>'. Alternatively, 'wpasvc.exe reg' can be used to register
285the service with the current location of wpasvc.exe. After this, wpasvc
286can be started like any other Windows service (e.g., 'net start wpasvc')
287or it can be configured to start automatically through the Services tool
288in administrative tasks. The service can be unregistered with
289'wpasvc.exe unreg'.
290
291If the service is set to start during system bootup to make the
292network connection available before any user has logged in, there may
293be a long (half a minute or so) delay in starting up wpa_supplicant
294due to WinPcap needing a driver called "Network Monitor Driver" which
295is started by default on demand.
296
297To speed up wpa_supplicant start during system bootup, "Network
298Monitor Driver" can be configured to be started sooner by setting its
299startup type to System instead of the default Demand. To do this, open
300up Device Manager, select Show Hidden Devices, expand the "Non
301Plug-and-Play devices" branch, double click "Network Monitor Driver",
302go to the Driver tab, and change the Demand setting to System instead.
303
304Configuration data is in HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs
305key. Each configuration profile has its own key under this. In terms of text
306files, each profile would map to a separate text file with possibly multiple
307networks. Under each profile, there is a networks key that lists all
308networks as a subkey. Each network has set of values in the same way as
309network block in the configuration file. In addition, blobs subkey has
310possible blobs as values.
311
312HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs\test\networks\0000
313 ssid="example"
314 key_mgmt=WPA-PSK
315
316See win_example.reg for an example on how to setup wpasvc.exe
317parameters in registry. It can also be imported to registry as a
318starting point for the configuration.
319
320
321
322License information for third party software used in this product:
323
324 OpenSSL License
325 ---------------
326
327/* ====================================================================
328 * Copyright (c) 1998-2004 The OpenSSL Project. All rights reserved.
329 *
330 * Redistribution and use in source and binary forms, with or without
331 * modification, are permitted provided that the following conditions
332 * are met:
333 *
334 * 1. Redistributions of source code must retain the above copyright
335 * notice, this list of conditions and the following disclaimer.
336 *
337 * 2. Redistributions in binary form must reproduce the above copyright
338 * notice, this list of conditions and the following disclaimer in
339 * the documentation and/or other materials provided with the
340 * distribution.
341 *
342 * 3. All advertising materials mentioning features or use of this
343 * software must display the following acknowledgment:
344 * "This product includes software developed by the OpenSSL Project
345 * for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
346 *
347 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
348 * endorse or promote products derived from this software without
349 * prior written permission. For written permission, please contact
350 * openssl-core@openssl.org.
351 *
352 * 5. Products derived from this software may not be called "OpenSSL"
353 * nor may "OpenSSL" appear in their names without prior written
354 * permission of the OpenSSL Project.
355 *
356 * 6. Redistributions of any form whatsoever must retain the following
357 * acknowledgment:
358 * "This product includes software developed by the OpenSSL Project
359 * for use in the OpenSSL Toolkit (http://www.openssl.org/)"
360 *
361 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
362 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
363 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
364 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
365 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
366 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
367 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
368 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
369 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
370 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
371 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
372 * OF THE POSSIBILITY OF SUCH DAMAGE.
373 * ====================================================================
374 *
375 * This product includes cryptographic software written by Eric Young
376 * (eay@cryptsoft.com). This product includes software written by Tim
377 * Hudson (tjh@cryptsoft.com).
378 *
379 */
380
381 Original SSLeay License
382 -----------------------
383
384/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
385 * All rights reserved.
386 *
387 * This package is an SSL implementation written
388 * by Eric Young (eay@cryptsoft.com).
389 * The implementation was written so as to conform with Netscapes SSL.
390 *
391 * This library is free for commercial and non-commercial use as long as
392 * the following conditions are aheared to. The following conditions
393 * apply to all code found in this distribution, be it the RC4, RSA,
394 * lhash, DES, etc., code; not just the SSL code. The SSL documentation
395 * included with this distribution is covered by the same copyright terms
396 * except that the holder is Tim Hudson (tjh@cryptsoft.com).
397 *
398 * Copyright remains Eric Young's, and as such any Copyright notices in
399 * the code are not to be removed.
400 * If this package is used in a product, Eric Young should be given attribution
401 * as the author of the parts of the library used.
402 * This can be in the form of a textual message at program startup or
403 * in documentation (online or textual) provided with the package.
404 *
405 * Redistribution and use in source and binary forms, with or without
406 * modification, are permitted provided that the following conditions
407 * are met:
408 * 1. Redistributions of source code must retain the copyright
409 * notice, this list of conditions and the following disclaimer.
410 * 2. Redistributions in binary form must reproduce the above copyright
411 * notice, this list of conditions and the following disclaimer in the
412 * documentation and/or other materials provided with the distribution.
413 * 3. All advertising materials mentioning features or use of this software
414 * must display the following acknowledgement:
415 * "This product includes cryptographic software written by
416 * Eric Young (eay@cryptsoft.com)"
417 * The word 'cryptographic' can be left out if the rouines from the library
418 * being used are not cryptographic related :-).
419 * 4. If you include any Windows specific code (or a derivative thereof) from
420 * the apps directory (application code) you must include an acknowledgement:
421 * "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
422 *
423 * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
424 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
425 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
426 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
427 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
428 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
429 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
430 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
431 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
432 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
433 * SUCH DAMAGE.
434 *
435 * The licence and distribution terms for any publically available version or
436 * derivative of this code cannot be changed. i.e. this code cannot simply be
437 * copied and put under another distribution licence
438 * [including the GNU Public Licence.]
439 */
440
441
442
443 Qt Open Source Edition
444 ----------------------
445
446The Qt GUI Toolkit is Copyright (C) 1994-2007 Trolltech ASA.
447Qt Open Source Edition is licensed under GPL version 2.
448
449Source code for the library is available at
450http://w1.fi/wpa_supplicant/qt4/qt-win-opensource-src-4.3.3.zip
451