1/**
2\page eap_peer_module EAP peer implementation
3
4Extensible Authentication Protocol (EAP) is an authentication framework
5defined in RFC 3748. wpa_supplicant uses a separate code module for EAP
6peer implementation. This module was designed to use only a minimal set
7of direct function calls (mainly, to debug/event functions) in order for
8it to be usable in other programs. The design of the EAP
9implementation is based loosely on RFC 4137. The state machine is
10defined in this RFC and so is the interface between the peer state
11machine and methods. As such, this RFC provides useful information for
12understanding the EAP peer implementation in wpa_supplicant.
13
14Some of the terminology used in EAP state machine is referring to
15EAPOL (IEEE 802.1X), but there is no strict requirement on the lower
16layer being IEEE 802.1X if EAP module is built for other programs than
17wpa_supplicant. These terms should be understood to refer to the
18lower layer as defined in RFC 4137.
19
20
21\section adding_eap_methods Adding EAP methods
22
23Each EAP method is implemented as a separate module, usually as one C
24file named eap_<name of the method>.c, e.g., \ref eap_md5.c. All EAP
25methods use the same interface between the peer state machine and
26method specific functions. This allows new EAP methods to be added
27without modifying the core EAP state machine implementation.
28
29New EAP methods need to be registered by adding them into the build
30(Makefile) and the EAP method registration list in the
31\ref eap_peer_register_methods() function of \ref eap_methods.c. Each EAP
32method should use a build-time configuration option, e.g., EAP_TLS, in
33order to make it possible to select which of the methods are included
34in the build.
35
36EAP methods must implement the interface defined in \ref eap_i.h. struct
37\ref eap_method defines the needed function pointers that each EAP method
38must provide. In addition, the EAP type and name are registered using
39this structure. This interface is based on section 4.4 of RFC 4137.
40
41It is recommended that the EAP methods would use generic helper
42functions, \ref eap_msg_alloc() and \ref eap_hdr_validate() when processing
43messages. This allows code sharing and can avoid missing some of the
44needed validation steps for received packets. In addition, these
45functions make it easier to change between expanded and legacy EAP
46header, if needed.
47
48When adding an EAP method that uses a vendor specific EAP type
49(Expanded Type as defined in RFC 3748, Chapter 5.7), the new method
50must be registered by passing vendor id instead of EAP_VENDOR_IETF to
51\ref eap_peer_method_alloc(). These methods must not try to emulate
52expanded types by registering a legacy EAP method for type 254. See
53\ref eap_vendor_test.c for an example of an EAP method implementation that
54is implemented as an expanded type.
55
56
57\section used_eap_library Using EAP implementation as a library
58
59The Git repository has an eap_example directory that contains an
60example showing how EAP peer and server code from wpa_supplicant and
61hostapd can be used as a library. The example program initializes both
62an EAP server and an EAP peer entities and then runs through an
63EAP-PEAP/MSCHAPv2 authentication.
64
65\ref eap_example_peer.c shows the initialization and glue code needed to
66control the EAP peer implementation. \ref eap_example_server.c does the
67same for EAP server. \ref eap_example.c is an example that ties in both the
68EAP server and client parts to allow an EAP authentication to be
69shown.
70
71In this example, the EAP messages are passed between the server and
72the peer are passed by direct function calls within the same process.
73In practice, server and peer functionalities would likely reside in
74separate devices and the EAP messages would be transmitted between the
75devices based on an external protocol. For example, in IEEE 802.11
76uses IEEE 802.1X EAPOL state machines to control the transmission of
77EAP messages and WiMax supports optional PMK EAP authentication
78mechanism that transmits EAP messages as defined in IEEE 802.16e.
79
80The EAP library links in number of helper functions from \ref src/utils and
81\ref src/crypto directories. Most of these are suitable as-is, but it may
82be desirable to replace the debug output code in \ref src/utils/wpa_debug.c
83by dropping this file from the library and re-implementing the
84functions there in a way that better fits in with the main
85application.
86
87*/
88