| /** |
| \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., 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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. |
| |
| 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 |
| 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 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 |
| by dropping this file from the library and re-implementing the |
| functions there in a way that better fits in with the main |
| application. |
| |
| */ |