doc/ctrl_iface.doxygen

   1 /**
   2 \page ctrl_iface_page %wpa_supplicant 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 \subsection ctrl_iface_P2P_FIND P2P_FIND
 384
 385 Start P2P device discovery. Optional parameter can be used to specify
 386 the duration for the discovery in seconds (e.g., "P2P_FIND 5"). If the
 387 duration is not specified, discovery will be started for indefinite
 388 time, i.e., until it is terminated by P2P_STOP_FIND or P2P_CONNECT (to
 389 start group formation with a discovered peer).
 390
 391 The default search type is to first run a full scan of all channels
 392 and then continue scanning only social channels (1, 6, 11). This
 393 behavior can be changed by specifying a different search type: social
 394 (e.g., "P2P_FIND 5 type=social") will skip the initial full scan and
 395 only search social channels; progressive (e.g., "P2P_FIND
 396 type=progressive") starts with a full scan and then searches
 397 progressively through all channels one channel at the time with the
 398 social channel scans. Progressive device discovery can be used to find
 399 new groups (and groups that were not found during the initial scan,
 400 e.g., due to the GO being asleep) over time without adding
 401 considerable extra delay for every Search state round.
 402
 403
 404 \subsection ctrl_iface_P2P_STOP_FIND P2P_STOP_FIND
 405
 406 Stop ongoing P2P device discovery or other operation (connect, listen
 407 mode).
 408
 409
 410 \subsection ctrl_iface_P2P_CONNECT P2P_CONNECT
 411
 412 Start P2P group formation with a discovered P2P peer. This includes
 413 group owner negotiation, group interface setup, provisioning, and
 414 establishing data connection.
 415
 416 P2P_CONNECT <peer device address> <pbc|pin|PIN#>
 417 [label|display|keypad] [persistent] [join|auth] [go_intent=<0..15>]
 418
 419 Start P2P group formation with a discovered P2P peer. This includes
 420 optional group owner negotiation, group interface setup, provisioning,
 421 and establishing data connection.
 422
 423 The <pbc|pin|PIN#> parameter specifies the WPS provisioning
 424 method. "pbc" string starts pushbutton method, "pin" string start PIN
 425 method using an automatically generated PIN (which will be returned as
 426 the command return code), PIN# means that a pre-selected PIN can be
 427 used (e.g., 12345670). [label|display|keypad] is used with PIN method
 428 to specify which PIN is used (label=PIN from local label,
 429 display=dynamically generated random PIN from local display,
 430 keypad=PIN entered from peer device label or display). "persistent"
 431 parameter can be used to request a persistent group to be formed.
 432
 433 "join" indicates that this is a command to join an existing group as a
 434 client. It skips the GO Negotiation part.
 435
 436 "auth" indicates that the WPS parameters are authorized for the peer
 437 device without actually starting GO Negotiation (i.e., the peer is
 438 expected to initiate GO Negotiation). This is mainly for testing
 439 purposes.
 440
 441 The optional "go_intent" parameter can be used to override the default
 442 GO Intent value.
 443
 444
 445 \subsection ctrl_iface_P2P_LISTEN P2P_LISTEN
 446
 447 Start Listen-only state. Optional parameter can be used to specify the
 448 duration for the Listen operation in seconds. This command may not
 449 be of that much use during normal operations and is mainly designed
 450 for testing. It can also be used to keep the device discoverable
 451 without having to maintain a group.
 452
 453
 454 \subsection ctrl_iface_P2P_GROUP_REMOVE P2P_GROUP_REMOVE
 455
 456 Terminate a P2P group. If a new virtual network interface was used for
 457 the group, it will also be removed. The network interface name of the
 458 group interface is used as a parameter for this command.
 459
 460
 461 \subsection ctrl_iface_P2P_GROUP_ADD P2P_GROUP_ADD
 462
 463 Set up a P2P group owner manually (i.e., without group owner
 464 negotiation with a specific peer). This is also known as autonomous
 465 GO. Optional persistent=<network id> can be used to specify restart of
 466 a persistent group.
 467
 468
 469 \subsection ctrl_iface_P2P_PROV_DISC P2P_PROV_DISC
 470
 471 Send P2P provision discovery request to the specified peer. The
 472 parameters for this command are the P2P device address of the peer and
 473 the desired configuration method. For example, "P2P_PROV_DISC
 474 02:01:02:03:04:05 display" would request the peer to display a PIN for
 475 us and "P2P_PROV_DISC 02:01:02:03:04:05 keypad" would request the peer
 476 to enter a PIN that we display.
 477
 478
 479 \subsection ctrl_iface_P2P_GET_PASSPHRASE P2P_GET_PASSPHRASE
 480
 481 Get the passphrase for a group (only available when acting as a GO).
 482
 483
 484 \subsection ctrl_iface_P2P_SERV_DISC_REQ P2P_SERV_DISC_REQ
 485
 486 Schedule a P2P service discovery request. The parameters for this
 487 command are the device address of the peer device (or 00:00:00:00:00:00
 488 for wildcard query that is sent to every discovered P2P peer that
 489 supports service discovery) and P2P Service Query TLV(s) as hexdump.
 490 For example, "P2P_SERV_DISC_REQ 00:00:00:00:00:00 02000001" schedules
 491 a request for listing all supported service discovery protocols and
 492 requests this to be sent to all discovered peers. The pending requests
 493 are sent during device discovery (see \ref ctrl_iface_P2P_FIND).
 494
 495 This command returns an identifier for the pending query (e.g.,
 496 "1f77628") that can be used to cancel the request. Directed requests
 497 will be automatically removed when the specified peer has replied to
 498 it.
 499
 500
 501 \subsection ctrl_iface_P2P_SERV_DISC_CANCEL_REQ P2P_SERV_DISC_CANCEL_REQ
 502
 503 Cancel a pending P2P service discovery request. This command takes a
 504 single parameter: identifier for the pending query (the value returned
 505 by \ref ctrl_iface_P2P_SERV_DISC_REQ), e.g.,
 506 "P2P_SERV_DISC_CANCEL_REQ 1f77628".
 507
 508
 509 \subsection ctrl_iface_P2P_SERV_DISC_RESP P2P_SERV_DISC_RESP
 510
 511 Reply to a service discovery query. This command takes following
 512 parameters: frequency in MHz, destination address, dialog token,
 513 response TLV(s). The first three parameters are copied from the
 514 request event. For example,
 515 "P2P_SERV_DISC_RESP 2437 02:40:61:c2:f3:b7 1 0300000101".
 516
 517
 518 \subsection ctrl_iface_P2P_SERVICE_UPDATE P2P_SERVICE_UPDATE
 519
 520 Indicate that local services have changed. This is used to increment
 521 the P2P service indicator value so that peers know when previously
 522 cached information may have changed.
 523
 524
 525 \subsection ctrl_iface_P2P_SERV_DISC_EXTERNAL P2P_SERV_DISC_EXTERNAL
 526
 527 Configure external processing of P2P service requests: 0 (default) =
 528 no external processing of requests (i.e., internal code will reject
 529 each request), 1 = external processing of requests (external program
 530 is responsible for replying to service discovery requests with
 531 \ref ctrl_iface_P2P_SERV_DISC_RESP).
 532
 533
 534 \subsection ctrl_iface_P2P_REJECT P2P_REJECT
 535
 536 Reject connection attempt from a peer (specified with a device
 537 address). This is a mechanism to reject a pending GO Negotiation with
 538 a peer and request to automatically block any further connection or
 539 discovery of the peer.
 540
 541
 542 \subsection ctrl_iface_P2P_INVITE P2P_INVITE
 543
 544 Invite a peer to join a group or to (re)start a persistent group.
 545
 546
 547 \subsection ctrl_iface_P2P_PEER P2P_PEER
 548
 549 Fetch information about a discovered peer. This command takes in an
 550 argument specifying which peer to select: P2P Device Address of the
 551 peer, "FIRST" to indicate the first peer in the list, or "NEXT-<P2P
 552 Device Address>" to indicate the entry following the specified peer
 553 (to allow for iterating through the list).
 554
 555
 556 \subsection ctrl_iface_P2P_EXT_LISTEN P2P_EXT_LISTEN
 557
 558 Enable/disable extended listen timing. Without parameters, this
 559 command disables extended listen timing. When enabling the feature,
 560 two parameters are used: availibility period and availability interval
 561 (both in milliseconds and with range of 1-65535).
 562
 563
 564 \section ctrl_iface_interactive Interactive requests
 565
 566 If %wpa_supplicant needs additional information during authentication
 567 (e.g., password), it will use a specific prefix, \c CTRL-REQ-
 568 (\a WPA_CTRL_REQ macro) in an unsolicited event message. An external
 569 program, e.g., a GUI, can provide such information by using
 570 \c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matching
 571 field name.
 572
 573 The following fields can be requested in this way from the user:
 574 - IDENTITY (EAP identity/user name)
 575 - PASSWORD (EAP password)
 576 - NEW_PASSWORD (New password if the server is requesting password change)
 577 - PIN (PIN code for accessing a SIM or smartcard)
 578 - OTP (one-time password; like password, but the value is used only once)
 579 - PASSPHRASE (passphrase for a private key file)
 580
 581 \verbatim
 582 CTRL-REQ-<field name>-<network id>-<human readable text>
 583 CTRL-RSP-<field name>-<network id>-<value>
 584 \endverbatim
 585
 586 For example, request from %wpa_supplicant:
 587 \verbatim
 588 CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
 589 \endverbatim
 590
 591 And a matching reply from the GUI:
 592 \verbatim
 593 CTRL-RSP-PASSWORD-1-secret
 594 \endverbatim
 595
 596
 597 \subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option> [strict]
 598
 599 Get list of supported functionality (eap, pairwise, group,
 600 proto). Supported functionality is shown as space separate lists of
 601 values used in the same format as in %wpa_supplicant configuration.
 602 If optional argument, 'strict', is added, only the values that the
 603 driver claims to explicitly support are included. Without this, all
 604 available capabilities are included if the driver does not provide
 605 a mechanism for querying capabilities.
 606
 607 Example request/reply pairs:
 608
 609 \verbatim
 610 GET_CAPABILITY eap
 611 AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
 612 \endverbatim
 613
 614 \verbatim
 615 GET_CAPABILITY pairwise
 616 CCMP TKIP NONE
 617 \endverbatim
 618
 619 \verbatim
 620 GET_CAPABILITY pairwise strict
 621 \endverbatim
 622
 623 \verbatim
 624 GET_CAPABILITY group
 625 CCMP TKIP WEP104 WEP40
 626 \endverbatim
 627
 628 \verbatim
 629 GET_CAPABILITY key_mgmt
 630 WPA-PSK WPA-EAP IEEE8021X NONE
 631 \endverbatim
 632
 633 \verbatim
 634 GET_CAPABILITY proto
 635 RSN WPA
 636 \endverbatim
 637
 638 \verbatim
 639 GET_CAPABILITY auth_alg
 640 OPEN SHARED LEAP
 641 \endverbatim
 642
 643
 644 \subsection ctrl_iface_AP_SCAN AP_SCAN <ap_scan value>
 645
 646 Change ap_scan value:
 647 0 = no scanning,
 648 1 = %wpa_supplicant requests scans and uses scan results to select the AP,
 649 2 = %wpa_supplicant does not use scanning and just requests driver to
 650 associate and take care of AP selection
 651
 652
 653 \subsection ctrl_iface_INTERFACES INTERFACES
 654
 655 List configured interfaces.
 656
 657 \verbatim
 658 wlan0
 659 eth0
 660 \endverbatim
 661
 662
 663 \section ctrl_iface_events Control interface events
 664
 665 %wpa_supplicant generates number messages based on events like
 666 connection or a completion of a task. These are available to external
 667 programs that attach to receive unsolicited messages over the control
 668 interface with wpa_ctrl_attach().
 669
 670 The event messages will be delivered over the attach control interface
 671 as text strings that start with the priority level of the message and
 672 a fixed prefix text as defined in wpa_ctrl.h. After this, optional
 673 additional information may be included depending on the event
 674 message. For example, following event message is delivered when new
 675 scan results are available:
 676
 677 \verbatim
 678 <2>CTRL-EVENT-SCAN-RESULTS
 679 \endverbatim
 680
 681 Following priority levels are used:
 682 - 0 = MSGDUMP
 683 - 1 = DEBUG
 684 - 2 = INFO
 685 - 3 = WARNING
 686 - 4 = ERROR
 687
 688 By default, any priority level greater than equal to 2 (INFO) are
 689 delivered over the attached control interface. LEVEL command can be
 690 used to set the level of messages which will be delivered. It should
 691 be noted that there are many debug messages that do not include any
 692 particulat prefix and are subject to change. They may be used for
 693 debug information, but can usually be ignored by external programs.
 694
 695 In most cases, the external program can skip over the priority field
 696 in the beginning of the event message and then compare the following
 697 text to the event strings from wpa_ctrl.h that the program is
 698 interested in processing.
 699
 700 Following subsections describe the most common event notifications
 701 generated by %wpa_supplicant.
 702
 703 \subsection ctrl_iface_event_CTRL_REQ CTRL-REQ-
 704
 705 WPA_CTRL_REQ: Request information from a user. See
 706 \ref ctrl_iface_interactive "Interactive requests" sections for more
 707 details.
 708
 709 \subsection ctrl_iface_event_CONNECTED CTRL-EVENT-CONNECTED
 710
 711 WPA_EVENT_CONNECTED: Indicate successfully completed authentication
 712 and that the data connection is now enabled.
 713
 714 \subsection ctrl_iface_event_DISCONNECTED CTRL-EVENT-DISCONNECTED
 715
 716 WPA_EVENT_DISCONNECTED: Disconnected, data connection is not available
 717
 718 \subsection ctrl_iface_event_TERMINATING  CTRL-EVENT-TERMINATING
 719
 720 WPA_EVENT_TERMINATING: %wpa_supplicant is exiting
 721
 722 \subsection ctrl_iface_event_PASSWORD_CHANGED CTRL-EVENT-PASSWORD-CHANGED
 723
 724 WPA_EVENT_PASSWORD_CHANGED: Password change was completed successfully
 725
 726 \subsection ctrl_iface_event_EAP_NOTIFICATION CTRL-EVENT-EAP-NOTIFICATION
 727
 728 WPA_EVENT_EAP_NOTIFICATION: EAP-Request/Notification received
 729
 730 \subsection ctrl_iface_event_EAP_STARTED CTRL-EVENT-EAP-STARTED
 731
 732 WPA_EVENT_EAP_STARTED: EAP authentication started (EAP-Request/Identity
 733 received)
 734
 735 \subsection ctrl_iface_event_EAP_METHOD CTRL-EVENT-EAP-METHOD
 736
 737 WPA_EVENT_EAP_METHOD: EAP method selected
 738
 739 \subsection ctrl_iface_event_EAP_SUCCESS CTRL-EVENT-EAP-SUCCESS
 740
 741 WPA_EVENT_EAP_SUCCESS: EAP authentication completed successfully
 742
 743 \subsection ctrl_iface_event_EAP_FAILURE CTRL-EVENT-EAP-FAILURE
 744
 745 WPA_EVENT_EAP_FAILURE: EAP authentication failed (EAP-Failure received)
 746
 747 \subsection ctrl_iface_event_SCAN_RESULTS CTRL-EVENT-SCAN-RESULTS
 748
 749 WPA_EVENT_SCAN_RESULTS: New scan results available
 750
 751 \subsection ctrl_iface_event_BSS_ADDED CTRL-EVENT-BSS-ADDED
 752
 753 WPA_EVENT_BSS_ADDED: A new BSS entry was added. The event prefix is
 754 followed by the BSS entry id and BSSID.
 755
 756 \verbatim
 757 CTRL-EVENT-BSS-ADDED 34 00:11:22:33:44:55
 758 \endverbatim
 759
 760 \subsection ctrl_iface_event_BSS_REMOVED CTRL-EVENT-BSS-REMOVED
 761
 762 WPA_EVENT_BSS_REMOVED: A BSS entry was removed. The event prefix is
 763 followed by BSS entry id and BSSID.
 764
 765 \verbatim
 766 CTRL-EVENT-BSS-REMOVED 34 00:11:22:33:44:55
 767 \endverbatim
 768
 769 \subsection ctrl_iface_event_WPS_OVERLAP_DETECTED WPS-OVERLAP-DETECTED
 770
 771 WPS_EVENT_OVERLAP: WPS overlap detected in PBC mode
 772
 773 \subsection ctrl_iface_event_WPS_AP_AVAILABLE_PBC WPS-AP-AVAILABLE-PBC
 774
 775 WPS_EVENT_AP_AVAILABLE_PBC: Available WPS AP with active PBC found in
 776 scan results.
 777
 778 \subsection ctrl_iface_event_WPS_AP_AVAILABLE_PIN WPS-AP-AVAILABLE-PIN
 779
 780 WPS_EVENT_AP_AVAILABLE_PIN: Available WPS AP with recently selected PIN
 781 registrar found in scan results.
 782
 783 \subsection ctrl_iface_event_WPS_AP_AVAILABLE WPS-AP-AVAILABLE
 784
 785 WPS_EVENT_AP_AVAILABLE: Available WPS AP found in scan results
 786
 787 \subsection ctrl_iface_event_WPS_CRED_RECEIVED WPS-CRED-RECEIVED
 788
 789 WPS_EVENT_CRED_RECEIVED: A new credential received
 790
 791 \subsection ctrl_iface_event_WPS_M2D WPS-M2D
 792
 793 WPS_EVENT_M2D: M2D received
 794
 795 \subsection ctrl_iface_event_WPS_FAIL
 796
 797 WPS_EVENT_FAIL: WPS registration failed after M2/M2D
 798
 799 \subsection ctrl_iface_event_WPS_SUCCESS WPS-SUCCESS
 800
 801 WPS_EVENT_SUCCESS: WPS registration completed successfully
 802
 803 \subsection ctrl_iface_event_WPS_TIMEOUT WPS-TIMEOUT
 804
 805 WPS_EVENT_TIMEOUT: WPS enrollment attempt timed out and was terminated
 806
 807 \subsection ctrl_iface_event_WPS_ENROLLEE_SEEN WPS-ENROLLEE-SEEN
 808
 809 WPS_EVENT_ENROLLEE_SEEN: WPS Enrollee was detected (used in AP mode).
 810 The event prefix is followed by MAC addr, UUID-E, pri dev type,
 811 config methods, dev passwd id, request type, [dev name].
 812
 813 \verbatim
 814 WPS-ENROLLEE-SEEN 02:00:00:00:01:00
 815 572cf82f-c957-5653-9b16-b5cfb298abf1 1-0050F204-1 0x80 4 1
 816 [Wireless Client]
 817 \endverbatim
 818
 819 \subsection ctrl_iface_event_WPS_ER_AP_ADD WPS-ER-AP-ADD
 820
 821 WPS_EVENT_ER_AP_ADD: WPS ER discovered an AP
 822
 823 \verbatim
 824 WPS-ER-AP-ADD 87654321-9abc-def0-1234-56789abc0002 02:11:22:33:44:55
 825 pri_dev_type=6-0050F204-1 wps_state=1 |Very friendly name|Company|
 826 Long description of the model|WAP|http://w1.fi/|http://w1.fi/hostapd/
 827 \endverbatim
 828
 829 \subsection ctrl_iface_event_WPS_ER_AP_REMOVE WPS-ER-AP-REMOVE
 830
 831 WPS_EVENT_ER_AP_REMOVE: WPS ER removed an AP entry
 832
 833 \verbatim
 834 WPS-ER-AP-REMOVE 87654321-9abc-def0-1234-56789abc0002
 835 \endverbatim
 836
 837 \subsection ctrl_iface_event_WPS_ER_ENROLLEE_ADD WPS-ER-ENROLLEE-ADD
 838
 839 WPS_EVENT_ER_ENROLLEE_ADD: WPS ER discovered a new Enrollee
 840
 841 \verbatim
 842 WPS-ER-ENROLLEE-ADD 2b7093f1-d6fb-5108-adbb-bea66bb87333
 843 02:66:a0:ee:17:27 M1=1 config_methods=0x14d dev_passwd_id=0
 844 pri_dev_type=1-0050F204-1
 845 |Wireless Client|Company|cmodel|123|12345|
 846 \endverbatim
 847
 848 \subsection ctrl_iface_event_WPS_ER_ENROLLEE_REMOVE WPS-ER-ENROLLEE-REMOVE
 849
 850 WPS_EVENT_ER_ENROLLEE_REMOVE: WPS ER removed an Enrollee entry
 851
 852 \verbatim
 853 WPS-ER-ENROLLEE-REMOVE 2b7093f1-d6fb-5108-adbb-bea66bb87333
 854 02:66:a0:ee:17:27
 855 \endverbatim
 856
 857 \subsection ctrl_iface_event_WPS_PIN_NEEDED WPS-PIN-NEEDED
 858
 859 WPS_EVENT_PIN_NEEDED: PIN is needed to complete provisioning with an
 860 Enrollee. This is followed by information about the Enrollee (UUID,
 861 MAC address, device name, manufacturer, model name, model number,
 862 serial number, primary device type).
 863 \verbatim
 864 WPS-PIN-NEEDED 5a02a5fa-9199-5e7c-bc46-e183d3cb32f7 02:2a:c4:18:5b:f3
 865 [Wireless Client|Company|cmodel|123|12345|1-0050F204-1]
 866 \endverbatim
 867
 868 \subsection ctrl_iface_event_WPS_NEW_AP_SETTINGS WPS-NEW-AP-SETTINGS
 869
 870 WPS_EVENT_NEW_AP_SETTINGS: New AP settings were received
 871
 872 \subsection ctrl_iface_event_WPS_REG_SUCCESS WPS-REG-SUCCESS
 873
 874 WPS_EVENT_REG_SUCCESS: WPS provisioning was completed successfully
 875 (AP/Registrar)
 876
 877 \subsection ctrl_iface_event_WPS_AP_SETUP_LOCKED WPS-AP-SETUP-LOCKED
 878
 879 WPS_EVENT_AP_SETUP_LOCKED: AP changed into setup locked state due to
 880 multiple failed configuration attempts using the AP PIN.
 881
 882 \subsection ctrl_iface_event_AP_STA_CONNECTED AP-STA-CONNECTED
 883
 884 AP_STA_CONNECTED: A station associated with us (AP mode event). The
 885 event prefix is followed by the MAC address of the station.
 886
 887 \verbatim
 888 AP-STA-CONNECTED 02:2a:c4:18:5b:f3
 889 \endverbatim
 890
 891 \subsection ctrl_iface_event_AP_STA_DISCONNECTED AP-STA-DISCONNECTED
 892
 893 AP_STA_DISCONNECTED: A station disassociated (AP mode event)
 894
 895 \verbatim
 896 AP-STA-DISCONNECTED 02:2a:c4:18:5b:f3
 897 \endverbatim
 898
 899 \subsection ctrl_iface_event_P2P_EVENT_DEVICE_FOUND P2P-DEVICE-FOUND
 900
 901 P2P_EVENT_DEVICE_FOUND: Indication of a discovered P2P device with
 902 information about that device.
 903
 904 \verbatim
 905 P2P-DEVICE-FOUND 02:b5:64:63:30:63 p2p_dev_addr=02:b5:64:63:30:63
 906 pri_dev_type=1-0050f204-1 name='Wireless Client' config_methods=0x84
 907 dev_capab=0x21 group_capab=0x0
 908 \endverbatim
 909
 910 \subsection ctrl_iface_event_P2P_EVENT_GO_NEG_REQUEST P2P-GO-NEG-REQUEST
 911
 912 P2P_EVENT_GO_NEG_REQUEST: A P2P device requested GO negotiation, but we
 913 were not ready to start the negotiation.
 914
 915 \verbatim
 916 P2P-GO-NEG-REQUEST 02:40:61:c2:f3:b7 dev_passwd_id=4
 917 \endverbatim
 918
 919 \subsection ctrl_iface_event_P2P_EVENT_GO_NEG_SUCCESS P2P-GO-NEG-SUCCESS
 920
 921 P2P_EVENT_GO_NEG_SUCCESS: Indication of successfully complete group
 922 owner negotiation.
 923
 924 \subsection ctrl_iface_event_P2P_EVENT_GO_NEG_FAILURE P2P-GO-NEG-FAILURE
 925
 926 P2P_EVENT_GO_NEG_FAILURE: Indication of failed group owner negotiation.
 927
 928 \subsection ctrl_iface_event_P2P_EVENT_GROUP_FORMATION_SUCCESS P2P-GROUP-FORMATION-SUCCESS
 929
 930 P2P_EVENT_GROUP_FORMATION_SUCCESS: Indication that P2P group formation
 931 has been completed successfully.
 932
 933 \subsection ctrl_iface_event_P2P_EVENT_GROUP_FORMATION_FAILURE P2P-GROUP-FORMATION-FAILURE
 934
 935 P2P_EVENT_GROUP_FORMATION_FAILURE: Indication that P2P group formation
 936 failed (e.g., due to provisioning failure or timeout).
 937
 938 \subsection ctrl_iface_event_P2P_EVENT_GROUP_STARTED P2P-GROUP-STARTED
 939
 940 P2P_EVENT_GROUP_STARTED: Indication of a new P2P group having been
 941 started. Additional parameters: network interface name for the group,
 942 role (GO/client), SSID. The passphrase used in the group is also
 943 indicated here if known (on GO) or PSK (on client). If the group is a
 944 persistent one, a flag indicating that is included.
 945
 946 \verbatim
 947 P2P-GROUP-STARTED wlan0-p2p-0 GO ssid="DIRECT-3F Testing"
 948 passphrase="12345678" go_dev_addr=02:40:61:c2:f3:b7 [PERSISTENT]
 949 \endverbatim
 950
 951 \subsection ctrl_iface_event_P2P_EVENT_GROUP_REMOVED P2P-GROUP-REMOVED
 952
 953 P2P_EVENT_GROUP_REMOVED: Indication of a P2P group having been removed.
 954 Additional parameters: network interface name for the group, role
 955 (GO/client).
 956
 957 \verbatim
 958 P2P-GROUP-REMOVED wlan0-p2p-0 GO
 959 \endverbatim
 960
 961 \subsection ctrl_iface_event_P2P_EVENT_PROV_DISC_SHOW_PIN P2P-PROV-DISC-SHOW-PIN
 962
 963 P2P_EVENT_PROV_DISC_SHOW_PIN: Request from the peer for us to display
 964 a PIN that will be entered on the peer. The following parameters are
 965 included after the event prefix: peer_address PIN. The PIN is a
 966 random PIN generated for this connection. P2P_CONNECT command can be
 967 used to accept the request with the same PIN configured for the
 968 connection.
 969
 970 \verbatim
 971 P2P-PROV-DISC-SHOW-PIN 02:40:61:c2:f3:b7 12345670
 972 p2p_dev_addr=02:40:61:c2:f3:b7 pri_dev_type=1-0050F204-1 name='Test'
 973 config_methods=0x188 dev_capab=0x21 group_capab=0x0
 974 \endverbatim
 975
 976 \subsection ctrl_iface_event_P2P_EVENT_PROV_DISC_ENTER_PIN P2P-PROV-DISC-ENTER-PIN
 977
 978 P2P_EVENT_PROV_DISC_ENTER_PIN: Request from the peer for us to enter a
 979 PIN displayed on the peer. The following parameter is included after
 980 the event prefix: peer address.
 981
 982 \verbatim
 983 P2P-PROV-DISC-ENTER-PIN 02:40:61:c2:f3:b7 p2p_dev_addr=02:40:61:c2:f3:b7
 984 pri_dev_type=1-0050F204-1 name='Test' config_methods=0x188
 985 dev_capab=0x21 group_capab=0x0
 986 \endverbatim
 987
 988 \subsection ctrl_iface_event_P2P_EVENT_PROV_DISC_PBC_REQ P2P-PROV-DISC-PBC-REQ
 989
 990 P2P_EVENT_PROV_DISC_PBC_REQ: Request from the peer for us to connect
 991 using PBC. The following parameters are included after the event prefix:
 992 peer_address. P2P_CONNECT command can be used to accept the request.
 993
 994 \verbatim
 995 P2P-PROV-DISC-PBC-REQ 02:40:61:c2:f3:b7 p2p_dev_addr=02:40:61:c2:f3:b7
 996 pri_dev_type=1-0050F204-1 name='Test' config_methods=0x188
 997 dev_capab=0x21 group_capab=0x0
 998 \endverbatim
 999
1000 \subsection ctrl_iface_event_P2P_EVENT_PROV_DISC_PBC_RESP P2P-PROV-DISC-PBC-RESP
1001
1002 P2P_EVENT_PROV_DISC_PBC_RESP: The peer accepted our provision discovery
1003 request to connect using PBC. The following parameters are included
1004 after the event prefix: peer_address. P2P_CONNECT command can be used to
1005 start GO Negotiation after this.
1006
1007 \verbatim
1008 P2P-PROV-DISC-PBC-RESP 02:40:61:c2:f3:b7
1009 \endverbatim
1010
1011 \subsection ctrl_iface_event_P2P_EVENT_SERV_DISC_REQ P2P-SERV-DISC-REQ
1012
1013 P2P-SERV-DISC-REQ: Indicate reception of a P2P service discovery
1014 request. The following parameters are included after the event prefix:
1015 frequency in MHz, source address, dialog token, Service Query TLV(s) as
1016 hexdump.
1017
1018 \verbatim
1019 P2P-SERV-DISC-REQ 2412 02:40:61:c2:f3:b7 0 0 02000001
1020 \endverbatim
1021
1022 \subsection ctrl_iface_event_P2P_EVENT_SERV_DISC_RESP P2P-SERV-DISC-RESP
1023
1024 P2P-SERV-DISC-RESP: Indicate reception of a P2P service discovery
1025 response. The following parameters are included after the event prefix:
1026 source address, dialog token, Service Responce TLV(s) as hexdump.
1027
1028 \verbatim
1029 P2P-SERV-DISC-RESP 02:40:61:c2:f3:b7 0 0300000101
1030 \endverbatim
1031
1032 \subsection ctrl_iface_event_P2P_EVENT_INVITATION_RECEIVED P2P-INVITATION-RECEIVED
1033
1034 P2P-INVITATION-RECEIVED: Indicate reception of a P2P Invitation
1035 Request. For persistent groups, the parameter after the event prefix
1036 indicates which network block includes the persistent group data.
1037
1038 \verbatim
1039 P2P-INVITATION-RECEIVED sa=02:40:61:c2:f3:b7 persistent=0
1040 \endverbatim
1041
1042 \subsection ctrl_iface_event_P2P_EVENT_INVITATION_RESULT P2P-INVITATION-RESULT
1043
1044 P2P-INVITATION-RESULT: Indicate result of a P2P invitation that was
1045 requested with \ref ctrl_iface_P2P_INVITE. The parameter
1046 status=<value> shows the status code returned by the peer (or -1 on
1047 local failure or timeout).
1048
1049 \verbatim
1050 P2P-INVITATION-RESULT status=1
1051 \endverbatim
1052
1053 */