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