WPA Control Interfacewpa_ctrl_recv() Parent topic: wpa_ctrl_recv()

WPA events

Updated: April 19, 2023

The WPA control interface generates messages for events such as connection establishment or access point discovery. Event messages are unsolicited, meaning they're not delivered in response to a command request but based on an occurrence in the underlying wpa_supplicant (or hostapd) service.

When you read an available event message with wpa_ctrl_recv(), the message's contents are written into the buffer referred to by the reply argument. Each message begins with the priority level (in angled brackets) and a prefix that defines the event type. Additional information may follow, depending on the event. For example, the following message is delivered when a new BSS entry was added:

<2>CTRL-EVENT-BSS-ADDED entry_ID BSS_ID

The following priority levels are possible:
  • 0 = MSGDUMP
  • 1 = DEBUG
  • 2 = INFO
  • 3 = WARNING
  • 4 = ERROR

By default, messages of any priority level of at least 2 (INFO) are delivered. The LEVEL command can be used to change the minimum level required for a message to be delivered. There are many debug messages that don't include a prefix and are subject to change; usually, external programs can ignore these. Often, programs can also ignore the priority field and then compare the text that follows to the message prefixes that represent events of interest. (In the event message examples below, we don't show the priority field, for compactness.)

The WPA control interface can report the following kinds of events:
  • Connectivity—Updates in connection and WPA supplicant availability, and password changes
  • Scanning—New scan results, and BSS entry additions and removals
  • Extensible Authentication Protocol (EAP)—EAP updates (e.g., authentication success or failure)
  • AP and WPS—Access Point (AP) and Wi-Fi Protected Setup (WPS) updates (e.g., AP or Enrollee additions or removals, registration success or failure, station associations and disassociations)
  • Peer-to-peer (P2P)— P2P device updates or operation results (e.g., device discovery, discovery requests, GO negotiation, group formation progress)
  • Interactive requests—Requests from the WPA supplicant for authentication data (e.g., a password)
Note:

The event type strings listed here are macros that provide aliases to the actual message prefixes. These macros are useful in parsing the message text.

Not all supported event types are listed here (or in the macros reference); we describe the more common ones. You can see the complete list of supported event types in wpa_ctrl.h.

Connectivity

WPA_EVENT_CONNECTED
Authentication has completed successfully and the data connection is now available.
WPA_EVENT_DISCONNECTED
The data connection has been disconnected and is no longer available.
WPA_EVENT_PASSWORD_CHANGED
The password change has completed successfully.
WPA_EVENT_TERMINATING
The wpa_supplicant service is exiting.

Scanning

WPA_EVENT_BSS_ADDED entry_ID BSS_ID
A new BSS entry was added. The message prefix is followed by the BSS entry ID and BSSID: 
CTRL-EVENT-BSS-ADDED 34 00:11:22:33:44:55
WPA_EVENT_BSS_REMOVED entry_ID BSS_ID
A BSS entry was removed. The message prefix is followed by the BSS entry ID and BSSID.
WPA_EVENT_SCAN_RESULTS
New scan results are available.

EAP

WPA_EVENT_EAP_FAILURE
EAP authentication has failed (i.e., EAP-Failure was received).
WPA_EVENT_EAP_METHOD
The EAP method has been selected.
WPA_EVENT_EAP_NOTIFICATION
EAP-Request/Notification was received.
WPA_EVENT_EAP_STARTED
EAP authentication has started (i.e., EAP-Request/Identity was received).
WPA_EVENT_EAP_SUCCESS
EAP authentication has succeeded.

AP and WPS

AP_STA_CONNECTED MAC
A station associated with us (this is used in AP mode). The message prefix is followed by the station's MAC address: 
AP-STA-CONNECTED 02:2a:c4:18:5b:f3
AP_STA_DISCONNECTED MAC
A station disassociated from us (this is used in AP mode). The message prefix is followed by the station's MAC address: 
AP-STA-DISCONNECTED 02:2a:c4:18:5b:f3
WPS_EVENT_AP_AVAILABLE
An available WPS AP was found in the scan results.
WPS_EVENT_AP_AVAILABLE_PBC
An available WPS AP with active PBC was found in the scan results.
WPS_EVENT_AP_AVAILABLE_PIN
An available WPS AP with a recently selected PIN registrar was found in the scan results.
WPS_EVENT_AP_SETUP_LOCKED
The AP has changed into setup locked state due to multiple failed configuration attempts using the AP PIN.
WPS_EVENT_CRED_RECEIVED
A new credential was received.
WPS_EVENT_ENROLLEE_SEEN field1 field2 ...
A WPS Enrollee was detected (this is used in AP mode). The message prefix is followed by the enrollee's MAC address, UUID, private device type, configuration methods, device password ID, request type, and device name (in square brackets): 
WPS-ENROLLEE-SEEN 02:00:00:00:01:00
572cf82f-c957-5653-9b16-b5cfb298abf1 1-0050F204-1 0x80 4 1
[Wireless Client]
WPS_EVENT_ER_AP_ADD field1 field2 ...
The WPS ER discovered an AP. The additional fields provide the UUID, MAC address, private device type, WPS state, user-friendly name, manufacturer, model description, model name, manufacturer URL, and model URL: 
WPS-ER-AP-ADD 87654321-9abc-def0-1234-56789abc0002 02:11:22:33:44:55
pri_dev_type=6-0050F204-1 wps_state=1 |Very friendly name|Company|
Long description of the model|WAP|http://w1.fi/|http://w1.fi/hostapd/
WPS_EVENT_ER_AP_REMOVE UUID
The WPS ER removed an AP entry. The message prefix is followed by the AP's UUID: 
WPS-ER-AP-REMOVE 87654321-9abc-def0-1234-56789abc0002
WPS_EVENT_ER_ENROLLEE_ADD field1 field2 ...
The WPS ER discovered a new Enrollee. The additional fields provide the UUID, MAC address, M1 received status, configuration methods, device password ID, private device type, device name, manufacturer, model name, model number, and serial number: 
WPS-ER-ENROLLEE-ADD 2b7093f1-d6fb-5108-adbb-bea66bb87333
02:66:a0:ee:17:27 M1=1 config_methods=0x14d dev_passwd_id=0
pri_dev_type=1-0050F204-1
|Wireless Client|Company|cmodel|123|12345|
WPS_EVENT_ER_ENROLLEE_REMOVE UUID MAC
The WPS ER removed an Enrollee entry. The message prefix is followed by the Enrollee's UUID and MAC address: 
WPS-ER-ENROLLEE-REMOVE 2b7093f1-d6fb-5108-adbb-bea66bb87333
02:66:a0:ee:17:27
WPS_EVENT_FAIL
WPS registration failed after M2/M2D.
WPS_EVENT_M2D
M2D was received.
WPS_EVENT_NEW_AP_SETTINGS
New AP settings were received.
WPS_EVENT_OVERLAP
WPS overlap has been detected in PBC mode.
WPS_EVENT_PIN_NEEDED field1 field2 ...
A PIN is needed to complete provisioning with an Enrollee. The additional fields specify the Enrollee's UUID, MAC address, device name, manufacturer, model name, model number, serial number, and primary device type: 
WPS-PIN-NEEDED 5a02a5fa-9199-5e7c-bc46-e183d3cb32f7 02:2a:c4:18:5b:f3
[Wireless Client|Company|cmodel|123|12345|1-0050F204-1]
WPS_EVENT_REG_SUCCESS
WPS provisioning completed successfully (this is used by the AP/Registrar).
WPS_EVENT_SUCCESS
WPS registration completed successfully.
WPS_EVENT_TIMEOUT
The WPS enrollment attempt timed out and was terminated.

P2P

P2P_EVENT_DEVICE_FOUND field1 field2 ...
A P2P device has been discovered. The message prefix is followed by the device's global MAC address, P2P device address (for communication within a group), private device type, device name, configuration methods, device capabilities, and group capabilities: 
P2P-DEVICE-FOUND 02:b5:64:63:30:63 p2p_dev_addr=02:b5:64:63:30:63
pri_dev_type=1-0050f204-1 name='Wireless Client' config_methods=0x84
dev_capab=0x21 group_capab=0x0
P2P_EVENT_GO_NEG_FAILURE
Group Owner (GO) negotiation failed.
P2P_EVENT_GO_NEG_REQUEST MAC dev_passwd_id=password_ID
A P2P device requested GO negotiation, but we weren't ready to start negotiation. The additional fields provide the device's MAC address and password ID: 
P2P-GO-NEG-REQUEST 02:40:61:c2:f3:b7 dev_passwd_id=4
P2P_EVENT_GO_NEG_SUCCESS
Group Owner (GO) negotiation completed successfully.
P2P_EVENT_GROUP_FORMATION_FAILURE
P2P group formation failed (e.g., due to a provisioning failure or timeout).
P2P_EVENT_GROUP_FORMATION_SUCCESS
P2P group formation completed successfully.
P2P_EVENT_GROUP_REMOVED iface_name role
A P2P group has been removed. The additional fields specify the network interface name for the group, and the role (GO/client): 
P2P-GROUP-REMOVED wlan0-p2p-0 GO
P2P_EVENT_GROUP_STARTED field1 field2 ...
A new P2P group has been started. There are many fields that can follow the message prefix. At a minimum, there are fields for the network interface name for the group, role (GO/client), SSID, and frequency. On a client, the PSK is then listed in the psk field; on a GO, the passphrase used in the group is listed (if it's known) in the passphrase field. The MAC address of the GO device is always present, and follows these optional fields. If the group is persistent, a flag for this property is included as the last field. 
P2P-GROUP-STARTED wlan0-p2p-0 GO ssid="DIRECT-3F Testing" freq=2412
passphrase="12345678" go_dev_addr=02:40:61:c2:f3:b7 [PERSISTENT]
P2P_EVENT_INVITATION_RECEIVED sa=MAC persistent=net_block
A P2P Invitation Request was received. There are additional fields for the source MAC address and for persistent groups, the network block that includes the persistent group data: 
P2P-INVITATION-RECEIVED sa=02:40:61:c2:f3:b7 persistent=0
P2P_EVENT_INVITATION_RESULT status=code
An invitation requested with P2P_INVITE has returned a result. The one additional field, status, shows the status code returned by the peer (or -1 on local failure or timeout): 
P2P-INVITATION-RESULT status=1
P2P_EVENT_PROV_DISC_ENTER_PIN field1 field2 ...
Request from the peer for us to enter a PIN displayed on it. There are fields for the device's global MAC address, P2P device address (for communication within a group), private device type, device name, configuration methods, device capabilities, and group capabilities: 
P2P-PROV-DISC-ENTER-PIN 02:40:61:c2:f3:b7 p2p_dev_addr=02:40:61:c2:f3:b7
pri_dev_type=1-0050F204-1 name='Test' config_methods=0x188
dev_capab=0x21 group_capab=0x0
P2P_EVENT_PROV_DISC_PBC_REQ field1 field2 ...
Request from the peer for us to connect using PBC. The additional fields specify the device's global MAC address, P2P device address (for communication within a group), private device type, device name, configuration methods, device capabilities, and group capabilities: 
P2P-PROV-DISC-PBC-REQ 02:40:61:c2:f3:b7 p2p_dev_addr=02:40:61:c2:f3:b7
pri_dev_type=1-0050F204-1 name='Test' config_methods=0x188
dev_capab=0x21 group_capab=0x0
The P2P_CONNECT command can then be used to accept the request.
P2P_EVENT_PROV_DISC_PBC_RESP MAC
The peer accepted our provision discovery request to connect using PBC. The message prefix is followed by the peer's global MAC address: 
P2P-PROV-DISC-PBC-RESP 02:40:61:c2:f3:b7
After this, the P2P_CONNECT command can be used to start GO Negotiation.
P2P_EVENT_PROV_DISC_SHOW_PIN field1 field2 ...
Request from the peer for us to display a PIN that will be entered on the peer. The fields included after the message prefix specify the peer's MAC address, PIN (this is a random PIN generated for this connection), P2P device address, private device type, device name, configuration methods, device capabilities, and group capabilities: 
P2P-PROV-DISC-SHOW-PIN 02:40:61:c2:f3:b7 12345670
p2p_dev_addr=02:40:61:c2:f3:b7 pri_dev_type=1-0050F204-1 name='Test'
config_methods=0x188 dev_capab=0x21 group_capab=0x0
The P2P_CONNECT command can then be used to accept the request with the same PIN configured for the connection.
P2P_EVENT_SERV_DISC_REQ freq MAC token update TLV1 TLV2 ...
A P2P service discovery request was received. The additional fields specify the frequency (in MHz), source MAC address, dialog token, Service Update Indicator, and Service Query TLV(s) as hexadecimal dumps: 
P2P-SERV-DISC-REQ 2412 02:40:61:c2:f3:b7 0 0 02000001
P2P_EVENT_SERV_DISC_RESP MAC update TLV1 TLV2 ...
A P2P service discovery response was received. The additional fields specify the source MAC address, Service Update Indicator, and Service Response TLV(s) as hexadecimal dumps: 
P2P-SERV-DISC-RESP 02:40:61:c2:f3:b7 0 0300000101

Interactive requests

WPA_CTRL_REQ field_name-net_id-description
The WPA supplicant is requesting authentication data.

When the WPA supplicant needs certain information to perform authentication, it sends an event message to the external program. This message contains the WPA_CTRL_REQ string, followed by the name of the data field needed for authentication, the network ID, and a description of the field.

The following fields can be requested in this way:
  • IDENTITY (EAP identity/username)
  • PASSWORD (EAP password)
  • NEW_PASSWORD (New password if the server is requesting a password change)
  • PIN (PIN code for accessing a SIM or smartcard)
  • OTP (one-time password, meaning the value is used only once)
  • PASSPHRASE (passphrase for a private key file)

The WPA_CTRL_REQ macro provides an alias for the CTRL-REQ- message prefix. Suppose the service requests the PASSWORD field. The actual event message that gets sent is then like the following: CTRL-REQ-PASSWORD-1-Password needed for SSID test-network

Parent topic: wpa_ctrl_recv()