jeltz/hostap
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

doc: Disable Doxygen autolink support

Browse source 
The way autolink support is implementing in Doxygen is a bit
inconvenient with wpa_supplicant being recognized as something that
would always be linked to struct wpa_supplicant. In addition, number of
links were not really noticed automatically. To get this working more
robustly and without having to use the %wpa_supplicant workaround (which
had its own issues, e.g., with titles), disable autolinking and use
explicit \ref commands instead.

This is also updating some of the obsolete notes to point to correct
file names, etc. changes in the source code tree.

Signed-off-by: Jouni Malinen <j@w1.fi>
This commit is contained in:
Jouni Malinen 2015-01-03 15:44:35 +02:00
parent bbd89bfca0
commit 5eb513c3ba
13 changed files with 411 additions and 408 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

183
doc/code_structure.doxygen
View file

@ -13,7 +13,7 @@
\ref win_port "Windows port" |
\ref test_programs "Test programs" ]
%wpa_supplicant implementation is divided into number of independent
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
@ -21,82 +21,77 @@ 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 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
\ref driver_wrapper "Driver interface API" is defined in \ref driver.h and
all hardware/driver dependent functionality is implemented in
driver_*.c.
\section _wpa_supplicant_core wpa_supplicant core functionality
wpa_supplicant.c
\ref wpa_supplicant.c
Program initialization, main control loop
main.c
\ref wpa_supplicant/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
\ref events.c
Driver event processing; \ref wpa_supplicant_event() and related functions
wpa_supplicant_i.h
Internal definitions for %wpa_supplicant core; should not be
\ref 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
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
\ref eloop.c and \ref eloop.h
Event loop (select() loop with registerable timeouts, socket read
callbacks, and signal callbacks)
common.c and common.h
\ref common.c and \ref common.h
Common helper functions
defs.h
\ref defs.h
Definitions shared by multiple files
l2_packet.h, l2_packet_linux.c, and l2_packet_pcap.c
\ref l2_packet.h, \ref l2_packet_linux.c, and \ref 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
l2_packet implementation is included. \ref l2_packet_linux.c uses Linux
packet sockets and \ref l2_packet_pcap.c has a more portable version using
libpcap and libdnet.
pcsc_funcs.c and pcsc_funcs.h
\ref pcsc_funcs.c and \ref pcsc_funcs.h
Wrapper for PC/SC lite SIM and smart card readers
priv_netlink.h
\ref 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
\ref 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
\ref md5.c and \ref 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
\ref rc4.c and \ref rc4.h
RC4 (broadcast/default key encryption)
sha1.c and sha1.h
\ref sha1.c and \ref 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)
@ -104,10 +99,10 @@ sha1.c and sha1.h
T-PRF (for EAP-FAST)
TLS-PRF (RFC 2246)
sha256.c and sha256.h
\ref sha256.c and \ref sha256.h
SHA-256 (replaced with a crypto library if TLS support is included)
aes_wrap.c, aes_wrap.h, aes.c
\ref aes-wrap.c, \ref aes_wrap.h, \ref 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),
@ -116,207 +111,205 @@ aes_wrap.c, aes_wrap.h, aes.c
AES-128 EAX mode encryption/decryption,
AES-128 CBC
crypto.h
\ref crypto.h
Definition of crypto library wrapper
crypto_openssl.c
\ref crypto_openssl.c
Wrapper functions for libcrypto (OpenSSL)
crypto_internal.c
\ref crypto_internal.c
Wrapper functions for internal crypto implementation
crypto_gnutls.c
\ref crypto_gnutls.c
Wrapper functions for libgcrypt (used by GnuTLS)
ms_funcs.c and ms_funcs.h
\ref ms_funcs.c and \ref ms_funcs.h
Helper functions for MSCHAPV2 and LEAP
tls.h
\ref tls.h
Definition of TLS library wrapper
tls_none.c
\ref tls_none.c
Dummy implementation of TLS library wrapper for cases where TLS
functionality is not included.
tls_openssl.c
\ref tls_openssl.c
TLS library wrapper for openssl
tls_internal.c
\ref tls_internal.c
TLS library for internal TLS implementation
tls_gnutls.c
\ref tls_gnutls.c
TLS library wrapper for GnuTLS
\section tls_func TLS library
asn1.c and asn1.h
\ref asn1.c and \ref asn1.h
ASN.1 DER parsing
bignum.c and bignum.h
\ref bignum.c and \ref bignum.h
Big number math
rsa.c and rsa.h
\ref rsa.c and \ref rsa.h
RSA
x509v3.c and x509v3.h
\ref x509v3.c and \ref x509v3.h
X.509v3 certificate parsing and processing
tlsv1_client.c, tlsv1_client.h
\ref tlsv1_client.c, \ref tlsv1_client.h
TLSv1 client (RFC 2246)
tlsv1_client_i.h
\ref tlsv1_client_i.h
Internal structures for TLSv1 client
tlsv1_client_read.c
\ref tlsv1_client_read.c
TLSv1 client: read handshake messages
tlsv1_client_write.c
\ref tlsv1_client_write.c
TLSv1 client: write handshake messages
tlsv1_common.c and tlsv1_common.h
\ref tlsv1_common.c and \ref tlsv1_common.h
Common TLSv1 routines and definitions
tlsv1_cred.c and tlsv1_cred.h
\ref tlsv1_cred.c and \ref tlsv1_cred.h
TLSv1 credentials
tlsv1_record.c and tlsv1_record.h
\ref tlsv1_record.c and \ref tlsv1_record.h
TLSv1 record protocol
\section configuration Configuration
config_ssid.h
\ref config_ssid.h
Definition of per network configuration items
config.h
Definition of the %wpa_supplicant configuration
\ref config.h
Definition of the wpa_supplicant configuration
config.c
\ref config.c
Configuration parser and common functions
config_file.c
\ref wpa_supplicant/config_file.c
Configuration backend for text files (e.g., wpa_supplicant.conf)
config_winreg.c
\ref config_winreg.c
Configuration backend for Windows registry
\section ctrl_iface Control interface
%wpa_supplicant has a \ref ctrl_iface_page "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.
are included in the wpa_supplicant distribution.
ctrl_iface.c and ctrl_iface.h
%wpa_supplicant-side of the control interface
\ref wpa_supplicant/ctrl_iface.c and \ref wpa_supplicant/ctrl_iface.h
wpa_supplicant-side of the control interface
ctrl_iface_unix.c
\ref ctrl_iface_unix.c
UNIX domain sockets -based control interface backend
ctrl_iface_udp.c
\ref ctrl_iface_udp.c
UDP sockets -based control interface backend
ctrl_iface_named_pipe.c
\ref ctrl_iface_named_pipe.c
Windows named pipes -based control interface backend
wpa_ctrl.c and wpa_ctrl.h
\ref wpa_ctrl.c and \ref wpa_ctrl.h
Library functions for external programs to provide access to the
%wpa_supplicant control interface
wpa_supplicant control interface
wpa_cli.c
Example program for using %wpa_supplicant control interface
\ref wpa_cli.c
Example program for using wpa_supplicant control interface
\section wpa_code WPA supplicant
wpa.c and wpa.h
\ref wpa.c and \ref wpa.h
WPA state machine and 4-Way/Group Key Handshake processing
preauth.c and preauth.h
\ref preauth.c and \ref preauth.h
PMKSA caching and pre-authentication (RSN/WPA2)
wpa_i.h
\ref wpa_i.h
Internal definitions for WPA code; not to be included to other modules.
\section eap_peer EAP peer
\ref eap_peer_module "EAP peer implementation" is a separate module that
can be used by other programs than just %wpa_supplicant.
can be used by other programs than just wpa_supplicant.
eap.c and eap.h
\ref eap.c and \ref eap.h
EAP state machine and method interface
eap_defs.h
\ref eap_defs.h
Common EAP definitions
eap_i.h
\ref 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
\ref eap_sim_common.c and \ref eap_sim_common.h
Common code for EAP-SIM and EAP-AKA
eap_tls_common.c and eap_tls_common.h
\ref eap_tls_common.c and \ref 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
\ref eap_ttls.c and \ref eap_ttls.h
EAP-TTLS
eap_pax.c, eap_pax_common.h, eap_pax_common.c
\ref eap_pax.c, \ref eap_pax_common.h, \ref eap_pax_common.c
EAP-PAX
eap_psk.c, eap_psk_common.h, eap_psk_common.c
\ref eap_psk.c, \ref eap_psk_common.h, \ref 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
\ref eap_sake.c, \ref eap_sake_common.h, \ref eap_sake_common.c
EAP-SAKE
eap_gpsk.c, eap_gpsk_common.h, eap_gpsk_common.c
\ref eap_gpsk.c, \ref eap_gpsk_common.h, \ref 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
\ref eap_aka.c, \ref eap_fast.c, \ref eap_gtc.c, \ref eap_leap.c,
\ref eap_md5.c, \ref eap_mschapv2.c, \ref eap_otp.c, \ref eap_peap.c,
\ref eap_sim.c, \ref eap_tls.c
Other EAP method implementations
\section eapol_supp EAPOL supplicant
eapol_supp_sm.c and eapol_supp_sm.h
\ref eapol_supp_sm.c and \ref eapol_supp_sm.h
EAPOL supplicant state machine and IEEE 802.1X processing
\section win_port Windows port
ndis_events.c
\ref ndis_events.c
Code for receiving NdisMIndicateStatus() events and delivering them to
%wpa_supplicant driver_ndis.c in more easier to use form
wpa_supplicant \ref driver_ndis.c in more easier to use form
win_if_list.c
\ref win_if_list.c
External program for listing current network interface
\section test_programs Test programs
radius_client.c and radius_client.h
\ref radius_client.c and \ref radius_client.h
RADIUS authentication client implementation for eapol_test
radius.c and radius.h
\ref radius.c and \ref radius.h
RADIUS message processing for eapol_test
eapol_test.c
\ref eapol_test.c
Standalone EAP testing tool with integrated RADIUS authentication
client
preauth_test.c
\ref preauth_test.c
Standalone RSN pre-authentication tool
wpa_passphrase.c
\ref wpa_passphrase.c
WPA ASCII passphrase to PSK conversion
*/

74
doc/ctrl_iface.doxygen
View file

@ -1,47 +1,47 @@
/**
\page ctrl_iface_page %wpa_supplicant control interface
\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
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
a small C library, in a form of a single C file, \ref 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
the library functions documented in \ref wpa_ctrl.h to interact with
wpa_supplicant. This library can also be used with C++. \ref 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
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 functions defined in \ref 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
communicate with wpa_supplicant should link in \ref 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().
interface with \ref wpa_ctrl_open() and to send commands with
\ref wpa_ctrl_request().
%wpa_supplicant uses the control interface for two types of communication:
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
wpa_supplicant. These can be executed using \ref 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
attach to the control interface with \ref 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,
\ref 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
control interface connections by calling \ref 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
@ -49,20 +49,20 @@ 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
be closed by calling \ref wpa_ctrl_close(). If the connection was used for
unsolicited event messages, it should be first detached by calling
wpa_ctrl_detach().
\ref wpa_ctrl_detach().
\section ctrl_iface_cmds Control interface commands
Following commands can be used with wpa_ctrl_request():
Following commands can be used with \ref wpa_ctrl_request():
\subsection ctrl_iface_PING PING
This command can be used to test whether %wpa_supplicant is replying
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.
connection is open and wpa_supplicant is processing commands.
\subsection ctrl_iface_MIB MIB
@ -217,13 +217,13 @@ 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().
be done with \ref 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().
be done with \ref wpa_ctrl_detach().
\subsection ctrl_iface_LEVEL LEVEL <debug level>
@ -233,12 +233,12 @@ Change debug level.
\subsection ctrl_iface_RECONFIGURE RECONFIGURE
Force %wpa_supplicant to re-read its configuration data.
Force wpa_supplicant to re-read its configuration data.
\subsection ctrl_iface_TERMINATE TERMINATE
Terminate %wpa_supplicant process.
Terminate wpa_supplicant process.
\subsection ctrl_iface_BSSID BSSID <network id> <BSSID>
@ -563,7 +563,7 @@ two parameters are used: availibility period and availability interval
\section ctrl_iface_interactive Interactive requests
If %wpa_supplicant needs additional information during authentication
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
@ -583,7 +583,7 @@ CTRL-REQ-<field name>-<network id>-<human readable text>
CTRL-RSP-<field name>-<network id>-<value>
\endverbatim
For example, request from %wpa_supplicant:
For example, request from wpa_supplicant:
\verbatim
CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
\endverbatim
@ -598,7 +598,7 @@ CTRL-RSP-PASSWORD-1-secret
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.
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
@ -645,8 +645,8 @@ OPEN SHARED LEAP
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
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
@ -662,14 +662,14 @@ eth0
\section ctrl_iface_events Control interface events
%wpa_supplicant generates number messages based on events like
wpa_supplicant generates number messages based on events like
connection or a completion of a task. These are available to external
programs that attach to receive unsolicited messages over the control
interface with wpa_ctrl_attach().
interface with \ref wpa_ctrl_attach().
The event messages will be delivered over the attach control interface
as text strings that start with the priority level of the message and
a fixed prefix text as defined in wpa_ctrl.h. After this, optional
a fixed prefix text as defined in \ref wpa_ctrl.h. After this, optional
additional information may be included depending on the event
message. For example, following event message is delivered when new
scan results are available:
@ -694,11 +694,11 @@ debug information, but can usually be ignored by external programs.
In most cases, the external program can skip over the priority field
in the beginning of the event message and then compare the following
text to the event strings from wpa_ctrl.h that the program is
text to the event strings from \ref wpa_ctrl.h that the program is
interested in processing.
Following subsections describe the most common event notifications
generated by %wpa_supplicant.
generated by wpa_supplicant.
\subsection ctrl_iface_event_CTRL_REQ CTRL-REQ-
@ -717,7 +717,7 @@ WPA_EVENT_DISCONNECTED: Disconnected, data connection is not available
\subsection ctrl_iface_event_TERMINATING CTRL-EVENT-TERMINATING
WPA_EVENT_TERMINATING: %wpa_supplicant is exiting
WPA_EVENT_TERMINATING: wpa_supplicant is exiting
\subsection ctrl_iface_event_PASSWORD_CHANGED CTRL-EVENT-PASSWORD-CHANGED

50
doc/dbus.doxygen
View file

@ -1,8 +1,8 @@
/**
\page dbus %wpa_supplicant D-Bus API
\page dbus wpa_supplicant D-Bus API
This section documents the %wpa_supplicant D-Bus API. Every D-Bus
interface implemented by %wpa_supplicant is described here including
This section documents the wpa_supplicant D-Bus API. Every D-Bus
interface implemented by wpa_supplicant is described here including
their methods, signals, and properties with arguments, returned
values, and possible errors.
@ -20,7 +20,7 @@ Interfaces:
\section dbus_main fi.w1.wpa_supplicant1
Interface implemented by the main %wpa_supplicant D-Bus object
Interface implemented by the main wpa_supplicant D-Bus object
registered in the bus with fi.w1.wpa_supplicant1 name.
\subsection dbus_main_methods Methods
@ -28,12 +28,12 @@ registered in the bus with fi.w1.wpa_supplicant1 name.
<ul>
<li>
<h3>CreateInterface ( a{sv} : args ) --> o : interface</h3>
<p>Registers a wireless interface in %wpa_supplicant.</p>
<p>Registers a wireless interface in wpa_supplicant.</p>
<h4>Arguments</h4>
<dl>
<dt>a{sv} : args</dt>
<dd>
A dictionary with arguments used to add the interface to %wpa_supplicant. The dictionary may contain the following entries:
A dictionary with arguments used to add the interface to wpa_supplicant. The dictionary may contain the following entries:
<table>
<tr><th>Key</th><th>Value type</th><th>Description</th><th>Required</th>
<tr><td>Ifname</td><td>s</td><td>Name of the network interface to control, e.g., wlan0</td><td>Yes</td>
@ -51,7 +51,7 @@ registered in the bus with fi.w1.wpa_supplicant1 name.
<h4>Possible errors</h4>
<dl>
<dt>fi.w1.wpa_supplicant1.InterfaceExists</dt>
<dd>%wpa_supplicant already controls this interface.</dd>
<dd>wpa_supplicant already controls this interface.</dd>
<dt>fi.w1.wpa_supplicant1.UnknownError</dt>
<dd>Creating interface failed for an unknown reason.</dd>
<dt>fi.w1.wpa_supplicant1.InvalidArgs</dt>
@ -61,7 +61,7 @@ registered in the bus with fi.w1.wpa_supplicant1 name.
<li>
<h3>RemoveInterface ( o : interface ) --> nothing</h3>
<p>Deregisters a wireless interface from %wpa_supplicant.</p>
<p>Deregisters a wireless interface from wpa_supplicant.</p>
<h4>Arguments</h4>
<dl>
<dt>o : interface</dt>
@ -78,7 +78,7 @@ registered in the bus with fi.w1.wpa_supplicant1 name.
<li>
<h3>GetInterface ( s : ifname ) --> o : interface</h3>
<p>Returns a D-Bus path to an object related to an interface which %wpa_supplicant already controls.</p>
<p>Returns a D-Bus path to an object related to an interface which wpa_supplicant already controls.</p>
<h4>Arguments</h4>
<dl>
<dt>s : ifname</dt>
@ -92,7 +92,7 @@ registered in the bus with fi.w1.wpa_supplicant1 name.
<h4>Possible errors</h4>
<dl>
<dt>fi.w1.wpa_supplicant1.InterfaceUnknown</dt>
<dd>An interface with the passed name in not controlled by %wpa_supplicant.</dd>
<dd>An interface with the passed name in not controlled by wpa_supplicant.</dd>
<dt>fi.w1.wpa_supplicant1.UnknownError</dt>
<dd>Getting an interface object path failed for an unknown reason.</dd>
</dl>
@ -104,19 +104,19 @@ registered in the bus with fi.w1.wpa_supplicant1 name.
<ul>
<li>
<h3>DebugLevel - s - (read/write)</h3>
<p>Global %wpa_supplicant debugging level. Possible values are
<p>Global wpa_supplicant debugging level. Possible values are
"msgdump" (verbose debugging), "debug" (debugging),
"info" (informative), "warning" (warnings), and "error" (errors).</p>
</li>
<li>
<h3>DebugTimestamp - b - (read/write)</h3>
<p>Global %wpa_supplicant debugging parameter. Determines if timestamps are shown in debug logs.</p>
<p>Global wpa_supplicant debugging parameter. Determines if timestamps are shown in debug logs.</p>
</li>
<li>
<h3>DebugShowKeys - b - (read/write)</h3>
<p>Global %wpa_supplicant debugging parameter. Determines if secrets are shown in debug logs.</p>
<p>Global wpa_supplicant debugging parameter. Determines if secrets are shown in debug logs.</p>
</li>
<li>
@ -145,7 +145,7 @@ registered in the bus with fi.w1.wpa_supplicant1 name.
<ul>
<li>
<h3>InterfaceAdded ( o : interface, a{sv} : properties )</h3>
<p>A new interface was added to %wpa_supplicant.</p>
<p>A new interface was added to wpa_supplicant.</p>
<h4>Arguments</h4>
<dl>
<dt>o : interface</dt>
@ -159,7 +159,7 @@ registered in the bus with fi.w1.wpa_supplicant1 name.
<li>
<h3>InterfaceRemoved ( o : interface )</h3>
<p>An interface was removed from %wpa_supplicant.</p>
<p>An interface was removed from wpa_supplicant.</p>
<h4>Arguments</h4>
<dl>
<dt>o : interface</dt>
@ -182,7 +182,7 @@ registered in the bus with fi.w1.wpa_supplicant1 name.
\section dbus_interface fi.w1.wpa_supplicant1.Interface
Interface implemented by objects related to network interface added to
%wpa_supplicant, i.e., returned by
wpa_supplicant, i.e., returned by
fi.w1.wpa_supplicant1.CreateInterface.
\subsection dbus_interface_methods Methods
@ -229,7 +229,7 @@ fi.w1.wpa_supplicant1.CreateInterface.
<h4>Arguments</h4>
<dl>
<dt>a{sv} : args</dt>
<dd>A dictionary with network configuration. Dictionary entries are equivalent to entries in the "network" block in %wpa_supplicant configuration file. Entry values should be appropriate type to the entry, e.g., an entry with key "frequency" should have value type int.</dd>
<dd>A dictionary with network configuration. Dictionary entries are equivalent to entries in the "network" block in wpa_supplicant configuration file. Entry values should be appropriate type to the entry, e.g., an entry with key "frequency" should have value type int.</dd>
</dl>
<h4>Returns</h4>
<dl>
@ -576,22 +576,22 @@ fi.w1.wpa_supplicant1.CreateInterface.
<li>
<h3>ApScan - u - (read/write)</h3>
<p>Identical to ap_scan entry in %wpa_supplicant configuration file. Possible values are 0, 1 or 2.</p>
<p>Identical to ap_scan entry in wpa_supplicant configuration file. Possible values are 0, 1 or 2.</p>
</li>
<li>
<h3>BSSExpireAge - u - (read/write)</h3>
<p>Identical to bss_expiration_age entry in %wpa_supplicant configuration file.</p>
<p>Identical to bss_expiration_age entry in wpa_supplicant configuration file.</p>
</li>
<li>
<h3>BSSExpireCount - u - (read/write)</h3>
<p>Identical to bss_expiration_scan_count entry in %wpa_supplicant configuration file.</p>
<p>Identical to bss_expiration_scan_count entry in wpa_supplicant configuration file.</p>
</li>
<li>
<h3>Country - s - (read/write)</h3>
<p>Identical to country entry in %wpa_supplicant configuration file.</p>
<p>Identical to country entry in wpa_supplicant configuration file.</p>
</li>
<li>
@ -611,12 +611,12 @@ fi.w1.wpa_supplicant1.CreateInterface.
<li>
<h3>CurrentBSS - o - (read)</h3>
<p>Path to D-Bus object representing BSS which %wpa_supplicant is associated with, or "/" if is not associated at all.</p>
<p>Path to D-Bus object representing BSS which wpa_supplicant is associated with, or "/" if is not associated at all.</p>
</li>
<li>
<h3>CurrentNetwork - o - (read)</h3>
<p>Path to D-Bus object representing configured network which %wpa_supplicant uses at the moment, or "/" if doesn't use any.</p>
<p>Path to D-Bus object representing configured network which wpa_supplicant uses at the moment, or "/" if doesn't use any.</p>
</li>
<li>
@ -641,7 +641,7 @@ fi.w1.wpa_supplicant1.CreateInterface.
<li>
<h3>FastReauth - b - (read/write)</h3>
<p>Identical to fast_reauth entry in %wpa_supplicant configuration file.</p>
<p>Identical to fast_reauth entry in wpa_supplicant configuration file.</p>
</li>
<li>
@ -1595,7 +1595,7 @@ i.e., returned by fi.w1.wpa_supplicant1.Interface.AddNetwork.
<li>
<h3>Properties - a{sv} - (read/write)</h3>
<p>Properties of the configured network. Dictionary contains entries from "network" block of %wpa_supplicant configuration file. All values are string type, e.g., frequency is "2437", not 2437.
<p>Properties of the configured network. Dictionary contains entries from "network" block of wpa_supplicant configuration file. All values are string type, e.g., frequency is "2437", not 2437.
</li>
</ul>

4
doc/directories.doxygen
View file

@ -82,9 +82,9 @@ Enrollee. Minimal UPnP and HTTP functionality is also provided for the
functionality needed to implement Wi-Fi Protected Setup.
\dir wpa_supplicant %wpa_supplicant
\dir wpa_supplicant wpa_supplicant
%wpa_supplicant-specific code for configuration, control interface, and
wpa_supplicant-specific code for configuration, control interface, and
client management.
*/

14
doc/doxygen.conf
View file

@ -31,7 +31,7 @@ PROJECT_NAME = "wpa_supplicant / hostapd"
# This could be handy for archiving the generated documentation or
# if some version control system is used.
PROJECT_NUMBER = 2.0
PROJECT_NUMBER = 2.4
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
@ -572,6 +572,8 @@ INPUT = \
doc \
hostapd \
wpa_supplicant \
wpa_supplicant/dbus \
eap_example \
src/ap \
src/common \
src/crypto \
@ -583,6 +585,7 @@ INPUT = \
src/eap_server \
src/l2_packet \
src/p2p \
src/pae \
src/radius \
src/rsn_supp \
src/tls \
@ -1533,3 +1536,12 @@ GENERATE_LEGEND = YES
# the various graphs.
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Project additions
#---------------------------------------------------------------------------
# Disable autolink support due to wpa_supplicant getting unfortunately
# auto-linked to struct wpa_supplicant due to having an underscore in the name.
AUTOLINK_SUPPORT = FALSE

70
doc/driver_wrapper.doxygen
View file

@ -3,7 +3,7 @@
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
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
@ -13,45 +13,45 @@ 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
can be replaced with generic code in \ref 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
defined in \ref driver.h. These functions are registered by filling struct
\ref 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.
callback function, \ref wpa_supplicant_event(), and its parameters are
documented in \ref driver.h. In addition, a pointer to the 'struct
\ref wpa_driver_ops' needs to be registered in \ref 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
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
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
\ref 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.
\ref driver_hostap.c. These files need to define struct \ref wpa_driver_ops
entry that will be used in \ref wpa_supplicant.c when calling driver
functions. struct \ref wpa_driver_ops entries are registered in \ref 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)
one. \ref driver_hostap.c and \ref driver_wext.c include a complete
implementation for Linux drivers that use wpa_supplicant-based control
of WPA IE and roaming. \ref driver_ndis.c (with help from \ref 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.
@ -61,7 +61,7 @@ example implementations include full support for all security modes.
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.
wpa_supplicant.
\subsection driver_tkip_ccmp TKIP/CCMP
@ -86,12 +86,12 @@ 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
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
recommended. The current driver wrapper (\ref driver_wext.c) uses this for
scan results.
Scan results must also include the WPA information element. Support for
@ -99,9 +99,9 @@ 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
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
\ref driver_hostap.c wrapper uses following sequence for this
request. Similar/identical mechanism should be usable also with other
drivers.
@ -113,28 +113,28 @@ drivers.
\subsection driver_wpa_ie WPA IE generation
%wpa_supplicant selects which cipher suites and key management suites
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
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
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
\ref 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
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).
details are defined in \ref driver.h (\ref wpa_supplicant_event() function
and enum \ref wpa_event_type).
On Linux, association and disassociation can use existing Wireless
Extensions event that is reporting new AP with SIOCGIWAP
@ -153,18 +153,18 @@ AP selection depends on ap_scan configuration:
ap_scan=1:
- %wpa_supplicant requests scan with SIOCSIWSCAN
- wpa_supplicant requests scan with SIOCSIWSCAN
- driver reports scan complete with wireless event SIOCGIWSCAN
- %wpa_supplicant reads scan results with SIOCGIWSCAN (multiple call if
- 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
- 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
- wpa_supplicant configures driver to associate with an SSID
(SIOCSIWMODE, SIOCSIWGENIE, SIOCSIWAUTH, SIOCSIWESSID)
@ -174,7 +174,7 @@ After this, both modes use similar steps:
(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
- 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)
*/

32
doc/eap.doxygen
View file

@ -2,44 +2,44 @@
\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
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.
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
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
file named eap_<name of the method>.c, e.g., \ref 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
\ref eap_peer_register_methods() function of \ref 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 methods must implement the interface defined in \ref 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
functions, \ref eap_msg_alloc() and \ref 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
@ -48,23 +48,23 @@ 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
\ref 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
\ref 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
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
\ref eap_example_peer.c shows the initialization and glue code needed to
control the EAP peer implementation. \ref eap_example_server.c does the
same for EAP server. \ref eap_example.c is an example that ties in both the
EAP server and client parts to allow an EAP authentication to be
shown.
@ -77,9 +77,9 @@ 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
The EAP library links in number of helper functions from \ref src/utils and
\ref src/crypto directories. Most of these are suitable as-is, but it may
be desirable to replace the debug output code in \ref 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.

16
doc/eap_server.doxygen
View file

@ -14,32 +14,32 @@ 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
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
file named eap_server_<name of the method>.c, e.g., \ref eap_server_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
\ref eap_server_register_methods() function of \ref eap_server_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
EAP methods must implement the interface defined in \ref eap_i.h. struct
\ref 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
functions, \ref eap_msg_alloc() and \ref 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
@ -48,9 +48,9 @@ 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
\ref 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
\ref eap_server_vendor_test.c for an example of an EAP method implementation that
is implemented as an expanded type.
*/

30
doc/hostapd_ctrl_iface.doxygen
View file

@ -4,58 +4,58 @@
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
a small C library, in a form of a single C file, \ref 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
the library functions documented in \ref wpa_ctrl.h to interact with
wpa_supplicant. This library can also be used with C++. \ref 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
control interface. The use of the functions defined in \ref 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
communicate with hostapd should link in \ref 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().
interface with \ref wpa_ctrl_open() and to send commands with
\ref 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().
hostapd. These can be executed using \ref 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
attach to the control interface with \ref 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,
\ref 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
control interface connections by calling \ref 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
not be broken by unsolicited messages. \ref wpa_cli.c 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
be closed by calling \ref wpa_ctrl_close(). If the connection was used for
unsolicited event messages, it should be first detached by calling
wpa_ctrl_detach().
\ref wpa_ctrl_detach().
\section ctrl_iface_cmds Control interface commands
Following commands can be used with wpa_ctrl_request():
Following commands can be used with \ref wpa_ctrl_request():
\subsection ctrl_iface_PING PING

16
doc/mainpage.doxygen
View file

@ -3,17 +3,17 @@
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
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 the
BSD license (the one with advertisement clause removed). All
contributions to %wpa_supplicant and hostapd are expected to use
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
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
@ -22,14 +22,14 @@ 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
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
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
@ -41,15 +41,15 @@ the \ref porting "porting page".
EAPOL (IEEE 802.1X) state machines are implemented as a separate
module that interacts with \ref eap_peer_module "EAP peer implementation".
In addition to programs aimed at normal production use,
%wpa_supplicant source tree includes number of \ref testing_tools
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
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
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++.

205
doc/p2p.doxygen
View file

@ -3,7 +3,7 @@
Wi-Fi Direct functionality is implemented any many levels in the WLAN
stack from low-level driver operations to high-level GUI design. This
document covers the parts that can be user by %wpa_supplicant. However,
document covers the parts that can be user by wpa_supplicant. However,
it should be noted that alternative designs are also possible, so some
of the functionality may reside in other components in the system.
@ -19,16 +19,16 @@ P2P module implements higher layer functionality for management P2P
groups. It takes care of Device Discovery, Service Discovery, Group
Owner Negotiation, P2P Invitation. In addition, it maintains
information about neighboring P2P Devices. This module could be used
in designs that do not use %wpa_supplicant and it could also reside
in designs that do not use wpa_supplicant and it could also reside
inside the driver/firmware component. P2P module API is defined in
src/p2p/p2p.h.
\ref src/p2p/p2p.h.
Provisioning step of Group Formation is implemented using WPS
(src/wps/wps.h).
(\ref src/wps/wps.h).
%wpa_supplicant includes code in interact with both the P2P module
(wpa_supplicant/p2p_supplicant.c) and WPS
(wpa_supplicant/wps_supplicant.c). The driver operations are passed
wpa_supplicant includes code in interact with both the P2P module
(\ref wpa_supplicant/p2p_supplicant.c) and WPS
(\ref wpa_supplicant/wps_supplicant.c). The driver operations are passed
through these files, i.e., core P2P or WPS code does not interact
directly with the driver interface.
@ -48,7 +48,7 @@ functionality.
\subsection p2p_arch_mac80211 P2P architecture with Linux/mac80211/ath9k
An architecture where the P2P module resides inside the
%wpa_supplicant process is used with Linux mac80211-based drivers,
wpa_supplicant process is used with Linux mac80211-based drivers,
e.g., ath9k. The following diagram shows the main components related
to P2P functionality in such an architecture.
@ -82,7 +82,7 @@ and the alternating Listen and Search states within Find).
\subsection p2p_module_api P2P module API
P2P module API is defined in src/p2p/p2p.h. The API consists of
P2P module API is defined in \ref src/p2p/p2p.h. The API consists of
functions for requesting operations and for providing event
notifications. Similar set of callback functions are configured with
struct p2p_config to provide callback functions that P2P module can
@ -92,51 +92,51 @@ used for P2P related operations.
These are the main functions for an upper layer management entity to
request P2P operations:
- p2p_find()
- p2p_stop_find()
- p2p_listen()
- p2p_connect()
- p2p_reject()
- p2p_prov_disc_req()
- p2p_sd_request()
- p2p_sd_cancel_request()
- p2p_sd_response()
- p2p_sd_service_update()
- p2p_invite()
- \ref p2p_find()
- \ref p2p_stop_find()
- \ref p2p_listen()
- \ref p2p_connect()
- \ref p2p_reject()
- \ref p2p_prov_disc_req()
- \ref p2p_sd_request()
- \ref p2p_sd_cancel_request()
- \ref p2p_sd_response()
- \ref p2p_sd_service_update()
- \ref p2p_invite()
These are the main callback functions for P2P module to provide event
notifications to the upper layer management entity:
- p2p_config::dev_found()
- p2p_config::go_neg_req_rx()
- p2p_config::go_neg_completed()
- p2p_config::sd_request()
- p2p_config::sd_response()
- p2p_config::prov_disc_req()
- p2p_config::prov_disc_resp()
- p2p_config::invitation_process()
- p2p_config::invitation_received()
- p2p_config::invitation_result()
- \ref p2p_config::dev_found()
- \ref p2p_config::go_neg_req_rx()
- \ref p2p_config::go_neg_completed()
- \ref p2p_config::sd_request()
- \ref p2p_config::sd_response()
- \ref p2p_config::prov_disc_req()
- \ref p2p_config::prov_disc_resp()
- \ref p2p_config::invitation_process()
- \ref p2p_config::invitation_received()
- \ref p2p_config::invitation_result()
The P2P module uses following functions to request lower layer driver
operations:
- p2p_config::p2p_scan()
- p2p_config::send_probe_resp()
- p2p_config::send_action()
- p2p_config::send_action_done()
- p2p_config::start_listen()
- p2p_config::stop_listen()
- \ref p2p_config::p2p_scan()
- \ref p2p_config::send_probe_resp()
- \ref p2p_config::send_action()
- \ref p2p_config::send_action_done()
- \ref p2p_config::start_listen()
- \ref p2p_config::stop_listen()
Events from lower layer driver operations are delivered to the P2P
module with following functions:
- p2p_probe_req_rx()
- p2p_rx_action()
- p2p_scan_res_handler()
- p2p_scan_res_handled()
- p2p_send_action_cb()
- p2p_listen_cb()
- \ref p2p_probe_req_rx()
- \ref p2p_rx_action()
- \ref p2p_scan_res_handler()
- \ref p2p_scan_res_handled()
- \ref p2p_send_action_cb()
- \ref p2p_listen_cb()
In addition to the per-device state, the P2P module maintains
per-group state for group owners. This is initialized with a call to
@ -144,39 +144,36 @@ p2p_group_init() when a group is created and deinitialized with
p2p_group_deinit(). The upper layer GO management entity uses
following functions to interact with the P2P per-group state:
- p2p_group_notif_assoc()
- p2p_group_notif_disassoc()
- p2p_group_notif_formation_done()
- p2p_group_match_dev_type()
- \ref p2p_group_notif_assoc()
- \ref p2p_group_notif_disassoc()
- \ref p2p_group_notif_formation_done()
- \ref p2p_group_match_dev_type()
The P2P module will use following callback function to update P2P IE
for GO Beacon and Probe Response frames:
- p2p_group_config::ie_update()
- \ref p2p_group_config::ie_update()
\section p2p_driver P2P driver operations (low-level interface)
The following driver wrapper functions are needed for P2P in addition
to the standard station/AP mode operations when the P2P module resides
within %wpa_supplicant:
- wpa_driver_ops::if_add()
- wpa_driver_ops::if_remove()
- wpa_driver_ops::alloc_interface_addr()
- wpa_driver_ops::release_interface_addr()
- wpa_driver_ops::remain_on_channel()
- wpa_driver_ops::cancel_remain_on_channel()
- wpa_driver_ops::send_action()
- wpa_driver_ops::probe_req_report()
- wpa_driver_ops::disable_11b_rates()
within wpa_supplicant:
- \ref wpa_driver_ops::if_add()
- \ref wpa_driver_ops::if_remove()
- \ref wpa_driver_ops::remain_on_channel()
- \ref wpa_driver_ops::cancel_remain_on_channel()
- \ref wpa_driver_ops::send_action()
- \ref wpa_driver_ops::probe_req_report()
The following driver wrapper events are needed for P2P in addition to
the standard station/AP mode events when the P2P module resides within
%wpa_supplicant:
- wpa_event_type::EVENT_RX_ACTION
- wpa_event_type::EVENT_REMAIN_ON_CHANNEL
- wpa_event_type::EVENT_CANCEL_REMAIN_ON_CHANNEL
- wpa_event_type::EVENT_RX_PROBE_REQ
wpa_supplicant:
- \ref wpa_event_type::EVENT_RX_MGMT
- \ref wpa_event_type::EVENT_REMAIN_ON_CHANNEL
- \ref wpa_event_type::EVENT_CANCEL_REMAIN_ON_CHANNEL
- \ref wpa_event_type::EVENT_RX_PROBE_REQ
\section p2p_go_neg P2P device discovery and group formation
@ -188,40 +185,40 @@ the glue code outside the P2P module depends on the architecture used
in the system.
An upper layer management entity starts P2P device discovery by
calling p2p_find(). The P2P module start the discovery by requesting a
full scan to be completed by calling p2p_config::p2p_scan(). Results
from the scan will be reported by calling p2p_scan_res_handler() and
calling \ref p2p_find(). The P2P module start the discovery by requesting a
full scan to be completed by calling \ref p2p_config::p2p_scan(). Results
from the scan will be reported by calling \ref p2p_scan_res_handler() and
after last result, the scan result processing is terminated with a
call to p2p_scan_res_handled(). The P2P peers that are found during
the full scan are reported with the p2p_config::dev_found() callback.
call to \ref p2p_scan_res_handled(). The P2P peers that are found during
the full scan are reported with the \ref p2p_config::dev_found() callback.
After the full scan, P2P module start alternating between Listen and
Search states until the device discovery operation times out or
terminated, e.g., with a call to p2p_stop_find().
terminated, e.g., with a call to \ref p2p_stop_find().
When going into the Listen state, the P2P module requests the driver
to be configured to be awake on the listen channel with a call to
p2p_config::start_listen(). The glue code using the P2P module may
\ref p2p_config::start_listen(). The glue code using the P2P module may
implement this, e.g., by using remain-on-channel low-level driver
functionality for off-channel operation. Once the driver is available
on the requested channel, notification of this is delivered by calling
p2p_listen_cb(). The Probe Request frames that are received during the
\ref p2p_listen_cb(). The Probe Request frames that are received during the
Listen period are delivered to the P2P module by calling
p2p_config::p2p_probe_req_rx() and P2P module request a response to
these to be sent by using p2p_config::send_probe_resp() callback
\ref p2p_config::p2p_probe_req_rx() and P2P module request a response to
these to be sent by using \ref p2p_config::send_probe_resp() callback
function. If a group owner negotiation from another P2P device is
received during the device discovery phase, that is indicated to the
upper layer code with the p2p_config::go_neg_req_tx() callback.
upper layer code with the \ref p2p_config::go_neg_req_tx() callback.
The Search state is implemented by using the normal scan interface,
i.e., the P2P module will call p2p_config::p2p_scan() just like in the
i.e., the P2P module will call \ref p2p_config::p2p_scan() just like in the
full scan phase described. Similarly, scan results from the search
operation will be delivered to the P2P module using the
p2p_scan_res_handler() and p2p_scan_res_handled() functions.
\ref p2p_scan_res_handler() and \ref p2p_scan_res_handled() functions.
Once the upper layer management entity has found a peer with which it
wants to connect by forming a new group, it initiates group owner
negotiation by calling p2p_connect(). Before doing this, the upper
negotiation by calling \ref p2p_connect(). Before doing this, the upper
layer code is responsible for asking the user to provide the PIN to be
used during the provisioning step with the peer or the push button
press for PBC mode. The glue code will need to figure out the intended
@ -231,25 +228,25 @@ started.
Optional Provision Discovery mechanism can be used to request the peer
to display a PIN for the local device to enter (and vice versa). Upper
layer management entity can request the specific mechanism by calling
p2p_prov_disc_req(). The response to this will be reported with the
p2p_config::prov_disc_resp() callback. If the peer device started
\ref p2p_prov_disc_req(). The response to this will be reported with the
\ref p2p_config::prov_disc_resp() callback. If the peer device started
Provision Discovery, an accepted request will be reported with the
p2p_config::prov_disc_req() callback. The P2P module will
\ref p2p_config::prov_disc_req() callback. The P2P module will
automatically accept the Provision Discovery for display and keypad
methods, but it is up to the upper layer manegement entity to actually
generate the PIN and to configure it with following p2p_connect() call
generate the PIN and to configure it with following \ref p2p_connect() call
to actually authorize the connection.
The P2P module will use p2p_config::send_action() callback to request
The P2P module will use \ref p2p_config::send_action() callback to request
lower layer code to transmit an Action frame during group owner
negotiation. p2p_send_action_cb() is used to report the result of
negotiation. \ref p2p_send_action_cb() is used to report the result of
transmission. If the peer is not reachable, the P2P module will try to
find it by alternating between Action frame send and Listen
states. The Listen state for this phase will be used similarly to the
Listen state during device discovery as described above.
Once the group owner negotiation has been completed, its results will
be reported with the p2p_config::go_neg_completed() callback. The
be reported with the \ref p2p_config::go_neg_completed() callback. The
upper layer management code or the glue code using the P2P module API
is responsible for creating a new group interface and starting
provisioning step at this point by configuring WPS Registrar or
@ -258,15 +255,15 @@ results. The upper layer code is also responsible for timing out WPS
provisioning if it cannot be completed in 15 seconds.
Successful completion of the WPS provisioning is reported with a call
to p2p_wps_success_cb(). The P2P module will clear its group formation
to \ref p2p_wps_success_cb(). The P2P module will clear its group formation
state at this point and allows new group formation attempts to be
started. The upper layer management code is responsible for configuring
the GO to accept associations from devices and the client to connect to
the GO with the provisioned credentials. GO is also responsible for
calling p2p_group_notif_formation_done() as described below.
calling \ref p2p_group_notif_formation_done() as described below.
If the WPS provisioning step fails or times out, this is reported with
a call to p2p_group_formation_failed(). The P2P module will clear its
a call to \ref p2p_group_formation_failed(). The P2P module will clear its
group formation state at this point and allows new group formation
attempts to be started. The upper layer management code is responsible
for removing the group interface for the failed group.
@ -289,23 +286,23 @@ Response TLV(s) for responses.
\subsection p2p_sd_query Quering services of peers
Service discovery is implemented by processing pending queries as a
part of the device discovery phase. p2p_sd_request() function is used
part of the device discovery phase. \ref p2p_sd_request() function is used
to schedule service discovery queries to a specific peer or to all
discovered peers. p2p_sd_cancel_request() can be used to cancel a
discovered peers. \ref p2p_sd_cancel_request() can be used to cancel a
scheduled query. Queries that are specific to a single peer will be
removed automatically after the response has been received.
After the service discovery queries have been queued, device discovery
is started with a call to p2p_find(). The pending service discovery
is started with a call to \ref p2p_find(). The pending service discovery
queries are then sent whenever a peer is discovered during the find
operation. Responses to the queries will be reported with the
p2p_config::sd_response() callback.
\ref p2p_config::sd_response() callback.
\subsection p2p_sd_response Replying to service discovery queries from peers
The received service discovery requests will be indicated with the
p2p_config::sd_request() callback. The response to the query is sent
by calling p2p_sd_response().
\ref p2p_config::sd_request() callback. The response to the query is sent
by calling \ref p2p_sd_response().
\subsection p2p_sd_indicator Service update indicator
@ -314,9 +311,9 @@ changes in available services. This works by incrementing Service
Update Indicator value whenever there is a change in the
services. This value is included in all SD request and response
frames. The value received from the peers will be included in the
p2p_config::sd_request() and p2p_config::sd_response() callbacks. The
\ref p2p_config::sd_request() and \ref p2p_config::sd_response() callbacks. The
value to be sent to the peers is incremented with a call to
p2p_sd_service_update() whenever availibility of the local services
\ref p2p_sd_service_update() whenever availibility of the local services
changes.
@ -329,29 +326,29 @@ code outside the P2P module depends on the architecture used in the
system.
When a P2P group interface is created in group owner role, per-group
data is initialized with p2p_group_init(). This call provides a
data is initialized with \ref p2p_group_init(). This call provides a
pointer to the per-device P2P module context and configures the
per-group operation. The configured p2p_group_config::ie_update()
per-group operation. The configured \ref p2p_group_config::ie_update()
callback is used to set the initial P2P IE for Beacon and Probe
Response frames in the group owner. The AP mode implementation may use
this information to add IEs into the frames.
Once the group formation has been completed (or if it is skipped in
case of manual group setup), p2p_group_notif_formation_done() is
case of manual group setup), \ref p2p_group_notif_formation_done() is
called. This will allow the P2P module to update the P2P IE for
Beacon and Probe Response frames.
The SME/MLME code that managements IEEE 802.11 association processing
needs to inform P2P module whenever a P2P client associates or
disassociates with the group. This is done by calling
p2p_group_notif_assoc() and p2p_group_notif_disassoc(). The P2P module
\ref p2p_group_notif_assoc() and \ref p2p_group_notif_disassoc(). The P2P module
manages a list of group members and updates the P2P Group Information
subelement in the P2P IE based on the information from the P2P
clients. The p2p_group_config::ie_update() callback is used whenever
clients. The \ref p2p_group_config::ie_update() callback is used whenever
the P2P IE in Probe Response frames needs to be changed.
The SME/MLME code that takes care of replying to Probe Request frames
can use p2p_group_match_dev_type() to check whether the Probe Request
can use \ref p2p_group_match_dev_type() to check whether the Probe Request
frame request a reply only from groups that include a specific device
type in one of the clients or GO. A match will be reported if the
Probe Request does not request a specific device type, so this
@ -359,13 +356,13 @@ function can be used to filter or received Probe Request frames and
only the ones that result in non-zero return value need to be replied.
When the P2P group interface for GO role is removed,
p2p_group_deinit() is used to deinitialize the per-group P2P module
\ref p2p_group_deinit() is used to deinitialize the per-group P2P module
state.
\section p2p_ctrl_iface P2P control interface
%wpa_supplicant \ref ctrl_iface_page "control interface" can be used
wpa_supplicant \ref ctrl_iface_page "control interface" can be used
to manage P2P functionality from an external program (e.g., a GUI or a
system configuration manager). This interface can be used directly
through the control interface backend mechanism (e.g., local domain
@ -414,11 +411,11 @@ control interface commands and events can be used.
\subsection p2p_wpa_cli wpa_cli example
wpa_cli can be used to control %wpa_supplicant in interactive
wpa_cli can be used to control wpa_supplicant in interactive
mode. The following sessions show examples of commands used for
device discovery and group formation. The lines starting with "> " are
commands from the user (followed by command result indication) and
lines starting with "<2>" are event messages from %wpa_supplicant.
lines starting with "<2>" are event messages from wpa_supplicant.
P2P device "Wireless Client":

109
doc/porting.doxygen
View file

@ -1,14 +1,14 @@
/**
\page porting Porting to different target boards and operating systems
%wpa_supplicant was designed to be easily portable to different
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
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,
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.
@ -16,48 +16,48 @@ supported.
\section ansi_c_extra Extra functions on top of ANSI C
%wpa_supplicant is mostly using ANSI C functions that are available on
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
prototypes in \ref 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
definitions in \ref 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
available. In addition, \ref os.h defines couple of common platform
specific functions that are implemented in \ref os_unix.c for UNIX like
targets and in \ref 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
platform needs different versions of the functions, \ref 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
\ref 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
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
a suitable source depending on the target platform. \ref 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
The included \ref config_file.c backend uses a text file for configuration
and \ref 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
\ref config_none.c can be used as an empty starting point for building a
new configuration backend.
@ -69,19 +69,19 @@ 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.
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
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.
and RSN pre-authentication 0x88c7. \ref 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
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
@ -89,26 +89,27 @@ 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
The main wpa_supplicant repository includes l2_packet implementations
for Linux using packet sockets (\ref l2_packet_linux.c), more portable
version using libpcap/libdnet libraries (\ref l2_packet_pcap.c; this
supports WinPcap, too), and FreeBSD specific version of libpcap
interface (l2_packet_freebsd.c).
interface (\ref 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
libdnet (sending), \ref 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
added. Alternatively, for hostapd,
struct \ref wpa_driver_ops::hapd_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
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
signal). eloop.h defines the event loop interface. \ref 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
@ -117,64 +118,64 @@ with OS specific mechanisms that provide similar functionality.
\section ctrl_iface_porting Control interface
%wpa_supplicant uses a \ref ctrl_iface_page "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
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.
The wpa_supplicant side of the control interface is implemented in
\ref wpa_supplicant/ctrl_iface.c. Matching client side is implemented as a control
interface library in \ref wpa_ctrl.c.
\section entry_point Program entry point
%wpa_supplicant defines a set of functions that can be used to
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.
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.
\ref 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. \ref wpa_supplicant/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
\ref 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
wpa_supplicant context is initialized with a call to
\ref wpa_supplicant_init(). After this, existing network interfaces can be
added with \ref wpa_supplicant_add_iface(). \ref 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
termination time, \ref wpa_supplicant_deinit() is used to release global
context data.
wpa_supplicant_add_iface() and wpa_supplicant_remove_iface() can be
\ref wpa_supplicant_add_iface() and \ref 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.,
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
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
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:
wpa_supplicant:
\verbatim
cc -o wpa_supplicant config.c eloop.c common.c md5.c rc4.c sha1.c \
@ -192,7 +193,7 @@ 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),
registration in \ref 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.

16
doc/testing_tools.doxygen
View file

@ -6,7 +6,7 @@
\ref unit_tests "Unit tests" |
\ref wpa_trace "Tracing code" ]
%wpa_supplicant source tree includes number of testing and development
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.
@ -14,7 +14,7 @@ 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
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
@ -34,7 +34,7 @@ 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
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:
@ -77,7 +77,7 @@ 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.
network blocks as wpa_supplicant.
\section preauth_test preauth_test - WPA2 pre-authentication and EAP peer testing
@ -85,8 +85,8 @@ network blocks as %wpa_supplicant.
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
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:
@ -112,7 +112,7 @@ pre-authentication packets would be sent using the eth0 interface.
\section unit_tests Unit tests
Number of the components (.c files) used in %wpa_supplicant define
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
@ -131,7 +131,7 @@ exit code if all tests were completed successfully.
\section wpa_trace Tracing code for developer debuggin
%wpa_supplicant and hostapd can be built with tracing code that will
wpa_supplicant and hostapd can be built with tracing code that will
track and analyze memory allocations and other resource registrations
and certain API uses. If incorrect use is detected, a backtrace of the
call location (and/or allocation location) is shown. This can also be