DSA Supplicant Portability
Porting to Other Operating Systems
Devicescape Agent Supplicant (DSA Supplicant) is designed to be easily portable to different hardware (board, CPU) and software (OS, drivers) targets. It is already used with a number of operating systems and numerous wireless card models and drivers. DSA Supplicant includes support for Linux, WinCE, Windows Mobile, and Windows. DSA Supplicant is used on a variety of systems: desktops, laptops, PDAs, and embedded devices with CPUs including x86, PowerPC, arm/xscale, and MIPS. Both big and little endian configurations are supported.
For a complete reference on how to port DSA Supplicant, see Porting to Different Target Boards and Operating Systems in the DSA Supplicant API Reference Manual.
The following subtopics are covered in the API Documentation:
|
Topic
|
Description
|
|
Driver Interface
|
Unless the target OS and driver is already supported, most porting projects require implementation of a driver wrapper. This may be done by adding a new driver interface module or modifying an existing module (driver_*.c) if the new target is similar to one of them.
|
|
|
Describes the details of the driver interface and discusses the tasks involved in porting this part of DSA Supplicant.
|
|
l2_packet (link layer access)
|
DSA Supplicant needs to have access to sending and receiving layer 2 (link layer) packets with two Ethertypes: EAP-over-LAN (EAPOL) 0x888e and RSN pre-authentication 0x88c7. l2_packet.h defines the interfaces used for this in the core wpa_supplicant implementation.
|
|
|
Defines the interfaces used for sending and receiving layer 2 (link layer) packets in the core wpa_supplicant implementation.
|
|
|
Layer2 packet handling with Linux packet sockets
|
|
|
Layer2 packet handling with libpcap/libdnet and support for WinPcap
|
|
|
Layer2 packet handling with FreeBSD
|
|
|
Used to override the l2_packet library if the link layer access is integrated with the driver interface implementation.
|
|
Event Loop
|
An event loop and a single process/thread model are used to provide callbacks on events (registered timeout, received packet, signal).
|
|
|
Defines the event loop interface.
|
|
|
An implementation of an event loop interface using select() and sockets.
|
|
Control Interface
|
Used by external programs to control the operations of the wpa_supplicant daemon and to get status information and event notifications.The control interface is an optional component. You can run DSA Supplicant without porting this part.
|
|
|
Defines where the wpa_supplicant side of the control interface is implemented.
|
|
|
Defines where the client side of the control interface is implemented.
|
|
Program Entry Point
|
DSA Supplicant defines a set of functions that can be used to initialize main supplicant processing. Each operating system has a mechanism for starting new processing or threads. This is usually a function with a specific set of arguments and calling conventions. This function is responsible for initializing DSA Supplicant.
|
|
|
Defines how the initialization process should be done.
|
|
|
Defines the supplicant initialization functions.
|
|
|
Used to initialize DSA Supplicant.
|
|
|
Used to add an existing network interface to the supplicant.
|
|
|
Used to start the main event loop.
|
|
|
Used to release global context data.
|
|
|
Used to dynamically remove a network interface from the supplicant.
|
Driver Interface
All hardware and driver dependent functionality is implemented as a separate C file(s) implementing defined wrapper functions. Other parts of DSA Supplicant are designed to be hardware, driver, and operating system independent.
In the future, full WPA/WPA2 support for Linux wireless extensions will allow new drivers to be supported without having to implement new driver-specific interface code in wpa_supplicant.
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.
The table below lists the files and functions used in driver wrapper implementation.
For a complete reference on how to implement driver wrappers, see the Driver Wrapper Implementation (driver.h, drivers.c) topic in the API Reference Documentation.
|
File/Function
|
Description
|
|
|
Some or all of the functions in this file need to be implemented by the driver wrapper.
|
|
|
Where the functions defined in the driver.h file are registered.
|
|
|
This event callback function supports driver events.
|
|
|
Where the parameters of the wpa_supplicant_event function are documented.
|
|
|
Where the pointers to the 'struct wpa_driver_ops' are registered.
|
|
|
Where generic Linux Wireless Extension functions are implemented.
|
|
|
Where driver functions are called from.
|
|
|
Includes a complete implementation for Linux drivers that use wpa_supplicant-based control of WPA IE and roaming.
|
|
|
An example of a complete interface for Windows/NDIS, for drivers that generate WPA/IE themselves and decide when to roam.
|
|
|
WinCE NDISUIO
|
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. For more details on driver requirements for WPA, see the Driver Wrapper Implementation (driver.h, drivers.c) topic.
|
Driver Requirements
|
Description
|
|
TKIP/CCMP
|
DSA Supplicant requires that the pairwise cipher suite (encryption algorithm for unicast data packets) is TKIP or CCMP. These are new encryption protocols and so, the driver will need to be modified to support them.
|
|
Optional roaming control and scanning report
|
DSA Supplicant can control AP selections based on the information received from Beacon and/or Probe Response frames. This means that the driver should support external controls for the 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.
|
|
WPA IE generation
|
DSA Supplicant selects which cipher suites and key management suites are used. It then generates a WPA IE based on this information. The information is then sent to the driver interface in the associate call. This does not match with Windows NDIS drivers which generate the WPA IE themselves. However, DSA Supplicant supports both operation modes.
|
|
Driver events
|
DSA Supplicant needs to receive event callbacks when certain driver 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.
|
Control Interface
DSA Supplicant includes a set of source files (a control interface) that you can include in the project for your external application. These source files implement procedures for passing data between your application and DSA Supplicant.
Once you link these files to your application, you can call a control interface function and supply a command message (to take a trivial example, the command might be "PING"). The reply from DSA Supplicant is received in a buffer supplied by your application. The communication between your configuration application and DSA Supplicant takes places over UNIX sockets or via UDP connections. However, the control interface manages the details of the connection for you. This interface allows you to build the application that communicates with DSA Supplicant and you do not have to worry about the details of how the data is passed between the applications.
The control interface also provides a way for your application to receive "unsolicited messages," such as event notification.
TLS Interface
The Devicescape Agent Supplicant supports use of Transport Layer Security (TLS) solutions from the following providers:
- OpenSSL - This is the solution with which Devicescape conducted validation testing. Using OpenSSL for DSA Supplicant requires a more complex development process, since you must build it from source. Therefore, we use this as the TLS solution described in the tasks and example walkthroughs in this topic. For more information on OpenSSL solutions, see http://www.openssl.org/.
OpenSSL is a very complete, full-featured security solution but also has a large footprint on the Flash in comparison with the other TLS solutions, which are more tailored for embedded deployment.
- MatrixSSL - MatrixSSL is typically built from source. For information on how to build it, follow the instructions obtained from the vendor. This Developer Guide explains how to integrate the resulting MatrixSSL libraries and files with DSA Supplicant. (For more information on Matrix solutions, see http://www.matrixssl.org/.)
- Certicom - Certicom provides a pre-built TLS solution. For information on how to integrate the Certicom pre-built solution with the DSA Supplicant application or service, follow the instructions in this Developer Guide. For more information on Certicom solutions, see http://www.certicom.com/.
