Driver wrapper implementation (driver.h, drivers.c)

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 system independent.

Driver wrappers need to implement whatever calls are used in the target operating system/driver for controlling wireless LAN devices. As an example, in case of Linux, these are mostly some glue code and ioctl() calls and netlink message parsing for Linux Wireless 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 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 card. In addition, support for driver events is required. The event callback function, wpa_supplicant_event(), and its parameters are documented in wpa_supplicant.h. In addition, a pointer to the 'struct wpa_driver_ops' needs to be registered in 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 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 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 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.

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) 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.

Driver requirements for WPA

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.

TKIP/CCMP

WPA requires that the pairwise cipher suite (encryption algorithm for unicast data packets) is TKIP or CCMP. These are new encryption protocols and thus, the driver will need to be modified to support them. Depending on the used wlan hardware, some parts of these may be implemented by the hardware/firmware.

Specification for both TKIP and CCMP is available from IEEE (IEEE 802.11i amendment). Fully functional, hardware independent implementation of both encryption protocols is also available in Host AP driver (driver/modules/hostap_{tkip,ccmp}.c). In addition, Linux 2.6 kernel tree has generic implementations for WEP, TKIP, and CCMP that can be used in Linux drivers.

The driver will also need to provide configuration mechanism to allow user space programs to configure TKIP and CCMP. Linux Wireless Extensions v18 added support for configuring these algorithms and individual/non-default keys. If the target kernel does not include WE-18, private ioctls can be used to provide similar functionality.

Roaming control and scanning support

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 scan results.

Scan results must also include the WPA information element. Support for this was added in WE-18. With older versions, a custom event can be used 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 associate with a specific BSS. Current Host AP driver and matching driver_hostap.c wrapper uses following sequence for this request. Similar/identical mechanism should be usable also with other drivers.

WPA IE generation

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 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 about the used WPA IE (i.e., the one it used in (Re)Associate Request). This notification is done using EVENT_ASSOCINFO event (see wpa_supplicant.h). wpa_supplicant is normally configured to use ap_scan=2 mode with drivers that control WPA IE generation and roaming.

Driver 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 wpa_supplicant.h (wpa_supplicant_event() function and enum wpa_event_type).

On Linux, association and disassociation can use existing Wireless Extensions event that is reporting new AP with SIOCGIWAP event. Similarly, completion of a scan can be reported with SIOCGIWSCAN event.

Michael MIC failure event was added in WE-18. Older versions of Wireless Extensions will need to use a custom event. Host AP driver used a custom event with following contents: MLME-MICHAELMICFAILURE.indication(keyid=# broadcast/unicast addr=addr2). This is the recommended format until the driver can be moved to use WE-18 mechanism.

Summary of Linux Wireless Extensions use

AP selection depends on ap_scan configuration:

ap_scan=1:

ap_scan=2:

After this, both modes use similar steps:


Generated on Sun Dec 31 13:56:00 2006 for wpa_supplicant by  doxygen 1.4.2