/**\page ctrl_iface_page Control interface%wpa_supplicant implements a control interface that can be used byexternal programs to control the operations of the %wpa_supplicantdaemon and to get status information and event notifications. There isa small C library, in a form of a single C file, wpa_ctrl.c, thatprovides helper functions to facilitate the use of the controlinterface. External programs can link this file into them and then usethe library functions documented in wpa_ctrl.h to interact with%wpa_supplicant. This library can also be used with C++. wpa_cli.c andwpa_gui are example programs using this library.There are multiple mechanisms for inter-process communication. Forexample, Linux version of %wpa_supplicant is using UNIX domain socketsfor the control interface and Windows version UDP sockets. The use ofthe functions defined in wpa_ctrl.h can be used to hide the details ofthe used IPC from external programs.\section using_ctrl_iface Using the control interfaceExternal programs, e.g., a GUI or a configuration utility, that need tocommunicate with %wpa_supplicant should link in wpa_ctrl.c. Thisallows them to use helper functions to open connection to the controlinterface with wpa_ctrl_open() and to send commands withwpa_ctrl_request().%wpa_supplicant uses the control interface for two types of communication:commands and unsolicited event messages. Commands are a pair ofmessages, 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 controlinterface connection without specific request from the external programfor receiving each message. However, the external program needs toattach to the control interface with wpa_ctrl_attach() to receive theseunsolicited messages.If the control interface connection is used both for commands andunsolicited event messages, there is potential for receiving anunsolicited 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 twocontrol interface connections by calling wpa_ctrl_open() twice andthen use one of the connections for commands and the other one forunsolicited messages. This way command request/response pairs willnot be broken by unsolicited messages. wpa_cli is an example of howto use only one connection for both purposes and wpa_gui demonstrateshow to use two separate connections.Once the control interface connection is not needed anymore, it shouldbe closed by calling wpa_ctrl_close(). If the connection was used forunsolicited event messages, it should be first detached by callingwpa_ctrl_detach().\section ctrl_iface_cmds Control interface commandsFollowing commands can be used with wpa_ctrl_request():\subsection ctrl_iface_PING PINGThis command can be used to test whether %wpa_supplicant is replyingto the control interface commands. The expected reply is \c PONG if theconnection is open and %wpa_supplicant is processing commands.\subsection ctrl_iface_MIB MIBRequest a list of MIB variables (dot1x, dot11). The output is a textblock with each line in \c variable=value format. For example:\verbatimdot11RSNAOptionImplemented=TRUEdot11RSNAPreauthenticationImplemented=TRUEdot11RSNAEnabled=FALSEdot11RSNAPreauthenticationEnabled=FALSEdot11RSNAConfigVersion=1dot11RSNAConfigPairwiseKeysSupported=5dot11RSNAConfigGroupCipherSize=128dot11RSNAConfigPMKLifetime=43200dot11RSNAConfigPMKReauthThreshold=70dot11RSNAConfigNumberOfPTKSAReplayCounters=1dot11RSNAConfigSATimeout=60dot11RSNAAuthenticationSuiteSelected=00-50-f2-2dot11RSNAPairwiseCipherSelected=00-50-f2-4dot11RSNAGroupCipherSelected=00-50-f2-4dot11RSNAPMKIDUsed=dot11RSNAAuthenticationSuiteRequested=00-50-f2-2dot11RSNAPairwiseCipherRequested=00-50-f2-4dot11RSNAGroupCipherRequested=00-50-f2-4dot11RSNAConfigNumberOfGTKSAReplayCounters=0dot11RSNA4WayHandshakeFailures=0dot1xSuppPaeState=5dot1xSuppHeldPeriod=60dot1xSuppAuthPeriod=30dot1xSuppStartPeriod=30dot1xSuppMaxStart=3dot1xSuppSuppControlledPortStatus=Authorizeddot1xSuppBackendPaeState=2dot1xSuppEapolFramesRx=0dot1xSuppEapolFramesTx=440dot1xSuppEapolStartFramesTx=2dot1xSuppEapolLogoffFramesTx=0dot1xSuppEapolRespFramesTx=0dot1xSuppEapolReqIdFramesRx=0dot1xSuppEapolReqFramesRx=0dot1xSuppInvalidEapolFramesRx=0dot1xSuppEapLengthErrorFramesRx=0dot1xSuppLastEapolFrameVersion=0dot1xSuppLastEapolFrameSource=00:00:00:00:00:00\endverbatim\subsection ctrl_iface_STATUS STATUSRequest current WPA/EAPOL/EAP status information. The output is a textblock with each line in \c variable=value format. For example:\verbatimbssid=02:00:01:02:03:04ssid=test networkpairwise_cipher=CCMPgroup_cipher=CCMPkey_mgmt=WPA-PSKwpa_state=COMPLETEDip_address=192.168.1.21Supplicant PAE state=AUTHENTICATEDsuppPortStatus=AuthorizedEAP state=SUCCESS\endverbatim\subsection ctrl_iface_STATUS-VERBOSE STATUS-VERBOSESame as STATUS, but with more verbosity (i.e., more \c variable=value pairs).\verbatimbssid=02:00:01:02:03:04ssid=test networkpairwise_cipher=CCMPgroup_cipher=CCMPkey_mgmt=WPA-PSKwpa_state=COMPLETEDip_address=192.168.1.21Supplicant PAE state=AUTHENTICATEDsuppPortStatus=AuthorizedheldPeriod=60authPeriod=30startPeriod=30maxStart=3portControl=AutoSupplicant Backend state=IDLEEAP state=SUCCESSreqMethod=0methodState=NONEdecision=COND_SUCCClientTimeout=60\endverbatim\subsection ctrl_iface_PMKSA PMKSAShow PMKSA cache\verbatimIndex / AA / PMKID / expiration (in seconds) / opportunistic1 / 02:00:01:02:03:04 / 000102030405060708090a0b0c0d0e0f / 41362 / 02 / 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- dot11RSNAConfigSATimeoutExample command:\verbatimSET EAPOL::heldPeriod 45\endverbatim\subsection ctrl_iface_LOGON LOGONIEEE 802.1X EAPOL state machine logon.\subsection ctrl_iface_LOGOFF LOGOFFIEEE 802.1X EAPOL state machine logoff.\subsection ctrl_iface_REASSOCIATE REASSOCIATEForce reassociation.\subsection ctrl_iface_PREAUTH PREAUTH <BSSID>Start pre-authentication with the given BSSID.\subsection ctrl_iface_ATTACH ATTACHAttach the connection as a monitor for unsolicited events. This canbe done with wpa_ctrl_attach().\subsection ctrl_iface_DETACH DETACHDetach the connection as a monitor for unsolicited events. This canbe done with wpa_ctrl_detach().\subsection ctrl_iface_LEVEL LEVEL <debug level>Change debug level.\subsection ctrl_iface_RECONFIGURE RECONFIGUREForce %wpa_supplicant to re-read its configuration data.\subsection ctrl_iface_TERMINATE TERMINATETerminate %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_NETWORKSList configured networks.\verbatimnetwork id / ssid / bssid / flags0	example network	any	[CURRENT]\endverbatim(note: fields are separated with tabs)\subsection ctrl_iface_DISCONNECT DISCONNECTDisconnect and wait for \c REASSOCIATE command before connecting.\subsection ctrl_iface_SCAN SCANRequest a new BSS scan.\subsection ctrl_iface_SCAN_RESULTS SCAN_RESULTSGet the latest scan results.\verbatimbssid / frequency / signal level / flags / ssid00:09:5b:95:e0:4e	2412	208	[WPA-PSK-CCMP]	jkm private02:55:24:33:77:a3	2462	187	[WPA-PSK-TKIP]	testing00:09:5b:95:e0:4f	2412	209		jkm guest\endverbatim(note: fields are separated with tabs)\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.\subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>Disable a network. Network id can be received from the\c LIST_NETWORKS command output.\subsection ctrl_iface_ADD_NETWORK ADD_NETWORKAdd a new network. This command creates a new network with emptyconfiguration. The new network is disabled and once it has beenconfigured it can be enabled with \c ENABLE_NETWORK command. \c ADD_NETWORKreturns 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.\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 theconfiguration 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_CONFIGSave the current configuration.\section ctrl_iface_interactive Interactive requestsIf %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 externalprogram, e.g., a GUI, can provide such information by using\c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matchingfield 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)\verbatimCTRL-REQ-<field name>-<network id>-<human readable text>CTRL-RSP-<field name>-<network id>-<value>\endverbatimFor example, request from %wpa_supplicant:\verbatimCTRL-REQ-PASSWORD-1-Password needed for SSID test-network\endverbatimAnd a matching reply from the GUI:\verbatimCTRL-RSP-PASSWORD-1-secret\endverbatim\subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option>Get list of supported functionality (eap, pairwise, group,proto). Supported functionality is shown as space separate lists ofvalues used in the same format as in %wpa_supplicant configuration.Example request/reply pairs:\verbatimGET_CAPABILITY eapAKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS\endverbatim\verbatimGET_CAPABILITY pairwiseCCMP TKIP NONE\endverbatim\verbatimGET_CAPABILITY groupCCMP TKIP WEP104 WEP40\endverbatim\verbatimGET_CAPABILITY key_mgmtWPA-PSK WPA-EAP IEEE8021X NONE\endverbatim\verbatimGET_CAPABILITY protoRSN WPA\endverbatim\verbatimGET_CAPABILITY auth_algOPEN SHARED LEAP\endverbatim*/