123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053 |
- /**
- \page ctrl_iface_page %wpa_supplicant control interface
- %wpa_supplicant implements a control interface that can be used by
- external programs to control the operations of the %wpa_supplicant
- daemon and to get status information and event notifications. There is
- a small C library, in a form of a single C file, wpa_ctrl.c, that
- provides helper functions to facilitate the use of the control
- interface. External programs can link this file into them and then use
- the library functions documented in wpa_ctrl.h to interact with
- %wpa_supplicant. This library can also be used with C++. wpa_cli.c and
- wpa_gui are example programs using this library.
- There are multiple mechanisms for inter-process communication. For
- example, Linux version of %wpa_supplicant is using UNIX domain sockets
- for the control interface and Windows version UDP sockets. The use of
- the functions defined in wpa_ctrl.h can be used to hide the details of
- the used IPC from external programs.
- \section using_ctrl_iface Using the control interface
- External programs, e.g., a GUI or a configuration utility, that need to
- communicate with %wpa_supplicant should link in wpa_ctrl.c. This
- allows them to use helper functions to open connection to the control
- interface with wpa_ctrl_open() and to send commands with
- wpa_ctrl_request().
- %wpa_supplicant uses the control interface for two types of communication:
- commands and unsolicited event messages. Commands are a pair of
- messages, a request from the external program and a response from
- %wpa_supplicant. These can be executed using wpa_ctrl_request().
- Unsolicited event messages are sent by %wpa_supplicant to the control
- interface connection without specific request from the external program
- for receiving each message. However, the external program needs to
- attach to the control interface with wpa_ctrl_attach() to receive these
- unsolicited messages.
- If the control interface connection is used both for commands and
- unsolicited event messages, there is potential for receiving an
- unsolicited message between the command request and response.
- wpa_ctrl_request() caller will need to supply a callback, msg_cb,
- for processing these messages. Often it is easier to open two
- control interface connections by calling wpa_ctrl_open() twice and
- then use one of the connections for commands and the other one for
- unsolicited messages. This way command request/response pairs will
- not be broken by unsolicited messages. wpa_cli is an example of how
- to use only one connection for both purposes and wpa_gui demonstrates
- how to use two separate connections.
- Once the control interface connection is not needed anymore, it should
- be closed by calling wpa_ctrl_close(). If the connection was used for
- unsolicited event messages, it should be first detached by calling
- wpa_ctrl_detach().
- \section ctrl_iface_cmds Control interface commands
- Following commands can be used with wpa_ctrl_request():
- \subsection ctrl_iface_PING PING
- This command can be used to test whether %wpa_supplicant is replying
- to the control interface commands. The expected reply is \c PONG if the
- connection is open and %wpa_supplicant is processing commands.
- \subsection ctrl_iface_MIB MIB
- Request a list of MIB variables (dot1x, dot11). The output is a text
- block with each line in \c variable=value format. For example:
- \verbatim
- dot11RSNAOptionImplemented=TRUE
- dot11RSNAPreauthenticationImplemented=TRUE
- dot11RSNAEnabled=FALSE
- dot11RSNAPreauthenticationEnabled=FALSE
- dot11RSNAConfigVersion=1
- dot11RSNAConfigPairwiseKeysSupported=5
- dot11RSNAConfigGroupCipherSize=128
- dot11RSNAConfigPMKLifetime=43200
- dot11RSNAConfigPMKReauthThreshold=70
- dot11RSNAConfigNumberOfPTKSAReplayCounters=1
- dot11RSNAConfigSATimeout=60
- dot11RSNAAuthenticationSuiteSelected=00-50-f2-2
- dot11RSNAPairwiseCipherSelected=00-50-f2-4
- dot11RSNAGroupCipherSelected=00-50-f2-4
- dot11RSNAPMKIDUsed=
- dot11RSNAAuthenticationSuiteRequested=00-50-f2-2
- dot11RSNAPairwiseCipherRequested=00-50-f2-4
- dot11RSNAGroupCipherRequested=00-50-f2-4
- dot11RSNAConfigNumberOfGTKSAReplayCounters=0
- dot11RSNA4WayHandshakeFailures=0
- dot1xSuppPaeState=5
- dot1xSuppHeldPeriod=60
- dot1xSuppAuthPeriod=30
- dot1xSuppStartPeriod=30
- dot1xSuppMaxStart=3
- dot1xSuppSuppControlledPortStatus=Authorized
- dot1xSuppBackendPaeState=2
- dot1xSuppEapolFramesRx=0
- dot1xSuppEapolFramesTx=440
- dot1xSuppEapolStartFramesTx=2
- dot1xSuppEapolLogoffFramesTx=0
- dot1xSuppEapolRespFramesTx=0
- dot1xSuppEapolReqIdFramesRx=0
- dot1xSuppEapolReqFramesRx=0
- dot1xSuppInvalidEapolFramesRx=0
- dot1xSuppEapLengthErrorFramesRx=0
- dot1xSuppLastEapolFrameVersion=0
- dot1xSuppLastEapolFrameSource=00:00:00:00:00:00
- \endverbatim
- \subsection ctrl_iface_STATUS STATUS
- Request current WPA/EAPOL/EAP status information. The output is a text
- block with each line in \c variable=value format. For example:
- \verbatim
- bssid=02:00:01:02:03:04
- ssid=test network
- pairwise_cipher=CCMP
- group_cipher=CCMP
- key_mgmt=WPA-PSK
- wpa_state=COMPLETED
- ip_address=192.168.1.21
- Supplicant PAE state=AUTHENTICATED
- suppPortStatus=Authorized
- EAP state=SUCCESS
- \endverbatim
- \subsection ctrl_iface_STATUS-VERBOSE STATUS-VERBOSE
- Same as STATUS, but with more verbosity (i.e., more \c variable=value pairs).
- \verbatim
- bssid=02:00:01:02:03:04
- ssid=test network
- id=0
- pairwise_cipher=CCMP
- group_cipher=CCMP
- key_mgmt=WPA-PSK
- wpa_state=COMPLETED
- ip_address=192.168.1.21
- Supplicant PAE state=AUTHENTICATED
- suppPortStatus=Authorized
- heldPeriod=60
- authPeriod=30
- startPeriod=30
- maxStart=3
- portControl=Auto
- Supplicant Backend state=IDLE
- EAP state=SUCCESS
- reqMethod=0
- methodState=NONE
- decision=COND_SUCC
- ClientTimeout=60
- \endverbatim
- \subsection ctrl_iface_PMKSA PMKSA
- Show PMKSA cache
- \verbatim
- Index / AA / PMKID / expiration (in seconds) / opportunistic
- 1 / 02:00:01:02:03:04 / 000102030405060708090a0b0c0d0e0f / 41362 / 0
- 2 / 02:00:01:33:55:77 / 928389281928383b34afb34ba4212345 / 362 / 1
- \endverbatim
- \subsection ctrl_iface_SET SET <variable> <value>
- Set variables:
- - EAPOL::heldPeriod
- - EAPOL::authPeriod
- - EAPOL::startPeriod
- - EAPOL::maxStart
- - dot11RSNAConfigPMKLifetime
- - dot11RSNAConfigPMKReauthThreshold
- - dot11RSNAConfigSATimeout
- Example command:
- \verbatim
- SET EAPOL::heldPeriod 45
- \endverbatim
- \subsection ctrl_iface_LOGON LOGON
- IEEE 802.1X EAPOL state machine logon.
- \subsection ctrl_iface_LOGOFF LOGOFF
- IEEE 802.1X EAPOL state machine logoff.
- \subsection ctrl_iface_REASSOCIATE REASSOCIATE
- Force reassociation.
- \subsection ctrl_iface_RECONNECT RECONNECT
- Connect if disconnected (i.e., like \c REASSOCIATE, but only connect
- if in disconnected state).
- \subsection ctrl_iface_PREAUTH PREAUTH <BSSID>
- Start pre-authentication with the given BSSID.
- \subsection ctrl_iface_ATTACH ATTACH
- Attach the connection as a monitor for unsolicited events. This can
- be done with wpa_ctrl_attach().
- \subsection ctrl_iface_DETACH DETACH
- Detach the connection as a monitor for unsolicited events. This can
- be done with wpa_ctrl_detach().
- \subsection ctrl_iface_LEVEL LEVEL <debug level>
- Change debug level.
- \subsection ctrl_iface_RECONFIGURE RECONFIGURE
- Force %wpa_supplicant to re-read its configuration data.
- \subsection ctrl_iface_TERMINATE TERMINATE
- Terminate %wpa_supplicant process.
- \subsection ctrl_iface_BSSID BSSID <network id> <BSSID>
- Set preferred BSSID for a network. Network id can be received from the
- \c LIST_NETWORKS command output.
- \subsection ctrl_iface_LIST_NETWORKS LIST_NETWORKS
- List configured networks.
- \verbatim
- network id / ssid / bssid / flags
- 0 example network any [CURRENT]
- \endverbatim
- (note: fields are separated with tabs)
- \subsection ctrl_iface_DISCONNECT DISCONNECT
- Disconnect and wait for \c REASSOCIATE or \c RECONNECT command before
- connecting.
- \subsection ctrl_iface_SCAN SCAN
- Request a new BSS scan.
- \subsection ctrl_iface_SCAN_RESULTS SCAN_RESULTS
- Get the latest scan results.
- \verbatim
- bssid / frequency / signal level / flags / ssid
- 00:09:5b:95:e0:4e 2412 208 [WPA-PSK-CCMP] jkm private
- 02:55:24:33:77:a3 2462 187 [WPA-PSK-TKIP] testing
- 00:09:5b:95:e0:4f 2412 209 jkm guest
- \endverbatim
- (note: fields are separated with tabs)
- \subsection ctrl_iface_BSS BSS
- Get detailed per-BSS scan results. \c BSS command can be used to
- iterate through scan results one BSS at a time and to fetch all
- information from the found BSSes. This provides access to the same
- data that is available through \c SCAN_RESULTS but in a way that
- avoids problems with large number of scan results not fitting in the
- ctrl_iface messages.
- There are two options for selecting the BSS with the \c BSS command:
- "BSS <idx>" requests information for the BSS identified by the index
- (0 .. size-1) in the scan results table and "BSS <BSSID>" requests
- information for the given BSS (based on BSSID in 00:01:02:03:04:05
- format).
- BSS information is presented in following format. Please note that new
- fields may be added to this field=value data, so the ctrl_iface user
- should be prepared to ignore values it does not understand.
- \verbatim
- bssid=00:09:5b:95:e0:4e
- freq=2412
- beacon_int=0
- capabilities=0x0011
- qual=51
- noise=161
- level=212
- tsf=0000000000000000
- ie=000b6a6b6d2070726976617465010180dd180050f20101000050f20401000050f20401000050f2020000
- ssid=jkm private
- \endverbatim
- \subsection ctrl_iface_SELECT_NETWORK SELECT_NETWORK <network id>
- Select a network (disable others). Network id can be received from the
- \c LIST_NETWORKS command output.
- \subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK <network id>
- Enable a network. Network id can be received from the
- \c LIST_NETWORKS command output. Special network id \c all can be
- used to enable all network.
- \subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>
- Disable a network. Network id can be received from the
- \c LIST_NETWORKS command output. Special network id \c all can be
- used to disable all network.
- \subsection ctrl_iface_ADD_NETWORK ADD_NETWORK
- Add a new network. This command creates a new network with empty
- configuration. The new network is disabled and once it has been
- configured it can be enabled with \c ENABLE_NETWORK command. \c ADD_NETWORK
- returns the network id of the new network or FAIL on failure.
- \subsection ctrl_iface_REMOVE_NETWORK REMOVE_NETWORK <network id>
- Remove a network. Network id can be received from the
- \c LIST_NETWORKS command output. Special network id \c all can be
- used to remove all network.
- \subsection ctrl_iface_SET_NETWORK SET_NETWORK <network id> <variable> <value>
- Set network variables. Network id can be received from the
- \c LIST_NETWORKS command output.
- This command uses the same variables and data formats as the
- configuration file. See example wpa_supplicant.conf for more details.
- - ssid (network name, SSID)
- - psk (WPA passphrase or pre-shared key)
- - key_mgmt (key management protocol)
- - identity (EAP identity)
- - password (EAP password)
- - ...
- \subsection ctrl_iface_GET_NETWORK GET_NETWORK <network id> <variable>
- Get network variables. Network id can be received from the
- \c LIST_NETWORKS command output.
- \subsection ctrl_iface_SAVE_CONFIG SAVE_CONFIG
- Save the current configuration.
- \subsection ctrl_iface_P2P_FIND P2P_FIND
- Start P2P device discovery. Optional parameter can be used to specify
- the duration for the discovery in seconds (e.g., "P2P_FIND 5"). If the
- duration is not specified, discovery will be started for indefinite
- time, i.e., until it is terminated by P2P_STOP_FIND or P2P_CONNECT (to
- start group formation with a discovered peer).
- The default search type is to first run a full scan of all channels
- and then continue scanning only social channels (1, 6, 11). This
- behavior can be changed by specifying a different search type: social
- (e.g., "P2P_FIND 5 type=social") will skip the initial full scan and
- only search social channels; progressive (e.g., "P2P_FIND
- type=progressive") starts with a full scan and then searches
- progressively through all channels one channel at the time with the
- social channel scans. Progressive device discovery can be used to find
- new groups (and groups that were not found during the initial scan,
- e.g., due to the GO being asleep) over time without adding
- considerable extra delay for every Search state round.
- \subsection ctrl_iface_P2P_STOP_FIND P2P_STOP_FIND
- Stop ongoing P2P device discovery or other operation (connect, listen
- mode).
- \subsection ctrl_iface_P2P_CONNECT P2P_CONNECT
- Start P2P group formation with a discovered P2P peer. This includes
- group owner negotiation, group interface setup, provisioning, and
- establishing data connection.
- P2P_CONNECT <peer device address> <pbc|pin|PIN#>
- [label|display|keypad] [persistent] [join|auth] [go_intent=<0..15>]
- Start P2P group formation with a discovered P2P peer. This includes
- optional group owner negotiation, group interface setup, provisioning,
- and establishing data connection.
- The <pbc|pin|PIN#> parameter specifies the WPS provisioning
- method. "pbc" string starts pushbutton method, "pin" string start PIN
- method using an automatically generated PIN (which will be returned as
- the command return code), PIN# means that a pre-selected PIN can be
- used (e.g., 12345670). [label|display|keypad] is used with PIN method
- to specify which PIN is used (label=PIN from local label,
- display=dynamically generated random PIN from local display,
- keypad=PIN entered from peer device label or display). "persistent"
- parameter can be used to request a persistent group to be formed.
- "join" indicates that this is a command to join an existing group as a
- client. It skips the GO Negotiation part.
- "auth" indicates that the WPS parameters are authorized for the peer
- device without actually starting GO Negotiation (i.e., the peer is
- expected to initiate GO Negotiation). This is mainly for testing
- purposes.
- The optional "go_intent" parameter can be used to override the default
- GO Intent value.
- \subsection ctrl_iface_P2P_LISTEN P2P_LISTEN
- Start Listen-only state. Optional parameter can be used to specify the
- duration for the Listen operation in seconds. This command may not
- be of that much use during normal operations and is mainly designed
- for testing. It can also be used to keep the device discoverable
- without having to maintain a group.
- \subsection ctrl_iface_P2P_GROUP_REMOVE P2P_GROUP_REMOVE
- Terminate a P2P group. If a new virtual network interface was used for
- the group, it will also be removed. The network interface name of the
- group interface is used as a parameter for this command.
- \subsection ctrl_iface_P2P_GROUP_ADD P2P_GROUP_ADD
- Set up a P2P group owner manually (i.e., without group owner
- negotiation with a specific peer). This is also known as autonomous
- GO. Optional persistent=<network id> can be used to specify restart of
- a persistent group.
- \subsection ctrl_iface_P2P_PROV_DISC P2P_PROV_DISC
- Send P2P provision discovery request to the specified peer. The
- parameters for this command are the P2P device address of the peer and
- the desired configuration method. For example, "P2P_PROV_DISC
- 02:01:02:03:04:05 display" would request the peer to display a PIN for
- us and "P2P_PROV_DISC 02:01:02:03:04:05 keypad" would request the peer
- to enter a PIN that we display.
- \subsection ctrl_iface_P2P_GET_PASSPHRASE P2P_GET_PASSPHRASE
- Get the passphrase for a group (only available when acting as a GO).
- \subsection ctrl_iface_P2P_SERV_DISC_REQ P2P_SERV_DISC_REQ
- Schedule a P2P service discovery request. The parameters for this
- command are the device address of the peer device (or 00:00:00:00:00:00
- for wildcard query that is sent to every discovered P2P peer that
- supports service discovery) and P2P Service Query TLV(s) as hexdump.
- For example, "P2P_SERV_DISC_REQ 00:00:00:00:00:00 02000001" schedules
- a request for listing all supported service discovery protocols and
- requests this to be sent to all discovered peers. The pending requests
- are sent during device discovery (see \ref ctrl_iface_P2P_FIND).
- This command returns an identifier for the pending query (e.g.,
- "1f77628") that can be used to cancel the request. Directed requests
- will be automatically removed when the specified peer has replied to
- it.
- \subsection ctrl_iface_P2P_SERV_DISC_CANCEL_REQ P2P_SERV_DISC_CANCEL_REQ
- Cancel a pending P2P service discovery request. This command takes a
- single parameter: identifier for the pending query (the value returned
- by \ref ctrl_iface_P2P_SERV_DISC_REQ), e.g.,
- "P2P_SERV_DISC_CANCEL_REQ 1f77628".
- \subsection ctrl_iface_P2P_SERV_DISC_RESP P2P_SERV_DISC_RESP
- Reply to a service discovery query. This command takes following
- parameters: frequency in MHz, destination address, dialog token,
- response TLV(s). The first three parameters are copied from the
- request event. For example,
- "P2P_SERV_DISC_RESP 2437 02:40:61:c2:f3:b7 1 0300000101".
- \subsection ctrl_iface_P2P_SERVICE_UPDATE P2P_SERVICE_UPDATE
- Indicate that local services have changed. This is used to increment
- the P2P service indicator value so that peers know when previously
- cached information may have changed.
- \subsection ctrl_iface_P2P_SERV_DISC_EXTERNAL P2P_SERV_DISC_EXTERNAL
- Configure external processing of P2P service requests: 0 (default) =
- no external processing of requests (i.e., internal code will reject
- each request), 1 = external processing of requests (external program
- is responsible for replying to service discovery requests with
- \ref ctrl_iface_P2P_SERV_DISC_RESP).
- \subsection ctrl_iface_P2P_REJECT P2P_REJECT
- Reject connection attempt from a peer (specified with a device
- address). This is a mechanism to reject a pending GO Negotiation with
- a peer and request to automatically block any further connection or
- discovery of the peer.
- \subsection ctrl_iface_P2P_INVITE P2P_INVITE
- Invite a peer to join a group or to (re)start a persistent group.
- \subsection ctrl_iface_P2P_PEER P2P_PEER
- Fetch information about a discovered peer. This command takes in an
- argument specifying which peer to select: P2P Device Address of the
- peer, "FIRST" to indicate the first peer in the list, or "NEXT-<P2P
- Device Address>" to indicate the entry following the specified peer
- (to allow for iterating through the list).
- \subsection ctrl_iface_P2P_EXT_LISTEN P2P_EXT_LISTEN
- Enable/disable extended listen timing. Without parameters, this
- command disables extended listen timing. When enabling the feature,
- two parameters are used: availibility period and availability interval
- (both in milliseconds and with range of 1-65535).
- \section ctrl_iface_interactive Interactive requests
- If %wpa_supplicant needs additional information during authentication
- (e.g., password), it will use a specific prefix, \c CTRL-REQ-
- (\a WPA_CTRL_REQ macro) in an unsolicited event message. An external
- program, e.g., a GUI, can provide such information by using
- \c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matching
- field name.
- The following fields can be requested in this way from the user:
- - IDENTITY (EAP identity/user name)
- - PASSWORD (EAP password)
- - NEW_PASSWORD (New password if the server is requesting password change)
- - PIN (PIN code for accessing a SIM or smartcard)
- - OTP (one-time password; like password, but the value is used only once)
- - PASSPHRASE (passphrase for a private key file)
- \verbatim
- CTRL-REQ-<field name>-<network id>-<human readable text>
- CTRL-RSP-<field name>-<network id>-<value>
- \endverbatim
- For example, request from %wpa_supplicant:
- \verbatim
- CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
- \endverbatim
- And a matching reply from the GUI:
- \verbatim
- CTRL-RSP-PASSWORD-1-secret
- \endverbatim
- \subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option> [strict]
- Get list of supported functionality (eap, pairwise, group,
- proto). Supported functionality is shown as space separate lists of
- values used in the same format as in %wpa_supplicant configuration.
- If optional argument, 'strict', is added, only the values that the
- driver claims to explicitly support are included. Without this, all
- available capabilities are included if the driver does not provide
- a mechanism for querying capabilities.
- Example request/reply pairs:
- \verbatim
- GET_CAPABILITY eap
- AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
- \endverbatim
- \verbatim
- GET_CAPABILITY pairwise
- CCMP TKIP NONE
- \endverbatim
- \verbatim
- GET_CAPABILITY pairwise strict
- \endverbatim
- \verbatim
- GET_CAPABILITY group
- CCMP TKIP WEP104 WEP40
- \endverbatim
- \verbatim
- GET_CAPABILITY key_mgmt
- WPA-PSK WPA-EAP IEEE8021X NONE
- \endverbatim
- \verbatim
- GET_CAPABILITY proto
- RSN WPA
- \endverbatim
- \verbatim
- GET_CAPABILITY auth_alg
- OPEN SHARED LEAP
- \endverbatim
- \subsection ctrl_iface_AP_SCAN AP_SCAN <ap_scan value>
- Change ap_scan value:
- 0 = no scanning,
- 1 = %wpa_supplicant requests scans and uses scan results to select the AP,
- 2 = %wpa_supplicant does not use scanning and just requests driver to
- associate and take care of AP selection
- \subsection ctrl_iface_INTERFACES INTERFACES
- List configured interfaces.
- \verbatim
- wlan0
- eth0
- \endverbatim
- \section ctrl_iface_events Control interface events
- %wpa_supplicant generates number messages based on events like
- connection or a completion of a task. These are available to external
- programs that attach to receive unsolicited messages over the control
- interface with wpa_ctrl_attach().
- The event messages will be delivered over the attach control interface
- as text strings that start with the priority level of the message and
- a fixed prefix text as defined in wpa_ctrl.h. After this, optional
- additional information may be included depending on the event
- message. For example, following event message is delivered when new
- scan results are available:
- \verbatim
- <2>CTRL-EVENT-SCAN-RESULTS
- \endverbatim
- Following priority levels are used:
- - 0 = MSGDUMP
- - 1 = DEBUG
- - 2 = INFO
- - 3 = WARNING
- - 4 = ERROR
- By default, any priority level greater than equal to 2 (INFO) are
- delivered over the attached control interface. LEVEL command can be
- used to set the level of messages which will be delivered. It should
- be noted that there are many debug messages that do not include any
- particulat prefix and are subject to change. They may be used for
- debug information, but can usually be ignored by external programs.
- In most cases, the external program can skip over the priority field
- in the beginning of the event message and then compare the following
- text to the event strings from wpa_ctrl.h that the program is
- interested in processing.
- Following subsections describe the most common event notifications
- generated by %wpa_supplicant.
- \subsection ctrl_iface_event_CTRL_REQ CTRL-REQ-
- WPA_CTRL_REQ: Request information from a user. See
- \ref ctrl_iface_interactive "Interactive requests" sections for more
- details.
- \subsection ctrl_iface_event_CONNECTED CTRL-EVENT-CONNECTED
- WPA_EVENT_CONNECTED: Indicate successfully completed authentication
- and that the data connection is now enabled.
- \subsection ctrl_iface_event_DISCONNECTED CTRL-EVENT-DISCONNECTED
- WPA_EVENT_DISCONNECTED: Disconnected, data connection is not available
- \subsection ctrl_iface_event_TERMINATING CTRL-EVENT-TERMINATING
- WPA_EVENT_TERMINATING: %wpa_supplicant is exiting
- \subsection ctrl_iface_event_PASSWORD_CHANGED CTRL-EVENT-PASSWORD-CHANGED
- WPA_EVENT_PASSWORD_CHANGED: Password change was completed successfully
- \subsection ctrl_iface_event_EAP_NOTIFICATION CTRL-EVENT-EAP-NOTIFICATION
- WPA_EVENT_EAP_NOTIFICATION: EAP-Request/Notification received
- \subsection ctrl_iface_event_EAP_STARTED CTRL-EVENT-EAP-STARTED
- WPA_EVENT_EAP_STARTED: EAP authentication started (EAP-Request/Identity
- received)
- \subsection ctrl_iface_event_EAP_METHOD CTRL-EVENT-EAP-METHOD
- WPA_EVENT_EAP_METHOD: EAP method selected
- \subsection ctrl_iface_event_EAP_SUCCESS CTRL-EVENT-EAP-SUCCESS
- WPA_EVENT_EAP_SUCCESS: EAP authentication completed successfully
- \subsection ctrl_iface_event_EAP_FAILURE CTRL-EVENT-EAP-FAILURE
- WPA_EVENT_EAP_FAILURE: EAP authentication failed (EAP-Failure received)
- \subsection ctrl_iface_event_SCAN_RESULTS CTRL-EVENT-SCAN-RESULTS
- WPA_EVENT_SCAN_RESULTS: New scan results available
- \subsection ctrl_iface_event_BSS_ADDED CTRL-EVENT-BSS-ADDED
- WPA_EVENT_BSS_ADDED: A new BSS entry was added. The event prefix is
- followed by the BSS entry id and BSSID.
- \verbatim
- CTRL-EVENT-BSS-ADDED 34 00:11:22:33:44:55
- \endverbatim
- \subsection ctrl_iface_event_BSS_REMOVED CTRL-EVENT-BSS-REMOVED
- WPA_EVENT_BSS_REMOVED: A BSS entry was removed. The event prefix is
- followed by BSS entry id and BSSID.
- \verbatim
- CTRL-EVENT-BSS-REMOVED 34 00:11:22:33:44:55
- \endverbatim
- \subsection ctrl_iface_event_WPS_OVERLAP_DETECTED WPS-OVERLAP-DETECTED
- WPS_EVENT_OVERLAP: WPS overlap detected in PBC mode
- \subsection ctrl_iface_event_WPS_AP_AVAILABLE_PBC WPS-AP-AVAILABLE-PBC
- WPS_EVENT_AP_AVAILABLE_PBC: Available WPS AP with active PBC found in
- scan results.
- \subsection ctrl_iface_event_WPS_AP_AVAILABLE_PIN WPS-AP-AVAILABLE-PIN
- WPS_EVENT_AP_AVAILABLE_PIN: Available WPS AP with recently selected PIN
- registrar found in scan results.
- \subsection ctrl_iface_event_WPS_AP_AVAILABLE WPS-AP-AVAILABLE
- WPS_EVENT_AP_AVAILABLE: Available WPS AP found in scan results
- \subsection ctrl_iface_event_WPS_CRED_RECEIVED WPS-CRED-RECEIVED
- WPS_EVENT_CRED_RECEIVED: A new credential received
- \subsection ctrl_iface_event_WPS_M2D WPS-M2D
- WPS_EVENT_M2D: M2D received
- \subsection ctrl_iface_event_WPS_FAIL
- WPS_EVENT_FAIL: WPS registration failed after M2/M2D
- \subsection ctrl_iface_event_WPS_SUCCESS WPS-SUCCESS
- WPS_EVENT_SUCCESS: WPS registration completed successfully
- \subsection ctrl_iface_event_WPS_TIMEOUT WPS-TIMEOUT
- WPS_EVENT_TIMEOUT: WPS enrollment attempt timed out and was terminated
- \subsection ctrl_iface_event_WPS_ENROLLEE_SEEN WPS-ENROLLEE-SEEN
- WPS_EVENT_ENROLLEE_SEEN: WPS Enrollee was detected (used in AP mode).
- The event prefix is followed by MAC addr, UUID-E, pri dev type,
- config methods, dev passwd id, request type, [dev name].
- \verbatim
- WPS-ENROLLEE-SEEN 02:00:00:00:01:00
- 572cf82f-c957-5653-9b16-b5cfb298abf1 1-0050F204-1 0x80 4 1
- [Wireless Client]
- \endverbatim
- \subsection ctrl_iface_event_WPS_ER_AP_ADD WPS-ER-AP-ADD
- WPS_EVENT_ER_AP_ADD: WPS ER discovered an AP
- \verbatim
- WPS-ER-AP-ADD 87654321-9abc-def0-1234-56789abc0002 02:11:22:33:44:55
- pri_dev_type=6-0050F204-1 wps_state=1 |Very friendly name|Company|
- Long description of the model|WAP|http://w1.fi/|http://w1.fi/hostapd/
- \endverbatim
- \subsection ctrl_iface_event_WPS_ER_AP_REMOVE WPS-ER-AP-REMOVE
- WPS_EVENT_ER_AP_REMOVE: WPS ER removed an AP entry
- \verbatim
- WPS-ER-AP-REMOVE 87654321-9abc-def0-1234-56789abc0002
- \endverbatim
- \subsection ctrl_iface_event_WPS_ER_ENROLLEE_ADD WPS-ER-ENROLLEE-ADD
- WPS_EVENT_ER_ENROLLEE_ADD: WPS ER discovered a new Enrollee
- \verbatim
- WPS-ER-ENROLLEE-ADD 2b7093f1-d6fb-5108-adbb-bea66bb87333
- 02:66:a0:ee:17:27 M1=1 config_methods=0x14d dev_passwd_id=0
- pri_dev_type=1-0050F204-1
- |Wireless Client|Company|cmodel|123|12345|
- \endverbatim
- \subsection ctrl_iface_event_WPS_ER_ENROLLEE_REMOVE WPS-ER-ENROLLEE-REMOVE
- WPS_EVENT_ER_ENROLLEE_REMOVE: WPS ER removed an Enrollee entry
- \verbatim
- WPS-ER-ENROLLEE-REMOVE 2b7093f1-d6fb-5108-adbb-bea66bb87333
- 02:66:a0:ee:17:27
- \endverbatim
- \subsection ctrl_iface_event_WPS_PIN_NEEDED WPS-PIN-NEEDED
- WPS_EVENT_PIN_NEEDED: PIN is needed to complete provisioning with an
- Enrollee. This is followed by information about the Enrollee (UUID,
- MAC address, device name, manufacturer, model name, model number,
- serial number, primary device type).
- \verbatim
- WPS-PIN-NEEDED 5a02a5fa-9199-5e7c-bc46-e183d3cb32f7 02:2a:c4:18:5b:f3
- [Wireless Client|Company|cmodel|123|12345|1-0050F204-1]
- \endverbatim
- \subsection ctrl_iface_event_WPS_NEW_AP_SETTINGS WPS-NEW-AP-SETTINGS
- WPS_EVENT_NEW_AP_SETTINGS: New AP settings were received
- \subsection ctrl_iface_event_WPS_REG_SUCCESS WPS-REG-SUCCESS
- WPS_EVENT_REG_SUCCESS: WPS provisioning was completed successfully
- (AP/Registrar)
- \subsection ctrl_iface_event_WPS_AP_SETUP_LOCKED WPS-AP-SETUP-LOCKED
- WPS_EVENT_AP_SETUP_LOCKED: AP changed into setup locked state due to
- multiple failed configuration attempts using the AP PIN.
- \subsection ctrl_iface_event_AP_STA_CONNECTED AP-STA-CONNECTED
- AP_STA_CONNECTED: A station associated with us (AP mode event). The
- event prefix is followed by the MAC address of the station.
- \verbatim
- AP-STA-CONNECTED 02:2a:c4:18:5b:f3
- \endverbatim
- \subsection ctrl_iface_event_AP_STA_DISCONNECTED AP-STA-DISCONNECTED
- AP_STA_DISCONNECTED: A station disassociated (AP mode event)
- \verbatim
- AP-STA-DISCONNECTED 02:2a:c4:18:5b:f3
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_DEVICE_FOUND P2P-DEVICE-FOUND
- P2P_EVENT_DEVICE_FOUND: Indication of a discovered P2P device with
- information about that device.
- \verbatim
- P2P-DEVICE-FOUND 02:b5:64:63:30:63 p2p_dev_addr=02:b5:64:63:30:63
- pri_dev_type=1-0050f204-1 name='Wireless Client' config_methods=0x84
- dev_capab=0x21 group_capab=0x0
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_GO_NEG_REQUEST P2P-GO-NEG-REQUEST
- P2P_EVENT_GO_NEG_REQUEST: A P2P device requested GO negotiation, but we
- were not ready to start the negotiation.
- \verbatim
- P2P-GO-NEG-REQUEST 02:40:61:c2:f3:b7 dev_passwd_id=4
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_GO_NEG_SUCCESS P2P-GO-NEG-SUCCESS
- P2P_EVENT_GO_NEG_SUCCESS: Indication of successfully complete group
- owner negotiation.
- \subsection ctrl_iface_event_P2P_EVENT_GO_NEG_FAILURE P2P-GO-NEG-FAILURE
- P2P_EVENT_GO_NEG_FAILURE: Indication of failed group owner negotiation.
- \subsection ctrl_iface_event_P2P_EVENT_GROUP_FORMATION_SUCCESS P2P-GROUP-FORMATION-SUCCESS
- P2P_EVENT_GROUP_FORMATION_SUCCESS: Indication that P2P group formation
- has been completed successfully.
- \subsection ctrl_iface_event_P2P_EVENT_GROUP_FORMATION_FAILURE P2P-GROUP-FORMATION-FAILURE
- P2P_EVENT_GROUP_FORMATION_FAILURE: Indication that P2P group formation
- failed (e.g., due to provisioning failure or timeout).
- \subsection ctrl_iface_event_P2P_EVENT_GROUP_STARTED P2P-GROUP-STARTED
- P2P_EVENT_GROUP_STARTED: Indication of a new P2P group having been
- started. Additional parameters: network interface name for the group,
- role (GO/client), SSID. The passphrase used in the group is also
- indicated here if known (on GO) or PSK (on client). If the group is a
- persistent one, a flag indicating that is included.
- \verbatim
- P2P-GROUP-STARTED wlan0-p2p-0 GO ssid="DIRECT-3F Testing"
- passphrase="12345678" go_dev_addr=02:40:61:c2:f3:b7 [PERSISTENT]
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_GROUP_REMOVED P2P-GROUP-REMOVED
- P2P_EVENT_GROUP_REMOVED: Indication of a P2P group having been removed.
- Additional parameters: network interface name for the group, role
- (GO/client).
- \verbatim
- P2P-GROUP-REMOVED wlan0-p2p-0 GO
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_PROV_DISC_SHOW_PIN P2P-PROV-DISC-SHOW-PIN
- P2P_EVENT_PROV_DISC_SHOW_PIN: Request from the peer for us to display
- a PIN that will be entered on the peer. The following parameters are
- included after the event prefix: peer_address PIN. The PIN is a
- random PIN generated for this connection. P2P_CONNECT command can be
- used to accept the request with the same PIN configured for the
- connection.
- \verbatim
- P2P-PROV-DISC-SHOW-PIN 02:40:61:c2:f3:b7 12345670
- p2p_dev_addr=02:40:61:c2:f3:b7 pri_dev_type=1-0050F204-1 name='Test'
- config_methods=0x188 dev_capab=0x21 group_capab=0x0
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_PROV_DISC_ENTER_PIN P2P-PROV-DISC-ENTER-PIN
- P2P_EVENT_PROV_DISC_ENTER_PIN: Request from the peer for us to enter a
- PIN displayed on the peer. The following parameter is included after
- the event prefix: peer address.
- \verbatim
- P2P-PROV-DISC-ENTER-PIN 02:40:61:c2:f3:b7 p2p_dev_addr=02:40:61:c2:f3:b7
- pri_dev_type=1-0050F204-1 name='Test' config_methods=0x188
- dev_capab=0x21 group_capab=0x0
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_PROV_DISC_PBC_REQ P2P-PROV-DISC-PBC-REQ
- P2P_EVENT_PROV_DISC_PBC_REQ: Request from the peer for us to connect
- using PBC. The following parameters are included after the event prefix:
- peer_address. P2P_CONNECT command can be used to accept the request.
- \verbatim
- P2P-PROV-DISC-PBC-REQ 02:40:61:c2:f3:b7 p2p_dev_addr=02:40:61:c2:f3:b7
- pri_dev_type=1-0050F204-1 name='Test' config_methods=0x188
- dev_capab=0x21 group_capab=0x0
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_PROV_DISC_PBC_RESP P2P-PROV-DISC-PBC-RESP
- P2P_EVENT_PROV_DISC_PBC_RESP: The peer accepted our provision discovery
- request to connect using PBC. The following parameters are included
- after the event prefix: peer_address. P2P_CONNECT command can be used to
- start GO Negotiation after this.
- \verbatim
- P2P-PROV-DISC-PBC-RESP 02:40:61:c2:f3:b7
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_SERV_DISC_REQ P2P-SERV-DISC-REQ
- P2P-SERV-DISC-REQ: Indicate reception of a P2P service discovery
- request. The following parameters are included after the event prefix:
- frequency in MHz, source address, dialog token, Service Query TLV(s) as
- hexdump.
- \verbatim
- P2P-SERV-DISC-REQ 2412 02:40:61:c2:f3:b7 0 0 02000001
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_SERV_DISC_RESP P2P-SERV-DISC-RESP
- P2P-SERV-DISC-RESP: Indicate reception of a P2P service discovery
- response. The following parameters are included after the event prefix:
- source address, dialog token, Service Response TLV(s) as hexdump.
- \verbatim
- P2P-SERV-DISC-RESP 02:40:61:c2:f3:b7 0 0300000101
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_INVITATION_RECEIVED P2P-INVITATION-RECEIVED
- P2P-INVITATION-RECEIVED: Indicate reception of a P2P Invitation
- Request. For persistent groups, the parameter after the event prefix
- indicates which network block includes the persistent group data.
- \verbatim
- P2P-INVITATION-RECEIVED sa=02:40:61:c2:f3:b7 persistent=0
- \endverbatim
- \subsection ctrl_iface_event_P2P_EVENT_INVITATION_RESULT P2P-INVITATION-RESULT
- P2P-INVITATION-RESULT: Indicate result of a P2P invitation that was
- requested with \ref ctrl_iface_P2P_INVITE. The parameter
- status=<value> shows the status code returned by the peer (or -1 on
- local failure or timeout).
- \verbatim
- P2P-INVITATION-RESULT status=1
- \endverbatim
- */
|