| b.liu | e958203 | 2025-04-17 19:18:16 +0800 | [diff] [blame^] | 1 | /** |
| 2 | \page eap_server_module EAP server implementation |
| 3 | |
| 4 | Extensible Authentication Protocol (EAP) is an authentication framework |
| 5 | defined in RFC 3748. hostapd uses a separate code module for EAP server |
| 6 | implementation. This module was designed to use only a minimal set of |
| 7 | 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 server state |
| 11 | machine and methods. As such, this RFC provides useful information for |
| 12 | understanding the EAP server implementation in hostapd. |
| 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 |
| 17 | wpa_supplicant. These terms should be understood to refer to the |
| 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 |
| 24 | file named eap_server_<name of the method>.c, e.g., \ref eap_server_md5.c. All EAP |
| 25 | methods use the same interface between the server 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 |
| 31 | \ref eap_server_register_methods() function of \ref eap_server_methods.c. Each EAP |
| 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 | |
| 36 | EAP 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 |
| 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 |
| 42 | functions, \ref eap_msg_alloc() and \ref eap_hdr_validate() when processing |
| 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 |
| 51 | \ref eap_server_method_alloc(). These methods must not try to emulate |
| 52 | expanded types by registering a legacy EAP method for type 254. See |
| 53 | \ref eap_server_vendor_test.c for an example of an EAP method implementation that |
| 54 | is implemented as an expanded type. |
| 55 | |
| 56 | */ |