contrib/wpa_supplicant/doc/ctrl_iface.doxygen

   1 /**
   2 \page ctrl_iface_page Control interface
   3
   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.
  13
  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.
  19
  20
  21 \section using_ctrl_iface Using the control interface
  22
  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
  27 wpa_ctrl_request().
  28
  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
  37 unsolicited messages.
  38
  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.
  50
  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
  54 wpa_ctrl_detach().
  55
  56
  57 \section ctrl_iface_cmds Control interface commands
  58
  59 Following commands can be used with wpa_ctrl_request():
  60
  61 \subsection ctrl_iface_PING PING
  62
  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.
  66
  67
  68 \subsection ctrl_iface_MIB MIB
  69
  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:
  72
  73 \verbatim
  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
  88 dot11RSNAPMKIDUsed=
  89 dot11RSNAAuthenticationSuiteRequested=00-50-f2-2
  90 dot11RSNAPairwiseCipherRequested=00-50-f2-4
  91 dot11RSNAGroupCipherRequested=00-50-f2-4
  92 dot11RSNAConfigNumberOfGTKSAReplayCounters=0
  93 dot11RSNA4WayHandshakeFailures=0
  94 dot1xSuppPaeState=5
  95 dot1xSuppHeldPeriod=60
  96 dot1xSuppAuthPeriod=30
  97 dot1xSuppStartPeriod=30
  98 dot1xSuppMaxStart=3
  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
 112 \endverbatim
 113
 114
 115 \subsection ctrl_iface_STATUS STATUS
 116
 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:
 119
 120 \verbatim
 121 bssid=02:00:01:02:03:04
 122 ssid=test network
 123 pairwise_cipher=CCMP
 124 group_cipher=CCMP
 125 key_mgmt=WPA-PSK
 126 wpa_state=COMPLETED
 127 ip_address=192.168.1.21
 128 Supplicant PAE state=AUTHENTICATED
 129 suppPortStatus=Authorized
 130 EAP state=SUCCESS
 131 \endverbatim
 132
 133
 134 \subsection ctrl_iface_STATUS-VERBOSE STATUS-VERBOSE
 135
 136 Same as STATUS, but with more verbosity (i.e., more \c variable=value pairs).
 137
 138 \verbatim
 139 bssid=02:00:01:02:03:04
 140 ssid=test network
 141 id=0
 142 pairwise_cipher=CCMP
 143 group_cipher=CCMP
 144 key_mgmt=WPA-PSK
 145 wpa_state=COMPLETED
 146 ip_address=192.168.1.21
 147 Supplicant PAE state=AUTHENTICATED
 148 suppPortStatus=Authorized
 149 heldPeriod=60
 150 authPeriod=30
 151 startPeriod=30
 152 maxStart=3
 153 portControl=Auto
 154 Supplicant Backend state=IDLE
 155 EAP state=SUCCESS
 156 reqMethod=0
 157 methodState=NONE
 158 decision=COND_SUCC
 159 ClientTimeout=60
 160 \endverbatim
 161
 162
 163 \subsection ctrl_iface_PMKSA PMKSA
 164
 165 Show PMKSA cache
 166
 167 \verbatim
 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
 171 \endverbatim
 172
 173
 174 \subsection ctrl_iface_SET SET <variable> <value>
 175
 176 Set variables:
 177 - EAPOL::heldPeriod
 178 - EAPOL::authPeriod
 179 - EAPOL::startPeriod
 180 - EAPOL::maxStart
 181 - dot11RSNAConfigPMKLifetime
 182 - dot11RSNAConfigPMKReauthThreshold
 183 - dot11RSNAConfigSATimeout
 184
 185 Example command:
 186 \verbatim
 187 SET EAPOL::heldPeriod 45
 188 \endverbatim
 189
 190
 191 \subsection ctrl_iface_LOGON LOGON
 192
 193 IEEE 802.1X EAPOL state machine logon.
 194
 195
 196 \subsection ctrl_iface_LOGOFF LOGOFF
 197
 198 IEEE 802.1X EAPOL state machine logoff.
 199
 200
 201 \subsection ctrl_iface_REASSOCIATE REASSOCIATE
 202
 203 Force reassociation.
 204
 205
 206 \subsection ctrl_iface_PREAUTH PREAUTH <BSSID>
 207
 208 Start pre-authentication with the given BSSID.
 209
 210
 211 \subsection ctrl_iface_ATTACH ATTACH
 212
 213 Attach the connection as a monitor for unsolicited events. This can
 214 be done with wpa_ctrl_attach().
 215
 216
 217 \subsection ctrl_iface_DETACH DETACH
 218
 219 Detach the connection as a monitor for unsolicited events. This can
 220 be done with wpa_ctrl_detach().
 221
 222
 223 \subsection ctrl_iface_LEVEL LEVEL <debug level>
 224
 225 Change debug level.
 226
 227
 228 \subsection ctrl_iface_RECONFIGURE RECONFIGURE
 229
 230 Force %wpa_supplicant to re-read its configuration data.
 231
 232
 233 \subsection ctrl_iface_TERMINATE TERMINATE
 234
 235 Terminate %wpa_supplicant process.
 236
 237
 238 \subsection ctrl_iface_BSSID BSSID <network id> <BSSID>
 239
 240 Set preferred BSSID for a network. Network id can be received from the
 241 \c LIST_NETWORKS command output.
 242
 243
 244 \subsection ctrl_iface_LIST_NETWORKS LIST_NETWORKS
 245
 246 List configured networks.
 247
 248 \verbatim
 249 network id / ssid / bssid / flags
 250 0       example network any     [CURRENT]
 251 \endverbatim
 252
 253 (note: fields are separated with tabs)
 254
 255
 256 \subsection ctrl_iface_DISCONNECT DISCONNECT
 257
 258 Disconnect and wait for \c REASSOCIATE command before connecting.
 259
 260
 261 \subsection ctrl_iface_SCAN SCAN
 262
 263 Request a new BSS scan.
 264
 265
 266 \subsection ctrl_iface_SCAN_RESULTS SCAN_RESULTS
 267
 268 Get the latest scan results.
 269
 270 \verbatim
 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
 275 \endverbatim
 276
 277 (note: fields are separated with tabs)
 278
 279
 280 \subsection ctrl_iface_SELECT_NETWORK SELECT_NETWORK <network id>
 281
 282 Select a network (disable others). Network id can be received from the
 283 \c LIST_NETWORKS command output.
 284
 285
 286 \subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK <network id>
 287
 288 Enable a network. Network id can be received from the
 289 \c LIST_NETWORKS command output.
 290
 291
 292 \subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>
 293
 294 Disable a network. Network id can be received from the
 295 \c LIST_NETWORKS command output.
 296
 297
 298 \subsection ctrl_iface_ADD_NETWORK ADD_NETWORK
 299
 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.
 304
 305
 306 \subsection ctrl_iface_REMOVE_NETWORK REMOVE_NETWORK <network id>
 307
 308 Remove a network. Network id can be received from the
 309 \c LIST_NETWORKS command output.
 310
 311
 312 \subsection ctrl_iface_SET_NETWORK SET_NETWORK <network id> <variable> <value>
 313
 314 Set network variables. Network id can be received from the
 315 \c LIST_NETWORKS command output.
 316
 317 This command uses the same variables and data formats as the
 318 configuration file. See example wpa_supplicant.conf for more details.
 319
 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)
 325 - ...
 326
 327
 328 \subsection ctrl_iface_GET_NETWORK GET_NETWORK <network id> <variable>
 329
 330 Get network variables. Network id can be received from the
 331 \c LIST_NETWORKS command output.
 332
 333
 334 \subsection ctrl_iface_SAVE_CONFIG SAVE_CONFIG
 335
 336 Save the current configuration.
 337
 338
 339 \section ctrl_iface_interactive Interactive requests
 340
 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
 346 field name.
 347
 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)
 355
 356 \verbatim
 357 CTRL-REQ-<field name>-<network id>-<human readable text>
 358 CTRL-RSP-<field name>-<network id>-<value>
 359 \endverbatim
 360
 361 For example, request from %wpa_supplicant:
 362 \verbatim
 363 CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
 364 \endverbatim
 365
 366 And a matching reply from the GUI:
 367 \verbatim
 368 CTRL-RSP-PASSWORD-1-secret
 369 \endverbatim
 370
 371
 372 \subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option> [strict]
 373
 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.
 381
 382 Example request/reply pairs:
 383
 384 \verbatim
 385 GET_CAPABILITY eap
 386 AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
 387 \endverbatim
 388
 389 \verbatim
 390 GET_CAPABILITY pairwise
 391 CCMP TKIP NONE
 392 \endverbatim
 393
 394 \verbatim
 395 GET_CAPABILITY pairwise strict
 396 \endverbatim
 397
 398 \verbatim
 399 GET_CAPABILITY group
 400 CCMP TKIP WEP104 WEP40
 401 \endverbatim
 402
 403 \verbatim
 404 GET_CAPABILITY key_mgmt
 405 WPA-PSK WPA-EAP IEEE8021X NONE
 406 \endverbatim
 407
 408 \verbatim
 409 GET_CAPABILITY proto
 410 RSN WPA
 411 \endverbatim
 412
 413 \verbatim
 414 GET_CAPABILITY auth_alg
 415 OPEN SHARED LEAP
 416 \endverbatim
 417
 418
 419 \subsection ctrl_iface_AP_SCAN AP_SCAN <ap_scan value>
 420
 421 Change ap_scan value:
 422 0 = no scanning,
 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
 426
 427
 428 \subsection ctrl_iface_INTERFACES INTERFACES
 429
 430 List configured interfaces.
 431
 432 \verbatim
 433 wlan0
 434 eth0
 435 \endverbatim
 436
 437 */