freebsd-nq/contrib/wpa_supplicant/doc/ctrl_iface.doxygen

/**
\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
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_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 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_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.


\subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>

Disable a network. Network id can be received from the
\c LIST_NETWORKS command output.


\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.


\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>

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.

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 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

*/