Home | History | Annotate | only in /external/wpa_supplicant_8/wpa_supplicant
Up to higher level directory
NameDateSize
.gitignore20-Jun-201410
android.config20-Jun-201419.2K
Android.mk20-Jun-201433.2K
ap.c20-Jun-201427.8K
ap.h20-Jun-20142.9K
autoscan.c20-Jun-20143K
autoscan.h20-Jun-20141.1K
autoscan_exponential.c20-Jun-20142K
autoscan_periodic.c20-Jun-20141.6K
bgscan.c20-Jun-20142.7K
bgscan.h20-Jun-20141.8K
bgscan_learn.c20-Jun-201414K
bgscan_simple.c20-Jun-20148.2K
blacklist.c20-Jun-20143.4K
blacklist.h20-Jun-2014660
bss.c20-Jun-201429.6K
bss.h20-Jun-20144.3K
ChangeLog20-Jun-201490.5K
config.c20-Jun-201476.8K
config.h20-Jun-201430.6K
config_file.c20-Jun-201427.5K
config_none.c20-Jun-20141.3K
config_ssid.h20-Jun-201416.9K
config_winreg.c20-Jun-201423.8K
ctrl_iface.c20-Jun-2014146.6K
ctrl_iface.h20-Jun-20145.1K
ctrl_iface_named_pipe.c20-Jun-201419.7K
ctrl_iface_udp.c20-Jun-201413.8K
ctrl_iface_unix.c20-Jun-201423K
dbus/20-Jun-2014
defconfig20-Jun-201419.1K
doc/20-Jun-2014
driver_i.h20-Jun-201418.5K
eap_proxy_dummy.mk20-Jun-20140
eap_register.c20-Jun-20144.9K
eap_testing.txt20-Jun-201414.4K
eapol_test.c20-Jun-201433.4K
events.c20-Jun-201486K
examples/20-Jun-2014
gas_query.c20-Jun-201414.1K
gas_query.h20-Jun-20141.4K
hs20_supplicant.c20-Jun-20145.3K
hs20_supplicant.h20-Jun-2014743
ibss_rsn.c20-Jun-201422.6K
ibss_rsn.h20-Jun-20141.7K
interworking.c20-Jun-201451.8K
interworking.h20-Jun-20141.2K
main.c20-Jun-20148.1K
main_none.c20-Jun-2014838
main_winmain.c20-Jun-20141.7K
main_winsvc.c20-Jun-201411.1K
Makefile20-Jun-201435.7K
nfc_pw_token.c20-Jun-20141.7K
nmake.mak20-Jun-20146.6K
notify.c20-Jun-201415.4K
notify.h20-Jun-20145.6K
offchannel.c20-Jun-201412.7K
offchannel.h20-Jun-20141.4K
p2p_supplicant.c20-Jun-2014178.1K
p2p_supplicant.h20-Jun-20148.3K
preauth_test.c20-Jun-20148.4K
README20-Jun-201434.5K
README-HS2020-Jun-201415.2K
README-P2P20-Jun-201421.4K
README-Windows.txt20-Jun-201412.1K
README-WPS20-Jun-201416.3K
scan.c20-Jun-201444.8K
scan.h20-Jun-20141.7K
sme.c20-Jun-201436.9K
sme.h20-Jun-20143K
src/20-Jun-2014
systemd/20-Jun-2014
tests/20-Jun-2014
todo.txt20-Jun-20145K
utils/20-Jun-2014
wifi_display.c20-Jun-20146.7K
wifi_display.h20-Jun-2014667
win_if_list.c20-Jun-20143.7K
wnm_sta.c20-Jun-201421.3K
wnm_sta.h20-Jun-20141.8K
wpa_cli.c20-Jun-201491.4K
wpa_gui-qt4/20-Jun-2014
wpa_passphrase.c20-Jun-20141.3K
wpa_priv.c20-Jun-201423.1K
wpa_supplicant.c20-Jun-2014111.9K
wpa_supplicant.conf20-Jun-201448.6K
wpa_supplicant_conf.mk20-Jun-20141.3K
wpa_supplicant_conf.sh20-Jun-2014458
wpa_supplicant_i.h20-Jun-201425K
wpa_supplicant_template.conf20-Jun-2014132
wpas_glue.c20-Jun-201423.8K
wpas_glue.h20-Jun-2014765
wps_supplicant.c20-Jun-201464.7K
wps_supplicant.h20-Jun-20144.7K

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