5eb513c3ba
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>
87 lines
4.3 KiB
Text
87 lines
4.3 KiB
Text
/**
|
|
\page eap_peer_module EAP peer implementation
|
|
|
|
Extensible Authentication Protocol (EAP) is an authentication framework
|
|
defined in RFC 3748. wpa_supplicant uses a separate code module for EAP
|
|
peer implementation. This module was designed to use only a minimal set
|
|
of direct function calls (mainly, to debug/event functions) in order for
|
|
it to be usable in other programs. The design of the EAP
|
|
implementation is based loosely on RFC 4137. The state machine is
|
|
defined in this RFC and so is the interface between the peer state
|
|
machine and methods. As such, this RFC provides useful information for
|
|
understanding the EAP peer implementation in wpa_supplicant.
|
|
|
|
Some of the terminology used in EAP state machine is referring to
|
|
EAPOL (IEEE 802.1X), but there is no strict requirement on the lower
|
|
layer being IEEE 802.1X if EAP module is built for other programs than
|
|
wpa_supplicant. These terms should be understood to refer to the
|
|
lower layer as defined in RFC 4137.
|
|
|
|
|
|
\section adding_eap_methods Adding EAP methods
|
|
|
|
Each EAP method is implemented as a separate module, usually as one C
|
|
file named eap_<name of the method>.c, e.g., \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
|
|
\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 \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, \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
|
|
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
|
|
\ref eap_peer_method_alloc(). These methods must not try to emulate
|
|
expanded types by registering a legacy EAP method for type 254. See
|
|
\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
|
|
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.
|
|
|
|
\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.
|
|
|
|
In this example, the EAP messages are passed between the server and
|
|
the peer are passed by direct function calls within the same process.
|
|
In practice, server and peer functionalities would likely reside in
|
|
separate devices and the EAP messages would be transmitted between the
|
|
devices based on an external protocol. For example, in IEEE 802.11
|
|
uses IEEE 802.1X EAPOL state machines to control the transmission of
|
|
EAP messages and WiMax supports optional PMK EAP authentication
|
|
mechanism that transmits EAP messages as defined in IEEE 802.16e.
|
|
|
|
The EAP library links in number of helper functions from \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.
|
|
|
|
*/
|