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_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_SELECT_NETWORK SELECT_NETWORK <network id>
 288
 289 Select a network (disable others). Network id can be received from the
 290 \c LIST_NETWORKS command output.
 291
 292
 293 \subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK <network id>
 294
 295 Enable a network. Network id can be received from the
 296 \c LIST_NETWORKS command output.
 297
 298
 299 \subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>
 300
 301 Disable a network. Network id can be received from the
 302 \c LIST_NETWORKS command output.
 303
 304
 305 \subsection ctrl_iface_ADD_NETWORK ADD_NETWORK
 306
 307 Add a new network. This command creates a new network with empty
 308 configuration. The new network is disabled and once it has been
 309 configured it can be enabled with \c ENABLE_NETWORK command. \c ADD_NETWORK
 310 returns the network id of the new network or FAIL on failure.
 311
 312
 313 \subsection ctrl_iface_REMOVE_NETWORK REMOVE_NETWORK <network id>
 314
 315 Remove a network. Network id can be received from the
 316 \c LIST_NETWORKS command output.
 317
 318
 319 \subsection ctrl_iface_SET_NETWORK SET_NETWORK <network id> <variable> <value>
 320
 321 Set network variables. Network id can be received from the
 322 \c LIST_NETWORKS command output.
 323
 324 This command uses the same variables and data formats as the
 325 configuration file. See example wpa_supplicant.conf for more details.
 326
 327 - ssid (network name, SSID)
 328 - psk (WPA passphrase or pre-shared key)
 329 - key_mgmt (key management protocol)
 330 - identity (EAP identity)
 331 - password (EAP password)
 332 - ...
 333
 334
 335 \subsection ctrl_iface_GET_NETWORK GET_NETWORK <network id> <variable>
 336
 337 Get network variables. Network id can be received from the
 338 \c LIST_NETWORKS command output.
 339
 340
 341 \subsection ctrl_iface_SAVE_CONFIG SAVE_CONFIG
 342
 343 Save the current configuration.
 344
 345
 346 \section ctrl_iface_interactive Interactive requests
 347
 348 If %wpa_supplicant needs additional information during authentication
 349 (e.g., password), it will use a specific prefix, \c CTRL-REQ-
 350 (\a WPA_CTRL_REQ macro) in an unsolicited event message. An external
 351 program, e.g., a GUI, can provide such information by using
 352 \c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matching
 353 field name.
 354
 355 The following fields can be requested in this way from the user:
 356 - IDENTITY (EAP identity/user name)
 357 - PASSWORD (EAP password)
 358 - NEW_PASSWORD (New password if the server is requesting password change)
 359 - PIN (PIN code for accessing a SIM or smartcard)
 360 - OTP (one-time password; like password, but the value is used only once)
 361 - PASSPHRASE (passphrase for a private key file)
 362
 363 \verbatim
 364 CTRL-REQ-<field name>-<network id>-<human readable text>
 365 CTRL-RSP-<field name>-<network id>-<value>
 366 \endverbatim
 367
 368 For example, request from %wpa_supplicant:
 369 \verbatim
 370 CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
 371 \endverbatim
 372
 373 And a matching reply from the GUI:
 374 \verbatim
 375 CTRL-RSP-PASSWORD-1-secret
 376 \endverbatim
 377
 378
 379 \subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option> [strict]
 380
 381 Get list of supported functionality (eap, pairwise, group,
 382 proto). Supported functionality is shown as space separate lists of
 383 values used in the same format as in %wpa_supplicant configuration.
 384 If optional argument, 'strict', is added, only the values that the
 385 driver claims to explicitly support are included. Without this, all
 386 available capabilities are included if the driver does not provide
 387 a mechanism for querying capabilities.
 388
 389 Example request/reply pairs:
 390
 391 \verbatim
 392 GET_CAPABILITY eap
 393 AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
 394 \endverbatim
 395
 396 \verbatim
 397 GET_CAPABILITY pairwise
 398 CCMP TKIP NONE
 399 \endverbatim
 400
 401 \verbatim
 402 GET_CAPABILITY pairwise strict
 403 \endverbatim
 404
 405 \verbatim
 406 GET_CAPABILITY group
 407 CCMP TKIP WEP104 WEP40
 408 \endverbatim
 409
 410 \verbatim
 411 GET_CAPABILITY key_mgmt
 412 WPA-PSK WPA-EAP IEEE8021X NONE
 413 \endverbatim
 414
 415 \verbatim
 416 GET_CAPABILITY proto
 417 RSN WPA
 418 \endverbatim
 419
 420 \verbatim
 421 GET_CAPABILITY auth_alg
 422 OPEN SHARED LEAP
 423 \endverbatim
 424
 425
 426 \subsection ctrl_iface_AP_SCAN AP_SCAN <ap_scan value>
 427
 428 Change ap_scan value:
 429 0 = no scanning,
 430 1 = %wpa_supplicant requests scans and uses scan results to select the AP,
 431 2 = %wpa_supplicant does not use scanning and just requests driver to
 432 associate and take care of AP selection
 433
 434
 435 \subsection ctrl_iface_INTERFACES INTERFACES
 436
 437 List configured interfaces.
 438
 439 \verbatim
 440 wlan0
 441 eth0
 442 \endverbatim
 443
 444 */