All hardware and driver dependent functionality is in separate C files
that implement defined wrapper functions. Other parts
-of the %wpa_supplicant are designed to be hardware, driver, and operating
+of the wpa_supplicant are designed to be hardware, driver, and operating
system independent.
Driver wrappers need to implement whatever calls are used in the
Extensions (WE). Since features required for WPA were added only recently to
Linux Wireless Extensions (in version 18), some driver specific code is used
in number of driver interface implementations. These driver dependent parts
-can be replaced with generic code in driver_wext.c once the target driver
+can be replaced with generic code in \ref driver_wext.c once the target driver
includes full support for WE-18. After that, all Linux drivers, at
least in theory, could use the same driver wrapper code.
A driver wrapper needs to implement some or all of the functions
-defined in driver.h. These functions are registered by filling struct
-wpa_driver_ops with function pointers. Hardware independent parts of
-%wpa_supplicant will call these functions to control the driver/wlan
+defined in \ref driver.h. These functions are registered by filling struct
+\ref wpa_driver_ops with function pointers. Hardware independent parts of
+wpa_supplicant will call these functions to control the driver/wlan
card. In addition, support for driver events is required. The event
-callback function, wpa_supplicant_event(), and its parameters are
-documented in driver.h. In addition, a pointer to the 'struct
-wpa_driver_ops' needs to be registered in drivers.c file.
+callback function, \ref wpa_supplicant_event(), and its parameters are
+documented in \ref driver.h. In addition, a pointer to the 'struct
+\ref wpa_driver_ops' needs to be registered in \ref drivers.c file.
When porting to other operating systems, the driver wrapper should be
modified to use the native interface of the target OS. It is possible
that some extra requirements for the interface between the driver
-wrapper and generic %wpa_supplicant code are discovered during porting
+wrapper and generic wpa_supplicant code are discovered during porting
to a new operating system. These will be addressed on case by case
basis by modifying the interface and updating the other driver
wrappers for this. The goal is to avoid changing this interface
without very good reasons in order to limit the number of changes
needed to other wrappers and hardware independent parts of
-%wpa_supplicant. When changes are required, recommended way is to
+wpa_supplicant. When changes are required, recommended way is to
make them in backwards compatible way that allows existing driver
interface implementations to be compiled without any modification.
Generic Linux Wireless Extensions functions are implemented in
-driver_wext.c. All Linux driver wrappers can use these when the kernel
+\ref driver_wext.c. All Linux driver wrappers can use these when the kernel
driver supports the generic ioctl()s and wireless events. Driver
specific functions are implemented in separate C files, e.g.,
-driver_hostap.c. These files need to define struct wpa_driver_ops
-entry that will be used in wpa_supplicant.c when calling driver
-functions. struct wpa_driver_ops entries are registered in drivers.c.
+\ref driver_hostap.c. These files need to define struct \ref wpa_driver_ops
+entry that will be used in \ref wpa_supplicant.c when calling driver
+functions. struct \ref wpa_driver_ops entries are registered in \ref drivers.c.
In general, it is likely to be useful to first take a look at couple
of driver interface examples before starting on implementing a new
-one. driver_hostap.c and driver_wext.c include a complete
-implementation for Linux drivers that use %wpa_supplicant-based control
-of WPA IE and roaming. driver_ndis.c (with help from driver_ndis_.c)
+one. \ref driver_hostap.c and \ref driver_wext.c include a complete
+implementation for Linux drivers that use wpa_supplicant-based control
+of WPA IE and roaming. \ref driver_ndis.c (with help from \ref driver_ndis_.c)
is an example of a complete interface for Windows NDIS interface for
drivers that generate WPA IE themselves and decide when to roam. These
example implementations include full support for all security modes.
WPA introduces new requirements for the device driver. At least some
of these need to be implemented in order to provide enough support for
-%wpa_supplicant.
+wpa_supplicant.
\subsection driver_tkip_ccmp TKIP/CCMP
\subsection driver_roaming Roaming control and scanning support
-%wpa_supplicant can optionally control AP selection based on the
+wpa_supplicant can optionally control AP selection based on the
information received from Beacon and/or Probe Response frames
(ap_scan=1 mode in configuration). This means that the driver should
support external control for scan process. In case of Linux, use of
new Wireless Extensions scan support (i.e., 'iwlist wlan0 scan') is
-recommended. The current driver wrapper (driver_wext.c) uses this for
+recommended. The current driver wrapper (\ref driver_wext.c) uses this for
scan results.
Scan results must also include the WPA information element. Support for
to provide the full WPA IE (including element id and length) as a hex
string that is included in the scan results.
-%wpa_supplicant needs to also be able to request the driver to
+wpa_supplicant needs to also be able to request the driver to
associate with a specific BSS. Current Host AP driver and matching
-driver_hostap.c wrapper uses following sequence for this
+\ref driver_hostap.c wrapper uses following sequence for this
request. Similar/identical mechanism should be usable also with other
drivers.
\subsection driver_wpa_ie WPA IE generation
-%wpa_supplicant selects which cipher suites and key management suites
+wpa_supplicant selects which cipher suites and key management suites
are used. Based on this information, it generates a WPA IE. This is
provided to the driver interface in the associate call. This does not
match with Windows NDIS drivers which generate the WPA IE
themselves.
-%wpa_supplicant allows Windows NDIS-like behavior by providing the
+wpa_supplicant allows Windows NDIS-like behavior by providing the
selected cipher and key management suites in the associate call. If
the driver generates its own WPA IE and that differs from the one
-generated by %wpa_supplicant, the driver has to inform %wpa_supplicant
+generated by wpa_supplicant, the driver has to inform wpa_supplicant
about the used WPA IE (i.e., the one it used in (Re)Associate
Request). This notification is done using EVENT_ASSOCINFO event (see
-driver.h). %wpa_supplicant is normally configured to use
+\ref driver.h). wpa_supplicant is normally configured to use
ap_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 events
+wpa_supplicant needs to receive event callbacks when certain events
occur (association, disassociation, Michael MIC failure, scan results
available, PMKSA caching candidate). These events and the callback
-details are defined in driver.h (wpa_supplicant_event() function
-and enum wpa_event_type).
+details are defined in \ref driver.h (\ref wpa_supplicant_event() function
+and enum \ref wpa_event_type).
On Linux, association and disassociation can use existing Wireless
Extensions event that is reporting new AP with SIOCGIWAP
ap_scan=1:
-- %wpa_supplicant requests scan with SIOCSIWSCAN
+- wpa_supplicant requests scan with SIOCSIWSCAN
- driver reports scan complete with wireless event SIOCGIWSCAN
-- %wpa_supplicant reads scan results with SIOCGIWSCAN (multiple call if
+- 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
+- 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
+- wpa_supplicant configures driver to associate with an SSID
(SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWESSID)
(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
+- 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)
*/
projects / mech_eap.git / blobdiff