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