459 lines
14 KiB
Plaintext
459 lines
14 KiB
Plaintext
Developer notes for wpa_supplicant
|
|
==================================
|
|
|
|
The design goal for wpa_supplicant was to use hardware, driver, and OS
|
|
independent, portable C code for all WPA functionality. All
|
|
hardware/driver specific functionality is in separate files that
|
|
implement a well-defined driver API.
|
|
|
|
The goal of this file and the comments in the header files is to give
|
|
enough information for other developers to be able to port the example
|
|
code. If any information is missing, feel free to contact Jouni Malinen
|
|
<jkmaline@cc.hut.fi> for more information. Contributions as patch files
|
|
are also very welcome at the same address.
|
|
|
|
Structure of the source code
|
|
----------------------------
|
|
|
|
Program initialization, main control loop and event handling is
|
|
implemented in wpa_supplicant.c. WPA state machines and 4-Way/Group
|
|
Key Handshake processing in in wpa.c. IEEE 802.1X/EAPOL processing and
|
|
state machines are in eapol_sm.c. EAP state machine is in eap.c. EAP
|
|
methods for the internal EAP peer are in eap_*.c. Parser for the
|
|
configuration file is implemented in config.c.
|
|
|
|
Driver interface API is defined in driver.h and all hardware/driver
|
|
dependent functionality is implemented in driver_*.c (see below).
|
|
|
|
|
|
Generic helper functions
|
|
------------------------
|
|
|
|
wpa_supplicant uses generic helper functions some of which are shared
|
|
with with hostapd. The following C files are currently used:
|
|
|
|
eloop.[ch]
|
|
event loop (select() loop with registerable timeouts, socket read
|
|
callbacks, and signal callbacks)
|
|
|
|
common.[ch]
|
|
common helper functions
|
|
|
|
defs.h
|
|
definitions shared by multiple files
|
|
|
|
l2_packet.[ch]
|
|
Layer 2 (link) access wrapper (includes native Linux implementation
|
|
and wrappers for libdnet/libpcap)
|
|
|
|
pcsc_funcs.[ch]
|
|
Wrapper for PC/SC lite SIM and smart card readers
|
|
|
|
|
|
Cryptographic functions
|
|
-----------------------
|
|
|
|
md5.c
|
|
MD5 (replaced with openssl/crypto if TLS support is included)
|
|
HMAC-MD5 (keyed checksum for message authenticity validation)
|
|
|
|
rc4.c
|
|
RC4 (broadcast/default key encryption)
|
|
|
|
sha1.c
|
|
SHA-1 (replaced with openssl/crypto if TLS support is included)
|
|
HMAC-SHA-1 (keyed checksum for message authenticity validation)
|
|
PRF-SHA-1 (pseudorandom (key/nonce generation) function)
|
|
PBKDF2-SHA-1 (ASCII passphrase to shared secret)
|
|
T-PRF (for EAP-FAST)
|
|
TLS-PRF (RFC 2246)
|
|
|
|
aes_wrap.[ch], aes.c
|
|
AES
|
|
AES Key Wrap Algorithm with 128-bit KEK, RFC3394 (broadcast/default
|
|
key encryption)
|
|
One-Key CBC MAC (OMAC1) hash with AES-128
|
|
AES-128 CTR mode encryption
|
|
AES-128 EAX mode encryption/decryption
|
|
AES-128 CBC
|
|
|
|
crypto.[ch]
|
|
Wrapper functions for libcrypto (MD4 and DES)
|
|
|
|
ms_funcs.[ch]
|
|
Helper functions for MSCHAPV2 and LEAP
|
|
|
|
tls.h
|
|
Definition of TLS library wrapper
|
|
|
|
tls_none.c
|
|
Dummy implementation of TLS library wrapper for cases where TLS
|
|
functionality is not included.
|
|
|
|
tls_openssl.c
|
|
TLS library wrapper for openssl
|
|
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
config_ssid.h
|
|
Definition of per network configuration items
|
|
|
|
config.h
|
|
Definition of the wpa_supplicant configuration
|
|
|
|
config.c
|
|
Configuration file parser
|
|
|
|
|
|
Control interface
|
|
-----------------
|
|
|
|
wpa_supplicant has a control interface that can be used to get status
|
|
information and manage operations from external programs. An example,
|
|
command line interface, wpa_cli, for this interface is included in the
|
|
wpa_supplicant distribution.
|
|
|
|
ctrl_iface.[ch]
|
|
wpa_supplicant-side of the control interface
|
|
|
|
wpa_ctrl.[ch]
|
|
Library functions for external programs to provide access to the
|
|
wpa_supplicant control interface
|
|
|
|
wpa_cli.c
|
|
Example program for using wpa_supplicant control interface
|
|
|
|
|
|
EAP peer
|
|
--------
|
|
|
|
eap.[ch]
|
|
EAP state machine
|
|
|
|
eap_defs.h
|
|
Common EAP definitions
|
|
|
|
eap_i.h
|
|
Internal definitions for EAP state machine and EAP methods
|
|
|
|
eap_sim_common.[ch]
|
|
Common code for EAP-SIM and EAP-AKA
|
|
|
|
eap_tls_common.[ch]
|
|
Common code for EAP-PEAP, EAP-TTLS, and EAP-FAST
|
|
|
|
eap_tlv.[ch]
|
|
EAP-TLV code for EAP-PEAP and EAP-FAST
|
|
|
|
eap_{aka,fast,gtc,leap,md5,mschapv2,otp,peap,psk,sim,tls,ttls}.c
|
|
EAP method implementations
|
|
|
|
|
|
EAPOL supplicant
|
|
----------------
|
|
|
|
eapol_sm.[ch]
|
|
EAPOL supplicant state machine and IEEE 802.1X processing
|
|
|
|
|
|
Windows port
|
|
------------
|
|
|
|
ndis_events.cpp
|
|
External program for receiving NdisMIndicateStatus() events and
|
|
delivering them to wpa_supplicant in more easier to use form
|
|
|
|
win_if_list.c
|
|
External program for listing current network interface
|
|
|
|
|
|
Test programs
|
|
-------------
|
|
|
|
radius_client.[ch]
|
|
RADIUS authentication client implementation for eapol_test
|
|
|
|
eapol_test.c
|
|
Standalone EAP testing tool with integrated RADIUS authentication
|
|
client
|
|
|
|
preauth_test.c
|
|
Standalone RSN pre-authentication tool
|
|
|
|
|
|
wpa_supplicant.c
|
|
----------------
|
|
|
|
main()
|
|
- parse command line
|
|
- call config file parser
|
|
- initialize Supplicant data structures
|
|
- call functions to initialize WPA support in the driver
|
|
- initialize event loop
|
|
- cleanup when exiting
|
|
|
|
wpa_supplicant_dot1x_receive()
|
|
- receive master session key update from Xsupplicant (optional)
|
|
|
|
wpa_supplicant_get_beacon_ie()
|
|
|
|
wpa_supplicant_deauthenticate()
|
|
|
|
wpa_supplicant_disassociate()
|
|
|
|
wpa_supplicant_scan()
|
|
|
|
wpa_supplicant_reconfig()
|
|
- SIGHUP signal processing
|
|
|
|
wpa_supplicant_terminate()
|
|
- SIGINT and SIGTERM processing
|
|
|
|
wpa_supplicant_reload_configuration()
|
|
|
|
wpa_supplicant_event()
|
|
- receive driver events (through driver wrapper functions)
|
|
* wpa_supplicant_scan_results(): process scan result event, BSS selection
|
|
* wpa_supplicant_associnfo(): process association information event
|
|
|
|
wpa_supplicant_associate()
|
|
- control association (select cipher and key management suites, initiate
|
|
association)
|
|
|
|
wpa_supplicant_req_auth_timeout()
|
|
|
|
wpa_supplicant_cancel_auth_timeout()
|
|
|
|
wpa_supplicant_req_scan()
|
|
|
|
wpa_supplicant_cancel_scan()
|
|
|
|
wpa_supplicant_notify_eapol_done()
|
|
|
|
wpa_eapol_send()
|
|
- send EAPOL frames
|
|
|
|
wpa_eapol_send_preauth()
|
|
- send RSN preauthentication frames
|
|
|
|
wpa_msg()
|
|
- event/debug function
|
|
|
|
|
|
wpa_supplicant.h
|
|
----------------
|
|
|
|
- driver event definition
|
|
- common function definition (e.g., wpa_msg)
|
|
|
|
|
|
wpa_supplicant_i.h
|
|
------------------
|
|
- internal definitions for wpa_supplicant; must not be included into
|
|
common code, EAP methods, driver interface implementations
|
|
|
|
|
|
wpa.[ch]
|
|
--------
|
|
- WPA supplicant state machine and 4-Way/Group Key Handshake processing
|
|
- PMKSA cache and RSN pre-authentication
|
|
|
|
pmksa_cache_free()
|
|
|
|
pmksa_cache_get()
|
|
|
|
pmksa_cache_list()
|
|
|
|
pmksa_candidate_free()
|
|
|
|
wpa_parse_wpa_ie()
|
|
- WPA/RSN IE parsing
|
|
|
|
wpa_gen_wpa_ei()
|
|
- WPA/RSN IE generation
|
|
|
|
wpa_supplicant_get_ssid()
|
|
|
|
wpa_supplicant_key_request()
|
|
- trigger function to start key requests
|
|
|
|
wpa_sm_rx_eapol()
|
|
- WPA processing for received EAPOL-Key frames
|
|
* wpa_supplicant_process_1_of_4() (message 1 of 4-Way Handshake)
|
|
* wpa_supplicant_process_3_of_4() (message 3 of 4-Way Handshake)
|
|
* wpa_supplicant_process_1_of_2() (message 1 of Group Key Handshake)
|
|
|
|
wpa_supplicant_rx_eapol()
|
|
- l2_packet RX callback for EAPOL frames; sends the frames to WPA and EAPOL
|
|
state machines for further processing
|
|
|
|
wpa_get_mib()
|
|
|
|
rsn_preauth_receive()
|
|
- l2_packet RX callback for preauthentication frames
|
|
|
|
rsn_preauth_eapol_cb()
|
|
- callback function to be called when EAPOL authentication has been completed
|
|
(either successfully or unsuccessfully) for RSN pre-authentication
|
|
|
|
rsn_preauth_init()
|
|
rsn_preauth_deinit()
|
|
|
|
pmksa_candidate_add()
|
|
- add a BSSID to PMKSA candidate list
|
|
|
|
rsn_preauth_scan_results()
|
|
- update RSN pre-authentication candidate list based on scan results
|
|
|
|
|
|
Driver wrapper implementation (driver.h, drivers.c)
|
|
---------------------------------------------------
|
|
|
|
All hardware and driver dependent functionality is implemented in as a
|
|
separate C file(s) implementing 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. Since all features required for WPA are not yet included
|
|
in Wireless Extensions, some driver specific code is used in the
|
|
example implementation for Host AP driver. These driver dependent parts
|
|
are to be replaced with generic code once the needed changes are
|
|
included in the Wireless Extensions. 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 (see that file for detailed documentation of the
|
|
functions). 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, pointer to the 'struct wpa_driver_ops'
|
|
needs to be registered in drivers.c file.
|
|
|
|
When porting to other operating systems, 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 addresses on case by case
|
|
basic 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.
|
|
|
|
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. These entries need to be added to the lists in
|
|
wpa_supplicant_set_driver() and usage() functions in wpa_supplicant.c.
|
|
|
|
In general, it is likely to be useful to first take a look at couple
|
|
of the driver interfaces 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 draft version 3.0). Fully functional, hardware independent
|
|
implementation of both encryption protocols is also available in Host
|
|
AP driver (driver/modules/hostap_{tkip,ccmp}.c).
|
|
|
|
The driver will also need to provide configuration mechanism to allow
|
|
user space programs to configure TKIP and CCMP. Current Linux Wireless
|
|
Extensions (v16) does not yet support these algorithms or
|
|
individual/non-default keys. Host AP driver has an example of private
|
|
ioctl()s for this. Eventually, this should be replaced with modified
|
|
Linux Wireless Extensions.
|
|
|
|
Roaming control and scanning support
|
|
|
|
wpa_supplicant controls AP selections based on the information
|
|
received from Beacon and/or Probe Response frames. 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 WPA information element. This is not
|
|
yet defined in Linux Wireless Extensions and Host AP driver uses a
|
|
custom event to provide the full WPA IE (including element id and
|
|
length) as a hex string that is included in the scan results.
|
|
Eventually, this should be defined as a Wireless Extensions ioctl
|
|
that can be used both with scan results and with configuration of WPA IE
|
|
for association request (and Beacon/Probe Response in case of an
|
|
AP/IBSS).
|
|
|
|
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.
|
|
|
|
- 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)
|
|
|
|
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).
|
|
|
|
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.
|
|
|
|
On Linux, association and disassociation can use existing Wireless
|
|
Extensions event that is reporting new AP with SIOCGIWAP
|
|
event. Similarly, completion of scan can be reported with SIOCGIWSCAN
|
|
event.
|
|
|
|
Michael MIC failure event is not yet included in Wireless Extensions,
|
|
so this needs a custom event. Host AP driver uses custom event with
|
|
following contents: MLME-MICHAELMICFAILURE.indication(keyid=#
|
|
broadcast/unicast addr=addr2). This is the recommended format until
|
|
the event is added to Linux Wireless Extensions.
|