2
\page driver_wrapper Driver wrapper implementation (driver.h, drivers.c)
4
All hardware and driver dependent functionality is in separate C files
5
that implement defined wrapper functions. Other parts
6
of the %wpa_supplicant are designed to be hardware, driver, and operating
9
Driver wrappers need to implement whatever calls are used in the
10
target operating system/driver for controlling wireless LAN
11
devices. As an example, in case of Linux, these are mostly some glue
12
code and ioctl() calls and netlink message parsing for Linux Wireless
13
Extensions (WE). Since features required for WPA were added only recently to
14
Linux Wireless Extensions (in version 18), some driver specific code is used
15
in number of driver interface implementations. These driver dependent parts
16
can be replaced with generic code in driver_wext.c once the target driver
17
includes full support for WE-18. After that, all Linux drivers, at
18
least in theory, could use the same driver wrapper code.
20
A driver wrapper needs to implement some or all of the functions
21
defined in driver.h. These functions are registered by filling struct
22
wpa_driver_ops with function pointers. Hardware independent parts of
23
%wpa_supplicant will call these functions to control the driver/wlan
24
card. In addition, support for driver events is required. The event
25
callback function, wpa_supplicant_event(), and its parameters are
26
documented in driver.h. In addition, a pointer to the 'struct
27
wpa_driver_ops' needs to be registered in drivers.c file.
29
When porting to other operating systems, the driver wrapper should be
30
modified to use the native interface of the target OS. It is possible
31
that some extra requirements for the interface between the driver
32
wrapper and generic %wpa_supplicant code are discovered during porting
33
to a new operating system. These will be addressed on case by case
34
basis by modifying the interface and updating the other driver
35
wrappers for this. The goal is to avoid changing this interface
36
without very good reasons in order to limit the number of changes
37
needed to other wrappers and hardware independent parts of
38
%wpa_supplicant. When changes are required, recommended way is to
39
make them in backwards compatible way that allows existing driver
40
interface implementations to be compiled without any modification.
42
Generic Linux Wireless Extensions functions are implemented in
43
driver_wext.c. All Linux driver wrappers can use these when the kernel
44
driver supports the generic ioctl()s and wireless events. Driver
45
specific functions are implemented in separate C files, e.g.,
46
driver_hostap.c. These files need to define struct wpa_driver_ops
47
entry that will be used in wpa_supplicant.c when calling driver
48
functions. struct wpa_driver_ops entries are registered in drivers.c.
50
In general, it is likely to be useful to first take a look at couple
51
of driver interface examples before starting on implementing a new
52
one. driver_hostap.c and driver_wext.c include a complete
53
implementation for Linux drivers that use %wpa_supplicant-based control
54
of WPA IE and roaming. driver_ndis.c (with help from driver_ndis_.c)
55
is an example of a complete interface for Windows NDIS interface for
56
drivers that generate WPA IE themselves and decide when to roam. These
57
example implementations include full support for all security modes.
60
\section driver_req Driver requirements for WPA
62
WPA introduces new requirements for the device driver. At least some
63
of these need to be implemented in order to provide enough support for
66
\subsection driver_tkip_ccmp TKIP/CCMP
68
WPA requires that the pairwise cipher suite (encryption algorithm for
69
unicast data packets) is TKIP or CCMP. These are new encryption
70
protocols and thus, the driver will need to be modified to support
71
them. Depending on the used wlan hardware, some parts of these may be
72
implemented by the hardware/firmware.
74
Specification for both TKIP and CCMP is available from IEEE (IEEE
75
802.11i amendment). Fully functional, hardware independent
76
implementation of both encryption protocols is also available in Host
77
AP driver (driver/modules/hostap_{tkip,ccmp}.c). In addition, Linux 2.6
78
kernel tree has generic implementations for WEP, TKIP, and CCMP that can
79
be used in Linux drivers.
81
The driver will also need to provide configuration mechanism to allow
82
user space programs to configure TKIP and CCMP. Linux Wireless Extensions
83
v18 added support for configuring these algorithms and
84
individual/non-default keys. If the target kernel does not include WE-18,
85
private ioctls can be used to provide similar functionality.
87
\subsection driver_roaming Roaming control and scanning support
89
%wpa_supplicant can optionally control AP selection based on the
90
information received from Beacon and/or Probe Response frames
91
(ap_scan=1 mode in configuration). This means that the driver should
92
support external control for scan process. In case of Linux, use of
93
new Wireless Extensions scan support (i.e., 'iwlist wlan0 scan') is
94
recommended. The current driver wrapper (driver_wext.c) uses this for
97
Scan results must also include the WPA information element. Support for
98
this was added in WE-18. With older versions, a custom event can be used
99
to provide the full WPA IE (including element id and length) as a hex
100
string that is included in the scan results.
102
%wpa_supplicant needs to also be able to request the driver to
103
associate with a specific BSS. Current Host AP driver and matching
104
driver_hostap.c wrapper uses following sequence for this
105
request. Similar/identical mechanism should be usable also with other
108
- set WPA IE for AssocReq with private ioctl
109
- set SSID with SIOCSIWESSID
110
- set channel/frequency with SIOCSIWFREQ
111
- set BSSID with SIOCSIWAP
112
(this last ioctl will trigger the driver to request association)
114
\subsection driver_wpa_ie WPA IE generation
116
%wpa_supplicant selects which cipher suites and key management suites
117
are used. Based on this information, it generates a WPA IE. This is
118
provided to the driver interface in the associate call. This does not
119
match with Windows NDIS drivers which generate the WPA IE
122
%wpa_supplicant allows Windows NDIS-like behavior by providing the
123
selected cipher and key management suites in the associate call. If
124
the driver generates its own WPA IE and that differs from the one
125
generated by %wpa_supplicant, the driver has to inform %wpa_supplicant
126
about the used WPA IE (i.e., the one it used in (Re)Associate
127
Request). This notification is done using EVENT_ASSOCINFO event (see
128
driver.h). %wpa_supplicant is normally configured to use
129
ap_scan=2 mode with drivers that control WPA IE generation and roaming.
131
\subsection driver_events Driver events
133
%wpa_supplicant needs to receive event callbacks when certain events
134
occur (association, disassociation, Michael MIC failure, scan results
135
available, PMKSA caching candidate). These events and the callback
136
details are defined in driver.h (wpa_supplicant_event() function
137
and enum wpa_event_type).
139
On Linux, association and disassociation can use existing Wireless
140
Extensions event that is reporting new AP with SIOCGIWAP
141
event. Similarly, completion of a scan can be reported with SIOCGIWSCAN
144
Michael MIC failure event was added in WE-18. Older versions of Wireless
145
Extensions will need to use a custom event. Host AP driver used a custom
146
event with following contents: MLME-MICHAELMICFAILURE.indication(keyid=#
147
broadcast/unicast addr=addr2). This is the recommended format until
148
the driver can be moved to use WE-18 mechanism.
150
\subsection driver_wext_summary Summary of Linux Wireless Extensions use
152
AP selection depends on ap_scan configuration:
156
- %wpa_supplicant requests scan with SIOCSIWSCAN
157
- driver reports scan complete with wireless event SIOCGIWSCAN
158
- %wpa_supplicant reads scan results with SIOCGIWSCAN (multiple call if
159
a larget buffer is needed)
160
- %wpa_supplicant decides which AP to use based on scan results
161
- %wpa_supplicant configures driver to associate with the selected BSS
162
(SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWFREQ,
163
SIOCSIWESSID, SIOCSIWAP)
167
- %wpa_supplicant configures driver to associate with an SSID
168
(SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWESSID)
171
After this, both modes use similar steps:
173
- optionally (or required for drivers that generate WPA/RSN IE for
174
(Re)AssocReq), driver reports association parameters (AssocReq IEs)
175
with wireless event IWEVASSOCREQIE (and optionally IWEVASSOCRESPIE)
176
- driver reports association with wireless event SIOCGIWAP
177
- %wpa_supplicant takes care of EAPOL frame handling (validating
178
information from associnfo and if needed, from scan results if WPA/RSN
179
IE from the Beacon frame is not reported through associnfo)
added
removed
wpa_supplicant/doc/driver_wrapper.doxygen
