aboutsummaryrefslogtreecommitdiff
path: root/contrib/wpa_supplicant/developer.txt
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/wpa_supplicant/developer.txt')
-rw-r--r--contrib/wpa_supplicant/developer.txt458
1 files changed, 458 insertions, 0 deletions
diff --git a/contrib/wpa_supplicant/developer.txt b/contrib/wpa_supplicant/developer.txt
new file mode 100644
index 000000000000..bc5b34645d1a
--- /dev/null
+++ b/contrib/wpa_supplicant/developer.txt
@@ -0,0 +1,458 @@
+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.