wpa_supplicant
==============

Copyright (c) 2003-2022, Jouni Malinen <j@w1.fi> and contributors
All Rights Reserved.

This program is licensed under the BSD license (the one with
advertisement clause removed).

If you are submitting changes to the project, please see CONTRIBUTIONS
file for more instructions.



License
-------

This software may be distributed, used, and modified under the terms of
BSD license:

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

3. Neither the name(s) of the above-listed copyright holder(s) nor the
   names of its contributors may be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



Features
--------

Supported WPA/IEEE 802.11i features:
- WPA-PSK ("WPA-Personal")
- WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise")
  Following authentication methods are supported with an integrate IEEE 802.1X
  Supplicant:
  * EAP-TLS
  * EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)
  * EAP-PEAP/TLS (both PEAPv0 and PEAPv1)
  * EAP-PEAP/GTC (both PEAPv0 and PEAPv1)
  * EAP-PEAP/OTP (both PEAPv0 and PEAPv1)
  * EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)
  * EAP-TTLS/EAP-MD5-Challenge
  * EAP-TTLS/EAP-GTC
  * EAP-TTLS/EAP-OTP
  * EAP-TTLS/EAP-MSCHAPv2
  * EAP-TTLS/EAP-TLS
  * EAP-TTLS/MSCHAPv2
  * EAP-TTLS/MSCHAP
  * EAP-TTLS/PAP
  * EAP-TTLS/CHAP
  * EAP-SIM
  * EAP-AKA
  * EAP-AKA'
  * EAP-PSK
  * EAP-PAX
  * EAP-SAKE
  * EAP-IKEv2
  * EAP-GPSK
  * EAP-pwd
  * LEAP (note: requires special support from the driver for IEEE 802.11
	  authentication)
  (following methods are supported, but since they do not generate keying
   material, they cannot be used with WPA or IEEE 802.1X WEP keying)
  * EAP-MD5-Challenge
  * EAP-MSCHAPv2
  * EAP-GTC
  * EAP-OTP
- key management for CCMP, TKIP, WEP104, WEP40
- RSN/WPA2 (IEEE 802.11i)
  * pre-authentication
  * PMKSA caching

Supported TLS/crypto libraries:
- OpenSSL (default)
- GnuTLS

Internal TLS/crypto implementation (optional):
- can be used in place of an external TLS/crypto library
- TLSv1
- X.509 certificate processing
- PKCS #1
- ASN.1
- RSA
- bignum
- minimal size (ca. 50 kB binary, parts of which are already needed for WPA;
  TLSv1/X.509/ASN.1/RSA/bignum parts are about 25 kB on x86)


Requirements
------------

Current hardware/software requirements:
- Linux kernel 2.4.x or 2.6.x with Linux Wireless Extensions v15 or newer
- FreeBSD 6-CURRENT
- NetBSD-current
- Microsoft Windows with WinPcap (at least WinXP, may work with other versions)
- drivers:
	Linux drivers that support cfg80211/nl80211. Even though there are
	number of driver specific interface included in wpa_supplicant, please
	note that Linux drivers are moving to use generic wireless configuration
	interface driver_nl80211 (-Dnl80211 on wpa_supplicant command line)
	should be the default option to start with before falling back to driver
	specific interface.

	Linux drivers that support WPA/WPA2 configuration with the generic
	Linux wireless extensions (WE-18 or newer). Obsoleted by nl80211.

	In theory, any driver that supports Linux wireless extensions can be
	used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in
	configuration file.

	Wired Ethernet drivers (with ap_scan=0)

	BSD net80211 layer (e.g., Atheros driver)
	At the moment, this is for FreeBSD 6-CURRENT branch and NetBSD-current.

	Windows NDIS
	The current Windows port requires WinPcap (http://winpcap.polito.it/).
	See README-Windows.txt for more information.

wpa_supplicant was designed to be portable for different drivers and
operating systems. Hopefully, support for more wlan cards and OSes will be
added in the future. See developer's documentation
(http://hostap.epitest.fi/wpa_supplicant/devel/) for more information about the
design of wpa_supplicant and porting to other drivers. One main goal
is to add full WPA/WPA2 support to Linux wireless extensions to allow
new drivers to be supported without having to implement new
driver-specific interface code in wpa_supplicant.

Optional libraries for layer2 packet processing:
- libpcap (tested with 0.7.2, most relatively recent versions assumed to work,
	this is likely to be available with most distributions,
	http://tcpdump.org/)
- libdnet (tested with v1.4, most versions assumed to work,
	http://libdnet.sourceforge.net/)

These libraries are _not_ used in the default Linux build. Instead,
internal Linux specific implementation is used. libpcap/libdnet are
more portable and they can be used by adding CONFIG_L2_PACKET=pcap into
.config. They may also be selected automatically for other operating
systems. In case of Windows builds, WinPcap is used by default
(CONFIG_L2_PACKET=winpcap).


Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS:
- OpenSSL (tested with 1.0.1 and 1.0.2 versions; assumed to
  work with most relatively recent versions; this is likely to be
  available with most distributions, http://www.openssl.org/)
- GnuTLS
- internal TLSv1 implementation

One of these libraries is needed when EAP-TLS, EAP-PEAP, EAP-TTLS, or
EAP-FAST support is enabled. WPA-PSK mode does not require this or EAPOL/EAP
implementation. A configuration file, .config, for compilation is
needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5,
EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so
they should only be enabled if testing the EAPOL/EAP state
machines. However, there can be used as inner authentication
algorithms with EAP-PEAP and EAP-TTLS.

See Building and installing section below for more detailed
information about the wpa_supplicant build time configuration.



WPA
---

The original security mechanism of IEEE 802.11 standard was not
designed to be strong and has proven to be insufficient for most
networks that require some kind of security. Task group I (Security)
of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked
to address the flaws of the base standard and has in practice
completed its work in May 2004. The IEEE 802.11i amendment to the IEEE
802.11 standard was approved in June 2004 and published in July 2004.

Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the
IEEE 802.11i work (draft 3.0) to define a subset of the security
enhancements that can be implemented with existing wlan hardware. This
is called Wi-Fi Protected Access<TM> (WPA). This has now become a
mandatory component of interoperability testing and certification done
by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web
site (http://www.wi-fi.org/OpenSection/protected_access.asp).

IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm
for protecting wireless networks. WEP uses RC4 with 40-bit keys,
24-bit initialization vector (IV), and CRC32 to protect against packet
forgery. All these choices have proven to be insufficient: key space is
too small against current attacks, RC4 key scheduling is insufficient
(beginning of the pseudorandom stream should be skipped), IV space is
too small and IV reuse makes attacks easier, there is no replay
protection, and non-keyed authentication does not protect against bit
flipping packet data.

WPA is an intermediate solution for the security issues. It uses
Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a
compromise on strong security and possibility to use existing
hardware. It still uses RC4 for the encryption like WEP, but with
per-packet RC4 keys. In addition, it implements replay protection,
keyed packet authentication mechanism (Michael MIC).

Keys can be managed using two different mechanisms. WPA can either use
an external authentication server (e.g., RADIUS) and EAP just like
IEEE 802.1X is using or pre-shared keys without need for additional
servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",
respectively. Both mechanisms will generate a master session key for
the Authenticator (AP) and Supplicant (client station).

WPA implements a new key handshake (4-Way Handshake and Group Key
Handshake) for generating and exchanging data encryption keys between
the Authenticator and Supplicant. This handshake is also used to
verify that both Authenticator and Supplicant know the master session
key. These handshakes are identical regardless of the selected key
management mechanism (only the method for generating master session
key changes).



IEEE 802.11i / WPA2
-------------------

The design for parts of IEEE 802.11i that were not included in WPA has
finished (May 2004) and this amendment to IEEE 802.11 was approved in
June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new
version of WPA called WPA2. This includes, e.g., support for more
robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
to replace TKIP and optimizations for handoff (reduced number of
messages in initial key handshake, pre-authentication, and PMKSA caching).



wpa_supplicant
--------------

wpa_supplicant is an implementation of the WPA Supplicant component,
i.e., the part that runs in the client stations. It implements WPA key
negotiation with a WPA Authenticator and EAP authentication with
Authentication Server. In addition, it controls the roaming and IEEE
802.11 authentication/association of the wlan driver.

wpa_supplicant is designed to be a "daemon" program that runs in the
background and acts as the backend component controlling the wireless
connection. wpa_supplicant supports separate frontend programs and an
example text-based frontend, wpa_cli, is included with wpa_supplicant.

Following steps are used when associating with an AP using WPA:

- wpa_supplicant requests the kernel driver to scan neighboring BSSes
- wpa_supplicant selects a BSS based on its configuration
- wpa_supplicant requests the kernel driver to associate with the chosen
  BSS
- If WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP
  authentication with the authentication server (proxied by the
  Authenticator in the AP)
- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant
- If WPA-PSK: wpa_supplicant uses PSK as the master session key
- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake
  with the Authenticator (AP)
- wpa_supplicant configures encryption keys for unicast and broadcast
- normal data packets can be transmitted and received



Building and installing
-----------------------

In order to be able to build wpa_supplicant, you will first need to
select which parts of it will be included. This is done by creating a
build time configuration file, .config, in the wpa_supplicant root
directory. Configuration options are text lines using following
format: CONFIG_<option>=y. Lines starting with # are considered
comments and are ignored. See defconfig file for an example configuration
and a list of available options and additional notes.

The build time configuration can be used to select only the needed
features and limit the binary size and requirements for external
libraries. The main configuration parts are the selection of which
driver interfaces (e.g., nl80211, wext, ..) and which authentication
methods (e.g., EAP-TLS, EAP-PEAP, ..) are included.

Following build time configuration options are used to control IEEE
802.1X/EAPOL and EAP state machines and all EAP methods. Including
TLS, PEAP, or TTLS will require linking wpa_supplicant with OpenSSL
library for TLS implementation. Alternatively, GnuTLS or the internal
TLSv1 implementation can be used for TLS functionality.

CONFIG_IEEE8021X_EAPOL=y
CONFIG_EAP_MD5=y
CONFIG_EAP_MSCHAPV2=y
CONFIG_EAP_TLS=y
CONFIG_EAP_PEAP=y
CONFIG_EAP_TTLS=y
CONFIG_EAP_GTC=y
CONFIG_EAP_OTP=y
CONFIG_EAP_SIM=y
CONFIG_EAP_AKA=y
CONFIG_EAP_AKA_PRIME=y
CONFIG_EAP_PSK=y
CONFIG_EAP_SAKE=y
CONFIG_EAP_GPSK=y
CONFIG_EAP_PAX=y
CONFIG_EAP_LEAP=y
CONFIG_EAP_IKEV2=y
CONFIG_EAP_PWD=y

Following option can be used to include GSM SIM/USIM interface for GSM/UMTS
authentication algorithm (for EAP-SIM/EAP-AKA/EAP-AKA'). This requires pcsc-lite
(http://www.linuxnet.com/) for smart card access.

CONFIG_PCSC=y

Following options can be added to .config to select which driver
interfaces are included.

CONFIG_DRIVER_NL80211=y
CONFIG_DRIVER_WEXT=y
CONFIG_DRIVER_BSD=y
CONFIG_DRIVER_NDIS=y

Following example includes some more features and driver interfaces that
are included in the wpa_supplicant package:

CONFIG_DRIVER_NL80211=y
CONFIG_DRIVER_WEXT=y
CONFIG_DRIVER_BSD=y
CONFIG_DRIVER_NDIS=y
CONFIG_IEEE8021X_EAPOL=y
CONFIG_EAP_MD5=y
CONFIG_EAP_MSCHAPV2=y
CONFIG_EAP_TLS=y
CONFIG_EAP_PEAP=y
CONFIG_EAP_TTLS=y
CONFIG_EAP_GTC=y
CONFIG_EAP_OTP=y
CONFIG_EAP_SIM=y
CONFIG_EAP_AKA=y
CONFIG_EAP_PSK=y
CONFIG_EAP_SAKE=y
CONFIG_EAP_GPSK=y
CONFIG_EAP_PAX=y
CONFIG_EAP_LEAP=y
CONFIG_EAP_IKEV2=y
CONFIG_PCSC=y

EAP-PEAP and EAP-TTLS will automatically include configured EAP
methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection.


After you have created a configuration file, you can build
wpa_supplicant and wpa_cli with 'make' command. You may then install
the binaries to a suitable system directory, e.g., /usr/local/bin.

Example commands:

# build wpa_supplicant and wpa_cli
make
# install binaries (this may need root privileges)
cp wpa_cli wpa_supplicant /usr/local/bin


You will need to make a configuration file, e.g.,
/etc/wpa_supplicant.conf, with network configuration for the networks
you are going to use. Configuration file section below includes
explanation of the configuration file format and includes various
examples. Once the configuration is ready, you can test whether the
configuration work by first running wpa_supplicant with following
command to start it on foreground with debugging enabled:

wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d

Assuming everything goes fine, you can start using following command
to start wpa_supplicant on background without debugging:

wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B

Please note that if you included more than one driver interface in the
build time configuration (.config), you may need to specify which
interface to use by including -D<driver name> option on the command
line. See following section for more details on command line options
for wpa_supplicant.



Command line options
--------------------

usage:
  wpa_supplicant [-BddfhKLqqtuvW] [-P<pid file>] [-g<global ctrl>] \
        [-G<group>] \
        -i<ifname> -c<config file> [-C<ctrl>] [-D<driver>] [-p<driver_param>] \
        [-b<br_ifname> [-MN -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] \
        [-p<driver_param>] [-b<br_ifname>] [-m<P2P Device config file>] ...

options:
  -b = optional bridge interface name
  -B = run daemon in the background
  -c = Configuration file
  -C = ctrl_interface parameter (only used if -c is not)
  -i = interface name
  -d = increase debugging verbosity (-dd even more)
  -D = driver name (can be multiple drivers: nl80211,wext)
  -f = Log output to default log location (normally /tmp)
  -g = global ctrl_interface
  -G = global ctrl_interface group
  -K = include keys (passwords, etc.) in debug output
  -t = include timestamp in debug messages
  -h = show this help text
  -L = show license (BSD)
  -p = driver parameters
  -P = PID file
  -q = decrease debugging verbosity (-qq even less)
  -u = enable DBus control interface
  -v = show version
  -W = wait for a control interface monitor before starting
  -M = start describing matching interface
  -N = start describing new interface
  -m = Configuration file for the P2P Device

drivers:
  nl80211 = Linux nl80211/cfg80211
  wext = Linux wireless extensions (generic)
  wired = wpa_supplicant wired Ethernet driver
  macsec_linux = MACsec Ethernet driver for Linux
  roboswitch = wpa_supplicant Broadcom switch driver
  none = no driver (RADIUS server/WPS ER only)
  bsd = BSD 802.11 support (Atheros, etc.)
  ndis = Windows NDIS driver

In most common cases, wpa_supplicant is started with

wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0

This makes the process fork into background.

The easiest way to debug problems, and to get debug log for bug
reports, is to start wpa_supplicant on foreground with debugging
enabled:

wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d

If the specific driver wrapper is not known beforehand, it is possible
to specify multiple comma separated driver wrappers on the command
line. wpa_supplicant will use the first driver wrapper that is able to
initialize the interface.

wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0


wpa_supplicant can control multiple interfaces (radios) either by
running one process for each interface separately or by running just
one process and list of options at command line. Each interface is
separated with -N argument. As an example, following command would
start wpa_supplicant for two interfaces:

wpa_supplicant \
	-c wpa1.conf -i wlan0 -D nl80211 -N \
	-c wpa2.conf -i wlan1 -D wext


If the interfaces on which wpa_supplicant is to run are not known or do
not exist, wpa_supplicant can match an interface when it arrives. Each
matched interface is separated with -M argument and the -i argument now
allows for pattern matching.

As an example, the following command would start wpa_supplicant for a
specific wired interface called lan0, any interface starting with wlan
and lastly any other interface. Each match has its own configuration
file, and for the wired interface a specific driver has also been given.

wpa_supplicant \
	-M -c wpa_wired.conf -ilan0 -D wired \
	-M -c wpa1.conf -iwlan* \
	-M -c wpa2.conf


If the interface is added in a Linux bridge (e.g., br0), the bridge
interface needs to be configured to wpa_supplicant in addition to the
main interface:

wpa_supplicant -cw.conf -Dnl80211 -iwlan0 -bbr0


Configuration file
------------------

wpa_supplicant is configured using a text file that lists all accepted
networks and security policies, including pre-shared keys. See
example configuration file, wpa_supplicant.conf, for detailed
information about the configuration format and supported fields.

Changes to configuration file can be reloaded be sending SIGHUP signal
to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly,
reloading can be triggered with 'wpa_cli reconfigure' command.

Configuration file can include one or more network blocks, e.g., one
for each used SSID. wpa_supplicant will automatically select the best
network based on the order of network blocks in the configuration
file, network security level (WPA/WPA2 is preferred), and signal
strength.

Example configuration files for some common configurations:

1) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work
   network

# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
#
# home network; allow all valid ciphers
network={
	ssid="home"
	scan_ssid=1
	key_mgmt=WPA-PSK
	psk="very secret passphrase"
}
#
# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
network={
	ssid="work"
	scan_ssid=1
	key_mgmt=WPA-EAP
	pairwise=CCMP TKIP
	group=CCMP TKIP
	eap=TLS
	identity="user@example.com"
	ca_cert="/etc/cert/ca.pem"
	client_cert="/etc/cert/user.pem"
	private_key="/etc/cert/user.prv"
	private_key_passwd="password"
}


2) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
   (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series)

ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
network={
	ssid="example"
	scan_ssid=1
	key_mgmt=WPA-EAP
	eap=PEAP
	identity="user@example.com"
	password="foobar"
	ca_cert="/etc/cert/ca.pem"
	phase1="peaplabel=0"
	phase2="auth=MSCHAPV2"
}


3) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
   unencrypted use. Real identity is sent only within an encrypted TLS tunnel.

ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
network={
	ssid="example"
	scan_ssid=1
	key_mgmt=WPA-EAP
	eap=TTLS
	identity="user@example.com"
	anonymous_identity="anonymous@example.com"
	password="foobar"
	ca_cert="/etc/cert/ca.pem"
	phase2="auth=MD5"
}


4) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and
   broadcast); use EAP-TLS for authentication

ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
network={
	ssid="1x-test"
	scan_ssid=1
	key_mgmt=IEEE8021X
	eap=TLS
	identity="user@example.com"
	ca_cert="/etc/cert/ca.pem"
	client_cert="/etc/cert/user.pem"
	private_key="/etc/cert/user.prv"
	private_key_passwd="password"
	eapol_flags=3
}


5) Catch all example that allows more or less all configuration modes. The
   configuration options are used based on what security policy is used in the
   selected SSID. This is mostly for testing and is not recommended for normal
   use.

ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
network={
	ssid="example"
	scan_ssid=1
	key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
	pairwise=CCMP TKIP
	group=CCMP TKIP WEP104 WEP40
	psk="very secret passphrase"
	eap=TTLS PEAP TLS
	identity="user@example.com"
	password="foobar"
	ca_cert="/etc/cert/ca.pem"
	client_cert="/etc/cert/user.pem"
	private_key="/etc/cert/user.prv"
	private_key_passwd="password"
	phase1="peaplabel=0"
	ca_cert2="/etc/cert/ca2.pem"
	client_cert2="/etc/cer/user.pem"
	private_key2="/etc/cer/user.prv"
	private_key2_passwd="password"
}


6) Authentication for wired Ethernet. This can be used with 'wired' or
   'roboswitch' interface (-Dwired or -Droboswitch on command line).

ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
ap_scan=0
network={
	key_mgmt=IEEE8021X
	eap=MD5
	identity="user"
	password="password"
	eapol_flags=0
}



Certificates
------------

Some EAP authentication methods require use of certificates. EAP-TLS
uses both server side and client certificates whereas EAP-PEAP and
EAP-TTLS only require the server side certificate. When client
certificate is used, a matching private key file has to also be
included in configuration. If the private key uses a passphrase, this
has to be configured in wpa_supplicant.conf ("private_key_passwd").

wpa_supplicant supports X.509 certificates in PEM and DER
formats. User certificate and private key can be included in the same
file.

If the user certificate and private key is received in PKCS#12/PFX
format, they need to be converted to suitable PEM/DER format for
wpa_supplicant. This can be done, e.g., with following commands:

# convert client certificate and private key to PEM format
openssl pkcs12 -in example.pfx -out user.pem -clcerts
# convert CA certificate (if included in PFX file) to PEM format
openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys



wpa_cli
-------

wpa_cli is a text-based frontend program for interacting with
wpa_supplicant. It is used to query current status, change
configuration, trigger events, and request interactive user input.

wpa_cli can show the current authentication status, selected security
mode, dot11 and dot1x MIBs, etc. In addition, it can configure some
variables like EAPOL state machine parameters and trigger events like
reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user
interface to request authentication information, like username and
password, if these are not included in the configuration. This can be
used to implement, e.g., one-time-passwords or generic token card
authentication where the authentication is based on a
challenge-response that uses an external device for generating the
response.

The control interface of wpa_supplicant can be configured to allow
non-root user access (ctrl_interface_group in the configuration
file). This makes it possible to run wpa_cli with a normal user
account.

wpa_cli supports two modes: interactive and command line. Both modes
share the same command set and the main difference is in interactive
mode providing access to unsolicited messages (event messages,
username/password requests).

Interactive mode is started when wpa_cli is executed without including
the command as a command line parameter. Commands are then entered on
the wpa_cli prompt. In command line mode, the same commands are
entered as command line arguments for wpa_cli.


Interactive authentication parameters request

When wpa_supplicant need authentication parameters, like username and
password, which are not present in the configuration file, it sends a
request message to all attached frontend programs, e.g., wpa_cli in
interactive mode. wpa_cli shows these requests with
"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or
OTP (one-time-password). <id> is a unique identifier for the current
network. <text> is description of the request. In case of OTP request,
it includes the challenge from the authentication server.

The reply to these requests can be given with 'identity', 'password',
and 'otp' commands. <id> needs to be copied from the the matching
request. 'password' and 'otp' commands can be used regardless of
whether the request was for PASSWORD or OTP. The main difference
between these two commands is that values given with 'password' are
remembered as long as wpa_supplicant is running whereas values given
with 'otp' are used only once and then forgotten, i.e., wpa_supplicant
will ask frontend for a new value for every use. This can be used to
implement one-time-password lists and generic token card -based
authentication.

Example request for password and a matching reply:

CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
> password 1 mysecretpassword

Example request for generic token card challenge-response:

CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
> otp 2 9876


wpa_cli commands

  status = get current WPA/EAPOL/EAP status
  mib = get MIB variables (dot1x, dot11)
  help = show this usage help
  interface [ifname] = show interfaces/select interface
  level <debug level> = change debug level
  license = show full wpa_cli license
  logoff = IEEE 802.1X EAPOL state machine logoff
  logon = IEEE 802.1X EAPOL state machine logon
  set = set variables (shows list of variables when run without arguments)
  pmksa = show PMKSA cache
  reassociate = force reassociation
  reconfigure = force wpa_supplicant to re-read its configuration file
  preauthenticate <BSSID> = force preauthentication
  identity <network id> <identity> = configure identity for an SSID
  password <network id> <password> = configure password for an SSID
  pin <network id> <pin> = configure pin for an SSID
  otp <network id> <password> = configure one-time-password for an SSID
  passphrase <network id> <passphrase> = configure private key passphrase
    for an SSID
  bssid <network id> <BSSID> = set preferred BSSID for an SSID
  list_networks = list configured networks
  select_network <network id> = select a network (disable others)
  enable_network <network id> = enable a network
  disable_network <network id> = disable a network
  add_network = add a network
  remove_network <network id> = remove a network
  set_network <network id> <variable> <value> = set network variables (shows
    list of variables when run without arguments)
  get_network <network id> <variable> = get network variables
  save_config = save the current configuration
  disconnect = disconnect and wait for reassociate command before connecting
  scan = request new BSS scan
  scan_results = get latest scan results
  get_capability <eap/pairwise/group/key_mgmt/proto/auth_alg> = get capabilities
  terminate = terminate wpa_supplicant
  quit = exit wpa_cli


wpa_cli command line options

wpa_cli [-p<path to ctrl sockets>] [-i<ifname>] [-hvB] [-a<action file>] \
        [-P<pid file>] [-g<global ctrl>]  [command..]
  -h = help (show this usage text)
  -v = shown version information
  -a = run in daemon mode executing the action file based on events from
       wpa_supplicant
  -B = run a daemon in the background
  default path: /var/run/wpa_supplicant
  default interface: first interface found in socket path


Using wpa_cli to run external program on connect/disconnect
-----------------------------------------------------------

wpa_cli can used to run external programs whenever wpa_supplicant
connects or disconnects from a network. This can be used, e.g., to
update network configuration and/or trigget DHCP client to update IP
addresses, etc.

One wpa_cli process in "action" mode needs to be started for each
interface. For example, the following command starts wpa_cli for the
default interface (-i can be used to select the interface in case of
more than one interface being used at the same time):

wpa_cli -a/sbin/wpa_action.sh -B

The action file (-a option, /sbin/wpa_action.sh in this example) will
be executed whenever wpa_supplicant completes authentication (connect
event) or detects disconnection). The action script will be called
with two command line arguments: interface name and event (CONNECTED
or DISCONNECTED). If the action script needs to get more information
about the current network, it can use 'wpa_cli status' to query
wpa_supplicant for more information.

Following example can be used as a simple template for an action
script:

#!/bin/sh

IFNAME=$1
CMD=$2

if [ "$CMD" = "CONNECTED" ]; then
    SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=`
    # configure network, signal DHCP client, etc.
fi

if [ "$CMD" = "DISCONNECTED" ]; then
    # remove network configuration, if needed
    SSID=
fi



Integrating with pcmcia-cs/cardmgr scripts
------------------------------------------

wpa_supplicant needs to be running when using a wireless network with
WPA. It can be started either from system startup scripts or from
pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be
completed before data frames can be exchanged, so wpa_supplicant
should be started before DHCP client.

For example, following small changes to pcmcia-cs scripts can be used
to enable WPA support:

Add MODE="Managed" and WPA="y" to the network scheme in
/etc/pcmcia/wireless.opts.

Add the following block to the end of 'start' action handler in
/etc/pcmcia/wireless:

    if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
	/usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf \
		-i$DEVICE
    fi

Add the following block to the end of 'stop' action handler (may need
to be separated from other actions) in /etc/pcmcia/wireless:

    if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
	killall wpa_supplicant
    fi

This will make cardmgr start wpa_supplicant when the card is plugged
in.



Dynamic interface add and operation without configuration files
---------------------------------------------------------------

wpa_supplicant can be started without any configuration files or
network interfaces. When used in this way, a global (i.e., per
wpa_supplicant process) control interface is used to add and remove
network interfaces. Each network interface can then be configured
through a per-network interface control interface. For example,
following commands show how to start wpa_supplicant without any
network interfaces and then add a network interface and configure a
network (SSID):

# Start wpa_supplicant in the background
wpa_supplicant -g/var/run/wpa_supplicant-global -B

# Add a new interface (wlan0, no configuration file, driver=nl80211, and
# enable control interface)
wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \
	"" nl80211 /var/run/wpa_supplicant

# Configure a network using the newly added network interface:
wpa_cli -iwlan0 add_network
wpa_cli -iwlan0 set_network 0 ssid '"test"'
wpa_cli -iwlan0 set_network 0 key_mgmt WPA-PSK
wpa_cli -iwlan0 set_network 0 psk '"12345678"'
wpa_cli -iwlan0 set_network 0 pairwise TKIP
wpa_cli -iwlan0 set_network 0 group TKIP
wpa_cli -iwlan0 set_network 0 proto WPA
wpa_cli -iwlan0 enable_network 0

# At this point, the new network interface should start trying to associate
# with the WPA-PSK network using SSID test.

# Remove network interface
wpa_cli -g/var/run/wpa_supplicant-global interface_remove wlan0


Privilege separation
--------------------

To minimize the size of code that needs to be run with root privileges
(e.g., to control wireless interface operation), wpa_supplicant
supports optional privilege separation. If enabled, this separates the
privileged operations into a separate process (wpa_priv) while leaving
rest of the code (e.g., EAP authentication and WPA handshakes) into an
unprivileged process (wpa_supplicant) that can be run as non-root
user. Privilege separation restricts the effects of potential software
errors by containing the majority of the code in an unprivileged
process to avoid full system compromise.

Privilege separation is not enabled by default and it can be enabled
by adding CONFIG_PRIVSEP=y to the build configuration (.config). When
enabled, the privileged operations (driver wrapper and l2_packet) are
linked into a separate daemon program, wpa_priv. The unprivileged
program, wpa_supplicant, will be built with a special driver/l2_packet
wrappers that communicate with the privileged wpa_priv process to
perform the needed operations. wpa_priv can control what privileged
are allowed.

wpa_priv needs to be run with network admin privileges (usually, root
user). It opens a UNIX domain socket for each interface that is
included on the command line; any other interface will be off limits
for wpa_supplicant in this kind of configuration. After this,
wpa_supplicant can be run as a non-root user (e.g., all standard users
on a laptop or as a special non-privileged user account created just
for this purpose to limit access to user files even further).


Example configuration:
- create user group for users that are allowed to use wpa_supplicant
  ('wpapriv' in this example) and assign users that should be able to
  use wpa_supplicant into that group
- create /var/run/wpa_priv directory for UNIX domain sockets and control
  user access by setting it accessible only for the wpapriv group:
  mkdir /var/run/wpa_priv
  chown root:wpapriv /var/run/wpa_priv
  chmod 0750 /var/run/wpa_priv
- start wpa_priv as root (e.g., from system startup scripts) with the
  enabled interfaces configured on the command line:
  wpa_priv -B -P /var/run/wpa_priv.pid nl80211:wlan0
- run wpa_supplicant as non-root with a user that is in wpapriv group:
  wpa_supplicant -i ath0 -c wpa_supplicant.conf

wpa_priv does not use the network interface before wpa_supplicant is
started, so it is fine to include network interfaces that are not
available at the time wpa_priv is started. As an alternative, wpa_priv
can be started when an interface is added (hotplug/udev/etc. scripts).
wpa_priv can control multiple interface with one process, but it is
also possible to run multiple wpa_priv processes at the same time, if
desired.

It should be noted that the interface used between wpa_supplicant and
wpa_priv does not include all the capabilities of the wpa_supplicant
driver interface and at times, this interface lacks update especially
for recent addition. Consequently, use of wpa_priv does come with the
price of somewhat reduced available functionality. The next section
describing how wpa_supplicant can be used with reduced privileges
without having to handle the complexity of separate wpa_priv. While that
approve does not provide separation for network admin capabilities, it
does allow other root privileges to be dropped without the drawbacks of
the wpa_priv process.


Linux capabilities instead of privileged process
------------------------------------------------

wpa_supplicant performs operations that need special permissions, e.g.,
to control the network connection. Traditionally this has been achieved
by running wpa_supplicant as a privileged process with effective user id
0 (root). Linux capabilities can be used to provide restricted set of
capabilities to match the functions needed by wpa_supplicant. The
minimum set of capabilities needed for the operations is CAP_NET_ADMIN
and CAP_NET_RAW.

setcap(8) can be used to set file capabilities. For example:

sudo setcap cap_net_raw,cap_net_admin+ep wpa_supplicant

Please note that this would give anyone being able to run that
wpa_supplicant binary access to the additional capabilities. This can
further be limited by file owner/group and mode bits. For example:

sudo chown wpas wpa_supplicant
sudo chmod 0100 wpa_supplicant

This combination of setcap, chown, and chmod commands would allow wpas
user to execute wpa_supplicant with additional network admin/raw
capabilities.

Common way style of creating a control interface socket in
/var/run/wpa_supplicant could not be done by this user, but this
directory could be created before starting the wpa_supplicant and set to
suitable mode to allow wpa_supplicant to create sockets
there. Alternatively, other directory or abstract socket namespace could
be used for the control interface.


External requests for radio control
-----------------------------------

External programs can request wpa_supplicant to not start offchannel
operations during other tasks that may need exclusive control of the
radio. The RADIO_WORK control interface command can be used for this.

"RADIO_WORK add <name> [freq=<MHz>] [timeout=<seconds>]" command can be
used to reserve a slot for radio access. If freq is specified, other
radio work items on the same channel may be completed in
parallel. Otherwise, all other radio work items are blocked during
execution. Timeout is set to 10 seconds by default to avoid blocking
wpa_supplicant operations for excessive time. If a longer (or shorter)
safety timeout is needed, that can be specified with the optional
timeout parameter. This command returns an identifier for the radio work
item.

Once the radio work item has been started, "EXT-RADIO-WORK-START <id>"
event message is indicated that the external processing can start. Once
the operation has been completed, "RADIO_WORK done <id>" is used to
indicate that to wpa_supplicant. This allows other radio works to be
performed. If this command is forgotten (e.g., due to the external
program terminating), wpa_supplicant will time out the radio work item
and send "EXT-RADIO-WORK-TIMEOUT <id>" event to indicate that this has
happened. "RADIO_WORK done <id>" can also be used to cancel items that
have not yet been started.

For example, in wpa_cli interactive mode:

> radio_work add test
1
<3>EXT-RADIO-WORK-START 1
> radio_work show
ext:test@wlan0:0:1:2.487797
> radio_work done 1
OK
> radio_work show


> radio_work done 3
OK
> radio_work show
ext:test freq=2412 timeout=30@wlan0:2412:1:28.583483
<3>EXT-RADIO-WORK-TIMEOUT 2


> radio_work add test2 freq=2412 timeout=60
5
<3>EXT-RADIO-WORK-START 5
> radio_work add test3
6
> radio_work add test4
7
> radio_work show
ext:test2 freq=2412 timeout=60@wlan0:2412:1:9.751844
ext:test3@wlan0:0:0:5.071812
ext:test4@wlan0:0:0:3.143870
> radio_work done 6
OK
> radio_work show
ext:test2 freq=2412 timeout=60@wlan0:2412:1:16.287869
ext:test4@wlan0:0:0:9.679895
> radio_work done 5
OK
<3>EXT-RADIO-WORK-START 7
<3>EXT-RADIO-WORK-TIMEOUT 7


DSCP policy procedures
----------------------

DSCP policy procedures defined in WFA QoS Management-R2 program
facilitates AP devices to configure DSCP settings for specific uplink
data streams.

An AP may transmit a DSCP Policy Request frame containing zero or more
QoS Management IEs to an associated STA which supports DSCP policy
procedures. Each QoS Management element in a DSCP Policy Request frame
represents one DSCP policy, and shall include one DSCP Policy attribute
including a DSCP Policy ID, Request type, and a DSCP value.

wpa_supplicant sends control interface event messages consisting details
of DSCP policies requested by the AP through a DSCP Policy Request frame
to external programs. The format of the control interface event messages
is as shown below:

- Control interface event message format to indicate DSCP request start

  <3>CTRL-EVENT-DSCP-POLICY request_start [clear_all] [more]

  clear_all - AP requested to clear all DSCP policies configured earlier
  more      - AP may request to configure more DSCP policies with new DSCP
              request

- Control interface event message format to add new policy

  <3>CTRL-EVENT-DSCP-POLICY add <policy_id> <dscp_value> <ip_version=0|4|6>
  [protocol] [source ip] [destination_ip]/[domain name] [source port]
  [[<start_port> <end_port>]/destination port]

  ip_version = 0: Both IPv4 and IPv6
             = 4: IPv4
             = 6: IPv6
  protocol: Internet Protocol Numbers as per IETF RFCs
	 = 6: TCP
	 = 17: UDP
	 = 50: ESP

- Control interface event message format to remove a particular policy,
  identified by the policy_id attribute.

  <3>CTRL-EVENT-DSCP-POLICY remove <policy_id>

- DSCP policy may get rejected due to invalid policy parameters. Ccontrol
  interface event message format for rejected policy.

  <3>CTRL-EVENT-DSCP-POLICY reject <policy_id>

- Control interface event message format to indicate end of DSCP request.

  <3>CTRL-EVENT-DSCP-POLICY request_end

- External applications shall clear active DSCP policies upon receiving
  "CTRL-EVENT-DISCONNECTED" or "CTRL-EVENT-DSCP-POLICY clear_all" events.

- Control interface event message format to indicate wpa_supplicant started
  a timer to wait until the unsolicited DSCP request from the AP.

  <3>CTRL-EVENT-DSCP-POLICY request_wait start

- Control interface event message format to indicate timeout to receive the
  unsolicited DSCP request. This event is expected only when an unsolicited
  DSCP request is not received from the AP before timeout.

  <3>CTRL-EVENT-DSCP-POLICY request_wait end

DSCP Response:
A QoS Management STA that enables DSCP Policy capability shall respond
with DSCP response on receipt of a successful DSCP request from its
associated AP.  wpa_supplicant sends DSCP policy response based on the
control interface command received from the user is as below:

DSCP_RESP <[reset]>/<[solicited] [policy_id=1 status=0...]> [more]

DSCP Query:
DSCP Policy Query enables a STA to query its associated AP for DSCP
policies applicable to the STA. Currently, this includes support to send
a wildcard DSCP query or a DSCP query with a single domain name
attribute. The command format for the DSCP query command is as follows:
DSCP_QUERY <wildcard>/<domain_name=<string>>

Device Provisioning Protocol (DPP)
==================================

This document describes how the Device Provisioning Protocol (DPP)
implementation in wpa_supplicant and hostapd can be configured and how
the STA device and AP can be configured to connect each other using DPP
Connector mechanism.

Introduction to DPP
-------------------

Device Provisioning Protocol (also known as Wi-Fi Easy Connect) allows
enrolling of interface-less devices in a secure Wi-Fi network using many
methods like QR code based authentication (detailed below), PKEX based
authentication (password with in-band provisioning), etc. In DPP a
Configurator is used to provide network credentials to the devices. The
three phases of DPP connection are authentication, configuration and
network introduction.

More information about Wi-Fi Easy Connect is available from this Wi-Fi
Alliance web page:
https://www.wi-fi.org/discover-wi-fi/wi-fi-easy-connect

Build config setup
------------------

The following parameters must be included in the config file used to
compile hostapd and wpa_supplicant.

wpa_supplicant build config
---------------------------

Enable DPP in wpa_supplicant build config file

CONFIG_DPP=y

hostapd build config
--------------------

Enable DPP in hostapd build config file

CONFIG_DPP=y

Configurator build config
-------------------------

Any STA or AP device can act as a Configurator. Enable DPP in build
config. For an AP to act as a Configurator, Interworking needs to be
enabled for GAS. For wpa_supplicant it is not required.

CONFIG_INTERWORKING=y


Sample supplicant config file before provisioning
-------------------------------------------------

ctrl_interface=DIR=/var/run/wpa_supplicant
ctrl_interface_group=0
update_config=1
pmf=2
dpp_config_processing=2

Sample hostapd config file before provisioning
----------------------------------------------

interface=wlan0
driver=nl80211
ctrl_interface=/var/run/hostapd
ssid=test
channel=1
wpa=2
wpa_key_mgmt=DPP
ieee80211w=1
wpa_pairwise=CCMP
rsn_pairwise=CCMP


Pre-requisites
--------------

It is assumed that an AP and client station are up by running hostapd
and wpa_supplicant using respective config files.


Creating Configurator
---------------------

Add a Configurator over the control interface (wpa_cli/hostapd_cli)

> dpp_configurator_add
(returns id)

To get key of Configurator
> dpp_configurator_get_key <id>


How to configure an Enrollee using Configurator
-----------------------------------------------

On Enrollee side:

Generate QR code for the device. Store the QR code id returned by the
command.

> dpp_bootstrap_gen type=qrcode mac=<mac-address-of-device> chan=<operating-class/channel> key=<key of the device>
(Returns bootstrapping info id. If the key parameter is not included, a new key
is generated automatically. The MAC address is specified without octet
separating colons. The channel list includes the possible channels on which the
device is waiting. This uses global operating classes; e.g., 81/1 is the 2.4
GHz channel 1 on 2412 MHz.)

Get URI for the QR Code of device using the bootstrap info id.
> dpp_bootstrap_get_uri <bootstrap-id>

Make device listen to DPP request. The central frequency of the 2.4 GHz
band channel 1 is 2412 MHz) in case the Enrollee is a client device. An
AP as an Enrollee is listening on its operating channel.

> dpp_listen <frequency>

On Configurator side:

Enter the QR Code in the Configurator.
> dpp_qr_code "<URI-from-QR-Code-read-from-enrollee>"

On successfully adding QR Code, a bootstrapping info id is returned.

Send provisioning request to Enrollee. (conf is ap-dpp if Enrollee is an
AP. conf is sta-dpp if Enrollee is a client)
> dpp_auth_init peer=<qr-code-id> conf=<ap-dpp|sta-dpp> ssid=<SSID hexdump> configurator=<configurator-id>
or for legacy (PSK/SAE) provisioning for a station Enrollee:
> dpp_auth_init peer=<qr-code-id> conf=sta-psk ssid=<SSID hexdump> pass=<passphrase hexdump>

The DPP values will be printed in the console. Save these values into the
config file. If the Enrollee is an AP, we need to manually write these
values to the hostapd config file. If the Enrollee is a client device,
these details can be automatically saved to config file using the
following command.

> save_config

To set values in runtime for AP enrollees

> set dpp_connector <Connector-value-printed-on-console>
> set dpp_csign <csign-value-on-console>
> set dpp_netaccesskey <netaccess-value-on-console>

To set values in runtime for client enrollees, set dpp_config_processing
to 2 in wpa_supplicant conf file.

Once the values are set in run-time (if not set in run-time, but saved
in config files, they are taken up in next restart), the client device
will automatically connect to the already provisioned AP and connection
will be established.


Self-configuring a device
-------------------------

It is possible for a device to configure itself if it is the
Configurator for the network.

Create a Configurator in the device and use the dpp_configurator_sign
command to get DPP credentials.

> dpp_configurator_add
(returns configurator id)
> dpp_configurator_sign conf=<ap-dpp|sta-dpp> configurator=<configurator-id> ssid=<SSID hexdump>


Sample AP configuration files after provisioning
------------------------------------------------

interface=wlan0
driver=nl80211
ctrl_interface=/var/run/hostapd
ssid=test
channel=1
wpa=2
wpa_key_mgmt=DPP
ieee80211w=1
wpa_pairwise=CCMP
rsn_pairwise=CCMP
dpp_connector=<Connector value provided by Configurator>
dpp_csign=<C-Sign-Key value provided by Configurator>
dpp_netaccesskey=<Net access key provided by Configurator>


Sample station configuration file after provisioning
----------------------------------------------------

ctrl_interface=DIR=/var/run/wpa_supplicant
ctrl_interface_group=0
update_config=1
pmf=2
dpp_config_processing=2
network={
	ssid="test"
	key_mgmt=DPP
	ieee80211w=2
	dpp_connector="<Connector value provided by Configurator>"
	dpp_netaccesskey=<Net access key provided by Configurator>
	dpp_csign=<C-sign-key value provided by Configurator>
}

wpa_supplicant and Hotspot 2.0
==============================

This document describe how the IEEE 802.11u Interworking and Wi-Fi
Hotspot 2.0 (Release 1) implementation in wpa_supplicant can be
configured and how an external component on the client e.g., management
GUI or Wi-Fi framework) is used to manage this functionality.


Introduction to Wi-Fi Hotspot 2.0
---------------------------------

Hotspot 2.0 is the name of the Wi-Fi Alliance specification that is used
in the Wi-Fi CERTIFIED Passpoint<TM> program. More information about
this is available in this white paper:

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

The Hotspot 2.0 specification is also available from WFA:
https://www.wi-fi.org/knowledge-center/published-specifications

The core Interworking functionality (network selection, GAS/ANQP) were
standardized in IEEE Std 802.11u-2011 which is now part of the IEEE Std
802.11-2012.


wpa_supplicant network selection
--------------------------------

Interworking support added option for configuring credentials that can
work with multiple networks as an alternative to configuration of
network blocks (e.g., per-SSID parameters). When requested to perform
network selection, wpa_supplicant picks the highest priority enabled
network block or credential. If a credential is picked (based on ANQP
information from APs), a temporary network block is created
automatically for the matching network. This temporary network block is
used similarly to the network blocks that can be configured by the user,
but it is not stored into the configuration file and is meant to be used
only for temporary period of time since a new one can be created
whenever needed based on ANQP information and the credential.

By default, wpa_supplicant is not using automatic network selection
unless requested explicitly with the interworking_select command. This
can be changed with the auto_interworking=1 parameter to perform network
selection automatically whenever trying to find a network for connection
and none of the enabled network blocks match with the scan results. This
case works similarly to "interworking_select auto", i.e., wpa_supplicant
will internally determine which network or credential is going to be
used based on configured priorities, scan results, and ANQP information.


wpa_supplicant configuration
----------------------------

Interworking and Hotspot 2.0 functionality are optional components that
need to be enabled in the wpa_supplicant build configuration
(.config). This is done by adding following parameters into that file:

CONFIG_INTERWORKING=y
CONFIG_HS20=y

It should be noted that this functionality requires a driver that
supports GAS/ANQP operations. This uses the same design as P2P, i.e.,
Action frame processing and building in user space within
wpa_supplicant. The Linux nl80211 driver interface provides the needed
functionality for this.


There are number of run-time configuration parameters (e.g., in
wpa_supplicant.conf when using the configuration file) that can be used
to control Hotspot 2.0 operations.

# Enable Interworking
interworking=1

# Enable Hotspot 2.0
hs20=1

# Parameters for controlling scanning

# Homogeneous ESS identifier
# If this is set, scans will be used to request response only from BSSes
# belonging to the specified Homogeneous ESS. This is used only if interworking
# is enabled.
#hessid=00:11:22:33:44:55

# Access Network Type
# When Interworking is enabled, scans can be limited to APs that advertise the
# specified Access Network Type (0..15; with 15 indicating wildcard match).
# This value controls the Access Network Type value in Probe Request frames.
#access_network_type=15

# Automatic network selection behavior
# 0 = do not automatically go through Interworking network selection
#     (i.e., require explicit interworking_select command for this; default)
# 1 = perform Interworking network selection if one or more
#     credentials have been configured and scan did not find a
#     matching network block
#auto_interworking=0


Credentials can be pre-configured for automatic network selection:

# credential block
#
# Each credential used for automatic network selection is configured as a set
# of parameters that are compared to the information advertised by the APs when
# interworking_select and interworking_connect commands are used.
#
# credential fields:
#
# temporary: Whether this credential is temporary and not to be saved
#
# priority: Priority group
#	By default, all networks and credentials get the same priority group
#	(0). This field can be used to give higher priority for credentials
#	(and similarly in struct wpa_ssid for network blocks) to change the
#	Interworking automatic networking selection behavior. The matching
#	network (based on either an enabled network block or a credential)
#	with the highest priority value will be selected.
#
# pcsc: Use PC/SC and SIM/USIM card
#
# realm: Home Realm for Interworking
#
# username: Username for Interworking network selection
#
# password: Password for Interworking network selection
#
# ca_cert: CA certificate for Interworking network selection
#
# client_cert: File path to client certificate file (PEM/DER)
#	This field is used with Interworking networking selection for a case
#	where client certificate/private key is used for authentication
#	(EAP-TLS). Full path to the file should be used since working
#	directory may change when wpa_supplicant is run in the background.
#
#	Alternatively, a named configuration blob can be used by setting
#	this to blob://blob_name.
#
# private_key: File path to client private key file (PEM/DER/PFX)
#	When PKCS#12/PFX file (.p12/.pfx) is used, client_cert should be
#	commented out. Both the private key and certificate will be read
#	from the PKCS#12 file in this case. Full path to the file should be
#	used since working directory may change when wpa_supplicant is run
#	in the background.
#
#	Windows certificate store can be used by leaving client_cert out and
#	configuring private_key in one of the following formats:
#
#	cert://substring_to_match
#
#	hash://certificate_thumbprint_in_hex
#
#	For example: private_key="hash://63093aa9c47f56ae88334c7b65a4"
#
#	Note that when running wpa_supplicant as an application, the user
#	certificate store (My user account) is used, whereas computer store
#	(Computer account) is used when running wpasvc as a service.
#
#	Alternatively, a named configuration blob can be used by setting
#	this to blob://blob_name.
#
# private_key_passwd: Password for private key file
#
# imsi: IMSI in <MCC> | <MNC> | '-' | <MSIN> format
#
# milenage: Milenage parameters for SIM/USIM simulator in <Ki>:<OPc>:<SQN>
#	format
#
# imsi_privacy_cert: IMSI privacy certificate (PEM encoded X.509v3 certificate)
#	This field is used with EAP-SIM/AKA/AKA' to encrypt the permanent
#	identity (IMSI) to improve privacy. The X.509v3 certificate needs to
#	include a 2048-bit RSA public key and this is from the operator who
#	authenticates the SIM/USIM.
# imsi_privacy_attr: IMSI privacy attribute
#	This field is used to help the EAP-SIM/AKA/AKA' server to identify
#	the used certificate (and as such, the matching private key). This
#	is set to an attribute in name=value format if the operator needs
#	this information.
#
# domain_suffix_match: Constraint for server domain name
#	If set, this FQDN is used as a suffix match requirement for the AAA
#	server certificate in SubjectAltName dNSName element(s). If a
#	matching dNSName is found, this constraint is met. If no dNSName
#	values are present, this constraint is matched against SubjectName CN
#	using same suffix match comparison. Suffix match here means that the
#	host/domain name is compared one label at a time starting from the
#	top-level domain and all the labels in @domain_suffix_match shall be
#	included in the certificate. The certificate may include additional
#	sub-level labels in addition to the required labels.
#
#	For example, domain_suffix_match=example.com would match
#	test.example.com but would not match test-example.com.
#
# domain: Home service provider FQDN(s)
#	This is used to compare against the Domain Name List to figure out
#	whether the AP is operated by the Home SP. Multiple domain entries can
#	be used to configure alternative FQDNs that will be considered home
#	networks.
#
# home_ois: Home OI(s)
#	This string field contains one or more comma delimited OIs (hexdump)
#	identifying the access the access points that support authentication
#	with this credential. There are an alternative to the use of the realm
#	parameter. When using Home OIs to match the network, the EAP parameters
#	need to be pre-configured with the credentials since the NAI Realm
#	information may not be available or fetched.
#	A successful authentication with the access point is possible as soon
#	as at least one Home OI from the list matches an OI in the Roaming
#	Consortium advertised by the access point.
#	(Hotspot 2.0 PerProviderSubscription/<X+>/HomeSP/HomeOIList/<X+>/HomeOI)
#
# required_home_ois: Required Home OI(s)
#	This string field contains the set of Home OI(s) (hexdump) that are
#	required to be advertised by the AP for the credential to be considered
#	matching.
#	(Hotspot 2.0 PerProviderSubscription/<X+>/HomeSP/HomeOIList/<X+>/HomeOIRequired)
#
# roaming_consortium: Roaming Consortium OI
#	Deprecated: use home_ois instead.
#	If roaming_consortium_len is non-zero, this field contains the
#	Roaming Consortium OI that can be used to determine which access
#	points support authentication with this credential. This is an
#	alternative to the use of the realm parameter. When using Roaming
#	Consortium to match the network, the EAP parameters need to be
#	pre-configured with the credential since the NAI Realm information
#	may not be available or fetched.
#
# required_roaming_consortium: Required Roaming Consortium OI
#	Deprecated: use required_home_ois instead.
#	If required_roaming_consortium_len is non-zero, this field contains the
#	Roaming Consortium OI that is required to be advertised by the AP for
#	the credential to be considered matching.
#
# roaming_consortiums: Roaming Consortium OI(s) memberships
#	This string field contains one or more comma delimited OIs (hexdump)
#	identifying the roaming consortiums of which the provider is a member.
#	The list is sorted from the most preferred one to the least preferred
#	one. A match between the Roaming Consortium OIs advertised by an AP and
#	the OIs in this list indicates that successful authentication is
#	possible.
#	(Hotspot 2.0 PerProviderSubscription/<X+>/HomeSP/RoamingConsortiumOI)
#
# eap: Pre-configured EAP method
#	This optional field can be used to specify which EAP method will be
#	used with this credential. If not set, the EAP method is selected
#	automatically based on ANQP information (e.g., NAI Realm).
#
# phase1: Pre-configure Phase 1 (outer authentication) parameters
#	This optional field is used with like the 'eap' parameter.
#
# phase2: Pre-configure Phase 2 (inner authentication) parameters
#	This optional field is used with like the 'eap' parameter.
#
# excluded_ssid: Excluded SSID
#	This optional field can be used to excluded specific SSID(s) from
#	matching with the network. Multiple entries can be used to specify more
#	than one SSID.
#
# roaming_partner: Roaming partner information
#	This optional field can be used to configure preferences between roaming
#	partners. The field is a string in following format:
#	<FQDN>,<0/1 exact match>,<priority>,<* or country code>
#	(non-exact match means any subdomain matches the entry; priority is in
#	0..255 range with 0 being the highest priority)
#
# update_identifier: PPS MO ID
#	(Hotspot 2.0 PerProviderSubscription/UpdateIdentifier)
#
# provisioning_sp: FQDN of the SP that provisioned the credential
#	This optional field can be used to keep track of the SP that provisioned
#	the credential to find the PPS MO (./Wi-Fi/<provisioning_sp>).
#
# sp_priority: Credential priority within a provisioning SP
#	This is the priority of the credential among all credentials
#	provisioned by the same SP (i.e., for entries that have identical
#	provisioning_sp value). The range of this priority is 0-255 with 0
#	being the highest and 255 the lower priority.
#
# Minimum backhaul threshold (PPS/<X+>/Policy/MinBackhauldThreshold/*)
#	These fields can be used to specify minimum download/upload backhaul
#	bandwidth that is preferred for the credential. This constraint is
#	ignored if the AP does not advertise WAN Metrics information or if the
#	limit would prevent any connection. Values are in kilobits per second.
# min_dl_bandwidth_home
# min_ul_bandwidth_home
# min_dl_bandwidth_roaming
# min_ul_bandwidth_roaming
#
# max_bss_load: Maximum BSS Load Channel Utilization (1..255)
#	(PPS/<X+>/Policy/MaximumBSSLoadValue)
#	This value is used as the maximum channel utilization for network
#	selection purposes for home networks. If the AP does not advertise
#	BSS Load or if the limit would prevent any connection, this constraint
#	will be ignored.
#
# req_conn_capab: Required connection capability
#	(PPS/<X+>/Policy/RequiredProtoPortTuple)
#	This value is used to configure set of required protocol/port pairs that
#	a roaming network shall support (include explicitly in Connection
#	Capability ANQP element). This constraint is ignored if the AP does not
#	advertise Connection Capability or if this constraint would prevent any
#	network connection. This policy is not used in home networks.
#	Format: <protocol>[:<comma-separated list of ports]
#	Multiple entries can be used to list multiple requirements.
#	For example, number of common TCP protocols:
#	req_conn_capab=6:22,80,443
#	For example, IPSec/IKE:
#	req_conn_capab=17:500
#	req_conn_capab=50
#
# ocsp: Whether to use/require OCSP to check server certificate
#	0 = do not use OCSP stapling (TLS certificate status extension)
#	1 = try to use OCSP stapling, but not require response
#	2 = require valid OCSP stapling response
#
# sim_num: Identifier for which SIM to use in multi-SIM devices
#
# engine: Whether to use an engine for private key operations (0/1)
# engine_id: String identifying the engine to use
# ca_cert_id: The CA certificate identifier when using an engine
# cert_id: The certificate identifier when using an engine
# key_id: The private key identifier when using an engine
#
# for example:
#
#cred={
#	realm="example.com"
#	username="user@example.com"
#	password="password"
#	ca_cert="/etc/wpa_supplicant/ca.pem"
#	domain="example.com"
#	domain_suffix_match="example.com"
#}
#
#cred={
#	imsi="310026-000000000"
#	milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82"
#}
#
#cred={
#	realm="example.com"
#	username="user"
#	password="password"
#	ca_cert="/etc/wpa_supplicant/ca.pem"
#	domain="example.com"
#	home_ois="223344"
#	roaming_consortiums="112233,4455667788,aabbcc"
#	eap=TTLS
#	phase2="auth=MSCHAPV2"
#}


Control interface
-----------------

wpa_supplicant provides a control interface that can be used from
external programs to manage various operations. The included command
line tool, wpa_cli, can be used for manual testing with this interface.

Following wpa_cli interactive mode commands show some examples of manual
operations related to Hotspot 2.0:

Remove configured networks and credentials:

> remove_network all
OK
> remove_cred all
OK


Add a username/password credential:

> add_cred
0
> set_cred 0 realm "mail.example.com"
OK
> set_cred 0 username "username"
OK
> set_cred 0 password "password"
OK
> set_cred 0 priority 1
OK
> set_cred 0 temporary 1
OK

Add a SIM credential using a simulated SIM/USIM card for testing:

> add_cred
1
> set_cred 1 imsi "23456-0000000000"
OK
> set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123"
OK
> set_cred 1 priority 1
OK

Note: the return value of add_cred is used as the first argument to
the following set_cred commands.

Add a SIM credential using a external SIM/USIM processing:

> set external_sim 1
OK
> add_cred
1
> set_cred 1 imsi "23456-0000000000"
OK
> set_cred 1 eap SIM
OK


Add a WPA2-Enterprise network:

> add_network
0
> set_network 0 key_mgmt WPA-EAP
OK
> set_network 0 ssid "enterprise"
OK
> set_network 0 eap TTLS
OK
> set_network 0 anonymous_identity "anonymous"
OK
> set_network 0 identity "user"
OK
> set_network 0 password "password"
OK
> set_network 0 priority 0
OK
> enable_network 0 no-connect
OK


Add an open network:

> add_network
3
> set_network 3 key_mgmt NONE
OK
> set_network 3 ssid "coffee-shop"
OK
> select_network 3
OK

Note: the return value of add_network is used as the first argument to
the following set_network commands.

The preferred credentials/networks can be indicated with the priority
parameter (1 is higher priority than 0).


Interworking network selection can be started with interworking_select
command. This instructs wpa_supplicant to run a network scan and iterate
through the discovered APs to request ANQP information from the APs that
advertise support for Interworking/Hotspot 2.0:

> interworking_select
OK
<3>Starting ANQP fetch for 02:00:00:00:01:00
<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
<3>ANQP fetch completed
<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown


INTERWORKING-AP event messages indicate the APs that support network
selection and for which there is a matching
credential. interworking_connect command can be used to select a network
to connect with:


> interworking_connect 02:00:00:00:01:00
OK
<3>CTRL-EVENT-SCAN-RESULTS
<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
<3>Associated with 02:00:00:00:01:00
<3>CTRL-EVENT-EAP-STARTED EAP authentication started
<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=]


wpa_supplicant creates a temporary network block for the selected
network based on the configured credential and ANQP information from the
AP:

> list_networks
network id / ssid / bssid / flags
0	Example Network	any	[CURRENT]
> get_network 0 key_mgmt
WPA-EAP
> get_network 0 eap
TTLS


Alternatively to using an external program to select the network,
"interworking_select auto" command can be used to request wpa_supplicant
to select which network to use based on configured priorities:


> remove_network all
OK
<3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1
> interworking_select auto
OK
<3>Starting ANQP fetch for 02:00:00:00:01:00
<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
<3>ANQP fetch completed
<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
<3>CTRL-EVENT-SCAN-RESULTS
<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
<3>Associated with 02:00:00:00:01:00
<3>CTRL-EVENT-EAP-STARTED EAP authentication started
<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=]


The connection status can be shown with the status command:

> status
bssid=02:00:00:00:01:00
ssid=Example Network
id=0
mode=station
pairwise_cipher=CCMP       <--- link layer security indication
group_cipher=CCMP
key_mgmt=WPA2/IEEE 802.1X/EAP
wpa_state=COMPLETED
p2p_device_address=02:00:00:00:00:00
address=02:00:00:00:00:00
hs20=1      <--- HS 2.0 indication
Supplicant PAE state=AUTHENTICATED
suppPortStatus=Authorized
EAP state=SUCCESS
selectedMethod=21 (EAP-TTLS)
EAP TLS cipher=AES-128-SHA
EAP-TTLSv0 Phase2 method=PAP


> status
bssid=02:00:00:00:02:00
ssid=coffee-shop
id=3
mode=station
pairwise_cipher=NONE
group_cipher=NONE
key_mgmt=NONE
wpa_state=COMPLETED
p2p_device_address=02:00:00:00:00:00
address=02:00:00:00:00:00


Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status
command output. Link layer security is indicated with the
pairwise_cipher (CCMP = secure, NONE = no encryption used).


Also the scan results include the Hotspot 2.0 indication:

> scan_results
bssid / frequency / signal level / flags / ssid
02:00:00:00:01:00	2412	-30	[WPA2-EAP-CCMP][ESS][HS20]	Example Network


ANQP information for the BSS can be fetched using the BSS command:

> bss 02:00:00:00:01:00
id=1
bssid=02:00:00:00:01:00
freq=2412
beacon_int=100
capabilities=0x0411
qual=0
noise=-92
level=-30
tsf=1345573286517276
age=105
ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000
flags=[WPA2-EAP-CCMP][ESS][HS20]
ssid=Example Network
anqp_roaming_consortium=031122330510203040500601020304050603fedcba


ANQP queries can also be requested with the anqp_get and hs20_anqp_get
commands:

> anqp_get 02:00:00:00:01:00 261
OK
<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
> hs20_anqp_get 02:00:00:00:01:00 2
OK
<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List

In addition, fetch_anqp command can be used to request similar set of
ANQP queries to be done as is run as part of interworking_select:

> scan
OK
<3>CTRL-EVENT-SCAN-RESULTS
> fetch_anqp
OK
<3>Starting ANQP fetch for 02:00:00:00:01:00
<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
<3>ANQP fetch completed


Hotspot 2.0 Rel 2 online signup and OSEN
----------------------------------------

Following parameters can be used to create a network profile for
link-layer protected Hotspot 2.0 online signup connection with
OSEN. Note that ssid and identify (NAI) values need to be set based on
the information for the selected provider in the OSU Providers list
ANQP-element.

network={
    ssid="HS 2.0 OSU"
    proto=OSEN
    key_mgmt=OSEN
    pairwise=CCMP
    group=GTK_NOT_USED
    eap=WFA-UNAUTH-TLS
    identity="anonymous@example.com"
    ca_cert="osu-ca.pem"
    ocsp=2
}


Hotspot 2.0 connection with external network selection
------------------------------------------------------

When a component controlling wpa_supplicant takes care of Interworking
network selection, following configuration and network profile
parameters can be used to configure a temporary network profile for a
Hotspot 2.0 connection (e.g., with SET, ADD_NETWORK, SET_NETWORK, and
SELECT_NETWORK control interface commands):

interworking=1
hs20=1
auto_interworking=0

network={
    ssid="test-hs20"
    proto=RSN
    key_mgmt=WPA-EAP
    pairwise=CCMP
    anonymous_identity="anonymous@example.com"
    identity="hs20-test@example.com"
    password="password"
    ca_cert="ca.pem"
    eap=TTLS
    phase2="auth=MSCHAPV2"
    update_identifier=54321
    roaming_consortium_selection=112233
    #ocsp=2
}


These parameters are set based on the PPS MO credential and/or NAI Realm
list ANQP-element:

anonymous_identity: Credential/UsernamePassword/Username with username part
		    replaced with "anonymous"
identity: Credential/UsernamePassword/Username
password: Credential/UsernamePassword/Password
update_identifier: PPS/UpdateIdentifier
ca_cert: from the downloaded trust root based on PPS information
eap: Credential/UsernamePassword/EAPMethod or NAI Realm list
phase2: Credential/UsernamePassword/EAPMethod or NAI Realm list
roaming_consortium_selection: Matching OI from HomeSP/RoamingConsortiumOI
ocsp: Credential/CheckAAAServerCertStatus

wpa_supplicant and Wi-Fi P2P
============================

This document describes how the Wi-Fi P2P implementation in
wpa_supplicant can be configured and how an external component on the
client (e.g., management GUI) is used to enable WPS enrollment and
registrar registration.


Introduction to Wi-Fi P2P
-------------------------

TODO

More information about Wi-Fi P2P is available from Wi-Fi Alliance:
http://www.wi-fi.org/Wi-Fi_Direct.php


wpa_supplicant implementation
-----------------------------

TODO


wpa_supplicant configuration
----------------------------

Wi-Fi P2P is an optional component that needs to be enabled in the
wpa_supplicant build configuration (.config). Here is an example
configuration that includes Wi-Fi P2P support and Linux nl80211
-based driver interface:

CONFIG_DRIVER_NL80211=y
CONFIG_CTRL_IFACE=y
CONFIG_P2P=y
CONFIG_AP=y
CONFIG_WPS=y


In run-time configuration file (wpa_supplicant.conf), some parameters
for P2P may be set. In order to make the devices easier to recognize,
device_name and device_type should be specified. For example,
something like this should be included:

ctrl_interface=/var/run/wpa_supplicant
device_name=My P2P Device
device_type=1-0050F204-1


wpa_cli
-------

Actual Wi-Fi P2P operations are requested during runtime. These can be
done for example using wpa_cli (which is described below) or a GUI
like wpa_gui-qt4.


wpa_cli starts in interactive mode if no command string is included on
the command line. By default, it will select the first network interface
that it can find (and that wpa_supplicant controls). If more than one
interface is in use, it may be necessary to select one of the explicitly
by adding -i argument on the command line (e.g., 'wpa_cli -i wlan1').

Most of the P2P operations are done on the main interface (e.g., the
interface that is automatically added when the driver is loaded, e.g.,
wlan0). When using a separate virtual interface for group operations
(e.g., wlan1), the control interface for that group interface may need
to be used for some operations (mainly WPS activation in GO). This may
change in the future so that all the needed operations could be done
over the main control interface.

Device Discovery

p2p_find [timeout in seconds] [type=<social|progressive>] \
	[dev_id=<addr>] [dev_type=<device type>] \
	[delay=<search delay in ms>] [seek=<service name>] [freq=<MHz>]

The default behavior is to run a single full scan in the beginning and
then scan only social channels. type=social will scan only social
channels, i.e., it skips the initial full scan. type=progressive is
like the default behavior, but it will scan through all the channels
progressively one channel at the time in the Search state rounds. This
will help in finding new groups or groups missed during the initial
full scan. When the type parameter is not included (i.e., full scan), the
optional freq parameter can be used to override the first scan to use only
the specified channel after which only social channels are scanned.

The optional dev_id option can be used to specify a single P2P peer to
search for. The optional delay parameter can be used to request an extra
delay to be used between search iterations (e.g., to free up radio
resources for concurrent operations).

The optional dev_type option can be used to specify a single device type
(primary or secondary) to search for, e.g.,
"p2p_find dev_type=1-0050F204-1".


With one or more seek arguments, the command sends Probe Request frames
for a P2PS service. For example,
p2p_find 5 dev_id=11:22:33:44:55:66 seek=alt.example.chat seek=alt.example.video

Parameters description:
    Timeout - Optional ASCII base-10-encoded u16. If missing, request will not
	time out and must be canceled manually
    dev_id - Optional to request responses from a single known remote device
    Service Name - Mandatory UTF-8 string for ASP seeks
	Service name must match the remote service being advertised exactly
	(no prefix matching).
	Service name may be empty, in which case all ASP services will be
	returned, and may be filtered with p2p_serv_disc_req settings, and
	p2p_serv_asp_resp results.
	Multiple service names may be requested, but if it exceeds internal
	limit, it will automatically revert to requesting all ASP services.

p2p_listen [timeout in seconds]

Start Listen-only state (become discoverable without searching for
other devices). Optional parameter can be used to specify the duration
for the Listen operation in seconds. This command may not be of that
much use during normal operations and is mainly designed for
testing. It can also be used to keep the device discoverable without
having to maintain a group.

p2p_stop_find

Stop ongoing P2P device discovery or other operation (connect, listen
mode).

p2p_flush

Flush P2P peer table and state.

Group Formation

p2p_prov_disc <peer device address> <display|keypad|pbc> [join|auto]

Send P2P provision discovery request to the specified peer. The
parameters for this command are the P2P device address of the peer and
the desired configuration method. For example, "p2p_prov_disc
02:01:02:03:04:05 display" would request the peer to display a PIN for
us and "p2p_prov_disc 02:01:02:03:04:05 keypad" would request the peer
to enter a PIN that we display.

The optional "join" parameter can be used to indicate that this command
is requesting an already running GO to prepare for a new client. This is
mainly used with "display" to request it to display a PIN. The "auto"
parameter can be used to request wpa_supplicant to automatically figure
out whether the peer device is operating as a GO and if so, use
join-a-group style PD instead of GO Negotiation style PD.

p2p_connect <peer device address> <pbc|pin|PIN#|p2ps> [display|keypad|p2ps]
	[persistent|persistent=<network id>] [join|auth]
	[go_intent=<0..15>] [freq=<in MHz>] [ht40] [vht] [he] [provdisc] [auto]
	[ssid=<hexdump>]

Start P2P group formation with a discovered P2P peer. This includes
optional group owner negotiation, group interface setup, provisioning,
and establishing data connection.

The <pbc|pin|PIN#> parameter specifies the WPS provisioning
method. "pbc" string starts pushbutton method, "pin" string start PIN
method using an automatically generated PIN (which will be returned as
the command return code), PIN# means that a pre-selected PIN can be
used (e.g., 12345670). [display|keypad] is used with PIN method
to specify which PIN is used (display=dynamically generated random PIN
from local display, keypad=PIN entered from peer display). "persistent"
parameter can be used to request a persistent group to be formed. The
"persistent=<network id>" alternative can be used to pre-populate
SSID/passphrase configuration based on a previously used persistent
group where this device was the GO. The previously used parameters will
then be used if the local end becomes the GO in GO Negotiation (which
can be forced with go_intent=15).

"join" indicates that this is a command to join an existing group as a
client. It skips the GO Negotiation part. This will send a Provision
Discovery Request message to the target GO before associating for WPS
provisioning.

"auth" indicates that the WPS parameters are authorized for the peer
device without actually starting GO Negotiation (i.e., the peer is
expected to initiate GO Negotiation). This is mainly for testing
purposes.

"go_intent" can be used to override the default GO Intent for this GO
Negotiation.

"freq" can be used to set a forced operating channel (e.g., freq=2412
to select 2.4 GHz channel 1).

"provdisc" can be used to request a Provision Discovery exchange to be
used prior to starting GO Negotiation as a workaround with some deployed
P2P implementations that require this to allow the user to accept the
connection.

"auto" can be used to request wpa_supplicant to automatically figure
out whether the peer device is operating as a GO and if so, use
join-a-group operation rather than GO Negotiation.

"ssid=<hexdump>" can be used to specify the Group SSID for join
operations. This allows the P2P Client interface to filter scan results
based on SSID to avoid selecting an incorrect BSS entry in case the same
P2P Device or Interface address have been used in multiple groups
recently.

P2PS attribute changes to p2p_connect command:

P2PS supports two WPS provisioning methods namely PIN method and P2PS default.
The remaining parameters hold same role as in legacy P2P. In case of P2PS
default config method "p2ps" keyword is added in p2p_connect command.

For example:
p2p_connect 02:0a:f5:85:11:00 12345670 p2ps persistent join
	(WPS Method = P2PS default)

p2p_connect 02:0a:f5:85:11:00 45629034 keypad persistent
	(WPS Method = PIN)

p2p_asp_provision <peer MAC address> <adv_id=peer adv id>
	<adv_mac=peer MAC address> [role=2|4|1] <session=session id>
	<session_mac=initiator mac address>
	[info='service info'] <method=Default|keypad|Display>

This command starts provision discovery with the P2PS enabled peer device.

For example,
p2p_asp_provision 00:11:22:33:44:55 adv_id=4d6fc7 adv_mac=00:55:44:33:22:11 role=1 session=12ab34 session_mac=00:11:22:33:44:55 info='name=john' method=1000

Parameter description:
    MAC address - Mandatory
    adv_id - Mandatory remote Advertising ID of service connection is being
	established for
    adv_mac - Mandatory MAC address that owns/registered the service
    role - Optional
	2 (group client only) or 4 (group owner only)
	if not present (or 1) role is negotiated by the two peers.
    session - Mandatory Session ID of the first session to be established
    session_mac - Mandatory MAC address that owns/initiated the session
    method - Optional method to request for provisioning (1000 - P2PS Default,
	100 - Keypad(PIN), 8 - Display(PIN))
    info - Optional UTF-8 string. Hint for service to indicate possible usage
	parameters - Escape single quote & backslash:
	with a backslash 0x27 == ' == \', and 0x5c == \ == \\

p2p_asp_provision_resp <peer mac address> <adv_id= local adv id>
	<adv_mac=local MAC address> <role=1|2|4> <status=0>
	<session=session id> <session_mac=peer MAC address>

This command sends a provision discovery response from responder side.

For example,
p2p_asp_provision_resp 00:55:44:33:22:11 adv_id=4d6fc7 adv_mac=00:55:44:33:22:11 role=1 status=0 session=12ab34 session_mac=00:11:22:33:44:55

Parameters definition:
    MAC address - Mandatory
    adv_id - Mandatory local Advertising ID of service connection is being
	established for
    adv_mac - Mandatory MAC address that owns/registered the service
    role -  Optional 2 (group client only) or 4 (group owner only)
	if not present (or 1) role is negotiated by the two peers.
    status - Mandatory Acceptance/Rejection code of Provisioning
    session - Mandatory Session ID of the first session to be established
    session_mac - Mandatory MAC address that owns/initiated the session

p2p_group_add [persistent|persistent=<network id>] [freq=<freq in MHz>]
	[ht40] [vht] [he]

Set up a P2P group owner manually (i.e., without group owner
negotiation with a specific peer). This is also known as autonomous
GO. Optional persistent=<network id> can be used to specify restart of
a persistent group. Optional freq=<freq in MHz> can be used to force
the GO to be started on a specific frequency. Special freq=2 or freq=5
options can be used to request the best 2.4 GHz or 5 GHz band channel
to be selected automatically.

p2p_reject <peer device address>

Reject connection attempt from a peer (specified with a device
address). This is a mechanism to reject a pending GO Negotiation with
a peer and request to automatically block any further connection or
discovery of the peer.

p2p_group_remove <group interface>

Terminate a P2P group. If a new virtual network interface was used for
the group, it will also be removed. The network interface name of the
group interface is used as a parameter for this command.

p2p_cancel

Cancel an ongoing P2P group formation and joining-a-group related
operation. This operation unauthorizes the specific peer device (if any
had been authorized to start group formation), stops P2P find (if in
progress), stops pending operations for join-a-group, and removes the
P2P group interface (if one was used) that is in the WPS provisioning
step. If the WPS provisioning step has been completed, the group is not
terminated.

p2p_remove_client <peer's P2P Device Address|iface=<interface address>>

This command can be used to remove the specified client from all groups
(operating and persistent) from the local GO. Note that the peer device
can rejoin the group if it is in possession of a valid key. See p2p_set
per_sta_psk command below for more details on how the peer can be
removed securely.

Service Discovery

p2p_service_add asp <auto accept> <adv id> <status 0/1> <Config Methods>
	<Service name> [Service Information] [Response Info]

This command can be used to search for a P2PS service which includes
Play, Send, Display, and Print service. The parameters for this command
are "asp" to identify the command as P2PS one, auto accept value,
advertisement id which uniquely identifies the service requests, state
of the service whether the service is available or not, config methods
which can be either P2PS method or PIN method, service name followed by
two optional parameters service information, and response info.

For example,
p2p_service_add asp 1 4d6fc7 0 1108 alt.example.chat svc_info='name=john' rsp_info='enter PIN 1234'

Parameters definition:
    asp - Mandatory for ASP service registration
    auto accept - Mandatory ASCII hex-encoded boolean (0 == no auto-accept,
	1 == auto-accept ANY role, 2 == auto-accept CLIENT role,
	4 == auto-accept GO role)
    Advertisement ID - Mandatory non-zero ASCII hex-encoded u32
	(Must be unique/not yet exist in svc db)
    State - Mandatory ASCII hex-encoded u8 (0 -- Svc not available,
	1 -- Svc available, 2-0xff  Application defined)
    Config Methods - Mandatory ASCII hex-encoded u16 (bitmask of WSC config
	methods)
    Service Name - Mandatory UTF-8 string
    Service Information - Optional UTF-8 string
	Escape single quote & backslash with a backslash:
	0x27 == ' == \', and 0x5c == \ == \\
    Session response information -  Optional (used only if auto accept is TRUE)
	UTF-8 string
	Escape single quote & backslash with a backslash:
	0x27 == ' == \', and 0x5c == \ == \\

p2p_service_rep asp <auto accept> <adv id> <status 0/1> <Config Methods>
	<Service name> [Service Information] [Response Info]

This command can be used to replace the existing service request
attributes from the initiator side. The replacement is only allowed if
the advertisement id issued in the command matches with any one entry in
the list of existing SD queries. If advertisement id doesn't match the
command returns a failure.

For example,
p2p_service_rep asp 1 4d6fc7 1 1108 alt.example.chat svc_info='name=john' rsp_info='enter PIN 1234'

Parameters definition:
    asp - Mandatory for ASP service registration
    auto accept - Mandatory ASCII hex-encoded boolean (1 == true, 0 == false)
    Advertisement ID - Mandatory non-zero ASCII hex-encoded u32
	(Must already exist in svc db)
    State - Mandatory ASCII hex-encoded u8 (can be used to indicate svc
	available or not available for instance)
    Config Methods - Mandatory ASCII hex-encoded u16 (bitmask of WSC config
	methods)
    Service Name - Mandatory UTF-8 string (Must match existing string in svc db)
    Service Information - Optional UTF-8 string
	Escape single quote & backslash with a backslash:
	0x27 == ' == \', and 0x5c == \ == \\
    Session response information -  Optional (used only if auto accept is TRUE)
	UTF-8 string
	Escape single quote & backslash with a backslash:
	0x27 == ' == \', and 0x5c == \ == \\

p2p_serv_disc_req

Schedule a P2P service discovery request. The parameters for this
command are the device address of the peer device (or 00:00:00:00:00:00
for wildcard query that is sent to every discovered P2P peer that
supports service discovery) and P2P Service Query TLV(s) as hexdump. For
example,

p2p_serv_disc_req 00:00:00:00:00:00 02000001

schedules a request for listing all available services of all service
discovery protocols and requests this to be sent to all discovered
peers (note: this can result in long response frames). The pending
requests are sent during device discovery (see p2p_find).

There can be multiple pending peer device specific queries (each will be
sent in sequence whenever the peer is found).

This command returns an identifier for the pending query (e.g.,
"1f77628") that can be used to cancel the request. Directed requests
will be automatically removed when the specified peer has replied to
it.

Service Query TLV has following format:
Length (2 octets, little endian) - length of following data
Service Protocol Type (1 octet) - see the table below
Service Transaction ID (1 octet) - nonzero identifier for the TLV
Query Data (Length - 2 octets of data) - service protocol specific data

Service Protocol Types:
0 = All service protocols
1 = Bonjour
2 = UPnP
3 = WS-Discovery
4 = Wi-Fi Display

For UPnP, an alternative command format can be used to specify a
single query TLV (i.e., a service discovery for a specific UPnP
service):

p2p_serv_disc_req 00:00:00:00:00:00 upnp <version hex> <ST: from M-SEARCH>

For example:

p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1

Additional examples for queries:

# list of all Bonjour services
p2p_serv_disc_req 00:00:00:00:00:00 02000101

# list of all UPnP services
p2p_serv_disc_req 00:00:00:00:00:00 02000201

# list of all WS-Discovery services
p2p_serv_disc_req 00:00:00:00:00:00 02000301

# list of all Bonjour and UPnP services
p2p_serv_disc_req 00:00:00:00:00:00 0200010102000202

# Apple File Sharing over TCP
p2p_serv_disc_req 00:00:00:00:00:00 130001010b5f6166706f766572746370c00c000c01

# Bonjour SSTH (supported service type hash)
p2p_serv_disc_req 00:00:00:00:00:00 05000101000000

# UPnP examples
p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 ssdp:all
p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 upnp:rootdevice
p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:service:ContentDirectory:2
p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 uuid:6859dede-8574-59ab-9332-123456789012
p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1

# Wi-Fi Display examples
# format: wifi-display <list of roles> <list of subelements>
p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source] 2,3,4,5
p2p_serv_disc_req 02:01:02:03:04:05 wifi-display [pri-sink] 3
p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [sec-source] 2
p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source+sink] 2,3,4,5
p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source][pri-sink] 2,3,4,5

p2p_serv_disc_req <Unicast|Broadcast mac address> asp <Transaction ID>
	<Service Name> [Service Information]

The command can be used for service discovery for P2PS enabled devices.

For example: p2p_serv_disc_req 00:00:00:00:00:00 asp a1 alt.example 'john'

Parameters definition:
    MAC address - Mandatory Existing
    asp - Mandatory for ASP queries
    Transaction ID - Mandatory non-zero ASCII hex-encoded u8 for GAS
    Service Name Prefix - Mandatory UTF-8 string.
	Will match from beginning of remote Service Name
    Service Information Substring - Optional UTF-8 string
	If Service Information Substring is not included, all services matching
	Service Name Prefix will be returned.
	If Service Information Substring is included, both the Substring and the
	Service Name Prefix must match for service to be returned.
	If remote service has no Service Information, all Substring searches
	will fail.

p2p_serv_disc_cancel_req <query identifier>

Cancel a pending P2P service discovery request. This command takes a
single parameter: identifier for the pending query (the value returned
by p2p_serv_disc_req, e.g., "p2p_serv_disc_cancel_req 1f77628".

p2p_serv_disc_resp

Reply to a service discovery query. This command takes following
parameters: frequency in MHz, destination address, dialog token,
response TLV(s). The first three parameters are copied from the
request event. For example, "p2p_serv_disc_resp 2437 02:40:61:c2:f3:b7
1 0300000101". This command is used only if external program is used
to process the request (see p2p_serv_disc_external).

p2p_service_update

Indicate that local services have changed. This is used to increment
the P2P service indicator value so that peers know when previously
cached information may have changed. This is only needed when external
service discovery processing is enabled since the commands to
pre-configure services for internal processing will increment the
indicator automatically.

p2p_serv_disc_external <0|1>

Configure external processing of P2P service requests: 0 (default) =
no external processing of requests (i.e., internal code will process
each request based on pre-configured services), 1 = external
processing of requests (external program is responsible for replying
to service discovery requests with p2p_serv_disc_resp). Please note
that there is quite strict limit on how quickly the response needs to
be transmitted, so use of the internal processing is strongly
recommended.

p2p_service_add bonjour <query hexdump> <RDATA hexdump>

Add a local Bonjour service for internal SD query processing.

Examples:

# AFP Over TCP (PTR)
p2p_service_add bonjour 0b5f6166706f766572746370c00c000c01 074578616d706c65c027
# AFP Over TCP (TXT) (RDATA=null)
p2p_service_add bonjour 076578616d706c650b5f6166706f766572746370c00c001001 00

# IP Printing over TCP (PTR) (RDATA=MyPrinter._ipp._tcp.local.)
p2p_service_add bonjour 045f697070c00c000c01 094d795072696e746572c027
# IP Printing over TCP (TXT) (RDATA=txtvers=1,pdl=application/postscript)
p2p_service_add bonjour 096d797072696e746572045f697070c00c001001 09747874766572733d311a70646c3d6170706c69636174696f6e2f706f7374736372797074

# Supported Service Type Hash (SSTH)
p2p_service_add bonjour 000000 <32-byte bitfield as hexdump>
(note: see P2P spec Annex E.4 for information on how to construct the bitfield)

p2p_service_del bonjour <query hexdump>

Remove a local Bonjour service from internal SD query processing.

p2p_service_add upnp <version hex> <service>

Add a local UPnP service for internal SD query processing.

Examples:

p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::upnp:rootdevice
p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::upnp:rootdevice
p2p_service_add upnp 10 uuid:1122de4e-8574-59ab-9322-333456789044::urn:schemas-upnp-org:service:ContentDirectory:2
p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::urn:schemas-upnp-org:service:ContentDirectory:2
p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::urn:schemas-upnp-org:device:InternetGatewayDevice:1

p2p_service_del upnp <version hex> <service>

Remove a local UPnP service from internal SD query processing.

p2p_service_del asp <adv id>

Removes the local asp service from internal SD query list.
For example: p2p_service_del asp 4d6fc7

p2p_service_flush

Remove all local services from internal SD query processing.

Invitation

p2p_invite [persistent=<network id>|group=<group ifname>] [peer=address]
	[go_dev_addr=address] [freq=<freq in MHz>] [ht40] [vht] [he]
	[pref=<MHz>]

Invite a peer to join a group (e.g., group=wlan1) or to reinvoke a
persistent group (e.g., persistent=4). If the peer device is the GO of
the persistent group, the peer parameter is not needed. Otherwise it is
used to specify which device to invite. go_dev_addr parameter can be
used to override the GO device address for Invitation Request should
it be not known for some reason (this should not be needed in most
cases). When reinvoking a persistent group, the GO device can specify
the frequency for the group with the freq parameter. When reinvoking a
persistent group, the P2P client device can use freq parameter to force
a specific operating channel (or invitation failure if GO rejects that)
or pref parameter to request a specific channel (while allowing GO to
select to use another channel, if needed).

Group Operations

(These are used on the group interface.)

wps_pin <any|address> <PIN>

Start WPS PIN method. This allows a single WPS Enrollee to connect to
the AP/GO. This is used on the GO when a P2P client joins an existing
group. The second parameter is the address of the Enrollee or a string
"any" to allow any station to use the entered PIN (which will restrict
the PIN for one-time-use). PIN is the Enrollee PIN read either from a
label or display on the P2P Client/WPS Enrollee.

wps_pbc

Start WPS PBC method (i.e., push the button). This allows a single WPS
Enrollee to connect to the AP/GO. This is used on the GO when a P2P
client joins an existing group.

p2p_get_passphrase

Get the passphrase for a group (only available when acting as a GO).

p2p_presence_req [<duration> <interval>] [<duration> <interval>]

Send a P2P Presence Request to the GO (this is only available when
acting as a P2P client). If no duration/interval pairs are given, the
request indicates that this client has no special needs for GO
presence. The first parameter pair gives the preferred duration and
interval values in microseconds. If the second pair is included, that
indicates which value would be acceptable. This command returns OK
immediately and the response from the GO is indicated in a
P2P-PRESENCE-RESPONSE event message.

Parameters

p2p_ext_listen [<period> <interval>]

Configure Extended Listen Timing. If the parameters are omitted, this
feature is disabled. If the parameters are included, Listen State will
be entered every interval msec for at least period msec. Both values
have acceptable range of 1-65535 (with interval obviously having to be
larger than or equal to duration). If the P2P module is not idle at
the time the Extended Listen Timing timeout occurs, the Listen State
operation will be skipped.

The configured values will also be advertised to other P2P Devices. The
received values are available in the p2p_peer command output:

ext_listen_period=100 ext_listen_interval=5000

p2p_set <field> <value>

Change dynamic P2P parameters

p2p_set discoverability <0/1>

Disable/enable advertisement of client discoverability. This is
enabled by default and this parameter is mainly used to allow testing
of device discoverability.

p2p_set managed <0/1>

Disable/enable managed P2P Device operations. This is disabled by
default.

p2p_set listen_channel <channel> [<op_class>]

Set P2P Listen channel. This is mainly meant for testing purposes and
changing the Listen channel during normal operations can result in
protocol failures.

When specifying a social channel on the 2.4 GHz band (1/6/11) there is
no need to specify the operating class since it defaults to 81.  When
specifying a social channel on the 60 GHz band (2), specify the 60 GHz
operating class (180).

p2p_set ssid_postfix <postfix>

Set postfix string to be added to the automatically generated P2P SSID
(DIRECT-<two random characters>). For example, postfix of "-testing"
could result in the SSID becoming DIRECT-ab-testing.

p2p_set per_sta_psk <0/1>

Disabled(default)/enables use of per-client PSK in the P2P groups. This
can be used to request GO to assign a unique PSK for each client during
WPS provisioning. When enabled, this allow clients to be removed from
the group securely with p2p_remove_client command since that client's
PSK is removed at the same time to prevent it from connecting back using
the old PSK. When per-client PSK is not used, the client can still be
disconnected, but it will be able to re-join the group since the PSK it
learned previously is still valid. It should be noted that the default
passphrase on the GO that is normally used to allow legacy stations to
connect through manual configuration does not change here, so if that is
shared, devices with knowledge of that passphrase can still connect.

set <field> <value>

Set global configuration parameters which may also affect P2P
operations. The format on these parameters is same as is used in
wpa_supplicant.conf. Only the parameters listen here should be
changed. Modifying other parameters may result in incorrect behavior
since not all existing users of the parameters are updated.

set uuid <UUID>

Set WPS UUID (by default, this is generated based on the MAC address).

set device_name <device name>

Set WPS Device Name (also included in some P2P messages).

set manufacturer <manufacturer>

Set WPS Manufacturer.

set model_name <model name>

Set WPS Model Name.

set model_number <model number>

Set WPS Model Number.

set serial_number <serial number>

Set WPS Serial Number.

set device_type <device type>

Set WPS Device Type.

set os_version <OS version>

Set WPS OS Version.

set config_methods <config methods>

Set WPS Configuration Methods.

set sec_device_type <device type>

Add a new Secondary Device Type.

set p2p_go_intent <GO intent>

Set the default P2P GO Intent. Note: This value can be overridden in
p2p_connect command and as such, there should be no need to change the
default value here during normal operations.

set p2p_ssid_postfix <P2P SSID postfix>

Set P2P SSID postfix.

set persistent_reconnect <0/1>

Disable/enabled persistent reconnect for reinvocation of persistent
groups. If enabled, invitations to reinvoke a persistent group will be
accepted without separate authorization (e.g., user interaction).

set country <two character country code>

Set country code (this is included in some P2P messages).

set p2p_search_delay <delay>

Set p2p_search_delay which adds extra delay in milliseconds between
concurrent search iterations to make p2p_find friendlier to concurrent
operations by avoiding it from taking 100% of radio resources. The
default value is 500 ms.

Status

p2p_peers [discovered]

List P2P Device Addresses of all the P2P peers we know. The optional
"discovered" parameter filters out the peers that we have not fully
discovered, i.e., which we have only seen in a received Probe Request
frame.

p2p_peer <P2P Device Address>

Fetch information about a known P2P peer.

Group Status

(These are used on the group interface.)

status

Show status information (connection state, role, use encryption
parameters, IP address, etc.).

sta

Show information about an associated station (when acting in AP/GO role).

all_sta

Lists the currently associated stations.

Configuration data

list_networks

Lists the configured networks, including stored information for
persistent groups. The identifier in this list is used with
p2p_group_add and p2p_invite to indicate which persistent group is to
be reinvoked.

remove_network <network id>

Remove a network entry from configuration.


P2PS Events/Responses:

P2PS-PROV-START: This events gets triggered when provisioning is issued for
either seeker or advertiser.

For example,
P2PS-PROV-START 00:55:44:33:22:11 adv_id=111 adv_mac=00:55:44:33:22:11 conncap=1 session=1234567 session_mac=00:11:22:33:44:55 info='xxxx'

Parameters definition:
    MAC address - always
    adv_id - always ASCII hex-encoded u32
    adv_mac - always MAC address that owns/registered the service
    conncap - always mask of 0x01 (new), 0x02 (group client), 0x04 (group owner)
	bits
    session - always Session ID of the first session to be established
    session_mac - always MAC address that owns/initiated the session
    info - if available, UTF-8 string
	Escaped single quote & backslash with a backslash:
	\' == 0x27 == ', and \\ == 0x5c == \

P2PS-PROV-DONE: When provisioning is completed then this event gets triggered.

For example,
P2PS-PROV-DONE 00:11:22:33:44:55 status=0 adv_id=111 adv_mac=00:55:44:33:22:11 conncap=1 session=1234567 session_mac=00:11:22:33:44:55 [dev_passwd_id=8 | go=p2p-wlan0-0 | join=11:22:33:44:55:66 | persist=0]

Parameters definition:
    MAC address - always main device address of peer. May be different from MAC
	ultimately connected to.
    status - always ascii hex-encoded u8 (0 == success, 12 == deferred success)
    adv_id - always ascii hex-encoded u32
    adv_mac - always MAC address that owns/registered the service
    conncap - always One of: 1 (new), 2 (group client), 4 (group owner) bits
    session - always Session ID of the first session to be established
    session_mac - always MAC address that owns/initiated the session
    dev_passwd_id - only if conncap value == 1 (New GO negotiation)
	8 - "p2ps" password must be passed in p2p_connect command
	1 - "display" password must be passed in p2p_connect command
	5 - "keypad" password must be passed in p2p_connect command
    join only - if conncap value == 2 (Client Only). Display password and "join"
	must be passed in p2p_connect and address must be the MAC specified
    go only - if conncap value == 4 (GO Only). Interface name must be set with a
	password
    persist - only if previous persistent group existed between peers and shall
	be re-used. Group is restarted by sending "p2p_group_add persistent=0"
	where value is taken from P2P-PROV-DONE

Extended Events/Response

P2P-DEVICE-FOUND 00:11:22:33:44:55 p2p_dev_addr=00:11:22:33:44:55 pri_dev_type=0-00000000-0 name='' config_methods=0x108 dev_capab=0x21 group_capab=0x0 adv_id=111 asp_svc=alt.example.chat

Parameters definition:
    adv_id - if ASP ASCII hex-encoded u32. If it is reporting the
	"wildcard service", this value will be 0
    asp_svc - if ASP this is the service string. If it is reporting the
	"wildcard service", this value will be org.wi-fi.wfds


wpa_cli action script
---------------------

See examples/p2p-action.sh

TODO: describe DHCP/DNS setup
TODO: cross-connection

wpa_supplicant and Wi-Fi Protected Setup (WPS)
==============================================

This document describes how the WPS implementation in wpa_supplicant
can be configured and how an external component on the client (e.g.,
management GUI) is used to enable WPS enrollment and registrar
registration.


Introduction to WPS
-------------------

Wi-Fi Protected Setup (WPS) is a mechanism for easy configuration of a
wireless network. It allows automated generation of random keys (WPA
passphrase/PSK) and configuration of an access point and client
devices. WPS includes number of methods for setting up connections
with PIN method and push-button configuration (PBC) being the most
commonly deployed options.

While WPS can enable more home networks to use encryption in the
wireless network, it should be noted that the use of the PIN and
especially PBC mechanisms for authenticating the initial key setup is
not very secure. As such, use of WPS may not be suitable for
environments that require secure network access without chance for
allowing outsiders to gain access during the setup phase.

WPS uses the following terms to describe the entities participating
in the network setup:
- access point: the WLAN access point
- Registrar: a device that control a network and can authorize
  addition of new devices); this may be either in the AP ("internal
  Registrar") or in an external device, e.g., a laptop, ("external
  Registrar")
- Enrollee: a device that is being authorized to use the network

It should also be noted that the AP and a client device may change
roles (i.e., AP acts as an Enrollee and client device as a Registrar)
when WPS is used to configure the access point.


More information about WPS is available from Wi-Fi Alliance:
http://www.wi-fi.org/wifi-protected-setup


wpa_supplicant implementation
-----------------------------

wpa_supplicant includes an optional WPS component that can be used as
an Enrollee to enroll new network credential or as a Registrar to
configure an AP.


wpa_supplicant configuration
----------------------------

WPS is an optional component that needs to be enabled in
wpa_supplicant build configuration (.config). Here is an example
configuration that includes WPS support and Linux nl80211-based
driver interface:

CONFIG_DRIVER_NL80211=y
CONFIG_WPS=y

If you want to enable WPS external registrar (ER) functionality, you
will also need to add the following line:

CONFIG_WPS_ER=y

The following parameter can be used to enable support for NFC config
method:

CONFIG_WPS_NFC=y

WPS needs the Universally Unique IDentifier (UUID; see RFC 4122) for
the device. This is configured in the runtime configuration for
wpa_supplicant (if not set, UUID will be generated based on local MAC
address):

# example UUID for WPS
uuid=12345678-9abc-def0-1234-56789abcdef0

The network configuration blocks needed for WPS are added
automatically based on control interface commands, so they do not need
to be added explicitly in the configuration file.

WPS registration will generate new network blocks for the acquired
credentials. If these are to be stored for future use (after
restarting wpa_supplicant), wpa_supplicant will need to be configured
to allow configuration file updates:

update_config=1


External operations
-------------------

WPS requires either a device PIN code (usually, 8-digit number) or a
pushbutton event (for PBC) to allow a new WPS Enrollee to join the
network. wpa_supplicant uses the control interface as an input channel
for these events.

The PIN value used in the commands must be processed by an UI to
remove non-digit characters and potentially, to verify the checksum
digit. "wpa_cli wps_check_pin <PIN>" can be used to do such processing.
It returns FAIL if the PIN is invalid, or FAIL-CHECKSUM if the checksum
digit is incorrect, or the processed PIN (non-digit characters removed)
if the PIN is valid.

If the client device has a display, a random PIN has to be generated
for each WPS registration session. wpa_supplicant can do this with a
control interface request, e.g., by calling wpa_cli:

wpa_cli wps_pin any

This will return the generated 8-digit PIN which will then need to be
entered at the Registrar to complete WPS registration. At that point,
the client will be enrolled with credentials needed to connect to the
AP to access the network.

If the client device does not have a display that could show the
random PIN, a hardcoded PIN that is printed on a label can be
used. wpa_supplicant is notified this with a control interface
request, e.g., by calling wpa_cli:

wpa_cli wps_pin any 12345670

This starts the WPS negotiation in the same way as above with the
generated PIN.

When the wps_pin command is issued for an AP (including P2P GO) mode
interface, an optional timeout parameter can be used to specify
expiration timeout for the PIN in seconds. For example:

wpa_cli wps_pin any 12345670 300

If a random PIN is needed for a user interface, "wpa_cli wps_pin get"
can be used to generate a new PIN without starting WPS negotiation.
This random PIN can then be passed as an argument to another wps_pin
call when the actual operation should be started.

If the client design wants to support optional WPS PBC mode, this can
be enabled by either a physical button in the client device or a
virtual button in the user interface. The PBC operation requires that
a button is also pressed at the AP/Registrar at about the same time (2
minute window). wpa_supplicant is notified of the local button event
over the control interface, e.g., by calling wpa_cli:

wpa_cli wps_pbc

At this point, the AP/Registrar has two minutes to complete WPS
negotiation which will generate a new WPA PSK in the same way as the
PIN method described above.

If the client wants to operate in the Registrar role to learn the
current AP configuration and optionally, to configure an AP,
wpa_supplicant is notified over the control interface, e.g., with
wpa_cli:

wpa_cli wps_reg <AP BSSID> <AP PIN>
(example: wpa_cli wps_reg 02:34:56:78:9a:bc 12345670)

This is used to fetch the current AP settings instead of actually
changing them. The main difference with the wps_pin command is that
wps_reg uses the AP PIN (e.g., from a label on the AP) instead of a
PIN generated at the client.

In order to change the AP configuration, the new configuration
parameters are given to the wps_reg command:

wpa_cli wps_reg <AP BSSID> <AP PIN> <new SSID> <auth> <encr> <new key>
examples:
  wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 testing WPA2PSK CCMP 12345678
  wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 clear OPEN NONE ""

<auth> must be one of the following: OPEN WPAPSK WPA2PSK
<encr> must be one of the following: NONE WEP TKIP CCMP


Scanning
--------

Scan results ('wpa_cli scan_results' or 'wpa_cli bss <idx>') include a
flags field that is used to indicate whether the BSS support WPS. If
the AP support WPS, but has not recently activated a Registrar, [WPS]
flag will be included. If PIN method has been recently selected,
[WPS-PIN] is shown instead. Similarly, [WPS-PBC] is shown if PBC mode
is in progress. GUI programs can use these as triggers for suggesting
a guided WPS configuration to the user. In addition, control interface
monitor events WPS-AP-AVAILABLE{,-PBC,-PIN} can be used to find out if
there are WPS enabled APs in scan results without having to go through
all the details in the GUI. These notification could be used, e.g., to
suggest possible WPS connection to the user.


wpa_gui
-------

wpa_gui-qt4 directory contains a sample GUI that shows an example of
how WPS support can be integrated into the GUI. Its main window has a
WPS tab that guides user through WPS registration with automatic AP
selection. In addition, it shows how WPS can be started manually by
selecting an AP from scan results.


Credential processing
---------------------

By default, wpa_supplicant processes received credentials and updates
its configuration internally. However, it is possible to
control these operations from external programs, if desired.

This internal processing can be disabled with wps_cred_processing=1
option. When this is used, an external program is responsible for
processing the credential attributes and updating wpa_supplicant
configuration based on them.

The following control interface messages are sent out for external
programs:

WPS-CRED-RECEIVED  <hexdump of Credential attribute(s)>
For example:
<2>WPS-CRED-RECEIVED 100e006f10260001011045000c6a6b6d2d7770732d74657374100300020020100f000200081027004030653462303435366332363666653064333961643135353461316634626637313234333761636664623766333939653534663166316230323061643434386235102000060266a0ee1727


wpa_supplicant as WPS External Registrar (ER)
---------------------------------------------

wpa_supplicant can be used as a WPS ER to configure an AP or enroll
new Enrollee to join the network. This functionality uses UPnP and
requires that a working IP connectivity is available with the AP (this
can be either over a wired or wireless connection).

Separate wpa_supplicant process can be started for WPS ER
operations. A special "none" driver can be used in such a case to
indicate that no local network interface is actually controlled. For
example, the following command could be used to start the ER:

wpa_supplicant -Dnone -c er.conf -ieth0

Sample er.conf:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=admin
device_name=WPS External Registrar

wpa_cli commands for ER functionality:

wps_er_start [IP address]
- start WPS ER functionality
- the optional IP address parameter can be used to filter operations only
  to include a single AP
- if run again while ER is active, the stored information (discovered APs
  and Enrollees) are shown again

wps_er_stop
- stop WPS ER functionality

wps_er_learn <UUID|BSSID> <AP PIN>
- learn AP configuration

wps_er_set_config <UUID|BSSID> <network id>
- use AP configuration from a locally configured network (e.g., from
  wps_reg command); this does not change the AP's configuration, but
  only prepares a configuration to be used when enrolling a new device
  to the AP

wps_er_config <UUID|BSSID> <AP PIN> <new SSID> <auth> <encr> <new key>
- examples:
  wps_er_config 87654321-9abc-def0-1234-56789abc0002 12345670 testing WPA2PSK CCMP 12345678
  wpa_er_config 87654321-9abc-def0-1234-56789abc0002 12345670 clear OPEN NONE ""

<auth> must be one of the following: OPEN WPAPSK WPA2PSK
<encr> must be one of the following: NONE WEP TKIP CCMP

wps_er_pbc <Enrollee UUID|MAC address>
- accept an Enrollee PBC using External Registrar

wps_er_pin <Enrollee UUID|"any"|MAC address> <PIN> [Enrollee MAC address]
- add an Enrollee PIN to External Registrar
- if Enrollee UUID is not known, "any" can be used to add a wildcard PIN
- if the MAC address of the enrollee is known, it should be configured
  to allow the AP to advertise list of authorized enrollees

WPS ER events:

WPS_EVENT_ER_AP_ADD
- WPS ER discovered an AP

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/

WPS_EVENT_ER_AP_REMOVE
- WPS ER removed an AP entry

WPS-ER-AP-REMOVE 87654321-9abc-def0-1234-56789abc0002

WPS_EVENT_ER_ENROLLEE_ADD
- WPS ER discovered a new Enrollee

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|

WPS_EVENT_ER_ENROLLEE_REMOVE
- WPS ER removed an Enrollee entry

WPS-ER-ENROLLEE-REMOVE 2b7093f1-d6fb-5108-adbb-bea66bb87333 02:66:a0:ee:17:27

WPS-ER-AP-SETTINGS
- WPS ER learned AP settings

WPS-ER-AP-SETTINGS uuid=fd91b4ec-e3fa-5891-a57d-8c59efeed1d2 ssid=test-wps auth_type=0x0020 encr_type=0x0008 key=12345678


WPS with NFC
------------

WPS can be used with NFC-based configuration method. An NFC tag
containing a password token from the Enrollee can be used to
authenticate the connection instead of the PIN. In addition, an NFC tag
with a configuration token can be used to transfer AP settings without
going through the WPS protocol.

When the station acts as an Enrollee, a local NFC tag with a password
token can be used by touching the NFC interface of a Registrar.

"wps_nfc [BSSID]" command starts WPS protocol run with the local end as
the Enrollee using the NFC password token that is either pre-configured
in the configuration file (wps_nfc_dev_pw_id, wps_nfc_dh_pubkey,
wps_nfc_dh_privkey, wps_nfc_dev_pw) or generated dynamically with
"wps_nfc_token <WPS|NDEF>" command. The included nfc_pw_token tool
(build with "make nfc_pw_token") can be used to generate NFC password
tokens during manufacturing (each station needs to have its own random
keys).

The "wps_nfc_config_token <WPS/NDEF>" command can be used to build an
NFC configuration token when wpa_supplicant is controlling an AP
interface (AP or P2P GO). The output value from this command is a
hexdump of the current AP configuration (WPS parameter requests this to
include only the WPS attributes; NDEF parameter requests additional NDEF
encapsulation to be included). This data needs to be written to an NFC
tag with an external program. Once written, the NFC configuration token
can be used to touch an NFC interface on a station to provision the
credentials needed to access the network.

The "wps_nfc_config_token <WPS/NDEF> <network id>" command can be used
to build an NFC configuration token based on a locally configured
network.

If the station includes NFC interface and reads an NFC tag with a MIME
media type "application/vnd.wfa.wsc", the NDEF message payload (with or
without NDEF encapsulation) can be delivered to wpa_supplicant using the
following wpa_cli command:

wps_nfc_tag_read <hexdump of payload>

If the NFC tag contains a configuration token, the network is added to
wpa_supplicant configuration. If the NFC tag contains a password token,
the token is added to the WPS Registrar component. This information can
then be used with wps_reg command (when the NFC password token was from
an AP) using a special value "nfc-pw" in place of the PIN parameter. If
the ER functionality has been started (wps_er_start), the NFC password
token is used to enable enrollment of a new station (that was the source
of the NFC password token).

"nfc_get_handover_req <NDEF> <WPS-CR>" command can be used to build the
WPS carrier record for a Handover Request Message for connection
handover. The first argument selects the format of the output data and
the second argument selects which type of connection handover is
requested (WPS-CR = Wi-Fi handover as specified in WSC 2.0).

"nfc_get_handover_sel <NDEF> <WPS> [UUID|BSSID]" command can be used to
build the contents of a Handover Select Message for connection handover
when this does not depend on the contents of the Handover Request
Message. The first argument selects the format of the output data and
the second argument selects which type of connection handover is
requested (WPS = Wi-Fi handover as specified in WSC 2.0). If the options
UUID|BSSID argument is included, this is a request to build the handover
message for the specified AP when wpa_supplicant is operating as a WPS
ER.

"nfc_report_handover <INIT/RESP> WPS <carrier from handover request>
<carrier from handover select>" can be used as an alternative way for
reporting completed NFC connection handover. The first parameter
indicates whether the local device initiated or responded to the
connection handover and the carrier records are the selected carrier
from the handover request and select messages as a hexdump.

The "wps_er_nfc_config_token <WPS/NDEF> <UUID|BSSID>" command can be
used to build an NFC configuration token for the specified AP when
wpa_supplicant is operating as a WPS ER. The output value from this
command is a hexdump of the selected AP configuration (WPS parameter
requests this to include only the WPS attributes; NDEF parameter
requests additional NDEF encapsulation to be included). This data needs
to be written to an NFC tag with an external program. Once written, the
NFC configuration token can be used to touch an NFC interface on a
station to provision the credentials needed to access the network.

wpa_supplicant for Windows
==========================

Copyright (c) 2003-2009, Jouni Malinen <j@w1.fi> and contributors
All Rights Reserved.

This program is licensed under the BSD license (the one with
advertisement clause removed).


wpa_supplicant has support for being used as a WPA/WPA2/IEEE 802.1X
Supplicant on Windows. The current port requires that WinPcap
(http://winpcap.polito.it/) is installed for accessing packets and the
driver interface. Both release versions 3.0 and 3.1 are supported.

The current port is still somewhat experimental. It has been tested
mainly on Windows XP (SP2) with limited set of NDIS drivers. In
addition, the current version has been reported to work with Windows
2000.

All security modes have been verified to work (at least complete
authentication and successfully ping a wired host):
- plaintext
- static WEP / open system authentication
- static WEP / shared key authentication
- IEEE 802.1X with dynamic WEP keys
- WPA-PSK, TKIP, CCMP, TKIP+CCMP
- WPA-EAP, TKIP, CCMP, TKIP+CCMP
- WPA2-PSK, TKIP, CCMP, TKIP+CCMP
- WPA2-EAP, TKIP, CCMP, TKIP+CCMP


Building wpa_supplicant with mingw
----------------------------------

The default build setup for wpa_supplicant is to use MinGW and
cross-compiling from Linux to MinGW/Windows. It should also be
possible to build this under Windows using the MinGW tools, but that
is not tested nor supported and is likely to require some changes to
the Makefile unless cygwin is used.


Building wpa_supplicant with MSVC
---------------------------------

wpa_supplicant can be built with Microsoft Visual C++ compiler. This
has been tested with Microsoft Visual C++ Toolkit 2003 and Visual
Studio 2005 using the included nmake.mak as a Makefile for nmake. IDE
can also be used by creating a project that includes the files and
defines mentioned in nmake.mak. Example VS2005 solution and project
files are included in vs2005 subdirectory. This can be used as a
starting point for building the programs with VS2005 IDE. Visual Studio
2008 Express Edition is also able to use these project files.

WinPcap development package is needed for the build and this can be
downloaded from http://www.winpcap.org/install/bin/WpdPack_4_0_2.zip. The
default nmake.mak expects this to be unpacked into C:\dev\WpdPack so
that Include and Lib directories are in this directory. The files can be
stored elsewhere as long as the WINPCAPDIR in nmake.mak is updated to
match with the selected directory. In case a project file in the IDE is
used, these Include and Lib directories need to be added to project
properties as additional include/library directories.

OpenSSL source package can be downloaded from
http://www.openssl.org/source/openssl-0.9.8i.tar.gz and built and
installed following instructions in INSTALL.W32. Note that if EAP-FAST
support will be included in the wpa_supplicant, OpenSSL needs to be
patched to# support it openssl-0.9.8i-tls-extensions.patch. The example
nmake.mak file expects OpenSSL to be installed into C:\dev\openssl, but
this directory can be modified by changing OPENSSLDIR variable in
nmake.mak.

If you do not need EAP-FAST support, you may also be able to use Win32
binary installation package of OpenSSL from
http://www.slproweb.com/products/Win32OpenSSL.html instead of building
the library yourself. In this case, you will need to copy Include and
Lib directories in suitable directory, e.g., C:\dev\openssl for the
default nmake.mak. Copy {Win32OpenSSLRoot}\include into
C:\dev\openssl\include and make C:\dev\openssl\lib subdirectory with
files from {Win32OpenSSLRoot}\VC (i.e., libeay*.lib and ssleay*.lib).
This will end up using dynamically linked OpenSSL (i.e., .dll files are
needed) for it. Alternative, you can copy files from
{Win32OpenSSLRoot}\VC\static to create a static build (no OpenSSL .dll
files needed).


Building wpa_supplicant for cygwin
----------------------------------

wpa_supplicant can be built for cygwin by installing the needed
development packages for cygwin. This includes things like compiler,
make, openssl development package, etc. In addition, developer's pack
for WinPcap (WPdpack.zip) from
http://winpcap.polito.it/install/default.htm is needed.

.config file should enable only one driver interface,
CONFIG_DRIVER_NDIS. In addition, include directories may need to be
added to match the system. An example configuration is available in
defconfig. The library and include files for WinPcap will either need
to be installed in compiler/linker default directories or their
location will need to be adding to .config when building
wpa_supplicant.

Othen than this, the build should be more or less identical to Linux
version, i.e., just run make after having created .config file. An
additional tool, win_if_list.exe, can be built by running "make
win_if_list".


Building wpa_gui
----------------

wpa_gui uses Qt application framework from Trolltech. It can be built
with the open source version of Qt4 and MinGW. Following commands can
be used to build the binary in the Qt 4 Command Prompt:

# go to the root directory of wpa_supplicant source code
cd wpa_gui-qt4
qmake -o Makefile wpa_gui.pro
make
# the wpa_gui.exe binary is created into 'release' subdirectory


Using wpa_supplicant for Windows
--------------------------------

wpa_supplicant, wpa_cli, and wpa_gui behave more or less identically to
Linux version, so instructions in README and example wpa_supplicant.conf
should be applicable for most parts. In addition, there is another
version of wpa_supplicant, wpasvc.exe, which can be used as a Windows
service and which reads its configuration from registry instead of
text file.

When using access points in "hidden SSID" mode, ap_scan=2 mode need to
be used (see wpa_supplicant.conf for more information).

Windows NDIS/WinPcap uses quite long interface names, so some care
will be needed when starting wpa_supplicant. Alternatively, the
adapter description can be used as the interface name which may be
easier since it is usually in more human-readable
format. win_if_list.exe can be used to find out the proper interface
name.

Example steps in starting up wpa_supplicant:

# win_if_list.exe
ifname: \Device\NPF_GenericNdisWanAdapter
description: Generic NdisWan adapter

ifname: \Device\NPF_{769E012B-FD17-4935-A5E3-8090C38E25D2}
description: Atheros Wireless Network Adapter (Microsoft's Packet Scheduler)

ifname: \Device\NPF_{732546E7-E26C-48E3-9871-7537B020A211}
description: Intel 8255x-based Integrated Fast Ethernet (Microsoft's Packet Scheduler)


Since the example configuration used Atheros WLAN card, the middle one
is the correct interface in this case. The interface name for -i
command line option is the full string following "ifname:" (the
"\Device\NPF_" prefix can be removed). In other words, wpa_supplicant
would be started with the following command:

# wpa_supplicant.exe -i'{769E012B-FD17-4935-A5E3-8090C38E25D2}' -c wpa_supplicant.conf -d

-d optional enables some more debugging (use -dd for even more, if
needed). It can be left out if debugging information is not needed.

With the alternative mechanism for selecting the interface, this
command has identical results in this case:

# wpa_supplicant.exe -iAtheros -c wpa_supplicant.conf -d


Simple configuration example for WPA-PSK:

#ap_scan=2
ctrl_interface=
network={
	ssid="test"
	key_mgmt=WPA-PSK
	proto=WPA
	pairwise=TKIP
	psk="secret passphrase"
}

(remove '#' from the comment out ap_scan line to enable mode in which
wpa_supplicant tries to associate with the SSID without doing
scanning; this allows APs with hidden SSIDs to be used)


wpa_cli.exe and wpa_gui.exe can be used to interact with the
wpa_supplicant.exe program in the same way as with Linux. Note that
ctrl_interface is using UNIX domain sockets when built for cygwin, but
the native build for Windows uses named pipes and the contents of the
ctrl_interface configuration item is used to control access to the
interface. Anyway, this variable has to be included in the configuration
to enable the control interface.


Example SDDL string formats:

(local admins group has permission, but nobody else):

ctrl_interface=SDDL=D:(A;;GA;;;BA)

("A" == "access allowed", "GA" == GENERIC_ALL == all permissions, and
"BA" == "builtin administrators" == the local admins.  The empty fields
are for flags and object GUIDs, none of which should be required in this
case.)

(local admins and the local "power users" group have permissions,
but nobody else):

ctrl_interface=SDDL=D:(A;;GA;;;BA)(A;;GA;;;PU)

(One ACCESS_ALLOWED ACE for GENERIC_ALL for builtin administrators, and
one ACCESS_ALLOWED ACE for GENERIC_ALL for power users.)

(close to wide open, but you have to be a valid user on
the machine):

ctrl_interface=SDDL=D:(A;;GA;;;AU)

(One ACCESS_ALLOWED ACE for GENERIC_ALL for the "authenticated users"
group.)

This one would allow absolutely everyone (including anonymous
users) -- this is *not* recommended, since named pipes can be attached
to from anywhere on the network (i.e. there's no "this machine only"
like there is with 127.0.0.1 sockets):

ctrl_interface=SDDL=D:(A;;GA;;;BU)(A;;GA;;;AN)

(BU == "builtin users", "AN" == "anonymous")

See also [1] for the format of ACEs, and [2] for the possible strings
that can be used for principal names.

[1]
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/ace_strings.asp
[2]
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/sid_strings.asp


Starting wpa_supplicant as a Windows service (wpasvc.exe)
---------------------------------------------------------

wpa_supplicant can be started as a Windows service by using wpasvc.exe
program that is alternative build of wpa_supplicant.exe. Most of the
core functionality of wpasvc.exe is identical to wpa_supplicant.exe,
but it is using Windows registry for configuration information instead
of a text file and command line parameters. In addition, it can be
registered as a service that can be started automatically or manually
like any other Windows service.

The root of wpa_supplicant configuration in registry is
HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant. This level includes global
parameters and a 'interfaces' subkey with all the interface configuration
(adapter to confname mapping). Each such mapping is a subkey that has
'adapter', 'config', and 'ctrl_interface' values.

This program can be run either as a normal command line application,
e.g., for debugging, with 'wpasvc.exe app' or as a Windows service.
Service need to be registered with 'wpasvc.exe reg <full path to
wpasvc.exe>'. Alternatively, 'wpasvc.exe reg' can be used to register
the service with the current location of wpasvc.exe. After this, wpasvc
can be started like any other Windows service (e.g., 'net start wpasvc')
or it can be configured to start automatically through the Services tool
in administrative tasks. The service can be unregistered with
'wpasvc.exe unreg'.

If the service is set to start during system bootup to make the
network connection available before any user has logged in, there may
be a long (half a minute or so) delay in starting up wpa_supplicant
due to WinPcap needing a driver called "Network Monitor Driver" which
is started by default on demand.

To speed up wpa_supplicant start during system bootup, "Network
Monitor Driver" can be configured to be started sooner by setting its
startup type to System instead of the default Demand. To do this, open
up Device Manager, select Show Hidden Devices, expand the "Non
Plug-and-Play devices" branch, double click "Network Monitor Driver",
go to the Driver tab, and change the Demand setting to System instead.

Configuration data is in HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs
key. Each configuration profile has its own key under this. In terms of text
files, each profile would map to a separate text file with possibly multiple
networks. Under each profile, there is a networks key that lists all
networks as a subkey. Each network has set of values in the same way as
network block in the configuration file. In addition, blobs subkey has
possible blobs as values.

HKEY_LOCAL_MACHINE\SOFTWARE\wpa_supplicant\configs\test\networks\0000
   ssid="example"
   key_mgmt=WPA-PSK

See win_example.reg for an example on how to setup wpasvc.exe
parameters in registry. It can also be imported to registry as a
starting point for the configuration.