\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
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)
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),
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
*/
/**
-\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
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
\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>
\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>
\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
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
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
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
\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:
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-
\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
/**
-\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.
\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
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
\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
<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>
<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>
<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>
<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>
<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>
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.
*/
# 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.
doc \
hostapd \
wpa_supplicant \
+ wpa_supplicant/dbus \
+ eap_example \
src/ap \
src/common \
src/crypto \
src/eap_server \
src/l2_packet \
src/p2p \
+ src/pae \
src/radius \
src/rsn_supp \
src/tls \
# 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
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
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.
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
\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
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.
\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
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)
(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)
*/
\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
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.
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.
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
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.
*/
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
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
\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
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++.
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.
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.
\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.
\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
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
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
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
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
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.
\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
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.
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
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
\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":
/**
\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.
\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.
(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
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
\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 \
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.
\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.
\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
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:
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
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:
\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
\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