[thirdparty/hostap.git] / doc / eap_server.doxygen

/**
\page eap_server_module EAP server implementation

Extensible Authentication Protocol (EAP) is an authentication framework
defined in RFC 3748. hostapd uses a separate code module for EAP server
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 server state
machine and methods. As such, this RFC provides useful information for
understanding the EAP server implementation in hostapd.

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_server_<name of the method>.c, e.g., \ref eap_server_md5.c. All EAP
methods use the same interface between the server 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
\ref eap_server_register_methods() function of \ref eap_server_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 \ref eap_i.h. struct
\ref 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, \ref eap_msg_alloc() and \ref 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
\ref eap_server_method_alloc(). These methods must not try to emulate
expanded types by registering a legacy EAP method for type 254. See
\ref eap_server_vendor_test.c for an example of an EAP method implementation that
is implemented as an expanded type.

*/
Commit	Line	Data
30c28971 JM	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
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_server_<name of the method>.c, e.g., \ref eap_server_md5.c. All EAP
30c28971 JM	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
5eb513c3	31	\ref eap_server_register_methods() function of \ref eap_server_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 JM	36	EAP methods must implement the interface defined in \ref eap_i.h. struct
5eb513c3 JM	37	\ref eap_method defines the needed function pointers that each EAP method
30c28971 JM	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_server_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_server_vendor_test.c for an example of an EAP method implementation that
30c28971 JM	54	is implemented as an expanded type.
	55
	56	*/