diff --git a/contrib/wpa/.gitignore b/contrib/wpa/.gitignore new file mode 100644 --- /dev/null +++ b/contrib/wpa/.gitignore @@ -0,0 +1,8 @@ +*.pyc +*~ +tests/hwsim/logs +tests/remote/logs +wpaspy/build +**/parallel-vm.log +tags +build/ diff --git a/contrib/wpa/Android.mk b/contrib/wpa/Android.mk new file mode 100644 --- /dev/null +++ b/contrib/wpa/Android.mk @@ -0,0 +1,10 @@ +LOCAL_PATH:= $(call my-dir) + +ifneq ($(filter VER_0_8_X VER_2_1_DEVEL,$(WPA_SUPPLICANT_VERSION)),) +# The order of the 2 Android.mks does matter! +# TODO: Clean up the Android.mks, reset all the temporary variables at the +# end of each Android.mk, so that one Android.mk doesn't depend on variables +# set up in the other Android.mk. +include $(LOCAL_PATH)/hostapd/Android.mk \ + $(LOCAL_PATH)/wpa_supplicant/Android.mk +endif diff --git a/contrib/wpa/CONTRIBUTIONS b/contrib/wpa/CONTRIBUTIONS --- a/contrib/wpa/CONTRIBUTIONS +++ b/contrib/wpa/CONTRIBUTIONS @@ -56,6 +56,9 @@ is by committing the changes to a cloned git repository and using git format-patch. The patch can then be sent, e.g., with git send-email. +A list of pending patches waiting for review is available in +Patchwork: https://patchwork.ozlabs.org/project/hostap/list/ + History of license and contributions terms ------------------------------------------ @@ -140,7 +143,7 @@ Modified BSD license (no advertisement clause): -Copyright (c) 2002-2019, Jouni Malinen and contributors +Copyright (c) 2002-2021, Jouni Malinen and contributors All Rights Reserved. Redistribution and use in source and binary forms, with or without diff --git a/contrib/wpa/build_release b/contrib/wpa/build_release new file mode 100755 --- /dev/null +++ b/contrib/wpa/build_release @@ -0,0 +1,47 @@ +#!/bin/sh + +set -e + +if [ -z "$1" ]; then + echo "build_release " + exit 1 +fi + +TMP=tmp.build_release +RELDIR=`pwd`/Release +VER=$1 +NOW=`date +%Y-%m-%d` + +echo "Version: $VER - $NOW" + +DATEw=`head -n 3 wpa_supplicant/ChangeLog | tail -n 1 | sed "s/ .*//"` +DATEh=`head -n 3 hostapd/ChangeLog | tail -n 1 | sed "s/ .*//"` + +if [ "$DATEw" != "$NOW" -o "$DATEh" != "$NOW" ]; then + echo "NOTE! Date mismatch in ChangeLog: wpa_supplicant $DATEw hostapd $DATEh != $NOW" +fi + +if [ -r $TMP ]; then + echo "Temporary directory '$TMP' exists. Remove it before running this." + exit 1 +fi + +mkdir $TMP +mkdir -p $RELDIR + +git archive --format=tar --prefix=wpa-$VER/ HEAD \ + README COPYING CONTRIBUTIONS src wpa_supplicant hostapd hs20 | + gzip > $RELDIR/wpa-$VER.tar.gz +git archive --format=tar --prefix=hostapd-$VER/ HEAD \ + README COPYING CONTRIBUTIONS src hostapd | + gzip > $RELDIR/hostapd-$VER.tar.gz +git archive --format=tar --prefix=wpa_supplicant-$VER/ HEAD \ + README COPYING CONTRIBUTIONS src wpa_supplicant hs20/client | + tar --directory=$TMP -xf - + +cd $TMP +make -C wpa_supplicant-$VER/wpa_supplicant/doc/docbook man +rm -f wpa_supplicant-$VER/wpa_supplicant/doc/docbook/manpage.{links,refs} +tar czf $RELDIR/wpa_supplicant-$VER.tar.gz wpa_supplicant-$VER +cd .. +rm -r $TMP diff --git a/contrib/wpa/doc/.gitignore b/contrib/wpa/doc/.gitignore new file mode 100644 --- /dev/null +++ b/contrib/wpa/doc/.gitignore @@ -0,0 +1,14 @@ +doxygen.warnings +hostapd.eps +hostapd.png +html +latex +p2p_arch.eps +p2p_arch.png +p2p_arch2.eps +p2p_arch2.png +p2p_sm.eps +p2p_sm.png +wpa_supplicant.eps +wpa_supplicant.png +wpa_supplicant-devel.pdf diff --git a/contrib/wpa/doc/Makefile b/contrib/wpa/doc/Makefile new file mode 100644 --- /dev/null +++ b/contrib/wpa/doc/Makefile @@ -0,0 +1,42 @@ +all: docs + +%.eps: %.fig + fig2dev -L eps $*.fig $*.eps + +%.png: %.fig + fig2dev -L png -m 3 $*.fig | pngtopnm | pnmscale 0.4 | pnmtopng \ + > $*.png + +%.png: %.dot + dot $*.dot -Tpng -o $*.png + +%.eps: %.dot + dot $*.dot -Tps -o $*.eps + +_wpa_supplicant.png: wpa_supplicant.png + cp $< $@ + +_wpa_supplicant.eps: wpa_supplicant.eps + cp $< $@ + +docs-pics: wpa_supplicant.png wpa_supplicant.eps hostapd.png hostapd.eps p2p_sm.png p2p_sm.eps p2p_arch.png p2p_arch.eps p2p_arch2.png p2p_arch2.eps _wpa_supplicant.png _wpa_supplicant.eps + +docs: docs-pics + (cd ..; doxygen doc/doxygen.conf; cd doc) + $(MAKE) -C latex + cp latex/refman.pdf wpa_supplicant-devel.pdf + +html: docs-pics + (cd ..; doxygen doc/doxygen.conf; cd doc) + +clean: + rm -f *~ + rm -f wpa_supplicant.eps wpa_supplicant.png + rm -f _wpa_supplicant.png _wpa_supplicant.eps + rm -f hostapd.eps hostapd.png + rm -f p2p_sm.eps p2p_sm.png + rm -f p2p_arch.eps p2p_arch.png + rm -f p2p_arch2.eps p2p_arch2.png + rm -f doxygen.warnings + rm -rf html latex + rm -f wpa_supplicant-devel.pdf diff --git a/contrib/wpa/doc/code_structure.doxygen b/contrib/wpa/doc/code_structure.doxygen new file mode 100644 --- /dev/null +++ b/contrib/wpa/doc/code_structure.doxygen @@ -0,0 +1,315 @@ +/** +\page code_structure Structure of the source code + +[ \ref _wpa_supplicant_core "wpa_supplicant core functionality" | +\ref generic_helper_func "Generic helper functions" | +\ref crypto_func "Cryptographic functions" | +\ref tls_func "TLS library" | +\ref configuration "Configuration" | +\ref ctrl_iface "Control interface" | +\ref wpa_code "WPA supplicant" | +\ref eap_peer "EAP peer" | +\ref eapol_supp "EAPOL supplicant" | +\ref win_port "Windows port" | +\ref test_programs "Test programs" ] + +wpa_supplicant implementation is divided into number of independent +modules. Core code includes functionality for controlling the network +selection, association, and configuration. Independent modules include +WPA code (key handshake, PMKSA caching, pre-authentication), EAPOL +state machine, and EAP state machine and methods. In addition, there +are number of separate files for generic helper functions. + +Both WPA and EAPOL/EAP state machines can be used separately in other +programs than wpa_supplicant. As an example, the included test +programs eapol_test and preauth_test are using these modules. + +\ref driver_wrapper "Driver interface API" is defined in \ref driver.h and +all hardware/driver dependent functionality is implemented in +driver_*.c. + + +\section _wpa_supplicant_core wpa_supplicant core functionality + +\ref wpa_supplicant.c + Program initialization, main control loop + +\ref wpa_supplicant/main.c + main() for UNIX-like operating systems and MinGW (Windows); this + uses command line arguments to configure wpa_supplicant + +\ref events.c + Driver event processing; \ref wpa_supplicant_event() and related functions + +\ref wpa_supplicant_i.h + Internal definitions for wpa_supplicant core; should not be + included into independent modules + + +\section generic_helper_func Generic helper functions + +wpa_supplicant uses generic helper functions some of which are shared +with with hostapd. The following C files are currently used: + +\ref eloop.c and \ref eloop.h + Event loop (select() loop with registerable timeouts, socket read + callbacks, and signal callbacks) + +\ref common.c and \ref common.h + Common helper functions + +\ref defs.h + Definitions shared by multiple files + +\ref l2_packet.h, \ref l2_packet_linux.c, and \ref l2_packet_pcap.c + Layer 2 (link) access wrapper (includes native Linux implementation + and wrappers for libdnet/libpcap). A new l2_packet implementation + may need to be added when porting to new operating systems that are + not supported by libdnet/libpcap. Makefile can be used to select which + l2_packet implementation is included. \ref l2_packet_linux.c uses Linux + packet sockets and \ref l2_packet_pcap.c has a more portable version using + libpcap and libdnet. + +\ref pcsc_funcs.c and \ref pcsc_funcs.h + Wrapper for PC/SC lite SIM and smart card readers + +\ref priv_netlink.h + Private version of netlink definitions from Linux kernel header files; + this could be replaced with C library header file once suitable + version becomes commonly available + +\ref version.h + Version number definitions + + +\section crypto_func Cryptographic functions + +\ref md5.c and \ref md5.h + MD5 (replaced with a crypto library if TLS support is included) + HMAC-MD5 (keyed checksum for message authenticity validation) + +\ref rc4.c and \ref rc4.h + RC4 (broadcast/default key encryption) + +\ref sha1.c and \ref sha1.h + SHA-1 (replaced with a crypto library if TLS support is included) + HMAC-SHA-1 (keyed checksum for message authenticity validation) + PRF-SHA-1 (pseudorandom (key/nonce generation) function) + PBKDF2-SHA-1 (ASCII passphrase to shared secret) + T-PRF (for EAP-FAST) + TLS-PRF (RFC 2246) + +\ref sha256.c and \ref sha256.h + SHA-256 (replaced with a crypto library if TLS support is included) + +\ref aes-wrap.c, \ref aes_wrap.h, \ref aes.c + AES (replaced with a crypto library if TLS support is included), + AES Key Wrap Algorithm with 128-bit KEK, RFC3394 (broadcast/default + key encryption), + One-Key CBC MAC (OMAC1) hash with AES-128, + AES-128 CTR mode encryption, + AES-128 EAX mode encryption/decryption, + AES-128 CBC + +\ref crypto.h + Definition of crypto library wrapper + +\ref crypto_openssl.c + Wrapper functions for libcrypto (OpenSSL) + +\ref crypto_internal.c + Wrapper functions for internal crypto implementation + +\ref crypto_gnutls.c + Wrapper functions for libgcrypt (used by GnuTLS) + +\ref ms_funcs.c and \ref ms_funcs.h + Helper functions for MSCHAPV2 and LEAP + +\ref tls.h + Definition of TLS library wrapper + +\ref tls_none.c + Dummy implementation of TLS library wrapper for cases where TLS + functionality is not included. + +\ref tls_openssl.c + TLS library wrapper for openssl + +\ref tls_internal.c + TLS library for internal TLS implementation + +\ref tls_gnutls.c + TLS library wrapper for GnuTLS + + +\section tls_func TLS library + +\ref asn1.c and \ref asn1.h + ASN.1 DER parsing + +\ref bignum.c and \ref bignum.h + Big number math + +\ref rsa.c and \ref rsa.h + RSA + +\ref x509v3.c and \ref x509v3.h + X.509v3 certificate parsing and processing + +\ref tlsv1_client.c, \ref tlsv1_client.h + TLSv1 client (RFC 2246) + +\ref tlsv1_client_i.h + Internal structures for TLSv1 client + +\ref tlsv1_client_read.c + TLSv1 client: read handshake messages + +\ref tlsv1_client_write.c + TLSv1 client: write handshake messages + +\ref tlsv1_common.c and \ref tlsv1_common.h + Common TLSv1 routines and definitions + +\ref tlsv1_cred.c and \ref tlsv1_cred.h + TLSv1 credentials + +\ref tlsv1_record.c and \ref tlsv1_record.h + TLSv1 record protocol + + +\section configuration Configuration + +\ref config_ssid.h + Definition of per network configuration items + +\ref config.h + Definition of the wpa_supplicant configuration + +\ref config.c + Configuration parser and common functions + +\ref wpa_supplicant/config_file.c + Configuration backend for text files (e.g., wpa_supplicant.conf) + +\ref config_winreg.c + Configuration backend for Windows registry + + +\section ctrl_iface Control interface + +wpa_supplicant has a \ref ctrl_iface_page "control interface" +that can be used to get status +information and manage operations from external programs. An example +command line interface (wpa_cli) and GUI (wpa_gui) for this interface +are included in the wpa_supplicant distribution. + +\ref wpa_supplicant/ctrl_iface.c and \ref wpa_supplicant/ctrl_iface.h + wpa_supplicant-side of the control interface + +\ref ctrl_iface_unix.c + UNIX domain sockets -based control interface backend + +\ref ctrl_iface_udp.c + UDP sockets -based control interface backend + +\ref ctrl_iface_named_pipe.c + Windows named pipes -based control interface backend + +\ref wpa_ctrl.c and \ref wpa_ctrl.h + Library functions for external programs to provide access to the + wpa_supplicant control interface + +\ref wpa_cli.c + Example program for using wpa_supplicant control interface + + +\section wpa_code WPA supplicant + +\ref wpa.c and \ref wpa.h + WPA state machine and 4-Way/Group Key Handshake processing + +\ref preauth.c and \ref preauth.h + PMKSA caching and pre-authentication (RSN/WPA2) + +\ref wpa_i.h + Internal definitions for WPA code; not to be included to other modules. + +\section eap_peer EAP peer + +\ref eap_peer_module "EAP peer implementation" is a separate module that +can be used by other programs than just wpa_supplicant. + +\ref eap.c and \ref eap.h + EAP state machine and method interface + +\ref eap_defs.h + Common EAP definitions + +\ref eap_i.h + Internal definitions for EAP state machine and EAP methods; not to be + included in other modules + +\ref eap_sim_common.c and \ref eap_sim_common.h + Common code for EAP-SIM and EAP-AKA + +\ref eap_tls_common.c and \ref eap_tls_common.h + Common code for EAP-PEAP, EAP-TTLS, and EAP-FAST + +\ref eap_ttls.c and \ref eap_ttls.h + EAP-TTLS + +\ref eap_pax.c, \ref eap_pax_common.h, \ref eap_pax_common.c + EAP-PAX + +\ref eap_psk.c, \ref eap_psk_common.h, \ref eap_psk_common.c + EAP-PSK (note: this is not needed for WPA-PSK) + +\ref eap_sake.c, \ref eap_sake_common.h, \ref eap_sake_common.c + EAP-SAKE + +\ref eap_gpsk.c, \ref eap_gpsk_common.h, \ref eap_gpsk_common.c + EAP-GPSK + +\ref eap_aka.c, \ref eap_fast.c, \ref eap_gtc.c, \ref eap_leap.c, +\ref eap_md5.c, \ref eap_mschapv2.c, \ref eap_otp.c, \ref eap_peap.c, +\ref eap_sim.c, \ref eap_tls.c + Other EAP method implementations + + +\section eapol_supp EAPOL supplicant + +\ref eapol_supp_sm.c and \ref eapol_supp_sm.h + EAPOL supplicant state machine and IEEE 802.1X processing + + +\section win_port Windows port + +\ref ndis_events.c + Code for receiving NdisMIndicateStatus() events and delivering them to + wpa_supplicant \ref driver_ndis.c in more easier to use form + +\ref win_if_list.c + External program for listing current network interface + + +\section test_programs Test programs + +\ref radius_client.c and \ref radius_client.h + RADIUS authentication client implementation for eapol_test + +\ref radius.c and \ref radius.h + RADIUS message processing for eapol_test + +\ref eapol_test.c + Standalone EAP testing tool with integrated RADIUS authentication + client + +\ref preauth_test.c + Standalone RSN pre-authentication tool + +\ref wpa_passphrase.c + WPA ASCII passphrase to PSK conversion + +*/ diff --git a/contrib/wpa/doc/ctrl_iface.doxygen b/contrib/wpa/doc/ctrl_iface.doxygen new file mode 100644 --- /dev/null +++ b/contrib/wpa/doc/ctrl_iface.doxygen @@ -0,0 +1,1054 @@ +/** +\page ctrl_iface_page wpa_supplicant control interface + +wpa_supplicant implements a control interface that can be used by +external programs to control the operations of the wpa_supplicant +daemon and to get status information and event notifications. There is +a small C library, in a form of a single C file, \ref wpa_ctrl.c, that +provides helper functions to facilitate the use of the control +interface. External programs can link this file into them and then use +the library functions documented in \ref wpa_ctrl.h to interact with +wpa_supplicant. This library can also be used with C++. \ref wpa_cli.c and +wpa_gui are example programs using this library. + +There are multiple mechanisms for inter-process communication. For +example, Linux version of wpa_supplicant is using UNIX domain sockets +for the control interface and Windows version UDP sockets. The use of +the functions defined in \ref wpa_ctrl.h can be used to hide the details of +the used IPC from external programs. + + +\section using_ctrl_iface Using the control interface + +External programs, e.g., a GUI or a configuration utility, that need to +communicate with wpa_supplicant should link in \ref wpa_ctrl.c. This +allows them to use helper functions to open connection to the control +interface with \ref wpa_ctrl_open() and to send commands with +\ref wpa_ctrl_request(). + +wpa_supplicant uses the control interface for two types of communication: +commands and unsolicited event messages. Commands are a pair of +messages, a request from the external program and a response from +wpa_supplicant. These can be executed using \ref wpa_ctrl_request(). +Unsolicited event messages are sent by wpa_supplicant to the control +interface connection without specific request from the external program +for receiving each message. However, the external program needs to +attach to the control interface with \ref wpa_ctrl_attach() to receive these +unsolicited messages. + +If the control interface connection is used both for commands and +unsolicited event messages, there is potential for receiving an +unsolicited message between the command request and response. +\ref wpa_ctrl_request() caller will need to supply a callback, msg_cb, +for processing these messages. Often it is easier to open two +control interface connections by calling \ref wpa_ctrl_open() twice and +then use one of the connections for commands and the other one for +unsolicited messages. This way command request/response pairs will +not be broken by unsolicited messages. wpa_cli is an example of how +to use only one connection for both purposes and wpa_gui demonstrates +how to use two separate connections. + +Once the control interface connection is not needed anymore, it should +be closed by calling \ref wpa_ctrl_close(). If the connection was used for +unsolicited event messages, it should be first detached by calling +\ref wpa_ctrl_detach(). + + +\section ctrl_iface_cmds Control interface commands + +Following commands can be used with \ref wpa_ctrl_request(): + +\subsection ctrl_iface_PING PING + +This command can be used to test whether wpa_supplicant is replying +to the control interface commands. The expected reply is \c PONG if the +connection is open and wpa_supplicant is processing commands. + + +\subsection ctrl_iface_MIB MIB + +Request a list of MIB variables (dot1x, dot11). The output is a text +block with each line in \c variable=value format. For example: + +\verbatim +dot11RSNAOptionImplemented=TRUE +dot11RSNAPreauthenticationImplemented=TRUE +dot11RSNAEnabled=FALSE +dot11RSNAPreauthenticationEnabled=FALSE +dot11RSNAConfigVersion=1 +dot11RSNAConfigPairwiseKeysSupported=5 +dot11RSNAConfigGroupCipherSize=128 +dot11RSNAConfigPMKLifetime=43200 +dot11RSNAConfigPMKReauthThreshold=70 +dot11RSNAConfigNumberOfPTKSAReplayCounters=1 +dot11RSNAConfigSATimeout=60 +dot11RSNAAuthenticationSuiteSelected=00-50-f2-2 +dot11RSNAPairwiseCipherSelected=00-50-f2-4 +dot11RSNAGroupCipherSelected=00-50-f2-4 +dot11RSNAPMKIDUsed= +dot11RSNAAuthenticationSuiteRequested=00-50-f2-2 +dot11RSNAPairwiseCipherRequested=00-50-f2-4 +dot11RSNAGroupCipherRequested=00-50-f2-4 +dot11RSNAConfigNumberOfGTKSAReplayCounters=0 +dot11RSNA4WayHandshakeFailures=0 +dot1xSuppPaeState=5 +dot1xSuppHeldPeriod=60 +dot1xSuppAuthPeriod=30 +dot1xSuppStartPeriod=30 +dot1xSuppMaxStart=3 +dot1xSuppSuppControlledPortStatus=Authorized +dot1xSuppBackendPaeState=2 +dot1xSuppEapolFramesRx=0 +dot1xSuppEapolFramesTx=440 +dot1xSuppEapolStartFramesTx=2 +dot1xSuppEapolLogoffFramesTx=0 +dot1xSuppEapolRespFramesTx=0 +dot1xSuppEapolReqIdFramesRx=0 +dot1xSuppEapolReqFramesRx=0 +dot1xSuppInvalidEapolFramesRx=0 +dot1xSuppEapLengthErrorFramesRx=0 +dot1xSuppLastEapolFrameVersion=0 +dot1xSuppLastEapolFrameSource=00:00:00:00:00:00 +\endverbatim + + +\subsection ctrl_iface_STATUS STATUS + +Request current WPA/EAPOL/EAP status information. The output is a text +block with each line in \c variable=value format. For example: + +\verbatim +bssid=02:00:01:02:03:04 +ssid=test network +pairwise_cipher=CCMP +group_cipher=CCMP +key_mgmt=WPA-PSK +wpa_state=COMPLETED +ip_address=192.168.1.21 +Supplicant PAE state=AUTHENTICATED +suppPortStatus=Authorized +EAP state=SUCCESS +\endverbatim + + +\subsection ctrl_iface_STATUS-VERBOSE STATUS-VERBOSE + +Same as STATUS, but with more verbosity (i.e., more \c variable=value pairs). + +\verbatim +bssid=02:00:01:02:03:04 +ssid=test network +id=0 +pairwise_cipher=CCMP +group_cipher=CCMP +key_mgmt=WPA-PSK +wpa_state=COMPLETED +ip_address=192.168.1.21 +Supplicant PAE state=AUTHENTICATED +suppPortStatus=Authorized +heldPeriod=60 +authPeriod=30 +startPeriod=30 +maxStart=3 +portControl=Auto +Supplicant Backend state=IDLE +EAP state=SUCCESS +reqMethod=0 +methodState=NONE +decision=COND_SUCC +ClientTimeout=60 +\endverbatim + + +\subsection ctrl_iface_PMKSA PMKSA + +Show PMKSA cache + +\verbatim +Index / AA / PMKID / expiration (in seconds) / opportunistic +1 / 02:00:01:02:03:04 / 000102030405060708090a0b0c0d0e0f / 41362 / 0 +2 / 02:00:01:33:55:77 / 928389281928383b34afb34ba4212345 / 362 / 1 +\endverbatim + + +\subsection ctrl_iface_SET SET + +Set variables: +- EAPOL::heldPeriod +- EAPOL::authPeriod +- EAPOL::startPeriod +- EAPOL::maxStart +- dot11RSNAConfigPMKLifetime +- dot11RSNAConfigPMKReauthThreshold +- dot11RSNAConfigSATimeout + +Example command: +\verbatim +SET EAPOL::heldPeriod 45 +\endverbatim + + +\subsection ctrl_iface_LOGON LOGON + +IEEE 802.1X EAPOL state machine logon. + + +\subsection ctrl_iface_LOGOFF LOGOFF + +IEEE 802.1X EAPOL state machine logoff. + + +\subsection ctrl_iface_REASSOCIATE REASSOCIATE + +Force reassociation. + + +\subsection ctrl_iface_RECONNECT RECONNECT + +Connect if disconnected (i.e., like \c REASSOCIATE, but only connect +if in disconnected state). + + +\subsection ctrl_iface_PREAUTH PREAUTH + +Start pre-authentication with the given BSSID. + + +\subsection ctrl_iface_ATTACH ATTACH + +Attach the connection as a monitor for unsolicited events. This can +be done with \ref wpa_ctrl_attach(). + + +\subsection ctrl_iface_DETACH DETACH + +Detach the connection as a monitor for unsolicited events. This can +be done with \ref wpa_ctrl_detach(). + + +\subsection ctrl_iface_LEVEL LEVEL + +Change debug level. + + +\subsection ctrl_iface_RECONFIGURE RECONFIGURE + +Force wpa_supplicant to re-read its configuration data. + + +\subsection ctrl_iface_TERMINATE TERMINATE + +Terminate wpa_supplicant process. + + +\subsection ctrl_iface_BSSID BSSID + +Set preferred BSSID for a network. Network id can be received from the +\c LIST_NETWORKS command output. + + +\subsection ctrl_iface_LIST_NETWORKS LIST_NETWORKS + +List configured networks. + +\verbatim +network id / ssid / bssid / flags +0 example network any [CURRENT] +\endverbatim + +(note: fields are separated with tabs) + + +\subsection ctrl_iface_DISCONNECT DISCONNECT + +Disconnect and wait for \c REASSOCIATE or \c RECONNECT command before +connecting. + + +\subsection ctrl_iface_SCAN SCAN + +Request a new BSS scan. + + +\subsection ctrl_iface_SCAN_RESULTS SCAN_RESULTS + +Get the latest scan results. + +\verbatim +bssid / frequency / signal level / flags / ssid +00:09:5b:95:e0:4e 2412 208 [WPA-PSK-CCMP] jkm private +02:55:24:33:77:a3 2462 187 [WPA-PSK-TKIP] testing +00:09:5b:95:e0:4f 2412 209 jkm guest +\endverbatim + +(note: fields are separated with tabs) + + +\subsection ctrl_iface_BSS BSS + +Get detailed per-BSS scan results. \c BSS command can be used to +iterate through scan results one BSS at a time and to fetch all +information from the found BSSes. This provides access to the same +data that is available through \c SCAN_RESULTS but in a way that +avoids problems with large number of scan results not fitting in the +ctrl_iface messages. + +There are two options for selecting the BSS with the \c BSS command: +"BSS " requests information for the BSS identified by the index +(0 .. size-1) in the scan results table and "BSS " requests +information for the given BSS (based on BSSID in 00:01:02:03:04:05 +format). + +BSS information is presented in following format. Please note that new +fields may be added to this field=value data, so the ctrl_iface user +should be prepared to ignore values it does not understand. + +\verbatim +bssid=00:09:5b:95:e0:4e +freq=2412 +beacon_int=0 +capabilities=0x0011 +qual=51 +noise=161 +level=212 +tsf=0000000000000000 +ie=000b6a6b6d2070726976617465010180dd180050f20101000050f20401000050f20401000050f2020000 +ssid=jkm private +\endverbatim + + + +\subsection ctrl_iface_SELECT_NETWORK SELECT_NETWORK + +Select a network (disable others). Network id can be received from the +\c LIST_NETWORKS command output. + + +\subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK + +Enable a network. Network id can be received from the +\c LIST_NETWORKS command output. Special network id \c all can be +used to enable all network. + + +\subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK + +Disable a network. Network id can be received from the +\c LIST_NETWORKS command output. Special network id \c all can be +used to disable all network. + + +\subsection ctrl_iface_ADD_NETWORK ADD_NETWORK + +Add a new network. This command creates a new network with empty +configuration. The new network is disabled and once it has been +configured it can be enabled with \c ENABLE_NETWORK command. \c ADD_NETWORK +returns the network id of the new network or FAIL on failure. + + +\subsection ctrl_iface_REMOVE_NETWORK REMOVE_NETWORK + +Remove a network. Network id can be received from the +\c LIST_NETWORKS command output. Special network id \c all can be +used to remove all network. + + +\subsection ctrl_iface_SET_NETWORK SET_NETWORK + +Set network variables. Network id can be received from the +\c LIST_NETWORKS command output. + +This command uses the same variables and data formats as the +configuration file. See example wpa_supplicant.conf for more details. + +- ssid (network name, SSID) +- psk (WPA passphrase or pre-shared key) +- key_mgmt (key management protocol) +- identity (EAP identity) +- password (EAP password) +- ... + + +\subsection ctrl_iface_GET_NETWORK GET_NETWORK + +Get network variables. Network id can be received from the +\c LIST_NETWORKS command output. + + +\subsection ctrl_iface_SAVE_CONFIG SAVE_CONFIG + +Save the current configuration. + + +\subsection ctrl_iface_P2P_FIND P2P_FIND + +Start P2P device discovery. Optional parameter can be used to specify +the duration for the discovery in seconds (e.g., "P2P_FIND 5"). If the +duration is not specified, discovery will be started for indefinite +time, i.e., until it is terminated by P2P_STOP_FIND or P2P_CONNECT (to +start group formation with a discovered peer). + +The default search type is to first run a full scan of all channels +and then continue scanning only social channels (1, 6, 11). This +behavior can be changed by specifying a different search type: social +(e.g., "P2P_FIND 5 type=social") will skip the initial full scan and +only search social channels; progressive (e.g., "P2P_FIND +type=progressive") starts with a full scan and then searches +progressively through all channels one channel at the time with the +social channel scans. Progressive device discovery can be used to find +new groups (and groups that were not found during the initial scan, +e.g., due to the GO being asleep) over time without adding +considerable extra delay for every Search state round. + + +\subsection ctrl_iface_P2P_STOP_FIND P2P_STOP_FIND + +Stop ongoing P2P device discovery or other operation (connect, listen +mode). + + +\subsection ctrl_iface_P2P_CONNECT P2P_CONNECT + +Start P2P group formation with a discovered P2P peer. This includes +group owner negotiation, group interface setup, provisioning, and +establishing data connection. + +P2P_CONNECT +[label|display|keypad] [persistent] [join|auth] [go_intent=<0..15>] + +Start P2P group formation with a discovered P2P peer. This includes +optional group owner negotiation, group interface setup, provisioning, +and establishing data connection. + +The 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). [label|display|keypad] is used with PIN method +to specify which PIN is used (label=PIN from local label, +display=dynamically generated random PIN from local display, +keypad=PIN entered from peer device label or display). "persistent" +parameter can be used to request a persistent group to be formed. + +"join" indicates that this is a command to join an existing group as a +client. It skips the GO Negotiation part. + +"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. + +The optional "go_intent" parameter can be used to override the default +GO Intent value. + + +\subsection ctrl_iface_P2P_LISTEN P2P_LISTEN + +Start Listen-only state. 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. + + +\subsection ctrl_iface_P2P_GROUP_REMOVE P2P_GROUP_REMOVE + +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. + + +\subsection ctrl_iface_P2P_GROUP_ADD P2P_GROUP_ADD + +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= can be used to specify restart of +a persistent group. + + +\subsection ctrl_iface_P2P_PROV_DISC P2P_PROV_DISC + +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. + + +\subsection ctrl_iface_P2P_GET_PASSPHRASE P2P_GET_PASSPHRASE + +Get the passphrase for a group (only available when acting as a GO). + + +\subsection ctrl_iface_P2P_SERV_DISC_REQ 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 supported service discovery protocols and +requests this to be sent to all discovered peers. The pending requests +are sent during device discovery (see \ref ctrl_iface_P2P_FIND). + +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. + + +\subsection ctrl_iface_P2P_SERV_DISC_CANCEL_REQ P2P_SERV_DISC_CANCEL_REQ + +Cancel a pending P2P service discovery request. This command takes a +single parameter: identifier for the pending query (the value returned +by \ref ctrl_iface_P2P_SERV_DISC_REQ), e.g., +"P2P_SERV_DISC_CANCEL_REQ 1f77628". + + +\subsection ctrl_iface_P2P_SERV_DISC_RESP 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". + + +\subsection ctrl_iface_P2P_SERVICE_UPDATE 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. + + +\subsection ctrl_iface_P2P_SERV_DISC_EXTERNAL P2P_SERV_DISC_EXTERNAL + +Configure external processing of P2P service requests: 0 (default) = +no external processing of requests (i.e., internal code will reject +each request), 1 = external processing of requests (external program +is responsible for replying to service discovery requests with +\ref ctrl_iface_P2P_SERV_DISC_RESP). + + +\subsection ctrl_iface_P2P_REJECT P2P_REJECT + +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. + + +\subsection ctrl_iface_P2P_INVITE P2P_INVITE + +Invite a peer to join a group or to (re)start a persistent group. + + +\subsection ctrl_iface_P2P_PEER P2P_PEER + +Fetch information about a discovered peer. This command takes in an +argument specifying which peer to select: P2P Device Address of the +peer, "FIRST" to indicate the first peer in the list, or "NEXT-" to indicate the entry following the specified peer +(to allow for iterating through the list). + + +\subsection ctrl_iface_P2P_EXT_LISTEN P2P_EXT_LISTEN + +Enable/disable extended listen timing. Without parameters, this +command disables extended listen timing. When enabling the feature, +two parameters are used: availability period and availability interval +(both in milliseconds and with range of 1-65535). + + +\section ctrl_iface_interactive Interactive requests + +If wpa_supplicant needs additional information during authentication +(e.g., password), it will use a specific prefix, \c CTRL-REQ- +(\a WPA_CTRL_REQ macro) in an unsolicited event message. An external +program, e.g., a GUI, can provide such information by using +\c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matching +field name. + +The following fields can be requested in this way from the user: +- IDENTITY (EAP identity/user name) +- PASSWORD (EAP password) +- NEW_PASSWORD (New password if the server is requesting password change) +- PIN (PIN code for accessing a SIM or smartcard) +- OTP (one-time password; like password, but the value is used only once) +- PASSPHRASE (passphrase for a private key file) + +\verbatim +CTRL-REQ--- +CTRL-RSP--- +\endverbatim + +For example, request from wpa_supplicant: +\verbatim +CTRL-REQ-PASSWORD-1-Password needed for SSID test-network +\endverbatim + +And a matching reply from the GUI: +\verbatim +CTRL-RSP-PASSWORD-1-secret +\endverbatim + + +\subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY