doc/eap.doxygen

   1 /**
   2 \page eap_peer_module EAP peer implementation
   3
   4 Extensible Authentication Protocol (EAP) is an authentication framework
   5 defined in RFC 3748. %wpa_supplicant uses a separate code module for EAP
   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
  12 understanding the EAP peer implementation in %wpa_supplicant.
  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_<name of the method>.c, e.g., eap_md5.c. All EAP
  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
  31 eap_peer_register_methods() function of eap_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 eap_i.h. struct
  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
  42 functions, eap_msg_alloc() and 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 eap_peer_method_alloc(). These methods must not try to emulate
  52 expanded types by registering a legacy EAP method for type 254. See
  53 eap_vendor_test.c for an example of an EAP method implementation that
  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
  60 example showing how EAP peer and server code from %wpa_supplicant and
  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
  65 eap_example_peer.c shows the initialization and glue code needed to
  66 control the EAP peer implementation. eap_example_server.c does the
  67 same for EAP server. eap_example.c is an example that ties in both the
  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
  80 The EAP library links in number of helper functions from src/utils and
  81 src/crypto directories. Most of these are suitable as-is, but it may
  82 be desirable to replace the debug output code in src/utils/wpa_debug.c
  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 */