/**\page driver_wrapper Driver wrapper implementation (driver.h, drivers.c)All hardware and driver dependent functionality is in separate C filesthat implement defined wrapper functions. Other partsof the %wpa_supplicant are designed to be hardware, driver, and operatingsystem independent.Driver wrappers need to implement whatever calls are used in thetarget operating system/driver for controlling wireless LANdevices. As an example, in case of Linux, these are mostly some gluecode and ioctl() calls and netlink message parsing for Linux WirelessExtensions (WE). Since features required for WPA were added only recently toLinux Wireless Extensions (in version 18), some driver specific code is usedin number of driver interface implementations. These driver dependent partscan be replaced with generic code in driver_wext.c once the target driverincludes full support for WE-18. After that, all Linux drivers, atleast in theory, could use the same driver wrapper code.A driver wrapper needs to implement some or all of the functionsdefined in driver.h. These functions are registered by filling structwpa_driver_ops with function pointers. Hardware independent parts of%wpa_supplicant will call these functions to control the driver/wlancard. In addition, support for driver events is required. The eventcallback function, wpa_supplicant_event(), and its parameters aredocumented in wpa_supplicant.h. In addition, a pointer to the 'structwpa_driver_ops' needs to be registered in drivers.c file.When porting to other operating systems, the driver wrapper should bemodified to use the native interface of the target OS. It is possiblethat some extra requirements for the interface between the driverwrapper and generic %wpa_supplicant code are discovered during portingto a new operating system. These will be addressed on case by casebasis by modifying the interface and updating the other driverwrappers for this. The goal is to avoid changing this interfacewithout very good reasons in order to limit the number of changesneeded to other wrappers and hardware independent parts of%wpa_supplicant. When changes are required, recommended way is tomake them in backwards compatible way that allows existing driverinterface implementations to be compiled without any modification.Generic Linux Wireless Extensions functions are implemented indriver_wext.c. All Linux driver wrappers can use these when the kerneldriver supports the generic ioctl()s and wireless events. Driverspecific functions are implemented in separate C files, e.g.,driver_hostap.c. These files need to define struct wpa_driver_opsentry that will be used in wpa_supplicant.c when calling driverfunctions. struct wpa_driver_ops entries are registered in drivers.c.In general, it is likely to be useful to first take a look at coupleof driver interface examples before starting on implementing a newone. driver_hostap.c and driver_wext.c include a completeimplementation for Linux drivers that use %wpa_supplicant-based controlof WPA IE and roaming. driver_ndis.c (with help from driver_ndis_.c)is an example of a complete interface for Windows NDIS interface fordrivers that generate WPA IE themselves and decide when to roam. Theseexample implementations include full support for all security modes.\section driver_req Driver requirements for WPAWPA introduces new requirements for the device driver. At least someof these need to be implemented in order to provide enough support for%wpa_supplicant.\subsection driver_tkip_ccmp TKIP/CCMPWPA requires that the pairwise cipher suite (encryption algorithm forunicast data packets) is TKIP or CCMP. These are new encryptionprotocols and thus, the driver will need to be modified to supportthem. Depending on the used wlan hardware, some parts of these may beimplemented by the hardware/firmware.Specification for both TKIP and CCMP is available from IEEE (IEEE802.11i amendment). Fully functional, hardware independentimplementation of both encryption protocols is also available in HostAP driver (driver/modules/hostap_{tkip,ccmp}.c). In addition, Linux 2.6kernel tree has generic implementations for WEP, TKIP, and CCMP that canbe used in Linux drivers.The driver will also need to provide configuration mechanism to allowuser space programs to configure TKIP and CCMP. Linux Wireless Extensionsv18 added support for configuring these algorithms andindividual/non-default keys. If the target kernel does not include WE-18,private ioctls can be used to provide similar functionality.\subsection driver_roaming Roaming control and scanning support%wpa_supplicant can optionally control AP selection based on theinformation received from Beacon and/or Probe Response frames(ap_scan=1 mode in configuration). This means that the driver shouldsupport external control for scan process. In case of Linux, use ofnew Wireless Extensions scan support (i.e., 'iwlist wlan0 scan') isrecommended. The current driver wrapper (driver_wext.c) uses this forscan results.Scan results must also include the WPA information element. Support forthis was added in WE-18. With older versions, a custom event can be usedto provide the full WPA IE (including element id and length) as a hexstring that is included in the scan results.%wpa_supplicant needs to also be able to request the driver toassociate with a specific BSS. Current Host AP driver and matchingdriver_hostap.c wrapper uses following sequence for thisrequest. Similar/identical mechanism should be usable also with otherdrivers.- set WPA IE for AssocReq with private ioctl- set SSID with SIOCSIWESSID- set channel/frequency with SIOCSIWFREQ- set BSSID with SIOCSIWAP  (this last ioctl will trigger the driver to request association)\subsection driver_wpa_ie WPA IE generation%wpa_supplicant selects which cipher suites and key management suitesare used. Based on this information, it generates a WPA IE. This isprovided to the driver interface in the associate call. This does notmatch with Windows NDIS drivers which generate the WPA IEthemselves.%wpa_supplicant allows Windows NDIS-like behavior by providing theselected cipher and key management suites in the associate call. Ifthe driver generates its own WPA IE and that differs from the onegenerated by %wpa_supplicant, the driver has to inform %wpa_supplicantabout the used WPA IE (i.e., the one it used in (Re)AssociateRequest). This notification is done using EVENT_ASSOCINFO event (seewpa_supplicant.h). %wpa_supplicant is normally configured to useap_scan=2 mode with drivers that control WPA IE generation and roaming.\subsection driver_events Driver events%wpa_supplicant needs to receive event callbacks when certain eventsoccur (association, disassociation, Michael MIC failure, scan resultsavailable, PMKSA caching candidate). These events and the callbackdetails are defined in wpa_supplicant.h (wpa_supplicant_event() functionand enum wpa_event_type).On Linux, association and disassociation can use existing WirelessExtensions event that is reporting new AP with SIOCGIWAPevent. Similarly, completion of a scan can be reported with SIOCGIWSCANevent.Michael MIC failure event was added in WE-18. Older versions of WirelessExtensions will need to use a custom event. Host AP driver used a customevent with following contents: MLME-MICHAELMICFAILURE.indication(keyid=#broadcast/unicast addr=addr2). This is the recommended format untilthe driver can be moved to use WE-18 mechanism.\subsection driver_wext_summary Summary of Linux Wireless Extensions useAP selection depends on ap_scan configuration:ap_scan=1:- %wpa_supplicant requests scan with SIOCSIWSCAN- driver reports scan complete with wireless event SIOCGIWSCAN- %wpa_supplicant reads scan results with SIOCGIWSCAN (multiple call if  a larget buffer is needed)- %wpa_supplicant decides which AP to use based on scan results- %wpa_supplicant configures driver to associate with the selected BSS  (SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWFREQ,   SIOCSIWESSID, SIOCSIWAP)ap_scan=2:- %wpa_supplicant configures driver to associate with an SSID  (SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWESSID)After this, both modes use similar steps:- optionally (or required for drivers that generate WPA/RSN IE for  (Re)AssocReq), driver reports association parameters (AssocReq IEs)  with wireless event IWEVASSOCREQIE (and optionally IWEVASSOCRESPIE)- driver reports association with wireless event SIOCGIWAP- %wpa_supplicant takes care of EAPOL frame handling (validating  information from associnfo and if needed, from scan results if WPA/RSN  IE from the Beacon frame is not reported through associnfo)*/