DGNum/hostapd
6
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Add new, shared doxygen documentation for hostapd and wpa_supplicant

Browse source
This commit is contained in:
Jouni Malinen 2009-11-28 21:19:48 +02:00
parent e8f5625c45
commit 30c2897179
14 changed files with 3866 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
doc/.gitignore vendored Normal file
View file

@ -0,0 +1,8 @@
doxygen.warnings
hostapd.eps
hostapd.png
html
latex
wpa_supplicant.eps
wpa_supplicant.png
wpa_supplicant-devel.pdf

26
doc/Makefile Normal file
View file

@ -0,0 +1,26 @@
all: docs
%.eps: %.fig
fig2dev -L eps $*.fig $*.eps
%.png: %.fig
fig2dev -L png -m 3 $*.fig | pngtopnm | pnmscale 0.4 | pnmtopng \
> $*.png
docs-pics: wpa_supplicant.png wpa_supplicant.eps hostapd.png hostapd.eps
docs: docs-pics
(cd ..; doxygen doc/doxygen.conf; cd doc)
$(MAKE) -C latex
cp latex/refman.pdf wpa_supplicant-devel.pdf
html: docs-pics
(cd ..; doxygen doc/doxygen.conf; cd doc)
clean:
rm -f *~
rm -f wpa_supplicant.eps wpa_supplicant.png
rm -f hostapd.eps hostapd.png
rm -f doxygen.warnings
rm -rf html latex
rm -f wpa_supplicant-devel.pdf

322
doc/code_structure.doxygen Normal file
View file

@ -0,0 +1,322 @@
/**
\page code_structure Structure of the source code
[ \ref wpa_supplicant_core "wpa_supplicant core functionality" |
\ref generic_helper_func "Generic helper functions" |
\ref crypto_func "Cryptographic functions" |
\ref tls_func "TLS library" |
\ref configuration "Configuration" |
\ref ctrl_iface "Control interface" |
\ref wpa_code "WPA supplicant" |
\ref eap_peer "EAP peer" |
\ref eapol_supp "EAPOL supplicant" |
\ref win_port "Windows port" |
\ref test_programs "Test programs" ]
%wpa_supplicant implementation is divided into number of independent
modules. Core code includes functionality for controlling the network
selection, association, and configuration. Independent modules include
WPA code (key handshake, PMKSA caching, pre-authentication), EAPOL
state machine, and EAP state machine and methods. In addition, there
are number of separate files for generic helper functions.
Both WPA and EAPOL/EAP state machines can be used separately in other
programs than %wpa_supplicant. As an example, the included test
programs eapol_test and preauth_test are using these modules.
\ref driver_wrapper "Driver interface API" is defined in driver.h and
all hardware/driver dependent functionality is implemented in
driver_*.c.
\section wpa_supplicant_core wpa_supplicant core functionality
wpa_supplicant.c
Program initialization, main control loop
main.c
main() for UNIX-like operating systems and MinGW (Windows); this
uses command line arguments to configure wpa_supplicant
events.c
Driver event processing; wpa_supplicant_event() and related functions
wpa_supplicant_i.h
Internal definitions for %wpa_supplicant core; should not be
included into independent modules
\section generic_helper_func 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.c and eloop.h
Event loop (select() loop with registerable timeouts, socket read
callbacks, and signal callbacks)
common.c and common.h
Common helper functions
defs.h
Definitions shared by multiple files
l2_packet.h, l2_packet_linux.c, and l2_packet_pcap.c
Layer 2 (link) access wrapper (includes native Linux implementation
and wrappers for libdnet/libpcap). A new l2_packet implementation
may need to be added when porting to new operating systems that are
not supported by libdnet/libpcap. Makefile can be used to select which
l2_packet implementation is included. l2_packet_linux.c uses Linux
packet sockets and l2_packet_pcap.c has a more portable version using
libpcap and libdnet.
pcsc_funcs.c and pcsc_funcs.h
Wrapper for PC/SC lite SIM and smart card readers
priv_netlink.h
Private version of netlink definitions from Linux kernel header files;
this could be replaced with C library header file once suitable
version becomes commonly available
version.h
Version number definitions
wireless_copy.h
Private version of Linux wireless extensions definitions from kernel
header files; this could be replaced with C library header file once
suitable version becomes commonly available
\section crypto_func Cryptographic functions
md5.c and md5.h
MD5 (replaced with a crypto library if TLS support is included)
HMAC-MD5 (keyed checksum for message authenticity validation)
rc4.c and rc4.h
RC4 (broadcast/default key encryption)
sha1.c and sha1.h
SHA-1 (replaced with a crypto library 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)
sha256.c and sha256.h
SHA-256 (replaced with a crypto library if TLS support is included)
aes_wrap.c, aes_wrap.h, aes.c
AES (replaced with a crypto library if TLS support is included),
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.h
Definition of crypto library wrapper
crypto_openssl.c
Wrapper functions for libcrypto (OpenSSL)
crypto_internal.c
Wrapper functions for internal crypto implementation
crypto_gnutls.c
Wrapper functions for libgcrypt (used by GnuTLS)
ms_funcs.c and ms_funcs.h
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
tls_internal.c
TLS library for internal TLS implementation
tls_gnutls.c
TLS library wrapper for GnuTLS
\section tls_func TLS library
asn1.c and asn1.h
ASN.1 DER parsing
bignum.c and bignum.h
Big number math
rsa.c and rsa.h
RSA
x509v3.c and x509v3.h
X.509v3 certificate parsing and processing
tlsv1_client.c, tlsv1_client.h
TLSv1 client (RFC 2246)
tlsv1_client_i.h
Internal structures for TLSv1 client
tlsv1_client_read.c
TLSv1 client: read handshake messages
tlsv1_client_write.c
TLSv1 client: write handshake messages
tlsv1_common.c and tlsv1_common.h
Common TLSv1 routines and definitions
tlsv1_cred.c and tlsv1_cred.h
TLSv1 credentials
tlsv1_record.c and tlsv1_record.h
TLSv1 record protocol
\section configuration Configuration
config_ssid.h
Definition of per network configuration items
config.h
Definition of the %wpa_supplicant configuration
config.c
Configuration parser and common functions
config_file.c
Configuration backend for text files (e.g., wpa_supplicant.conf)
config_winreg.c
Configuration backend for Windows registry
\section ctrl_iface Control interface
%wpa_supplicant has a \ref ctrl_iface_page "control interface"
that can be used to get status
information and manage operations from external programs. An example
command line interface (wpa_cli) and GUI (wpa_gui) for this interface
are included in the %wpa_supplicant distribution.
ctrl_iface.c and ctrl_iface.h
%wpa_supplicant-side of the control interface
ctrl_iface_unix.c
UNIX domain sockets -based control interface backend
ctrl_iface_udp.c
UDP sockets -based control interface backend
ctrl_iface_named_pipe.c
Windows named pipes -based control interface backend
wpa_ctrl.c and wpa_ctrl.h
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
\section wpa_code WPA supplicant
wpa.c and wpa.h
WPA state machine and 4-Way/Group Key Handshake processing
preauth.c and preauth.h
PMKSA caching and pre-authentication (RSN/WPA2)
wpa_i.h
Internal definitions for WPA code; not to be included to other modules.
\section eap_peer EAP peer
\ref eap_module "EAP peer implementation" is a separate module that
can be used by other programs than just %wpa_supplicant.
eap.c and eap.h
EAP state machine and method interface
eap_defs.h
Common EAP definitions
eap_i.h
Internal definitions for EAP state machine and EAP methods; not to be
included in other modules
eap_sim_common.c and eap_sim_common.h
Common code for EAP-SIM and EAP-AKA
eap_tls_common.c and eap_tls_common.h
Common code for EAP-PEAP, EAP-TTLS, and EAP-FAST
eap_tlv.c and eap_tlv.h
EAP-TLV code for EAP-PEAP and EAP-FAST
eap_ttls.c and eap_ttls.h
EAP-TTLS
eap_pax.c, eap_pax_common.h, eap_pax_common.c
EAP-PAX
eap_psk.c, eap_psk_common.h, eap_psk_common.c
EAP-PSK (note: this is not needed for WPA-PSK)
eap_sake.c, eap_sake_common.h, eap_sake_common.c
EAP-SAKE
eap_gpsk.c, eap_gpsk_common.h, eap_gpsk_common.c
EAP-GPSK
eap_aka.c, eap_fast.c, eap_gtc.c, eap_leap.c, eap_md5.c, eap_mschapv2.c,
eap_otp.c, eap_peap.c, eap_sim.c, eap_tls.c
Other EAP method implementations
\section eapol_supp EAPOL supplicant
eapol_supp_sm.c and eapol_supp_sm.h
EAPOL supplicant state machine and IEEE 802.1X processing
\section win_port Windows port
ndis_events.c
Code for receiving NdisMIndicateStatus() events and delivering them to
%wpa_supplicant driver_ndis.c in more easier to use form
win_if_list.c
External program for listing current network interface
\section test_programs Test programs
radius_client.c and radius_client.h
RADIUS authentication client implementation for eapol_test
radius.c and radius.h
RADIUS message processing for eapol_test
eapol_test.c
Standalone EAP testing tool with integrated RADIUS authentication
client
preauth_test.c
Standalone RSN pre-authentication tool
wpa_passphrase.c
WPA ASCII passphrase to PSK conversion
*/

481
doc/ctrl_iface.doxygen Normal file
View file

@ -0,0 +1,481 @@
/**
\page ctrl_iface_page %wpa_supplicant control interface
%wpa_supplicant implements a control interface that can be used by
external programs to control the operations of the %wpa_supplicant
daemon and to get status information and event notifications. There is
a small C library, in a form of a single C file, wpa_ctrl.c, that
provides helper functions to facilitate the use of the control
interface. External programs can link this file into them and then use
the library functions documented in wpa_ctrl.h to interact with
%wpa_supplicant. This library can also be used with C++. wpa_cli.c and
wpa_gui are example programs using this library.
There are multiple mechanisms for inter-process communication. For
example, Linux version of %wpa_supplicant is using UNIX domain sockets
for the control interface and Windows version UDP sockets. The use of
the functions defined in wpa_ctrl.h can be used to hide the details of
the used IPC from external programs.
\section using_ctrl_iface Using the control interface
External programs, e.g., a GUI or a configuration utility, that need to
communicate with %wpa_supplicant should link in wpa_ctrl.c. This
allows them to use helper functions to open connection to the control
interface with wpa_ctrl_open() and to send commands with
wpa_ctrl_request().
%wpa_supplicant uses the control interface for two types of communication:
commands and unsolicited event messages. Commands are a pair of
messages, a request from the external program and a response from
%wpa_supplicant. These can be executed using wpa_ctrl_request().
Unsolicited event messages are sent by %wpa_supplicant to the control
interface connection without specific request from the external program
for receiving each message. However, the external program needs to
attach to the control interface with wpa_ctrl_attach() to receive these
unsolicited messages.
If the control interface connection is used both for commands and
unsolicited event messages, there is potential for receiving an
unsolicited message between the command request and response.
wpa_ctrl_request() caller will need to supply a callback, msg_cb,
for processing these messages. Often it is easier to open two
control interface connections by calling wpa_ctrl_open() twice and
then use one of the connections for commands and the other one for
unsolicited messages. This way command request/response pairs will
not be broken by unsolicited messages. wpa_cli is an example of how
to use only one connection for both purposes and wpa_gui demonstrates
how to use two separate connections.
Once the control interface connection is not needed anymore, it should
be closed by calling wpa_ctrl_close(). If the connection was used for
unsolicited event messages, it should be first detached by calling
wpa_ctrl_detach().
\section ctrl_iface_cmds Control interface commands
Following commands can be used with wpa_ctrl_request():
\subsection ctrl_iface_PING PING
This command can be used to test whether %wpa_supplicant is replying
to the control interface commands. The expected reply is \c PONG if the
connection is open and %wpa_supplicant is processing commands.
\subsection ctrl_iface_MIB MIB
Request a list of MIB variables (dot1x, dot11). The output is a text
block with each line in \c variable=value format. For example:
\verbatim
dot11RSNAOptionImplemented=TRUE
dot11RSNAPreauthenticationImplemented=TRUE
dot11RSNAEnabled=FALSE
dot11RSNAPreauthenticationEnabled=FALSE
dot11RSNAConfigVersion=1
dot11RSNAConfigPairwiseKeysSupported=5
dot11RSNAConfigGroupCipherSize=128
dot11RSNAConfigPMKLifetime=43200
dot11RSNAConfigPMKReauthThreshold=70
dot11RSNAConfigNumberOfPTKSAReplayCounters=1
dot11RSNAConfigSATimeout=60
dot11RSNAAuthenticationSuiteSelected=00-50-f2-2
dot11RSNAPairwiseCipherSelected=00-50-f2-4
dot11RSNAGroupCipherSelected=00-50-f2-4
dot11RSNAPMKIDUsed=
dot11RSNAAuthenticationSuiteRequested=00-50-f2-2
dot11RSNAPairwiseCipherRequested=00-50-f2-4
dot11RSNAGroupCipherRequested=00-50-f2-4
dot11RSNAConfigNumberOfGTKSAReplayCounters=0
dot11RSNA4WayHandshakeFailures=0
dot1xSuppPaeState=5
dot1xSuppHeldPeriod=60
dot1xSuppAuthPeriod=30
dot1xSuppStartPeriod=30
dot1xSuppMaxStart=3
dot1xSuppSuppControlledPortStatus=Authorized
dot1xSuppBackendPaeState=2
dot1xSuppEapolFramesRx=0
dot1xSuppEapolFramesTx=440
dot1xSuppEapolStartFramesTx=2
dot1xSuppEapolLogoffFramesTx=0
dot1xSuppEapolRespFramesTx=0
dot1xSuppEapolReqIdFramesRx=0
dot1xSuppEapolReqFramesRx=0
dot1xSuppInvalidEapolFramesRx=0
dot1xSuppEapLengthErrorFramesRx=0
dot1xSuppLastEapolFrameVersion=0
dot1xSuppLastEapolFrameSource=00:00:00:00:00:00
\endverbatim
\subsection ctrl_iface_STATUS STATUS
Request current WPA/EAPOL/EAP status information. The output is a text
block with each line in \c variable=value format. For example:
\verbatim
bssid=02:00:01:02:03:04
ssid=test network
pairwise_cipher=CCMP
group_cipher=CCMP
key_mgmt=WPA-PSK
wpa_state=COMPLETED
ip_address=192.168.1.21
Supplicant PAE state=AUTHENTICATED
suppPortStatus=Authorized
EAP state=SUCCESS
\endverbatim
\subsection ctrl_iface_STATUS-VERBOSE STATUS-VERBOSE
Same as STATUS, but with more verbosity (i.e., more \c variable=value pairs).
\verbatim
bssid=02:00:01:02:03:04
ssid=test network
id=0
pairwise_cipher=CCMP
group_cipher=CCMP
key_mgmt=WPA-PSK
wpa_state=COMPLETED
ip_address=192.168.1.21
Supplicant PAE state=AUTHENTICATED
suppPortStatus=Authorized
heldPeriod=60
authPeriod=30
startPeriod=30
maxStart=3
portControl=Auto
Supplicant Backend state=IDLE
EAP state=SUCCESS
reqMethod=0
methodState=NONE
decision=COND_SUCC
ClientTimeout=60
\endverbatim
\subsection ctrl_iface_PMKSA PMKSA
Show PMKSA cache
\verbatim
Index / AA / PMKID / expiration (in seconds) / opportunistic
1 / 02:00:01:02:03:04 / 000102030405060708090a0b0c0d0e0f / 41362 / 0
2 / 02:00:01:33:55:77 / 928389281928383b34afb34ba4212345 / 362 / 1
\endverbatim
\subsection ctrl_iface_SET SET <variable> <value>
Set variables:
- EAPOL::heldPeriod
- EAPOL::authPeriod
- EAPOL::startPeriod
- EAPOL::maxStart
- dot11RSNAConfigPMKLifetime
- dot11RSNAConfigPMKReauthThreshold
- dot11RSNAConfigSATimeout
Example command:
\verbatim
SET EAPOL::heldPeriod 45
\endverbatim
\subsection ctrl_iface_LOGON LOGON
IEEE 802.1X EAPOL state machine logon.
\subsection ctrl_iface_LOGOFF LOGOFF
IEEE 802.1X EAPOL state machine logoff.
\subsection ctrl_iface_REASSOCIATE REASSOCIATE
Force reassociation.
\subsection ctrl_iface_RECONNECT RECONNECT
Connect if disconnected (i.e., like \c REASSOCIATE, but only connect
if in disconnected state).
\subsection ctrl_iface_PREAUTH PREAUTH <BSSID>
Start pre-authentication with the given BSSID.
\subsection ctrl_iface_ATTACH ATTACH
Attach the connection as a monitor for unsolicited events. This can
be done with wpa_ctrl_attach().
\subsection ctrl_iface_DETACH DETACH
Detach the connection as a monitor for unsolicited events. This can
be done with wpa_ctrl_detach().
\subsection ctrl_iface_LEVEL LEVEL <debug level>
Change debug level.
\subsection ctrl_iface_RECONFIGURE RECONFIGURE
Force %wpa_supplicant to re-read its configuration data.
\subsection ctrl_iface_TERMINATE TERMINATE
Terminate %wpa_supplicant process.
\subsection ctrl_iface_BSSID BSSID <network id> <BSSID>
Set preferred BSSID for a network. Network id can be received from the
\c LIST_NETWORKS command output.
\subsection ctrl_iface_LIST_NETWORKS LIST_NETWORKS
List configured networks.
\verbatim
network id / ssid / bssid / flags
0 example network any [CURRENT]
\endverbatim
(note: fields are separated with tabs)
\subsection ctrl_iface_DISCONNECT DISCONNECT
Disconnect and wait for \c REASSOCIATE or \c RECONNECT command before
connecting.
\subsection ctrl_iface_SCAN SCAN
Request a new BSS scan.
\subsection ctrl_iface_SCAN_RESULTS SCAN_RESULTS
Get the latest scan results.
\verbatim
bssid / frequency / signal level / flags / ssid
00:09:5b:95:e0:4e 2412 208 [WPA-PSK-CCMP] jkm private
02:55:24:33:77:a3 2462 187 [WPA-PSK-TKIP] testing
00:09:5b:95:e0:4f 2412 209 jkm guest
\endverbatim
(note: fields are separated with tabs)
\subsection ctrl_iface_BSS BSS
Get detailed per-BSS scan results. \c BSS command can be used to
iterate through scan results one BSS at a time and to fetch all
information from the found BSSes. This provides access to the same
data that is available through \c SCAN_RESULTS but in a way that
avoids problems with large number of scan results not fitting in the
ctrl_iface messages.
There are two options for selecting the BSS with the \c BSS command:
"BSS <idx>" requests information for the BSS identified by the index
(0 .. size-1) in the scan results table and "BSS <BSSID>" requests
information for the given BSS (based on BSSID in 00:01:02:03:04:05
format).
BSS information is presented in following format. Please note that new
fields may be added to this field=value data, so the ctrl_iface user
should be prepared to ignore values it does not understand.
\verbatim
bssid=00:09:5b:95:e0:4e
freq=2412
beacon_int=0
capabilities=0x0011
qual=51
noise=161
level=212
tsf=0000000000000000
ie=000b6a6b6d2070726976617465010180dd180050f20101000050f20401000050f20401000050f2020000
ssid=jkm private
\endverbatim
\subsection ctrl_iface_SELECT_NETWORK SELECT_NETWORK <network id>
Select a network (disable others). Network id can be received from the
\c LIST_NETWORKS command output.
\subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK <network id>
Enable a network. Network id can be received from the
\c LIST_NETWORKS command output. Special network id \c all can be
used to enable all network.
\subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>
Disable a network. Network id can be received from the
\c LIST_NETWORKS command output. Special network id \c all can be
used to disable all network.
\subsection ctrl_iface_ADD_NETWORK ADD_NETWORK
Add a new network. This command creates a new network with empty
configuration. The new network is disabled and once it has been
configured it can be enabled with \c ENABLE_NETWORK command. \c ADD_NETWORK
returns the network id of the new network or FAIL on failure.
\subsection ctrl_iface_REMOVE_NETWORK REMOVE_NETWORK <network id>
Remove a network. Network id can be received from the
\c LIST_NETWORKS command output. Special network id \c all can be
used to remove all network.
\subsection ctrl_iface_SET_NETWORK SET_NETWORK <network id> <variable> <value>
Set network variables. Network id can be received from the
\c LIST_NETWORKS command output.
This command uses the same variables and data formats as the
configuration file. See example wpa_supplicant.conf for more details.
- ssid (network name, SSID)
- psk (WPA passphrase or pre-shared key)
- key_mgmt (key management protocol)
- identity (EAP identity)
- password (EAP password)
- ...
\subsection ctrl_iface_GET_NETWORK GET_NETWORK <network id> <variable>
Get network variables. Network id can be received from the
\c LIST_NETWORKS command output.
\subsection ctrl_iface_SAVE_CONFIG SAVE_CONFIG
Save the current configuration.
\section ctrl_iface_interactive Interactive requests
If %wpa_supplicant needs additional information during authentication
(e.g., password), it will use a specific prefix, \c CTRL-REQ-
(\a WPA_CTRL_REQ macro) in an unsolicited event message. An external
program, e.g., a GUI, can provide such information by using
\c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matching
field name.
The following fields can be requested in this way from the user:
- IDENTITY (EAP identity/user name)
- PASSWORD (EAP password)
- NEW_PASSWORD (New password if the server is requesting password change)
- PIN (PIN code for accessing a SIM or smartcard)
- OTP (one-time password; like password, but the value is used only once)
- PASSPHRASE (passphrase for a private key file)
\verbatim
CTRL-REQ-<field name>-<network id>-<human readable text>
CTRL-RSP-<field name>-<network id>-<value>
\endverbatim
For example, request from %wpa_supplicant:
\verbatim
CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
\endverbatim
And a matching reply from the GUI:
\verbatim
CTRL-RSP-PASSWORD-1-secret
\endverbatim
\subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option> [strict]
Get list of supported functionality (eap, pairwise, group,
proto). Supported functionality is shown as space separate lists of
values used in the same format as in %wpa_supplicant configuration.
If optional argument, 'strict', is added, only the values that the
driver claims to explicitly support are included. Without this, all
available capabilities are included if the driver does not provide
a mechanism for querying capabilities.
Example request/reply pairs:
\verbatim
GET_CAPABILITY eap
AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
\endverbatim
\verbatim
GET_CAPABILITY pairwise
CCMP TKIP NONE
\endverbatim
\verbatim
GET_CAPABILITY pairwise strict
\endverbatim
\verbatim
GET_CAPABILITY group
CCMP TKIP WEP104 WEP40
\endverbatim
\verbatim
GET_CAPABILITY key_mgmt
WPA-PSK WPA-EAP IEEE8021X NONE
\endverbatim
\verbatim
GET_CAPABILITY proto
RSN WPA
\endverbatim
\verbatim
GET_CAPABILITY auth_alg
OPEN SHARED LEAP
\endverbatim
\subsection ctrl_iface_AP_SCAN AP_SCAN <ap_scan value>
Change ap_scan value:
0 = no scanning,
1 = %wpa_supplicant requests scans and uses scan results to select the AP,
2 = %wpa_supplicant does not use scanning and just requests driver to
associate and take care of AP selection
\subsection ctrl_iface_INTERFACES INTERFACES
List configured interfaces.
\verbatim
wlan0
eth0
\endverbatim
*/

1531
doc/doxygen.conf Normal file
View file

File diff suppressed because it is too large Load diff

180
doc/driver_wrapper.doxygen Normal file
View file

@ -0,0 +1,180 @@
/**
\page driver_wrapper 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 driver.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.
\section driver_req 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.
\subsection driver_tkip_ccmp 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.
\subsection driver_roaming 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.
- 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)
\subsection driver_wpa_ie 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
driver.h). %wpa_supplicant is normally configured to use
ap_scan=2 mode with drivers that control WPA IE generation and roaming.
\subsection driver_events 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 driver.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.
\subsection driver_wext_summary Summary of Linux Wireless Extensions use
AP selection depends on ap_scan configuration:
ap_scan=1:
- %wpa_supplicant requests scan with SIOCSIWSCAN
- driver reports scan complete with wireless event SIOCGIWSCAN
- %wpa_supplicant reads scan results with SIOCGIWSCAN (multiple call if
a larget buffer is needed)
- %wpa_supplicant decides which AP to use based on scan results
- %wpa_supplicant configures driver to associate with the selected BSS
(SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWFREQ,
SIOCSIWESSID, SIOCSIWAP)
ap_scan=2:
- %wpa_supplicant configures driver to associate with an SSID
(SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWESSID)
After this, both modes use similar steps:
- optionally (or required for drivers that generate WPA/RSN IE for
(Re)AssocReq), driver reports association parameters (AssocReq IEs)
with wireless event IWEVASSOCREQIE (and optionally IWEVASSOCRESPIE)
- driver reports association with wireless event SIOCGIWAP
- %wpa_supplicant takes care of EAPOL frame handling (validating
information from associnfo and if needed, from scan results if WPA/RSN
IE from the Beacon frame is not reported through associnfo)
*/

87
doc/eap.doxygen Normal file
View file

@ -0,0 +1,87 @@
/**
\page eap_peer_module EAP peer implementation
Extensible Authentication Protocol (EAP) is an authentication framework
defined in RFC 3748. %wpa_supplicant uses a separate code module for EAP
peer implementation. This module was designed to use only a minimal set
of direct function calls (mainly, to debug/event functions) in order for
it to be usable in other programs. The design of the EAP
implementation is based loosely on RFC 4137. The state machine is
defined in this RFC and so is the interface between the peer state
machine and methods. As such, this RFC provides useful information for
understanding the EAP peer implementation in %wpa_supplicant.
Some of the terminology used in EAP state machine is referring to
EAPOL (IEEE 802.1X), but there is no strict requirement on the lower
layer being IEEE 802.1X if EAP module is built for other programs than
%wpa_supplicant. These terms should be understood to refer to the
lower layer as defined in RFC 4137.
\section adding_eap_methods Adding EAP methods
Each EAP method is implemented as a separate module, usually as one C
file named eap_<name of the method>.c, e.g., eap_md5.c. All EAP
methods use the same interface between the peer state machine and
method specific functions. This allows new EAP methods to be added
without modifying the core EAP state machine implementation.
New EAP methods need to be registered by adding them into the build
(Makefile) and the EAP method registration list in the
eap_peer_register_methods() function of eap_methods.c. Each EAP
method should use a build-time configuration option, e.g., EAP_TLS, in
order to make it possible to select which of the methods are included
in the build.
EAP methods must implement the interface defined in eap_i.h. struct
eap_method defines the needed function pointers that each EAP method
must provide. In addition, the EAP type and name are registered using
this structure. This interface is based on section 4.4 of RFC 4137.
It is recommended that the EAP methods would use generic helper
functions, eap_msg_alloc() and eap_hdr_validate() when processing
messages. This allows code sharing and can avoid missing some of the
needed validation steps for received packets. In addition, these
functions make it easier to change between expanded and legacy EAP
header, if needed.
When adding an EAP method that uses a vendor specific EAP type
(Expanded Type as defined in RFC 3748, Chapter 5.7), the new method
must be registered by passing vendor id instead of EAP_VENDOR_IETF to
eap_peer_method_alloc(). These methods must not try to emulate
expanded types by registering a legacy EAP method for type 254. See
eap_vendor_test.c for an example of an EAP method implementation that
is implemented as an expanded type.
\section used_eap_library Using EAP implementation as a library
The Git repository has an eap_example directory that contains an
example showing how EAP peer and server code from %wpa_supplicant and
hostapd can be used as a library. The example program initializes both
an EAP server and an EAP peer entities and then runs through an
EAP-PEAP/MSCHAPv2 authentication.
eap_example_peer.c shows the initialization and glue code needed to
control the EAP peer implementation. eap_example_server.c does the
same for EAP server. eap_example.c is an example that ties in both the
EAP server and client parts to allow an EAP authentication to be
shown.
In this example, the EAP messages are passed between the server and
the peer are passed by direct function calls within the same process.
In practice, server and peer functionalities would likely reside in
separate devices and the EAP messages would be transmitted between the
devices based on an external protocol. For example, in IEEE 802.11
uses IEEE 802.1X EAPOL state machines to control the transmission of
EAP messages and WiMax supports optional PMK EAP authentication
mechanism that transmits EAP messages as defined in IEEE 802.16e.
The EAP library links in number of helper functions from src/utils and
src/crypto directories. Most of these are suitable as-is, but it may
be desirable to replace the debug output code in src/utils/wpa_debug.c
by dropping this file from the library and re-implementing the
functions there in a way that better fits in with the main
application.
*/

56
doc/eap_server.doxygen Normal file
View file

@ -0,0 +1,56 @@
/**
\page eap_server_module EAP server implementation
Extensible Authentication Protocol (EAP) is an authentication framework
defined in RFC 3748. hostapd uses a separate code module for EAP server
implementation. This module was designed to use only a minimal set of
direct function calls (mainly, to debug/event functions) in order for
it to be usable in other programs. The design of the EAP
implementation is based loosely on RFC 4137. The state machine is
defined in this RFC and so is the interface between the server state
machine and methods. As such, this RFC provides useful information for
understanding the EAP server implementation in hostapd.
Some of the terminology used in EAP state machine is referring to
EAPOL (IEEE 802.1X), but there is no strict requirement on the lower
layer being IEEE 802.1X if EAP module is built for other programs than
%wpa_supplicant. These terms should be understood to refer to the
lower layer as defined in RFC 4137.
\section adding_eap_methods Adding EAP methods
Each EAP method is implemented as a separate module, usually as one C
file named eap_<name of the method>.c, e.g., eap_md5.c. All EAP
methods use the same interface between the server state machine and
method specific functions. This allows new EAP methods to be added
without modifying the core EAP state machine implementation.
New EAP methods need to be registered by adding them into the build
(Makefile) and the EAP method registration list in the
eap_server_register_methods() function of eap_methods.c. Each EAP
method should use a build-time configuration option, e.g., EAP_TLS, in
order to make it possible to select which of the methods are included
in the build.
EAP methods must implement the interface defined in eap_i.h. struct
eap_method defines the needed function pointers that each EAP method
must provide. In addition, the EAP type and name are registered using
this structure. This interface is based on section 4.4 of RFC 4137.
It is recommended that the EAP methods would use generic helper
functions, eap_msg_alloc() and eap_hdr_validate() when processing
messages. This allows code sharing and can avoid missing some of the
needed validation steps for received packets. In addition, these
functions make it easier to change between expanded and legacy EAP
header, if needed.
When adding an EAP method that uses a vendor specific EAP type
(Expanded Type as defined in RFC 3748, Chapter 5.7), the new method
must be registered by passing vendor id instead of EAP_VENDOR_IETF to
eap_server_method_alloc(). These methods must not try to emulate
expanded types by registering a legacy EAP method for type 254. See
eap_vendor_test.c for an example of an EAP method implementation that
is implemented as an expanded type.
*/

264
doc/hostapd.fig Normal file
View file

@ -0,0 +1,264 @@
#FIG 3.2
Landscape
Center
Inches
Letter
100.00
Single
-2
1200 2
6 1875 4050 2925 4350
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
1875 4050 2925 4050 2925 4350 1875 4350 1875 4050
4 0 0 50 -1 0 12 0.0000 4 180 735 2025 4275 l2_packet\001
-6
6 4725 1200 5925 1500
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4725 1200 5925 1200 5925 1500 4725 1500 4725 1200
4 0 0 50 -1 0 12 0.0000 4 135 1005 4800 1425 GUI frontend\001
-6
6 6000 2700 7200 3225
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6000 2700 7200 2700 7200 3225 6000 3225 6000 2700
4 0 0 50 -1 0 12 0.0000 4 135 975 6075 2925 WPA/WPA2\001
4 0 0 50 -1 0 12 0.0000 4 135 1065 6075 3150 state machine\001
-6
6 6000 4950 7200 5475
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6000 4950 7200 4950 7200 5475 6000 5475 6000 4950
4 0 0 50 -1 0 12 0.0000 4 135 360 6075 5175 EAP\001
4 0 0 50 -1 0 12 0.0000 4 135 1065 6075 5400 state machine\001
-6
6 4350 3900 5025 4425
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4350 3900 5025 3900 5025 4425 4350 4425 4350 3900
4 0 0 50 -1 0 12 0.0000 4 105 420 4500 4125 event\001
4 0 0 50 -1 0 12 0.0000 4 180 315 4500 4350 loop\001
-6
6 4275 2550 5100 2850
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4275 2550 5100 2550 5100 2850 4275 2850 4275 2550
4 0 0 50 -1 0 12 0.0000 4 135 450 4425 2775 ctrl i/f\001
-6
6 6000 3900 7200 4425
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6000 3900 7200 3900 7200 4425 6000 4425 6000 3900
4 0 0 50 -1 0 12 0.0000 4 135 600 6075 4125 EAPOL\001
4 0 0 50 -1 0 12 0.0000 4 135 1065 6075 4350 state machine\001
-6
6 2775 3150 4050 3450
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2775 3150 4050 3150 4050 3450 2775 3450 2775 3150
4 0 0 50 -1 0 12 0.0000 4 180 990 2925 3375 configuration\001
-6
6 3450 1200 4575 1500
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3450 1200 4575 1200 4575 1500 3450 1500 3450 1200
4 0 0 50 -1 0 12 0.0000 4 180 870 3600 1425 hostapd_cli\001
-6
6 3525 7800 5775 8100
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3525 7800 5775 7800 5775 8100 3525 8100 3525 7800
4 0 0 50 -1 0 12 0.0000 4 135 2145 3600 8025 kernel network device driver\001
-6
6 4275 6000 5100 6300
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4275 6000 5100 6000 5100 6300 4275 6300 4275 6000
4 0 0 50 -1 0 12 0.0000 4 135 630 4350 6225 driver i/f\001
-6
6 8175 4725 9225 5025
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 4725 9225 4725 9225 5025 8175 5025 8175 4725
4 0 0 50 -1 0 12 0.0000 4 135 735 8250 4950 EAP-TLS\001
-6
6 9300 4725 10350 5025
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 4725 10350 4725 10350 5025 9300 5025 9300 4725
4 0 0 50 -1 0 12 0.0000 4 135 810 9375 4950 EAP-MD5\001
-6
6 8175 5100 9225 5400
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 5100 9225 5100 9225 5400 8175 5400 8175 5100
4 0 0 50 -1 0 12 0.0000 4 135 885 8250 5325 EAP-PEAP\001
-6
6 9300 5100 10350 5400
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 5100 10350 5100 10350 5400 9300 5400 9300 5100
4 0 0 50 -1 0 12 0.0000 4 135 840 9375 5325 EAP-TTLS\001
-6
6 8175 5475 9225 5775
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 5475 9225 5475 9225 5775 8175 5775 8175 5475
4 0 0 50 -1 0 12 0.0000 4 135 780 8250 5700 EAP-GTC\001
-6
6 8175 5850 9225 6150
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 5850 9225 5850 9225 6150 8175 6150 8175 5850
4 0 0 50 -1 0 12 0.0000 4 135 750 8250 6075 EAP-SIM\001
-6
6 8175 6225 9225 6525
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 6225 9225 6225 9225 6525 8175 6525 8175 6225
4 0 0 50 -1 0 12 0.0000 4 135 765 8250 6450 EAP-PSK\001
-6
6 9300 5850 10350 6150
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 5850 10350 5850 10350 6150 9300 6150 9300 5850
4 0 0 50 -1 0 12 0.0000 4 135 825 9375 6075 EAP-AKA\001
-6
6 9300 5475 10350 5775
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 5475 10350 5475 10350 5775 9300 5775 9300 5475
4 0 0 50 -1 0 12 0.0000 4 135 795 9375 5700 EAP-PAX\001
-6
6 8175 6600 9675 6900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 6600 9675 6600 9675 6900 8175 6900 8175 6600
4 0 0 50 -1 0 12 0.0000 4 135 1365 8250 6825 EAP-MSCHAPv2\001
-6
6 8700 3450 9375 3750
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8700 3450 9375 3450 9375 3750 8700 3750 8700 3450
4 0 0 50 -1 0 12 0.0000 4 150 480 8775 3675 crypto\001
-6
6 9600 3450 10275 3750
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9600 3450 10275 3450 10275 3750 9600 3750 9600 3450
4 0 0 50 -1 0 12 0.0000 4 135 315 9750 3675 TLS\001
-6
6 6000 5775 7200 6300
6 6000 5775 7200 6300
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6000 5775 7200 5775 7200 6300 6000 6300 6000 5775
4 0 0 50 -1 0 12 0.0000 4 135 690 6075 6000 RADIUS\001
-6
4 0 0 50 -1 0 12 0.0000 4 90 480 6075 6225 server\001
-6
6 8100 2250 8925 2775
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8100 2250 8925 2250 8925 2775 8100 2775 8100 2250
4 0 0 50 -1 0 12 0.0000 4 135 690 8175 2475 RADIUS\001
4 0 0 50 -1 0 12 0.0000 4 135 420 8175 2700 client\001
-6
6 3150 5475 4425 5775
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3150 5475 4425 5475 4425 5775 3150 5775 3150 5475
4 0 0 50 -1 0 12 0.0000 4 135 990 3300 5700 driver events\001
-6
6 1950 5550 2625 6075
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
1950 5550 2625 5550 2625 6075 1950 6075 1950 5550
4 0 0 50 -1 0 12 0.0000 4 135 540 2025 5775 Station\001
4 0 0 50 -1 0 12 0.0000 4 135 375 2025 6000 table\001
-6
6 1875 4725 2925 5250
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
1875 4725 2925 4725 2925 5250 1875 5250 1875 4725
4 0 0 50 -1 0 12 0.0000 4 135 960 1950 4950 IEEE 802.11\001
4 0 0 50 -1 0 12 0.0000 4 135 555 1950 5175 MLME\001
-6
2 1 1 1 0 7 50 -1 -1 3.000 0 0 -1 0 0 2
1275 4200 1875 4200
2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
4500 2550 3900 1500
2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
4800 2550 5400 1500
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
2925 4200 4350 4200
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
5025 3900 6000 3000
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
5025 4200 6000 4200
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4650 6000 4650 4425
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
6600 4425 6600 4950
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
6600 3225 6600 3900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
7200 5250 8100 5250
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
9075 4425 9075 3750
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
7200 3000 8700 3525
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4650 3900 4650 2850
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
7200 4125 8700 3675
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
6000 4350 5025 6000
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
6000 3150 4875 6000
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
1500 2100 10800 2100 10800 7500 1500 7500 1500 2100
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
9900 4425 9900 3750
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 1
4350 3900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4350 3900 4050 3450
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4350 4425 4050 5475
2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
2250 7200 4200 7800
2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
7200 7200 5100 7800
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2775 6900 3675 6900 3675 7200 2775 7200 2775 6900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3750 6900 4650 6900 4650 7200 3750 7200 3750 6900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
2250 6900 2250 6600 7200 6600 7200 6900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
3225 6900 3225 6600
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4200 6900 4200 6600
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
5175 6900 5175 6600
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
6150 6900 6150 6600
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4650 6600 4650 6300
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
1800 6900 2700 6900 2700 7200 1800 7200 1800 6900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4725 6900 5625 6900 5625 7200 4725 7200 4725 6900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
5700 6900 6600 6900 6600 7200 5700 7200 5700 6900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6675 6900 7800 6900 7800 7200 6675 7200 6675 6900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8100 6975 10425 6975 10425 4425 8100 4425 8100 6975
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
6600 5475 6600 5775
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
5025 4425 6000 5775
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
4800 3900 5925 2550 8100 2550
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
7200 3900 8475 2775
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9450 2250 10425 2250 10425 2775 9450 2775 9450 2250
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
8925 2475 9450 2475
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
2325 5550 2325 5250
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
2925 4950 4350 4275
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
2850 4725 5775 2400 8100 2400
4 0 0 50 -1 0 12 0.0000 4 135 915 375 3975 EAPOL and\001
4 0 0 50 -1 0 12 0.0000 4 180 630 375 4200 pre-auth\001
4 0 0 50 -1 0 12 0.0000 4 180 810 375 4425 ethertypes\001
4 0 0 50 -1 0 12 0.0000 4 135 1050 375 4650 from/to kernel\001
4 0 0 50 -1 0 12 0.0000 4 135 1920 3675 1875 frontend control interface\001
4 0 0 50 -1 2 14 0.0000 4 195 720 1637 2371 hostapd\001
4 0 0 50 -1 0 12 0.0000 4 180 600 3825 7125 prism54\001
4 0 0 50 -1 0 12 0.0000 4 180 510 1875 7125 hostap\001
4 0 0 50 -1 0 12 0.0000 4 135 600 2850 7125 madwifi\001
4 0 0 50 -1 0 12 0.0000 4 135 270 4800 7125 bsd\001
4 0 0 50 -1 0 12 0.0000 4 105 300 6750 7125 test\001
4 0 0 50 -1 0 12 0.0000 4 135 420 5775 7125 wired\001
4 0 0 50 -1 0 12 0.0000 4 135 1050 8700 4650 EAP methods\001
4 0 0 50 -1 0 12 0.0000 4 135 690 9525 2475 RADIUS\001
4 0 0 50 -1 0 12 0.0000 4 180 825 9525 2700 accounting\001

66
doc/hostapd_ctrl_iface.doxygen Normal file
View file

@ -0,0 +1,66 @@
/**
\page hostapd_ctrl_iface_page hostapd control interface
hostapd implements a control interface that can be used by
external programs to control the operations of the hostapd
daemon and to get status information and event notifications. There is
a small C library, in a form of a single C file, wpa_ctrl.c, that
provides helper functions to facilitate the use of the control
interface. External programs can link this file into them and then use
the library functions documented in wpa_ctrl.h to interact with
%wpa_supplicant. This library can also be used with C++. hostapd_cli.c
is an example program using this library.
There are multiple mechanisms for inter-process communication. For
example, Linux version of hostapd is using UNIX domain sockets for the
control interface. The use of the functions defined in wpa_ctrl.h can
be used to hide the details of the used IPC from external programs.
\section using_ctrl_iface Using the control interface
External programs, e.g., a GUI or a configuration utility, that need to
communicate with hostapd should link in wpa_ctrl.c. This
allows them to use helper functions to open connection to the control
interface with wpa_ctrl_open() and to send commands with
wpa_ctrl_request().
hostapd uses the control interface for two types of communication:
commands and unsolicited event messages. Commands are a pair of
messages, a request from the external program and a response from
hostapd. These can be executed using wpa_ctrl_request().
Unsolicited event messages are sent by hostapd to the control
interface connection without specific request from the external program
for receiving each message. However, the external program needs to
attach to the control interface with wpa_ctrl_attach() to receive these
unsolicited messages.
If the control interface connection is used both for commands and
unsolicited event messages, there is potential for receiving an
unsolicited message between the command request and response.
wpa_ctrl_request() caller will need to supply a callback, msg_cb,
for processing these messages. Often it is easier to open two
control interface connections by calling wpa_ctrl_open() twice and
then use one of the connections for commands and the other one for
unsolicited messages. This way command request/response pairs will
not be broken by unsolicited messages. wpa_cli is an example of how
to use only one connection for both purposes and wpa_gui demonstrates
how to use two separate connections.
Once the control interface connection is not needed anymore, it should
be closed by calling wpa_ctrl_close(). If the connection was used for
unsolicited event messages, it should be first detached by calling
wpa_ctrl_detach().
\section ctrl_iface_cmds Control interface commands
Following commands can be used with wpa_ctrl_request():
\subsection ctrl_iface_PING PING
This command can be used to test whether hostapd is replying
to the control interface commands. The expected reply is \c PONG if the
connection is open and hostapd is processing commands.
*/

95
doc/mainpage.doxygen Normal file
View file

@ -0,0 +1,95 @@
/**
\mainpage Developers' documentation for wpa_supplicant and hostapd
The goal of this documentation and comments in the source code is to
give enough information for other developers to understand how
%wpa_supplicant and hostapd have been implemented, how they can be
modified, how new drivers can be supported, and how the source code
can be ported to other operating systems. If any information is
missing, feel free to contact Jouni Malinen <j@w1.fi> for more
information. Contributions as patch files are also very welcome at the
same address. Please note that this software is licensed under dual
license, GPLv2 or BSD at user's choice. All contributions to
%wpa_supplicant and hostapd are expected to use compatible licensing
terms.
The source code and read-only access to the combined %wpa_supplicant
and hostapd Git repository is available from the project home page at
http://w1.fi/wpa_supplicant/. This developers' documentation is also
available as a PDF file from
http://w1.fi/wpa_supplicant/wpa_supplicant-devel.pdf .
\section wpa_supplicant wpa_supplicant
%wpa_supplicant is a WPA Supplicant for Linux, BSD and Windows with
support for WPA and WPA2 (IEEE 802.11i / RSN). Supplicant is the IEEE
802.1X/WPA component that is used in the client stations. It
implements key negotiation with a WPA Authenticator and it can optionally
control roaming and IEEE 802.11 authentication/association of the wlan
driver.
The design goal for %wpa_supplicant was to use hardware, driver, and
OS independent, portable C code for all WPA functionality. The source
code is divided into separate C files as shown on the \ref
code_structure "code structure page". All hardware/driver specific
functionality is in separate files that implement a \ref
driver_wrapper "well-defined driver API". Information about porting
to different target boards and operating systems is available on
the \ref porting "porting page".
EAPOL (IEEE 802.1X) state machines are implemented as a separate
module that interacts with \ref eap_module "EAP peer implementation".
In addition to programs aimed at normal production use,
%wpa_supplicant source tree includes number of \ref testing_tools
"testing and development tools" that make it easier to test the
programs without having to setup a full test setup with wireless
cards. These tools can also be used to implement automatic test
suites.
%wpa_supplicant implements a
\ref ctrl_iface_page "control interface" that can be used by
external programs to control the operations of the %wpa_supplicant
daemon and to get status information and event notifications. There is
a small C library that provides helper functions to facilitate the use of the
control interface. This library can also be used with C++.
\image html wpa_supplicant.png "wpa_supplicant modules"
\image latex wpa_supplicant.eps "wpa_supplicant modules" width=15cm
\section hostapd hostapd
hostapd includes IEEE 802.11 access point management (authentication /
association), IEEE 802.1X/WPA/WPA2 Authenticator, EAP server, and
RADIUS authentication server functionality. It can be build with
various configuration option, e.g., a standalone AP management
solution or a RADIUS authentication server with support for number of
EAP methods.
The design goal for hostapd was to use hardware, driver, and
OS independent, portable C code for all WPA functionality. The source
code is divided into separate C files as shown on the \ref
code_structure "code structure page". All hardware/driver specific
functionality is in separate files that implement a \ref
driver_wrapper "well-defined driver API". Information about porting
to different target boards and operating systems is available on
the \ref porting "porting page".
EAPOL (IEEE 802.1X) state machines are implemented as a separate
module that interacts with \ref eap_module "EAP server implementation".
Similarly, RADIUS authentication server is in its own separate module.
Both IEEE 802.1X and RADIUS authentication server can use EAP server
functionality.
hostapd implements a \ref hostapd_ctrl_iface_page "control interface"
that can be used by external programs to control the operations of the
hostapdt daemon and to get status information and event notifications.
There is a small C library that provides helper functions to facilitate
the use of the control interface. This library can also be used with
C++.
\image html hostapd.png "hostapd modules"
\image latex hostapd.eps "hostapd modules" width=15cm
*/

208
doc/porting.doxygen Normal file
View file

@ -0,0 +1,208 @@
/**
\page porting Porting to different target boards and operating systems
%wpa_supplicant was designed to be easily portable to different
hardware (board, CPU) and software (OS, drivers) targets. It is
already used with number of operating systems and numerous wireless
card models and drivers. The main %wpa_supplicant repository includes
support for Linux, FreeBSD, and Windows. In addition, the code has been
ported to number of other operating systems like VxWorks, PalmOS,
Windows CE, and Windows Mobile. On the hardware
side, %wpa_supplicant is used on various systems: desktops, laptops,
PDAs, and embedded devices with CPUs including x86, PowerPC,
arm/xscale, and MIPS. Both big and little endian configurations are
supported.
\section ansi_c_extra Extra functions on top of ANSI C
%wpa_supplicant is mostly using ANSI C functions that are available on
most targets. However, couple of additional functions that are common
on modern UNIX systems are used. Number of these are listed with
prototypes in common.h (the \verbatim #ifdef CONFIG_ANSI_C_EXTRA \endverbatim
block). These functions may need to be implemented or at least defined
as macros to native functions in the target OS or C library.
Many of the common ANSI C functions are used through a wrapper
definitions in os.h to allow these to be replaced easily with a
platform specific version in case standard C libraries are not
available. In addition, os.h defines couple of common platform
specific functions that are implemented in os_unix.c for UNIX like
targets and in os_win32.c for Win32 API. If the target platform does
not support either of these examples, a new os_*.c file may need to be
added.
Unless OS_NO_C_LIB_DEFINES is defined, the standard ANSI C and POSIX
functions are used by defining the os_*() wrappers to use them
directly in order to avoid extra cost in size and speed. If the target
platform needs different versions of the functions, os.h can be
modified to define the suitable macros or alternatively,
OS_NO_C_LIB_DEFINES may be defined for the build and the wrapper
functions can then be implemented in a new os_*.c wrapper file.
common.h defines number of helper macros for handling integers of
different size and byte order. Suitable version of these definitions
may need to be added for the target platform.
\section configuration_backend Configuration backend
%wpa_supplicant implements a configuration interface that allows the
backend to be easily replaced in order to read configuration data from
a suitable source depending on the target platform. config.c
implements the generic code that can be shared with all configuration
backends. Each backend is implemented in its own config_*.c file.
The included config_file.c backend uses a text file for configuration
and config_winreg.c uses Windows registry. These files can be used as
an example for a new configuration backend if the target platform uses
different mechanism for configuration parameters. In addition,
config_none.c can be used as an empty starting point for building a
new configuration backend.
\section driver_iface_porting Driver interface
Unless the target OS and driver is already supported, most porting
projects have to implement 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. \ref
driver_wrapper "Driver wrapper implementation" describes the details
of the driver interface and discusses the tasks involved in porting
this part of %wpa_supplicant.
\section l2_packet_porting l2_packet (link layer access)
%wpa_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.
If the target operating system supports a generic mechanism for link
layer access, that is likely the best mechanism for providing the
needed functionality for %wpa_supplicant. Linux packet socket is an
example of such a generic mechanism. If this is not available, a
separate interface may need to be implemented to the network stack or
driver. This is usually an intermediate or protocol driver that is
operating between the device driver and the OS network stack. If such
a mechanism is not feasible, the interface can also be implemented
directly in the device driver.
The main %wpa_supplicant repository includes l2_packet implementations
for Linux using packet sockets (l2_packet_linux.c), more portable
version using libpcap/libdnet libraries (l2_packet_pcap.c; this
supports WinPcap, too), and FreeBSD specific version of libpcap
interface (l2_packet_freebsd.c).
If the target operating system is supported by libpcap (receiving) and
libdnet (sending), l2_packet_pcap.c can likely be used with minimal or
no changes. If this is not a case or a proprietary interface for link
layer is required, a new l2_packet module may need to be
added. Alternatively, struct wpa_driver_ops::send_eapol() handler can
be used to override the l2_packet library if the link layer access is
integrated with the driver interface implementation.
\section eloop_porting Event loop
%wpa_supplicant uses a single process/thread model and an event loop
to provide callbacks on events (registered timeout, received packet,
signal). eloop.h defines the event loop interface. eloop.c is an
implementation of such an event loop using select() and sockets. This
is suitable for most UNIX/POSIX systems. When porting to other
operating systems, it may be necessary to replace that implementation
with OS specific mechanisms that provide similar functionality.
\section ctrl_iface_porting Control interface
%wpa_supplicant uses a \ref ctrl_iface_page "control interface"
to allow external processed
to get status information and to control the operations. Currently,
this is implemented with socket based communication; both UNIX domain
sockets and UDP sockets are supported. If the target OS does not
support sockets, this interface will likely need to be modified to use
another mechanism like message queues. The control interface is
optional component, so it is also possible to run %wpa_supplicant
without porting this part.
The %wpa_supplicant side of the control interface is implemented in
ctrl_iface.c. Matching client side is implemented as a control
interface library in wpa_ctrl.c.
\section entry_point Program entry point
%wpa_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 convention. This
function is responsible on initializing %wpa_supplicant.
main.c includes an entry point for UNIX-like operating system, i.e.,
main() function that uses command line arguments for setting
parameters for %wpa_supplicant. When porting to other operating
systems, similar OS-specific entry point implementation is needed. It
can be implemented in a new file that is then linked with
%wpa_supplicant instead of main.o. main.c is also a good example on
how the initialization process should be done.
The supplicant initialization functions are defined in
wpa_supplicant_i.h. In most cases, the entry point function should
start by fetching configuration parameters. After this, a global
%wpa_supplicant context is initialized with a call to
wpa_supplicant_init(). After this, existing network interfaces can be
added with wpa_supplicant_add_iface(). wpa_supplicant_run() is then
used to start the main event loop. Once this returns at program
termination time, wpa_supplicant_deinit() is used to release global
context data.
wpa_supplicant_add_iface() and wpa_supplicant_remove_iface() can be
used dynamically to add and remove interfaces based on when
%wpa_supplicant processing is needed for them. This can be done, e.g.,
when hotplug network adapters are being inserted and ejected. It is
also possible to do this when a network interface is being
enabled/disabled if it is desirable that %wpa_supplicant processing
for the interface is fully enabled/disabled at the same time.
\section simple_build Simple build example
One way to start a porting project is to begin with a very simple
build of %wpa_supplicant with WPA-PSK support and once that is
building correctly, start adding features.
Following command can be used to build very simple version of
%wpa_supplicant:
\verbatim
cc -o wpa_supplicant config.c eloop.c common.c md5.c rc4.c sha1.c \
config_none.c l2_packet_none.c tls_none.c wpa.c preauth.c \
aes_wrap.c wpa_supplicant.c events.c main_none.c drivers.c
\endverbatim
The end result is not really very useful since it uses empty functions
for configuration parsing and layer 2 packet access and does not
include a driver interface. However, this is a good starting point
since the build is complete in the sense that all functions are
present and this is easy to configure to a build system by just
including the listed C files.
Once this version can be build successfully, the end result can be
made functional by adding a proper program entry point (main*.c),
driver interface (driver_*.c and matching CONFIG_DRIVER_* define for
registration in drivers.c), configuration parser/writer (config_*.c),
and layer 2 packet access implementation (l2_packet_*.c). After these
components have been added, the end result should be a working
WPA/WPA2-PSK enabled supplicant.
After the basic functionality has been verified to work, more features
can be added by linking in more files and defining C pre-processor
defines. Currently, the best source of information for what options
are available and which files needs to be included is in the Makefile
used for building the supplicant with make. Similar configuration will
be needed for build systems that either use different type of make
tool or a GUI-based project configuration.
*/

295
doc/testing_tools.doxygen Normal file
View file

@ -0,0 +1,295 @@
/**
\page testing_tools Testing and development tools
[ \ref eapol_test "eapol_test" |
\ref preauth_test "preauth_test" |
\ref driver_test "driver_test" |
\ref unit_tests "Unit tests" ]
%wpa_supplicant source tree includes number of testing and development
tools that make it easier to test the programs without having to setup
a full test setup with wireless cards. In addition, these tools can be
used to implement automatic tests suites.
\section eapol_test eapol_test - EAP peer and RADIUS client testing
eapol_test is a program that links together the same EAP peer
implementation that %wpa_supplicant is using and the RADIUS
authentication client code from hostapd. In addition, it has minimal
glue code to combine these two components in similar ways to IEEE
802.1X/EAPOL Authenticator state machines. In other words, it
integrates IEEE 802.1X Authenticator (normally, an access point) and
IEEE 802.1X Supplicant (normally, a wireless client) together to
generate a single program that can be used to test EAP methods without
having to setup an access point and a wireless client.
The main uses for eapol_test are in interoperability testing of EAP
methods against RADIUS servers and in development testing for new EAP
methods. It can be easily used to automate EAP testing for
interoperability and regression since the program can be run from
shell scripts without require additional test components apart from a
RADIUS server. For example, the automated EAP tests described in
eap_testing.txt are implemented with eapol_test. Similarly, eapol_test
could be used to implement an automated regression test suite for a
RADIUS authentication server.
eapol_test uses the same build time configuration file, .config, as
%wpa_supplicant. This file is used to select which EAP methods are
included in eapol_test. This program is not built with the default
Makefile target, so a separate make command needs to be used to
compile the tool:
\verbatim
make eapol_test
\endverbatim
The resulting eapol_test binary has following command like options:
\verbatim
usage:
eapol_test [-nWS] -c<conf> [-a<AS IP>] [-p<AS port>] [-s<AS secret>] \
[-r<count>] [-t<timeout>] [-C<Connect-Info>] \
[-M<client MAC address>]
eapol_test scard
eapol_test sim <PIN> <num triplets> [debug]
options:
-c<conf> = configuration file
-a<AS IP> = IP address of the authentication server, default 127.0.0.1
-p<AS port> = UDP port of the authentication server, default 1812
-s<AS secret> = shared secret with the authentication server, default 'radius'
-r<count> = number of re-authentications
-W = wait for a control interface monitor before starting
-S = save configuration after authentiation
-n = no MPPE keys expected
-t<timeout> = sets timeout in seconds (default: 30 s)
-C<Connect-Info> = RADIUS Connect-Info (default: CONNECT 11Mbps 802.11b)
-M<client MAC address> = Set own MAC address (Calling-Station-Id,
default: 02:00:00:00:00:01)
\endverbatim
As an example,
\verbatim
eapol_test -ctest.conf -a127.0.0.1 -p1812 -ssecret -r1
\endverbatim
tries to complete EAP authentication based on the network
configuration from test.conf against the RADIUS server running on the
local host. A re-authentication is triggered to test fast
re-authentication. The configuration file uses the same format for
network blocks as %wpa_supplicant.
\section preauth_test preauth_test - WPA2 pre-authentication and EAP peer testing
preauth_test is similar to eapol_test in the sense that in combines
EAP peer implementation with something else, in this case, with WPA2
pre-authentication. This tool can be used to test pre-authentication
based on the code that %wpa_supplicant is using. As such, it tests
both the %wpa_supplicant implementation and the functionality of an
access point.
preauth_test is built with:
\verbatim
make preauth_test
\endverbatim
and it uses following command line arguments:
\verbatim
usage: preauth_test <conf> <target MAC address> <ifname>
\endverbatim
For example,
\verbatim
preauth_test test.conf 02:11:22:33:44:55 eth0
\endverbatim
would use network configuration from test.conf to try to complete
pre-authentication with AP using BSSID 02:11:22:33:44:55. The
pre-authentication packets would be sent using the eth0 interface.
\section driver_test driver_test - driver interface for testing wpa_supplicant
%wpa_supplicant was designed to support number of different ways to
communicate with a network device driver. This design uses \ref
driver_wrapper "driver interface API" and number of driver interface
implementations. One of these is driver_test.c, i.e., a test driver
interface that is actually not using any drivers. Instead, it provides
a mechanism for running %wpa_supplicant without having to have a
device driver or wireless LAN hardware for that matter.
driver_test can be used to talk directly with hostapd's driver_test
component to create a test setup where one or more clients and access
points can be tested within one test host and without having to have
multiple wireless cards. This makes it easier to test the core code in
%wpa_supplicant, and hostapd for that matter. Since driver_test uses
the same driver API than any other driver interface implementation,
the core code of %wpa_supplicant and hostapd can be tested with the
same coverage as one would get when using real wireless cards. The
only area that is not tested is the driver interface implementation
(driver_*.c).
Having the possibility to use simulated network components makes it
much easier to do development testing while adding new features and to
reproduce reported bugs. As such, it is often easiest to just do most
of the development and bug fixing without using real hardware. Once
the driver_test setup has been used to implement a new feature or fix
a bug, the end result can be verified with wireless LAN cards. In many
cases, this may even be unnecessary, depending on what area the
feature/bug is relating to. Of course, changes to driver interfaces
will still require use of real hardware.
Since multiple components can be run within a single host, testing of
complex network configuration, e.g., large number of clients
association with an access point, becomes quite easy. All the tests
can also be automated without having to resort to complex test setup
using remote access to multiple computers.
driver_test can be included in the %wpa_supplicant build in the same
way as any other driver interface, i.e., by adding the following line
into .config:
\verbatim
CONFIG_DRIVER_TEST=y
\endverbatim
When running %wpa_supplicant, the test interface is selected by using
\a -Dtest command line argument. The interface name (\a -i argument)
can be selected arbitrarily, i.e., it does not need to match with any
existing network interface. The interface name is used to generate a
MAC address, so when using multiple clients, each should use a
different interface, e.g., \a sta1, \a sta2, and so on.
%wpa_supplicant and hostapd are configured in the same way as they
would be for normal use. Following example shows a simple test setup
for WPA-PSK.
hostapd is configured with following psk-test.conf configuration file:
\verbatim
driver=test
interface=ap1
logger_stdout=-1
logger_stdout_level=0
debug=2
dump_file=/tmp/hostapd.dump
test_socket=/tmp/Test/ap1
ssid=jkm-test-psk
wpa=1
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP
wpa_passphrase=12345678
\endverbatim
and started with following command:
\verbatim
hostapd psk-test.conf
\endverbatim
%wpa_supplicant uses following configuration file:
\verbatim
driver_param=test_socket=/tmp/Test/ap1
network={
ssid="jkm-test-psk"
key_mgmt=WPA-PSK
psk="12345678"
}
\endverbatim
%wpa_supplicant can then be started with following command:
\verbatim
wpa_supplicant -Dtest -cpsk-test.conf -ista1 -ddK
\endverbatim
If run without debug information, i.e., with
\verbatim
wpa_supplicant -Dtest -cpsk-test.conf -ista1
\endverbatim
%wpa_supplicant completes authentication and prints following events:
\verbatim
Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
Associated with 02:b8:a6:62:08:5a
WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
\endverbatim
If test setup is using multiple clients, it is possible to run
multiple %wpa_supplicant processes. Alternatively, the support for
multiple interfaces can be used with just one process to save some
resources on single-CPU systems. For example, following command runs
two clients:
\verbatim
./wpa_supplicant -Dtest -cpsk-test.conf -ista1 \
-N -Dtest -cpsk-test.conf -ista2
\endverbatim
This shows following event log:
\verbatim
Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
Associated with 02:b8:a6:62:08:5a
WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
Associated with 02:b8:a6:62:08:5a
WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
\endverbatim
hostapd shows this with following events:
\verbatim
ap1: STA 02:b5:64:63:30:63 IEEE 802.11: associated
ap1: STA 02:b5:64:63:30:63 WPA: pairwise key handshake completed (WPA)
ap1: STA 02:b5:64:63:30:63 WPA: group key handshake completed (WPA)
ap1: STA 02:2a:c4:18:5b:f3 IEEE 802.11: associated
ap1: STA 02:2a:c4:18:5b:f3 WPA: pairwise key handshake completed (WPA)
ap1: STA 02:2a:c4:18:5b:f3 WPA: group key handshake completed (WPA)
\endverbatim
By default, driver_param is simulating a driver that uses the WPA/RSN
IE generated by %wpa_supplicant. Driver-generated IE and AssocInfo
events can be tested by adding \a use_associnfo=1 to the \a driver_param
line in the configuration file. For example:
\verbatim
driver_param=test_socket=/tmp/Test/ap1 use_associnfo=1
\endverbatim
\section unit_tests Unit tests
Number of the components (.c files) used in %wpa_supplicant define
their own unit tests for automated validation of the basic
functionality. Most of the tests for cryptographic algorithms are
using standard test vectors to validate functionality. These tests can
be useful especially when verifying port to a new CPU target.
In most cases, these tests are implemented in the end of the same file
with functions that are normally commented out, but ca be included by
defining a pre-processor variable when building the file separately.
The details of the needed build options are included in the Makefile
(test-* targets). All automated unit tests can be run with
\verbatim
make tests
\endverbatim
This make target builds and runs each test and terminates with zero
exit code if all tests were completed successfully.
*/

247
doc/wpa_supplicant.fig Normal file
View file

@ -0,0 +1,247 @@
#FIG 3.2
Landscape
Center
Inches
Letter
100.00
Single
-2
1200 2
6 1875 4050 2925 4350
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
1875 4050 2925 4050 2925 4350 1875 4350 1875 4050
4 0 0 50 -1 0 12 0.0000 4 180 735 2025 4275 l2_packet\001
-6
6 3450 1200 4275 1500
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3450 1200 4275 1200 4275 1500 3450 1500 3450 1200
4 0 0 50 -1 0 12 0.0000 4 180 585 3600 1425 wpa_cli\001
-6
6 4725 1200 5925 1500
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4725 1200 5925 1200 5925 1500 4725 1500 4725 1200
4 0 0 50 -1 0 12 0.0000 4 135 1005 4800 1425 GUI frontend\001
-6
6 6000 2700 7200 3225
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6000 2700 7200 2700 7200 3225 6000 3225 6000 2700
4 0 0 50 -1 0 12 0.0000 4 135 975 6075 2925 WPA/WPA2\001
4 0 0 50 -1 0 12 0.0000 4 135 1065 6075 3150 state machine\001
-6
6 6000 4950 7200 5475
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6000 4950 7200 4950 7200 5475 6000 5475 6000 4950
4 0 0 50 -1 0 12 0.0000 4 135 360 6075 5175 EAP\001
4 0 0 50 -1 0 12 0.0000 4 135 1065 6075 5400 state machine\001
-6
6 8700 3000 9375 3300
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8700 3000 9375 3000 9375 3300 8700 3300 8700 3000
4 0 0 50 -1 0 12 0.0000 4 150 480 8775 3225 crypto\001
-6
6 4350 3900 5025 4425
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4350 3900 5025 3900 5025 4425 4350 4425 4350 3900
4 0 0 50 -1 0 12 0.0000 4 105 420 4500 4125 event\001
4 0 0 50 -1 0 12 0.0000 4 180 315 4500 4350 loop\001
-6
6 4275 2550 5100 2850
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4275 2550 5100 2550 5100 2850 4275 2850 4275 2550
4 0 0 50 -1 0 12 0.0000 4 135 450 4425 2775 ctrl i/f\001
-6
6 6000 3900 7200 4425
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6000 3900 7200 3900 7200 4425 6000 4425 6000 3900
4 0 0 50 -1 0 12 0.0000 4 135 600 6075 4125 EAPOL\001
4 0 0 50 -1 0 12 0.0000 4 135 1065 6075 4350 state machine\001
-6
6 1800 6000 7800 8100
6 1800 6000 7800 7200
6 1800 6900 2700 7200
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
1800 6900 2700 6900 2700 7200 1800 7200 1800 6900
4 0 0 50 -1 0 12 0.0000 4 105 375 1875 7125 wext\001
-6
6 4725 6900 5625 7200
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4725 6900 5625 6900 5625 7200 4725 7200 4725 6900
4 0 0 50 -1 0 12 0.0000 4 135 555 4800 7125 hermes\001
-6
6 6675 6900 7800 7200
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6675 6900 7800 6900 7800 7200 6675 7200 6675 6900
4 0 0 50 -1 0 12 0.0000 4 180 930 6750 7125 ndiswrapper\001
-6
6 5700 6900 6600 7200
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
5700 6900 6600 6900 6600 7200 5700 7200 5700 6900
4 0 0 50 -1 0 12 0.0000 4 135 420 5775 7125 atmel\001
-6
6 4275 6000 5100 6300
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4275 6000 5100 6000 5100 6300 4275 6300 4275 6000
4 0 0 50 -1 0 12 0.0000 4 135 630 4350 6225 driver i/f\001
-6
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2775 6900 3675 6900 3675 7200 2775 7200 2775 6900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3750 6900 4650 6900 4650 7200 3750 7200 3750 6900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
2250 6900 2250 6600 7200 6600 7200 6900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
3225 6900 3225 6600
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4200 6900 4200 6600
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
5175 6900 5175 6600
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
6150 6900 6150 6600
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4650 6600 4650 6300
4 0 0 50 -1 0 12 0.0000 4 180 510 2850 7125 hostap\001
4 0 0 50 -1 0 12 0.0000 4 135 600 3825 7125 madwifi\001
-6
6 3525 7800 5775 8100
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3525 7800 5775 7800 5775 8100 3525 8100 3525 7800
4 0 0 50 -1 0 12 0.0000 4 135 2145 3600 8025 kernel network device driver\001
-6
2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
2250 7200 4200 7800
2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
7200 7200 5100 7800
-6
6 9600 3000 10275 3300
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9600 3000 10275 3000 10275 3300 9600 3300 9600 3000
4 0 0 50 -1 0 12 0.0000 4 135 315 9750 3225 TLS\001
-6
6 8100 4425 10425 7350
6 8175 4725 9225 5025
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 4725 9225 4725 9225 5025 8175 5025 8175 4725
4 0 0 50 -1 0 12 0.0000 4 135 735 8250 4950 EAP-TLS\001
-6
6 9300 4725 10350 5025
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 4725 10350 4725 10350 5025 9300 5025 9300 4725
4 0 0 50 -1 0 12 0.0000 4 135 810 9375 4950 EAP-MD5\001
-6
6 8175 5100 9225 5400
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 5100 9225 5100 9225 5400 8175 5400 8175 5100
4 0 0 50 -1 0 12 0.0000 4 135 885 8250 5325 EAP-PEAP\001
-6
6 9300 5100 10350 5400
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 5100 10350 5100 10350 5400 9300 5400 9300 5100
4 0 0 50 -1 0 12 0.0000 4 135 840 9375 5325 EAP-TTLS\001
-6
6 8175 5475 9225 5775
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 5475 9225 5475 9225 5775 8175 5775 8175 5475
4 0 0 50 -1 0 12 0.0000 4 135 780 8250 5700 EAP-GTC\001
-6
6 9300 5475 10350 5775
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 5475 10350 5475 10350 5775 9300 5775 9300 5475
4 0 0 50 -1 0 12 0.0000 4 135 765 9375 5700 EAP-OTP\001
-6
6 8175 5850 9225 6150
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 5850 9225 5850 9225 6150 8175 6150 8175 5850
4 0 0 50 -1 0 12 0.0000 4 135 750 8250 6075 EAP-SIM\001
-6
6 9300 6225 10350 6525
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 6225 10350 6225 10350 6525 9300 6525 9300 6225
4 0 0 50 -1 0 12 0.0000 4 135 465 9375 6450 LEAP\001
-6
6 8175 6225 9225 6525
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 6225 9225 6225 9225 6525 8175 6525 8175 6225
4 0 0 50 -1 0 12 0.0000 4 135 765 8250 6450 EAP-PSK\001
-6
6 9300 5850 10350 6150
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 5850 10350 5850 10350 6150 9300 6150 9300 5850
4 0 0 50 -1 0 12 0.0000 4 135 825 9375 6075 EAP-AKA\001
-6
6 8175 6975 9675 7275
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 6975 9675 6975 9675 7275 8175 7275 8175 6975
4 0 0 50 -1 0 12 0.0000 4 135 1365 8250 7200 EAP-MSCHAPv2\001
-6
6 9300 6600 10350 6900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
9300 6600 10350 6600 10350 6900 9300 6900 9300 6600
4 0 0 50 -1 0 12 0.0000 4 135 870 9375 6825 EAP-FAST\001
-6
6 8175 6600 9225 6900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8175 6600 9225 6600 9225 6900 8175 6900 8175 6600
4 0 0 50 -1 0 12 0.0000 4 135 795 8250 6825 EAP-PAX\001
-6
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
8100 7350 10425 7350 10425 4425 8100 4425 8100 7350
4 0 0 50 -1 0 12 0.0000 4 135 1050 8700 4650 EAP methods\001
-6
6 2775 5025 4050 5325
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2775 5025 4050 5025 4050 5325 2775 5325 2775 5025
4 0 0 50 -1 0 12 0.0000 4 135 990 2925 5250 driver events\001
-6
6 2775 3150 4050 3450
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2775 3150 4050 3150 4050 3450 2775 3450 2775 3150
4 0 0 50 -1 0 12 0.0000 4 180 990 2925 3375 configuration\001
-6
2 1 1 1 0 7 50 -1 -1 3.000 0 0 -1 0 0 2
1275 4200 1875 4200
2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
4500 2550 3900 1500
2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
4800 2550 5400 1500
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
2925 4200 4350 4200
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
5025 3900 6000 3000
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
5025 4200 6000 4200
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4650 6000 4650 4425
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
6600 4425 6600 4950
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
6600 3225 6600 3900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
7200 5250 8100 5250
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
9075 4425 9075 3300
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
7200 3000 8700 3150
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4650 3900 4650 2850
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
7200 4125 8700 3300
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
6000 4350 5025 6000
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
6000 3150 4875 6000
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
1500 2100 10800 2100 10800 7500 1500 7500 1500 2100
2 1 0 1 2 7 50 -1 -1 0.000 0 0 -1 0 0 2
9900 4425 9900 3300
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 1
4350 3900
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4350 3900 4050 3450
2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
4350 4425 4050 5025
4 0 0 50 -1 0 12 0.0000 4 135 915 375 3975 EAPOL and\001
4 0 0 50 -1 0 12 0.0000 4 180 630 375 4200 pre-auth\001
4 0 0 50 -1 0 12 0.0000 4 180 810 375 4425 ethertypes\001
4 0 0 50 -1 0 12 0.0000 4 135 1050 375 4650 from/to kernel\001
4 0 0 50 -1 0 12 0.0000 4 135 1920 3675 1875 frontend control interface\001
4 0 0 50 -1 2 14 0.0000 4 210 1440 1637 2371 wpa_supplicant\001