2
\page ctrl_iface_page Control interface
4
%wpa_supplicant implements a control interface that can be used by
5
external programs to control the operations of the %wpa_supplicant
6
daemon and to get status information and event notifications. There is
7
a small C library, in a form of a single C file, wpa_ctrl.c, that
8
provides helper functions to facilitate the use of the control
9
interface. External programs can link this file into them and then use
10
the library functions documented in wpa_ctrl.h to interact with
11
%wpa_supplicant. This library can also be used with C++. wpa_cli.c and
12
wpa_gui are example programs using this library.
14
There are multiple mechanisms for inter-process communication. For
15
example, Linux version of %wpa_supplicant is using UNIX domain sockets
16
for the control interface and Windows version UDP sockets. The use of
17
the functions defined in wpa_ctrl.h can be used to hide the details of
18
the used IPC from external programs.
21
\section using_ctrl_iface Using the control interface
23
External programs, e.g., a GUI or a configuration utility, that need to
24
communicate with %wpa_supplicant should link in wpa_ctrl.c. This
25
allows them to use helper functions to open connection to the control
26
interface with wpa_ctrl_open() and to send commands with
29
%wpa_supplicant uses the control interface for two types of communication:
30
commands and unsolicited event messages. Commands are a pair of
31
messages, a request from the external program and a response from
32
%wpa_supplicant. These can be executed using wpa_ctrl_request().
33
Unsolicited event messages are sent by %wpa_supplicant to the control
34
interface connection without specific request from the external program
35
for receiving each message. However, the external program needs to
36
attach to the control interface with wpa_ctrl_attach() to receive these
39
If the control interface connection is used both for commands and
40
unsolicited event messages, there is potential for receiving an
41
unsolicited message between the command request and response.
42
wpa_ctrl_request() caller will need to supply a callback, msg_cb,
43
for processing these messages. Often it is easier to open two
44
control interface connections by calling wpa_ctrl_open() twice and
45
then use one of the connections for commands and the other one for
46
unsolicited messages. This way command request/response pairs will
47
not be broken by unsolicited messages. wpa_cli is an example of how
48
to use only one connection for both purposes and wpa_gui demonstrates
49
how to use two separate connections.
51
Once the control interface connection is not needed anymore, it should
52
be closed by calling wpa_ctrl_close(). If the connection was used for
53
unsolicited event messages, it should be first detached by calling
57
\section ctrl_iface_cmds Control interface commands
59
Following commands can be used with wpa_ctrl_request():
61
\subsection ctrl_iface_PING PING
63
This command can be used to test whether %wpa_supplicant is replying
64
to the control interface commands. The expected reply is \c PONG if the
65
connection is open and %wpa_supplicant is processing commands.
68
\subsection ctrl_iface_MIB MIB
70
Request a list of MIB variables (dot1x, dot11). The output is a text
71
block with each line in \c variable=value format. For example:
74
dot11RSNAOptionImplemented=TRUE
75
dot11RSNAPreauthenticationImplemented=TRUE
76
dot11RSNAEnabled=FALSE
77
dot11RSNAPreauthenticationEnabled=FALSE
78
dot11RSNAConfigVersion=1
79
dot11RSNAConfigPairwiseKeysSupported=5
80
dot11RSNAConfigGroupCipherSize=128
81
dot11RSNAConfigPMKLifetime=43200
82
dot11RSNAConfigPMKReauthThreshold=70
83
dot11RSNAConfigNumberOfPTKSAReplayCounters=1
84
dot11RSNAConfigSATimeout=60
85
dot11RSNAAuthenticationSuiteSelected=00-50-f2-2
86
dot11RSNAPairwiseCipherSelected=00-50-f2-4
87
dot11RSNAGroupCipherSelected=00-50-f2-4
89
dot11RSNAAuthenticationSuiteRequested=00-50-f2-2
90
dot11RSNAPairwiseCipherRequested=00-50-f2-4
91
dot11RSNAGroupCipherRequested=00-50-f2-4
92
dot11RSNAConfigNumberOfGTKSAReplayCounters=0
93
dot11RSNA4WayHandshakeFailures=0
95
dot1xSuppHeldPeriod=60
96
dot1xSuppAuthPeriod=30
97
dot1xSuppStartPeriod=30
99
dot1xSuppSuppControlledPortStatus=Authorized
100
dot1xSuppBackendPaeState=2
101
dot1xSuppEapolFramesRx=0
102
dot1xSuppEapolFramesTx=440
103
dot1xSuppEapolStartFramesTx=2
104
dot1xSuppEapolLogoffFramesTx=0
105
dot1xSuppEapolRespFramesTx=0
106
dot1xSuppEapolReqIdFramesRx=0
107
dot1xSuppEapolReqFramesRx=0
108
dot1xSuppInvalidEapolFramesRx=0
109
dot1xSuppEapLengthErrorFramesRx=0
110
dot1xSuppLastEapolFrameVersion=0
111
dot1xSuppLastEapolFrameSource=00:00:00:00:00:00
115
\subsection ctrl_iface_STATUS STATUS
117
Request current WPA/EAPOL/EAP status information. The output is a text
118
block with each line in \c variable=value format. For example:
121
bssid=02:00:01:02:03:04
127
ip_address=192.168.1.21
128
Supplicant PAE state=AUTHENTICATED
129
suppPortStatus=Authorized
134
\subsection ctrl_iface_STATUS-VERBOSE STATUS-VERBOSE
136
Same as STATUS, but with more verbosity (i.e., more \c variable=value pairs).
139
bssid=02:00:01:02:03:04
146
ip_address=192.168.1.21
147
Supplicant PAE state=AUTHENTICATED
148
suppPortStatus=Authorized
154
Supplicant Backend state=IDLE
163
\subsection ctrl_iface_PMKSA PMKSA
168
Index / AA / PMKID / expiration (in seconds) / opportunistic
169
1 / 02:00:01:02:03:04 / 000102030405060708090a0b0c0d0e0f / 41362 / 0
170
2 / 02:00:01:33:55:77 / 928389281928383b34afb34ba4212345 / 362 / 1
174
\subsection ctrl_iface_SET SET <variable> <value>
181
- dot11RSNAConfigPMKLifetime
182
- dot11RSNAConfigPMKReauthThreshold
183
- dot11RSNAConfigSATimeout
187
SET EAPOL::heldPeriod 45
191
\subsection ctrl_iface_LOGON LOGON
193
IEEE 802.1X EAPOL state machine logon.
196
\subsection ctrl_iface_LOGOFF LOGOFF
198
IEEE 802.1X EAPOL state machine logoff.
201
\subsection ctrl_iface_REASSOCIATE REASSOCIATE
206
\subsection ctrl_iface_PREAUTH PREAUTH <BSSID>
208
Start pre-authentication with the given BSSID.
211
\subsection ctrl_iface_ATTACH ATTACH
213
Attach the connection as a monitor for unsolicited events. This can
214
be done with wpa_ctrl_attach().
217
\subsection ctrl_iface_DETACH DETACH
219
Detach the connection as a monitor for unsolicited events. This can
220
be done with wpa_ctrl_detach().
223
\subsection ctrl_iface_LEVEL LEVEL <debug level>
228
\subsection ctrl_iface_RECONFIGURE RECONFIGURE
230
Force %wpa_supplicant to re-read its configuration data.
233
\subsection ctrl_iface_TERMINATE TERMINATE
235
Terminate %wpa_supplicant process.
238
\subsection ctrl_iface_BSSID BSSID <network id> <BSSID>
240
Set preferred BSSID for a network. Network id can be received from the
241
\c LIST_NETWORKS command output.
244
\subsection ctrl_iface_LIST_NETWORKS LIST_NETWORKS
246
List configured networks.
249
network id / ssid / bssid / flags
250
0 example network any [CURRENT]
253
(note: fields are separated with tabs)
256
\subsection ctrl_iface_DISCONNECT DISCONNECT
258
Disconnect and wait for \c REASSOCIATE command before connecting.
261
\subsection ctrl_iface_SCAN SCAN
263
Request a new BSS scan.
266
\subsection ctrl_iface_SCAN_RESULTS SCAN_RESULTS
268
Get the latest scan results.
271
bssid / frequency / signal level / flags / ssid
272
00:09:5b:95:e0:4e 2412 208 [WPA-PSK-CCMP] jkm private
273
02:55:24:33:77:a3 2462 187 [WPA-PSK-TKIP] testing
274
00:09:5b:95:e0:4f 2412 209 jkm guest
277
(note: fields are separated with tabs)
280
\subsection ctrl_iface_SELECT_NETWORK SELECT_NETWORK <network id>
282
Select a network (disable others). Network id can be received from the
283
\c LIST_NETWORKS command output.
286
\subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK <network id>
288
Enable a network. Network id can be received from the
289
\c LIST_NETWORKS command output.
292
\subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>
294
Disable a network. Network id can be received from the
295
\c LIST_NETWORKS command output.
298
\subsection ctrl_iface_ADD_NETWORK ADD_NETWORK
300
Add a new network. This command creates a new network with empty
301
configuration. The new network is disabled and once it has been
302
configured it can be enabled with \c ENABLE_NETWORK command. \c ADD_NETWORK
303
returns the network id of the new network or FAIL on failure.
306
\subsection ctrl_iface_REMOVE_NETWORK REMOVE_NETWORK <network id>
308
Remove a network. Network id can be received from the
309
\c LIST_NETWORKS command output.
312
\subsection ctrl_iface_SET_NETWORK SET_NETWORK <network id> <variable> <value>
314
Set network variables. Network id can be received from the
315
\c LIST_NETWORKS command output.
317
This command uses the same variables and data formats as the
318
configuration file. See example wpa_supplicant.conf for more details.
320
- ssid (network name, SSID)
321
- psk (WPA passphrase or pre-shared key)
322
- key_mgmt (key management protocol)
323
- identity (EAP identity)
324
- password (EAP password)
328
\subsection ctrl_iface_GET_NETWORK GET_NETWORK <network id> <variable>
330
Get network variables. Network id can be received from the
331
\c LIST_NETWORKS command output.
334
\subsection ctrl_iface_SAVE_CONFIG SAVE_CONFIG
336
Save the current configuration.
339
\section ctrl_iface_interactive Interactive requests
341
If %wpa_supplicant needs additional information during authentication
342
(e.g., password), it will use a specific prefix, \c CTRL-REQ-
343
(\a WPA_CTRL_REQ macro) in an unsolicited event message. An external
344
program, e.g., a GUI, can provide such information by using
345
\c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matching
348
The following fields can be requested in this way from the user:
349
- IDENTITY (EAP identity/user name)
350
- PASSWORD (EAP password)
351
- NEW_PASSWORD (New password if the server is requesting password change)
352
- PIN (PIN code for accessing a SIM or smartcard)
353
- OTP (one-time password; like password, but the value is used only once)
354
- PASSPHRASE (passphrase for a private key file)
357
CTRL-REQ-<field name>-<network id>-<human readable text>
358
CTRL-RSP-<field name>-<network id>-<value>
361
For example, request from %wpa_supplicant:
363
CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
366
And a matching reply from the GUI:
368
CTRL-RSP-PASSWORD-1-secret
372
\subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option> [strict]
374
Get list of supported functionality (eap, pairwise, group,
375
proto). Supported functionality is shown as space separate lists of
376
values used in the same format as in %wpa_supplicant configuration.
377
If optional argument, 'strict', is added, only the values that the
378
driver claims to explicitly support are included. Without this, all
379
available capabilities are included if the driver does not provide
380
a mechanism for querying capabilities.
382
Example request/reply pairs:
386
AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
390
GET_CAPABILITY pairwise
395
GET_CAPABILITY pairwise strict
400
CCMP TKIP WEP104 WEP40
404
GET_CAPABILITY key_mgmt
405
WPA-PSK WPA-EAP IEEE8021X NONE
414
GET_CAPABILITY auth_alg
419
\subsection ctrl_iface_AP_SCAN AP_SCAN <ap_scan value>
421
Change ap_scan value:
423
1 = %wpa_supplicant requests scans and uses scan results to select the AP,
424
2 = %wpa_supplicant does not use scanning and just requests driver to
425
associate and take care of AP selection
428
\subsection ctrl_iface_INTERFACES INTERFACES
430
List configured interfaces.
added
removed
doc/ctrl_iface.doxygen
