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.

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().

Control interface commands

Following commands can be used with wpa_ctrl_request():

PING

This command can be used to test whether wpa_supplicant is replying to the control interface commands. The expected reply is PONG if the connection is open and wpa_supplicant is processing commands.

MIB

Request a list of MIB variables (dot1x, dot11). The output is a text block with each line in variable=value format. For example:

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

STATUS

Request current WPA/EAPOL/EAP status information. The output is a text block with each line in variable=value format. For example:

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

STATUS-VERBOSE

Same as STATUS, but with more verbosity (i.e., more variable=value pairs).

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

PMKSA

Show PMKSA cache

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

SET <variable> <value>

Set variables:

• EAPOL::heldPeriod
• EAPOL::authPeriod
• EAPOL::startPeriod
• EAPOL::maxStart
• dot11RSNAConfigPMKLifetime
• dot11RSNAConfigPMKReauthThreshold
• dot11RSNAConfigSATimeout

Example command:

SET EAPOL::heldPeriod 45

LOGON

IEEE 802.1X EAPOL state machine logon.

LOGOFF

IEEE 802.1X EAPOL state machine logoff.

REASSOCIATE

Force reassociation.

PREAUTH <BSSID>

Start pre-authentication with the given BSSID.

ATTACH

Attach the connection as a monitor for unsolicited events. This can be done with wpa_ctrl_attach().

DETACH

Detach the connection as a monitor for unsolicited events. This can be done with wpa_ctrl_detach().

LEVEL <debug level>

Change debug level.

RECONFIGURE

Force wpa_supplicant to re-read its configuration data.

TERMINATE

Terminate wpa_supplicant process.

BSSID <network id> <BSSID>

Set preferred BSSID for a network. Network id can be received from the LIST_NETWORKS command output.

LIST_NETWORKS

List configured networks.

network id / ssid / bssid / flags
0	example network	any	[CURRENT]

(note: fields are separated with tabs)

DISCONNECT

Disconnect and wait for REASSOCIATE command before connecting.

SCAN

Request a new BSS scan.

SCAN_RESULTS

Get the latest scan results.

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

(note: fields are separated with tabs)

SELECT_NETWORK <network id>

Select a network (disable others). Network id can be received from the LIST_NETWORKS command output.

ENABLE_NETWORK <network id>

Enable a network. Network id can be received from the LIST_NETWORKS command output.

DISABLE_NETWORK <network id>

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

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 ENABLE_NETWORK command. ADD_NETWORK returns the network id of the new network or FAIL on failure.

REMOVE_NETWORK <network id>

Remove a network. Network id can be received from the LIST_NETWORKS command output.

SET_NETWORK <network id> <variable> <value>

Set network variables. Network id can be received from the 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)
• ...

GET_NETWORK <network id> <variable>

Get network variables. Network id can be received from the LIST_NETWORKS command output.

SAVE_CONFIG

Save the current configuration.

Interactive requests

If wpa_supplicant needs additional information during authentication (e.g., password), it will use a specific prefix, CTRL-REQ- (WPA_CTRL_REQ macro) in an unsolicited event message. An external program, e.g., a GUI, can provide such information by using CTRL-RSP- (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)

CTRL-REQ-<field name>-<network id>-<human readable text>
CTRL-RSP-<field name>-<network id>-<value>

For example, request from wpa_supplicant:

CTRL-REQ-PASSWORD-1-Password needed for SSID test-network

And a matching reply from the GUI:

CTRL-RSP-PASSWORD-1-secret

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:

GET_CAPABILITY eap
AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS

GET_CAPABILITY pairwise
CCMP TKIP NONE

GET_CAPABILITY group
CCMP TKIP WEP104 WEP40

GET_CAPABILITY key_mgmt
WPA-PSK WPA-EAP IEEE8021X NONE

GET_CAPABILITY proto
RSN WPA

GET_CAPABILITY auth_alg
OPEN SHARED LEAP

---