|
@@ -1,481 +0,0 @@
|
|
|
-/**
|
|
|
-\page ctrl_iface_page 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, 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 wpa_ctrl.h to interact with
|
|
|
-%wpa_supplicant. This library can also be used with C++. 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 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 wpa_ctrl.c. This
|
|
|
-allows them to use helper functions to open connection to the control
|
|
|
-interface with wpa_ctrl_open() and to send commands with
|
|
|
-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 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 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.
|
|
|
-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 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 wpa_ctrl_close(). If the connection was used for
|
|
|
-unsolicited event messages, it should be first detached by calling
|
|
|
-wpa_ctrl_detach().
|
|
|
-
|
|
|
-
|
|
|
-\section ctrl_iface_cmds Control interface commands
|
|
|
-
|
|
|
-Following commands can be used with 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 <variable> <value>
|
|
|
-
|
|
|
-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 <BSSID>
|
|
|
-
|
|
|
-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 wpa_ctrl_attach().
|
|
|
-
|
|
|
-
|
|
|
-\subsection ctrl_iface_DETACH DETACH
|
|
|
-
|
|
|
-Detach the connection as a monitor for unsolicited events. This can
|
|
|
-be done with wpa_ctrl_detach().
|
|
|
-
|
|
|
-
|
|
|
-\subsection ctrl_iface_LEVEL LEVEL <debug 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 <network id> <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 <idx>" requests information for the BSS identified by the index
|
|
|
-(0 .. size-1) in the scan results table and "BSS <BSSID>" 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 <network id>
|
|
|
-
|
|
|
-Select a network (disable others). Network id can be received from the
|
|
|
-\c LIST_NETWORKS command output.
|
|
|
-
|
|
|
-
|
|
|
-\subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK <network id>
|
|
|
-
|
|
|
-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 <network id>
|
|
|
-
|
|
|
-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 <network id>
|
|
|
-
|
|
|
-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 <network id> <variable> <value>
|
|
|
-
|
|
|
-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 <network id> <variable>
|
|
|
-
|
|
|
-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.
|
|
|
-
|
|
|
-
|
|
|
-\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-<field name>-<network id>-<human readable text>
|
|
|
-CTRL-RSP-<field name>-<network id>-<value>
|
|
|
-\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 <option> [strict]
|
|
|
-
|
|
|
-Get list of supported functionality (eap, pairwise, group,
|
|
|
-proto). Supported functionality is shown as space separate lists of
|
|
|
-values used in the same format as in %wpa_supplicant configuration.
|
|
|
-If optional argument, 'strict', is added, only the values that the
|
|
|
-driver claims to explicitly support are included. Without this, all
|
|
|
-available capabilities are included if the driver does not provide
|
|
|
-a mechanism for querying capabilities.
|
|
|
-
|
|
|
-Example request/reply pairs:
|
|
|
-
|
|
|
-\verbatim
|
|
|
-GET_CAPABILITY eap
|
|
|
-AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-\verbatim
|
|
|
-GET_CAPABILITY pairwise
|
|
|
-CCMP TKIP NONE
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-\verbatim
|
|
|
-GET_CAPABILITY pairwise strict
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-\verbatim
|
|
|
-GET_CAPABILITY group
|
|
|
-CCMP TKIP WEP104 WEP40
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-\verbatim
|
|
|
-GET_CAPABILITY key_mgmt
|
|
|
-WPA-PSK WPA-EAP IEEE8021X NONE
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-\verbatim
|
|
|
-GET_CAPABILITY proto
|
|
|
-RSN WPA
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-\verbatim
|
|
|
-GET_CAPABILITY auth_alg
|
|
|
-OPEN SHARED LEAP
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-
|
|
|
-\subsection ctrl_iface_AP_SCAN AP_SCAN <ap_scan value>
|
|
|
-
|
|
|
-Change ap_scan value:
|
|
|
-0 = no scanning,
|
|
|
-1 = %wpa_supplicant requests scans and uses scan results to select the AP,
|
|
|
-2 = %wpa_supplicant does not use scanning and just requests driver to
|
|
|
-associate and take care of AP selection
|
|
|
-
|
|
|
-
|
|
|
-\subsection ctrl_iface_INTERFACES INTERFACES
|
|
|
-
|
|
|
-List configured interfaces.
|
|
|
-
|
|
|
-\verbatim
|
|
|
-wlan0
|
|
|
-eth0
|
|
|
-\endverbatim
|
|
|
-
|
|
|
-*/
|