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 pairwise_cipher=CCMP
 142 group_cipher=CCMP
 143 key_mgmt=WPA-PSK
 144 wpa_state=COMPLETED
 145 ip_address=192.168.1.21
 146 Supplicant PAE state=AUTHENTICATED
 147 suppPortStatus=Authorized
 148 heldPeriod=60
 149 authPeriod=30
 150 startPeriod=30
 151 maxStart=3
 152 portControl=Auto
 153 Supplicant Backend state=IDLE
 154 EAP state=SUCCESS
 155 reqMethod=0
 156 methodState=NONE
 157 decision=COND_SUCC
 158 ClientTimeout=60
 159 \endverbatim
 160
 161
 162 \subsection ctrl_iface_PMKSA PMKSA
 163
 164 Show PMKSA cache
 165
 166 \verbatim
 167 Index / AA / PMKID / expiration (in seconds) / opportunistic
 168 1 / 02:00:01:02:03:04 / 000102030405060708090a0b0c0d0e0f / 41362 / 0
 169 2 / 02:00:01:33:55:77 / 928389281928383b34afb34ba4212345 / 362 / 1
 170 \endverbatim
 171
 172
 173 \subsection ctrl_iface_SET SET <variable> <value>
 174
 175 Set variables:
 176 - EAPOL::heldPeriod
 177 - EAPOL::authPeriod
 178 - EAPOL::startPeriod
 179 - EAPOL::maxStart
 180 - dot11RSNAConfigPMKLifetime
 181 - dot11RSNAConfigPMKReauthThreshold
 182 - dot11RSNAConfigSATimeout
 183
 184 Example command:
 185 \verbatim
 186 SET EAPOL::heldPeriod 45
 187 \endverbatim
 188
 189
 190 \subsection ctrl_iface_LOGON LOGON
 191
 192 IEEE 802.1X EAPOL state machine logon.
 193
 194
 195 \subsection ctrl_iface_LOGOFF LOGOFF
 196
 197 IEEE 802.1X EAPOL state machine logoff.
 198
 199
 200 \subsection ctrl_iface_REASSOCIATE REASSOCIATE
 201
 202 Force reassociation.
 203
 204
 205 \subsection ctrl_iface_PREAUTH PREAUTH <BSSID>
 206
 207 Start pre-authentication with the given BSSID.
 208
 209
 210 \subsection ctrl_iface_ATTACH ATTACH
 211
 212 Attach the connection as a monitor for unsolicited events. This can
 213 be done with wpa_ctrl_attach().
 214
 215
 216 \subsection ctrl_iface_DETACH DETACH
 217
 218 Detach the connection as a monitor for unsolicited events. This can
 219 be done with wpa_ctrl_detach().
 220
 221
 222 \subsection ctrl_iface_LEVEL LEVEL <debug level>
 223
 224 Change debug level.
 225
 226
 227 \subsection ctrl_iface_RECONFIGURE RECONFIGURE
 228
 229 Force %wpa_supplicant to re-read its configuration data.
 230
 231
 232 \subsection ctrl_iface_TERMINATE TERMINATE
 233
 234 Terminate %wpa_supplicant process.
 235
 236
 237 \subsection ctrl_iface_BSSID BSSID <network id> <BSSID>
 238
 239 Set preferred BSSID for a network. Network id can be received from the
 240 \c LIST_NETWORKS command output.
 241
 242
 243 \subsection ctrl_iface_LIST_NETWORKS LIST_NETWORKS
 244
 245 List configured networks.
 246
 247 \verbatim
 248 network id / ssid / bssid / flags
 249 0       example network any     [CURRENT]
 250 \endverbatim
 251
 252 (note: fields are separated with tabs)
 253
 254
 255 \subsection ctrl_iface_DISCONNECT DISCONNECT
 256
 257 Disconnect and wait for \c REASSOCIATE command before connecting.
 258
 259
 260 \subsection ctrl_iface_SCAN SCAN
 261
 262 Request a new BSS scan.
 263
 264
 265 \subsection ctrl_iface_SCAN_RESULTS SCAN_RESULTS
 266
 267 Get the latest scan results.
 268
 269 \verbatim
 270 bssid / frequency / signal level / flags / ssid
 271 00:09:5b:95:e0:4e       2412    208     [WPA-PSK-CCMP]  jkm private
 272 02:55:24:33:77:a3       2462    187     [WPA-PSK-TKIP]  testing
 273 00:09:5b:95:e0:4f       2412    209             jkm guest
 274 \endverbatim
 275
 276 (note: fields are separated with tabs)
 277
 278
 279 \subsection ctrl_iface_SELECT_NETWORK SELECT_NETWORK <network id>
 280
 281 Select a network (disable others). Network id can be received from the
 282 \c LIST_NETWORKS command output.
 283
 284
 285 \subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK <network id>
 286
 287 Enable a network. Network id can be received from the
 288 \c LIST_NETWORKS command output.
 289
 290
 291 \subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>
 292
 293 Disable a network. Network id can be received from the
 294 \c LIST_NETWORKS command output.
 295
 296
 297 \subsection ctrl_iface_ADD_NETWORK ADD_NETWORK
 298
 299 Add a new network. This command creates a new network with empty
 300 configuration. The new network is disabled and once it has been
 301 configured it can be enabled with \c ENABLE_NETWORK command. \c ADD_NETWORK
 302 returns the network id of the new network or FAIL on failure.
 303
 304
 305 \subsection ctrl_iface_REMOVE_NETWORK REMOVE_NETWORK <network id>
 306
 307 Remove a network. Network id can be received from the
 308 \c LIST_NETWORKS command output.
 309
 310
 311 \subsection ctrl_iface_SET_NETWORK SET_NETWORK <network id> <variable> <value>
 312
 313 Set network variables. Network id can be received from the
 314 \c LIST_NETWORKS command output.
 315
 316 This command uses the same variables and data formats as the
 317 configuration file. See example wpa_supplicant.conf for more details.
 318
 319 - ssid (network name, SSID)
 320 - psk (WPA passphrase or pre-shared key)
 321 - key_mgmt (key management protocol)
 322 - identity (EAP identity)
 323 - password (EAP password)
 324 - ...
 325
 326
 327 \subsection ctrl_iface_GET_NETWORK GET_NETWORK <network id> <variable>
 328
 329 Get network variables. Network id can be received from the
 330 \c LIST_NETWORKS command output.
 331
 332
 333 \subsection ctrl_iface_SAVE_CONFIG SAVE_CONFIG
 334
 335 Save the current configuration.
 336
 337
 338 \section ctrl_iface_interactive Interactive requests
 339
 340 If %wpa_supplicant needs additional information during authentication
 341 (e.g., password), it will use a specific prefix, \c CTRL-REQ-
 342 (\a WPA_CTRL_REQ macro) in an unsolicited event message. An external
 343 program, e.g., a GUI, can provide such information by using
 344 \c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matching
 345 field name.
 346
 347 The following fields can be requested in this way from the user:
 348 - IDENTITY (EAP identity/user name)
 349 - PASSWORD (EAP password)
 350 - NEW_PASSWORD (New password if the server is requesting password change)
 351 - PIN (PIN code for accessing a SIM or smartcard)
 352 - OTP (one-time password; like password, but the value is used only once)
 353 - PASSPHRASE (passphrase for a private key file)
 354
 355 \verbatim
 356 CTRL-REQ-<field name>-<network id>-<human readable text>
 357 CTRL-RSP-<field name>-<network id>-<value>
 358 \endverbatim
 359
 360 For example, request from %wpa_supplicant:
 361 \verbatim
 362 CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
 363 \endverbatim
 364
 365 And a matching reply from the GUI:
 366 \verbatim
 367 CTRL-RSP-PASSWORD-1-secret
 368 \endverbatim
 369
 370
 371 \subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option>
 372
 373 Get list of supported functionality (eap, pairwise, group,
 374 proto). Supported functionality is shown as space separate lists of
 375 values used in the same format as in %wpa_supplicant configuration.
 376
 377 Example request/reply pairs:
 378
 379 \verbatim
 380 GET_CAPABILITY eap
 381 AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
 382 \endverbatim
 383
 384 \verbatim
 385 GET_CAPABILITY pairwise
 386 CCMP TKIP NONE
 387 \endverbatim
 388
 389 \verbatim
 390 GET_CAPABILITY group
 391 CCMP TKIP WEP104 WEP40
 392 \endverbatim
 393
 394 \verbatim
 395 GET_CAPABILITY key_mgmt
 396 WPA-PSK WPA-EAP IEEE8021X NONE
 397 \endverbatim
 398
 399 \verbatim
 400 GET_CAPABILITY proto
 401 RSN WPA
 402 \endverbatim
 403
 404 \verbatim
 405 GET_CAPABILITY auth_alg
 406 OPEN SHARED LEAP
 407 \endverbatim
 408
 409 */