WPA commands

Updated: April 19, 2023
Commands can be sent to the WPA control interface through the cmd argument of wpa_ctrl_request(). The following types of commands are supported:
  • General—Start monitoring events, set the debug level, terminate wpa_supplicant, and more
  • Authentication and connection—Set and get authentication variables, start pre-authentication, get authentication status, and disconnect from and reconnect to an access point
  • Network setup—Add and remove network entries, initiate BSS scans and read the results, and enable, disable, and configure networks
  • Peer-to-peer (P2P)—Configure the Wi-Fi P2P implementation, with commands for device discovery, group formation, service discovery, and more
  • Responses to interactive requests—Respond to a WPA supplicant request for authentication data (e.g., a password)

General

ATTACH
Attach the connection as a monitor for unsolicited events, similar to wpa_ctrl_attach().
DETACH
Detach the connection as a monitor for unsolicited events, similar to wpa_ctrl_detach().
GET_CAPABILITY feature [strict]
Get the supported capabilities for a specific feature (e.g., eap, pairwise, group). These are shown as lists of space-separated values that are in the same format as in the wpa_supplicant configuration. If the optional strict argument is added, only the capabilities that the driver claims to explicitly support are included. Otherwise, all available capabilities are listed if the driver does not provide a mechanism for querying capabilities.
The following is an example of message pairs of capability requests and replies:
GET_CAPABILITY eap
AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS

GET_CAPABILITY pairwise
CCMP TKIP NONE

GET_CAPABILITY pairwise strict


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
LEVEL debug_level
Change the debug level. The argument is an MSG_* constant that maps to a slog2info debugging level as follows:
  • MSG_EXCESSIVE (SLOG2_DEBUG2)
  • MSG_MSGDUMP (SLOG2_DEBUG2)
  • MSG_DEBUG (SLOG2_DEBUG1)
  • MSG_INFO (SLOG2_INFO)
  • MSG_WARNING (SLOG2_WARNING)
  • MSG_ERROR (SLOG2_ERROR)

If you don't issue this command, the default debug level is SLOG2_NOTICE.

PING
Test whether the wpa_supplicant service is replying to control commands. The expected reply is PONG if the connection is open and the service is processing commands.
TERMINATE
Terminate the wpa_supplicant process.

Authentication and connection

DISCONNECT
Disconnect and wait for the REASSOCIATE or RECONNECT command before connecting.
LOGOFF
Log off. This is the IEEE 802.1X EAPOL state machine logoff operation.
LOGON
Log on. This is the IEEE 802.1X EAPOL state machine logon operation.
MIB
Request a list of MIB variables (dot1xVAR, dot11VAR). The output is a text block with each line in variable=value format. For example:
dot11RSNAOptionImplemented=TRUE
dot11RSNAPreauthenticationImplemented=TRUE
...
dot1xSuppPaeState=5
dot1xSuppHeldPeriod=60
...
PMKSA
Show the PMKSA cache. For example:
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
PREAUTH BSSID
Start pre-authentication with the given BSSID.
REASSOCIATE
Force reassociation with an access point. If the client is already connected to one, it will disconnect and then reconnect.
RECONNECT
Connect if disconnected. This is like REASSOCIATE but the service connects only if the client is disconnected.
SET variable value
Set any of the following variables:
  • EAPOL::heldPeriod
  • EAPOL::authPeriod
  • EAPOL::startPeriod
  • EAPOL::maxStart
  • dot11RSNAConfigPMKLifetime
  • dot11RSNAConfigPMKReauthThreshold
  • dot11RSNAConfigSATimeout
STATUS
Request current WPA/EAPOL/EAP status information. The output is a text block with each line in variable=value format:
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):
...
suppPortStatus=Authorized
heldPeriod=60
authPeriod=30
startPeriod=30
maxStart=3
portControl=Auto
Supplicant Backend state=IDLE
EAP state=SUCCESS

Network setup

ADD_NETWORK
Add a network. This command creates a new network with an empty configuration. This network is initially disabled but when it's been configured, it can be enabled with ENABLE_NETWORK. The ADD_NETWORK command returns the network ID of the new network on success, or FAIL on failure.
AP_SCAN ap_scan_policy
Change the access point (AP) scanning policy. The argument can be one of these values:
  • 0 — no scanning
  • 1 — the wpa_supplicant service requests scans and uses scan results to select the AP
  • 2 — the wpa_supplicant service does not use scanning and requests the driver to associate and handle AP selection
BSS
Get detailed per-BSS scan results. This command iterates through the results, one BSS at a time, and fetches all data from the found BSSes. This command returns the same data as SCAN_RESULTS but ensures large numbers of scan results fit into the response.
There are two options for selecting the BSS:
  • BSS idx—requests information for the BSS with the given zero-based index in the scan results table
  • BSS bssid—requests information for the BSS with the given ID, which is in the MAC address format (e.g., 00:01:02:03:04:05)
BSS data are presented in the format shown below. New fields may be added to this field=value data, so the caller should be prepared to ignore values it doesn't understand.
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
BSSID network_id bss_id
Set the preferred Basic Service Set ID (BSSID) for a network. The network ID can be received from the LIST_NETWORKS output.
DISABLE_NETWORK network_id
Disable a network. The network ID can be received from the LIST_NETWORKS output. The special network ID of all can be used to disable all networks.
ENABLE_NETWORK network_id
Enable a network. The network ID can be received from the LIST_NETWORKS output. The special network ID of all can be used to enable all networks.
GET_NETWORK network id variable
Get network variables. The network ID can be received from the LIST_NETWORKS output. For the list of variables that you can get, see SET_NETWORK.
INTERFACES
List the configured network interfaces. The interfaces are listed one per line in the output:
wlan0
eth0
LIST_NETWORKS
List the configured networks. The output is formatted as follows:
network id / ssid / bssid / flags
0       example network any     [CURRENT]
Note that the fields are separated with tabs.
RECONFIGURE
Force wpa_supplicant to re-read its configuration data.
REMOVE_NETWORK network_id
Remove a network. The network ID can be received from the LIST_NETWORKS output. The special network ID of all can be used to remove all networks.
SAVE_CONFIG
Save the current configuration.
SCAN
Request a new BSS scan.
SCAN_RESULTS
Get the latest scan results. The output is formatted as follows:
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 that the fields are separated with tabs.
SELECT_NETWORK network_id
Select a network (disable all others). The network ID can be received from the LIST_NETWORKS output.
SET_NETWORK network_id variable value
Set network variables. The network ID can be received from the LIST_NETWORKS output. The SET_NETWORK command uses the same variables and data formats as the configuration file (see the sample wpa_supplicant.conf for more details).
You can set the following variables:
  • ssid (network name, SSID)
  • psk (WPA passphrase or pre-shared key)
  • key_mgmt (key management protocol)
  • identity (EAP identity)
  • password (EAP password)

P2P: Device discovery

P2P_FIND [duration] [type=search_type|freq=MHz] [dev_id=addr] [dev_type=device_type] [delay=search_delay] [seek=service_name]*
Start P2P device discovery. This command accepts many optional parameters. The first specifies the discovery duration in seconds (e.g., P2P_FIND 5). If this is not specified, discovery persists indefinitely until it's terminated by P2P_STOP_FIND or P2P_CONNECT.
The default search behavior is to first run a full scan of all channels and then scan only social channels (1, 6, and 11). You can change this behavior by specifying the type parameter, which goes after the duration if you specify it. The following non-default search types are supported:
  • social—skips the initial full scan and scans only social channels (e.g., P2P_FIND 5 type=social)
  • progressive—starts with a full scan and then searches through all channels, one at the time, in the search state rounds (e.g., P2P_FIND type=progressive). Progressive searching can be used to find new groups (and groups not found during the initial scan) over time, without adding extra delay for every round.

If you don't specify type, you can set freq to make the initial scan use only the specified channel (with the given frequency in MHz), after which only social channels are scanned.

The next three optional parameters control the search as follows:
  • dev_id—search for a single P2P peer, specified by its MAC address
  • dev_type—search for a single device type (primary or secondary); for example, p2p_find dev_type=1-0050F204-1
  • delay—request an extra delay between search iterations (e.g., to free radio resources)
With seek arguments, you can send 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
P2P_LISTEN [duration]
Start listen-only state (i.e., become discoverable without searching for other devices). You can optionally specify the duration for the Listen operation in seconds. This command is mostly for testing purposes, but can be used to keep the device discoverable without maintaining a group.
P2P_STOP_FIND
Stop any P2P_FIND (device discovery), P2P_CONNECT, or P2P_LISTEN operations.

P2P: Group formation

P2P_CONNECT peer_device_address pbc|pin|PIN#|p2ps [display|keypad] [persistent[=network_id]] [join|auth] [go_intent=0..15] [freq=MHz] [provdisc] [auto] [ssid=hexdump]
Start P2P group formation with a discovered P2P peer. The peer device's MAC address must be specified. The WPS provisioning method must also be specified, in one of four ways:
  • pbc—use the pushbutton method
  • pin—use the PIN method
  • PIN#—use the PIN method with this pre-selected PIN (e.g., 12345670)
  • p2ps—use the P2PS default method

When you specify pin or a PIN value, you must follow this parameter with either display, to use a dynamically generated random PIN, or keypad, to use a PIN entered from the peer's display. These parameters can't be set with any other WPS provisioning method.

The persistent parameter can be used without a value to request to form a persistent group. Or, a network ID can be used as the value, to pre-populate an SSID/passphrase configuration based on a previously used group where this device was the Group Owner (GO). This group's parameters will be used if the local end becomes the GO in GO Negotiation.

You can use the join parameter to request to join an existing group as a client—this skips the GO Negotiation and sends a Provision Discovery Request to the target GO before associating for WPS provisioning. Alternatively, you can use auth to indicate that the WPS parameters are authorized for the peer device without starting GO Negotiation (i.e., the peer is expected to start negotiation). This is mainly for testing purposes.

The go_intent parameter overrides the default GO Intent value for this negotiation. The value range is 0 through 15, with 15 forcing the local end to become the GO.

The remaining optional parameters serve the following purposes:
  • freq—set a forced operating channel (e.g., freq=2412 selects 2.4 GHz channel 1)
  • provdisc—request that a Provision Discovery exchange be used before starting GO Negotiation, as a workaround with some P2P implementations that require this to allow the user to accept the connection
  • auto—request wpa_supplicant to automatically determine whether the peer device is operating as a GO and if so, use join-a-group operation rather than GO Negotiation
  • ssid—specify the Group SSID for join operations. This allows the P2P Client interface to filter scan results by SSID, to avoid selecting an incorrect BSS entry in case the same P2P Device or Interface address have been used in multiple groups recently.
CAUTION:
The open source documentation for this command may show additional parameters that aren't supported by our WPA control interface.
P2P_GROUP_ADD [persistent[=network_id]] [freq=MHz]
Set up a P2P group owner manually, that is, without group owner negotiation with a specific peer. This is also known as autonomous GO.

The optional persistent parameter can be specified without a value, to request that the group be persistent. A network ID can be used as the parameter value, to request the restart of a specific presistent group. The optional freq parameter lets the caller force the GO to be started on a specific frequency. Special settings of freq=2 or freq=5 request the best 2.4 GHz or 5 GHz band channel to be selected automatically.

CAUTION:
The open source documentation for this command may show additional parameters that aren't supported by our WPA control interface.
P2P_GROUP_REMOVE group_interface
Terminate a P2P group. If a new virtual network interface was used for the group, it is also removed. The command parameter must be the network interface name of the group interface.
P2P_PEER device_address
Fetch information about a discovered peer. The command's one required parameter specifies the peer's P2P Device Address. A value of FIRST means the first peer in the list, while NEXT-device_address means the entry following the specified peer (to iterate over the list).
P2P_PROV_DISC peer_device_address display|keypad|pbc [join|auto]
Send a Provision Discovery Request to the specified peer. The required parameters are the peer device's MAC address and the desired configuration method. For example, P2P_PROV_DISC 02:01:02:03:04:05 display requests the peer to display a PIN for the client (caller), and P2P_PROV_DISC 02:01:02:03:04:05 keypad requests the peer to enter a PIN that the client displays.

The optional join parameter can be used to request that a running GO prepare for a new client. This is mainly used with display to make it display a PIN. Alternatively, auto can be used to request wpa_supplicant to automatically determine whether the peer device is operating as a GO and if so, use join-a-group PD instead of GO Negotiation PD.

P2P_REJECT peer_device_address
Reject the connection attempt from a peer. The peer device's MAC address must be specified as a parameter. This comand 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 operation

P2P_EXT_LISTEN [period interval]
Disable or enable Extended Listen Timing. To disable it, you can issue this command without parameters. To enable it, you must provide two parameters: the availability period and the availability interval. Both are in milliseconds with a range of 1 to 65535, inclusive. The Listen State will be entered every interval milliseconds for at least period milliseconds.

If the P2P module is not idle when the Extended Listen Timing timeout occurs, the Listen State is skipped.

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

P2P: Invitation

P2P_INVITE persistent=network_id|group=group_ifname [peer=address] [go_dev_addr=address] [freq=MHz] [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 must be used to specify which device to invite.

The optional go_dev_addr parameter can be used to override the GO device address for the Invitation Request if it's unknown for some reason (usually, this isn't needed). When reinvoking a persistent group, the GO device can specify the group's frequency with the freq parameter (in MHz). Meanwhile, the P2P client device can use freq to force a specific operating channel (or invitation failure if GO rejects that), or pref to request a specific channel (while allowing GO to select another channel if needed).

CAUTION:
The open source documentation for this command may show additional parameters that aren't supported by our WPA control interface.

P2P: Service discovery

P2P_SERV_DISC_CANCEL_REQ query_id
Cancel a pending P2P service discovery request. This command takes one parameter: an identifier for the pending query, which was the value returned by P2P_SERV_DISC_REQ.
P2P_SERV_DISC_EXTERNAL external_processing_setting
Disable or enable external processing of P2P service requests. You should set the command parameter to 0 when there's no external processing of requests (i.e., internal code will reject each request). You should set it to 1 when an external program is responsible for replying to service discovery requests with P2P_SERV_DISC_RESP.
P2P_SERV_DISC_REQ peer_device_address TLV1 TLV2 ...
Schedule a P2P service discovery request. The command parameters are the peer device's MAC address, which can be set to all zeros to query every discovered P2P peer that supports service discovery, and P2P Service Query TLV(s) as hexadecimal dumps. 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 P2P_FIND).

This command returns an identifier for the pending query (e.g., 1f77628) that can be used to cancel the request. Directed requests are removed when the peer replies to them.

P2P_SERV_DISC_RESP frequency peer_device_address dialog_token TLV1 TLV2 ...
Reply to a service discovery query. This command takes the following parameters: the frequency in MHz, the peer device's MAC address, a dialog token, and the 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 an external program is used to process the request.

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.

Responses to interactive requests

WPA_CTRL_RSP field_name-network_id-value
Respond to a WPA supplicant request for authentication data.

When the WPA supplicant needs certain information to perform authentication, it sends an event message to the monitor program. For a list of data fields that the service can request, see the WPA_CTRL_REQ event description.

The program can provide the requested field by constructing a command using the WPA_CTRL_RSP macro. This macro provides an alias for the CTRL-RSP- message prefix, and can be used in, say, an snprintf() statement to construct the command. The command must contain the prefix followed by the field name, network ID, and field value.

Suppose the service requests the PASSWORD field. The program can respond as follows:
int send_password(struct wpa_ctrl *ctrl, int netID, char *password)
{
    char cmd[256], reply[256];
    snprintf(cmd, sizeof(cmd), WPA_CTRL_RSP "PASSWORD-%s:%s", netID, password);

    wpa_ctrl_request(ctrl, cmd, strlen(cmd), reply, sizeof(reply), NULL);

    /* Code to process the response and exit the function goes here */
}

The actual command that gets sent is then: CTRL-RSP-PASSWORD-netID-password