aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJouni Malinen <j@w1.fi>2005-06-26 03:33:40 (GMT)
committerJouni Malinen <j@w1.fi>2005-06-26 03:33:40 (GMT)
commitd04575c9488e0f789e865fd4e621296016be12f5 (patch)
treef0c7150e9e8ac410f2dc40e71b2d3f7f83fdf8bd
parent03e5e948bbe4c41e700feb56991441e9436bfb49 (diff)
downloadhostap-history-d04575c9488e0f789e865fd4e621296016be12f5.zip
hostap-history-d04575c9488e0f789e865fd4e621296016be12f5.tar.gz
hostap-history-d04575c9488e0f789e865fd4e621296016be12f5.tar.bz2
Removed developer.txt since it is not updated anymore and developers'
documentation at http://hostap.epitest.fi/wpa_supplicant/devel/ has replaced it as the current documentation.
-rw-r--r--wpa_supplicant/README3
-rw-r--r--wpa_supplicant/developer.txt462
2 files changed, 2 insertions, 463 deletions
diff --git a/wpa_supplicant/README b/wpa_supplicant/README
index c72e9c9..5b5e3f7 100644
--- a/wpa_supplicant/README
+++ b/wpa_supplicant/README
@@ -174,7 +174,8 @@ Current hardware/software requirements:
wpa_supplicant was designed to be portable for different drivers and
operating systems. Hopefully, support for more wlan cards and OSes will be
-added in the future. See developer.txt for more information about the
+added in the future. See developer's documentation
+(http://hostap.epitest.fi/wpa_supplicant/devel/) for more information about the
design of wpa_supplicant and porting to other drivers. One main goal
is to add full WPA/WPA2 support to Linux wireless extensions to allow
new drivers to be supported without having to implement new
diff --git a/wpa_supplicant/developer.txt b/wpa_supplicant/developer.txt
deleted file mode 100644
index 06cd130..0000000
--- a/wpa_supplicant/developer.txt
+++ /dev/null
@@ -1,462 +0,0 @@
-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_get_ssid()
-
-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_supplicant_rx_eapol()
-- l2_packet RX callback for EAPOL frames; sends the frames to WPA and EAPOL
- state machines for further processing
-
-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
-
-wpa_parse_wpa_ie()
-- WPA/RSN IE parsing
-
-wpa_gen_wpa_ei()
-- WPA/RSN IE generation
-
-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_get_mib()
-
-
-preauth.[ch]
-------------
-- PMKSA cache and RSN pre-authentication
-
-pmksa_cache_free()
-
-pmksa_cache_get()
-
-pmksa_cache_list()
-
-pmksa_candidate_free()
-
-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.