contrib/wpa/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_RECONNECT RECONNECT
 207
 208 Connect if disconnected (i.e., like \c REASSOCIATE, but only connect
 209 if in disconnected state).
 210
 211
 212 \subsection ctrl_iface_PREAUTH PREAUTH <BSSID>
 213
 214 Start pre-authentication with the given BSSID.
 215
 216
 217 \subsection ctrl_iface_ATTACH ATTACH
 218
 219 Attach the connection as a monitor for unsolicited events. This can
 220 be done with wpa_ctrl_attach().
 221
 222
 223 \subsection ctrl_iface_DETACH DETACH
 224
 225 Detach the connection as a monitor for unsolicited events. This can
 226 be done with wpa_ctrl_detach().
 227
 228
 229 \subsection ctrl_iface_LEVEL LEVEL <debug level>
 230
 231 Change debug level.
 232
 233
 234 \subsection ctrl_iface_RECONFIGURE RECONFIGURE
 235
 236 Force %wpa_supplicant to re-read its configuration data.
 237
 238
 239 \subsection ctrl_iface_TERMINATE TERMINATE
 240
 241 Terminate %wpa_supplicant process.
 242
 243
 244 \subsection ctrl_iface_BSSID BSSID <network id> <BSSID>
 245
 246 Set preferred BSSID for a network. Network id can be received from the
 247 \c LIST_NETWORKS command output.
 248
 249
 250 \subsection ctrl_iface_LIST_NETWORKS LIST_NETWORKS
 251
 252 List configured networks.
 253
 254 \verbatim
 255 network id / ssid / bssid / flags
 256 0       example network any     [CURRENT]
 257 \endverbatim
 258
 259 (note: fields are separated with tabs)
 260
 261
 262 \subsection ctrl_iface_DISCONNECT DISCONNECT
 263
 264 Disconnect and wait for \c REASSOCIATE or \c RECONNECT command before
 265 connecting.
 266
 267
 268 \subsection ctrl_iface_SCAN SCAN
 269
 270 Request a new BSS scan.
 271
 272
 273 \subsection ctrl_iface_SCAN_RESULTS SCAN_RESULTS
 274
 275 Get the latest scan results.
 276
 277 \verbatim
 278 bssid / frequency / signal level / flags / ssid
 279 00:09:5b:95:e0:4e       2412    208     [WPA-PSK-CCMP]  jkm private
 280 02:55:24:33:77:a3       2462    187     [WPA-PSK-TKIP]  testing
 281 00:09:5b:95:e0:4f       2412    209             jkm guest
 282 \endverbatim
 283
 284 (note: fields are separated with tabs)
 285
 286
 287 \subsection ctrl_iface_BSS BSS
 288
 289 Get detailed per-BSS scan results. \c BSS command can be used to
 290 iterate through scan results one BSS at a time and to fetch all
 291 information from the found BSSes. This provides access to the same
 292 data that is available through \c SCAN_RESULTS but in a way that
 293 avoids problems with large number of scan results not fitting in the
 294 ctrl_iface messages.
 295
 296 There are two options for selecting the BSS with the \c BSS command:
 297 "BSS <idx>" requests information for the BSS identified by the index
 298 (0 .. size-1) in the scan results table and "BSS <BSSID>" requests
 299 information for the given BSS (based on BSSID in 00:01:02:03:04:05
 300 format).
 301
 302 BSS information is presented in following format. Please note that new
 303 fields may be added to this field=value data, so the ctrl_iface user
 304 should be prepared to ignore values it does not understand.
 305
 306 \verbatim
 307 bssid=00:09:5b:95:e0:4e
 308 freq=2412
 309 beacon_int=0
 310 capabilities=0x0011
 311 qual=51
 312 noise=161
 313 level=212
 314 tsf=0000000000000000
 315 ie=000b6a6b6d2070726976617465010180dd180050f20101000050f20401000050f20401000050f2020000
 316 ssid=jkm private
 317 \endverbatim
 318
 319
 320
 321 \subsection ctrl_iface_SELECT_NETWORK SELECT_NETWORK <network id>
 322
 323 Select a network (disable others). Network id can be received from the
 324 \c LIST_NETWORKS command output.
 325
 326
 327 \subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK <network id>
 328
 329 Enable a network. Network id can be received from the
 330 \c LIST_NETWORKS command output. Special network id \c all can be
 331 used to enable all network.
 332
 333
 334 \subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>
 335
 336 Disable a network. Network id can be received from the
 337 \c LIST_NETWORKS command output. Special network id \c all can be
 338 used to disable all network.
 339
 340
 341 \subsection ctrl_iface_ADD_NETWORK ADD_NETWORK
 342
 343 Add a new network. This command creates a new network with empty
 344 configuration. The new network is disabled and once it has been
 345 configured it can be enabled with \c ENABLE_NETWORK command. \c ADD_NETWORK
 346 returns the network id of the new network or FAIL on failure.
 347
 348
 349 \subsection ctrl_iface_REMOVE_NETWORK REMOVE_NETWORK <network id>
 350
 351 Remove a network. Network id can be received from the
 352 \c LIST_NETWORKS command output. Special network id \c all can be
 353 used to remove all network.
 354
 355
 356 \subsection ctrl_iface_SET_NETWORK SET_NETWORK <network id> <variable> <value>
 357
 358 Set network variables. Network id can be received from the
 359 \c LIST_NETWORKS command output.
 360
 361 This command uses the same variables and data formats as the
 362 configuration file. See example wpa_supplicant.conf for more details.
 363
 364 - ssid (network name, SSID)
 365 - psk (WPA passphrase or pre-shared key)
 366 - key_mgmt (key management protocol)
 367 - identity (EAP identity)
 368 - password (EAP password)
 369 - ...
 370
 371
 372 \subsection ctrl_iface_GET_NETWORK GET_NETWORK <network id> <variable>
 373
 374 Get network variables. Network id can be received from the
 375 \c LIST_NETWORKS command output.
 376
 377
 378 \subsection ctrl_iface_SAVE_CONFIG SAVE_CONFIG
 379
 380 Save the current configuration.
 381
 382
 383 \section ctrl_iface_interactive Interactive requests
 384
 385 If %wpa_supplicant needs additional information during authentication
 386 (e.g., password), it will use a specific prefix, \c CTRL-REQ-
 387 (\a WPA_CTRL_REQ macro) in an unsolicited event message. An external
 388 program, e.g., a GUI, can provide such information by using
 389 \c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matching
 390 field name.
 391
 392 The following fields can be requested in this way from the user:
 393 - IDENTITY (EAP identity/user name)
 394 - PASSWORD (EAP password)
 395 - NEW_PASSWORD (New password if the server is requesting password change)
 396 - PIN (PIN code for accessing a SIM or smartcard)
 397 - OTP (one-time password; like password, but the value is used only once)
 398 - PASSPHRASE (passphrase for a private key file)
 399
 400 \verbatim
 401 CTRL-REQ-<field name>-<network id>-<human readable text>
 402 CTRL-RSP-<field name>-<network id>-<value>
 403 \endverbatim
 404
 405 For example, request from %wpa_supplicant:
 406 \verbatim
 407 CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
 408 \endverbatim
 409
 410 And a matching reply from the GUI:
 411 \verbatim
 412 CTRL-RSP-PASSWORD-1-secret
 413 \endverbatim
 414
 415
 416 \subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option> [strict]
 417
 418 Get list of supported functionality (eap, pairwise, group,
 419 proto). Supported functionality is shown as space separate lists of
 420 values used in the same format as in %wpa_supplicant configuration.
 421 If optional argument, 'strict', is added, only the values that the
 422 driver claims to explicitly support are included. Without this, all
 423 available capabilities are included if the driver does not provide
 424 a mechanism for querying capabilities.
 425
 426 Example request/reply pairs:
 427
 428 \verbatim
 429 GET_CAPABILITY eap
 430 AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
 431 \endverbatim
 432
 433 \verbatim
 434 GET_CAPABILITY pairwise
 435 CCMP TKIP NONE
 436 \endverbatim
 437
 438 \verbatim
 439 GET_CAPABILITY pairwise strict
 440 \endverbatim
 441
 442 \verbatim
 443 GET_CAPABILITY group
 444 CCMP TKIP WEP104 WEP40
 445 \endverbatim
 446
 447 \verbatim
 448 GET_CAPABILITY key_mgmt
 449 WPA-PSK WPA-EAP IEEE8021X NONE
 450 \endverbatim
 451
 452 \verbatim
 453 GET_CAPABILITY proto
 454 RSN WPA
 455 \endverbatim
 456
 457 \verbatim
 458 GET_CAPABILITY auth_alg
 459 OPEN SHARED LEAP
 460 \endverbatim
 461
 462
 463 \subsection ctrl_iface_AP_SCAN AP_SCAN <ap_scan value>
 464
 465 Change ap_scan value:
 466 0 = no scanning,
 467 1 = %wpa_supplicant requests scans and uses scan results to select the AP,
 468 2 = %wpa_supplicant does not use scanning and just requests driver to
 469 associate and take care of AP selection
 470
 471
 472 \subsection ctrl_iface_INTERFACES INTERFACES
 473
 474 List configured interfaces.
 475
 476 \verbatim
 477 wlan0
 478 eth0
 479 \endverbatim
 480
 481 */