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 */ 57