import from HEAD:

[freeradius.git] / doc / rlm_eap

            Extensible Authentication Protocol (EAP)


INTRODUCTION

  Extensible Authentication Protocol(EAP), rfc2284, is a general protocol 
  that allows network access points to support multiple authentication 
  methods. Each EAP-Type indicates a specific authentication mechanism. 
  802.1x standard authenticates wireless LAN users trying to access
  enterprise networks.

  RADIUS attribute used for EAP is EAP-Message, 79(rfc2869). RADIUS 
  communicates all EAP messages by embedding them in this attribute.

  General Terminology
  Supplicant/EAP Client - is the software on the end-user/client machine
                          (machine with the wireless card).
  Authenticator/NAS/Access Point(AP) -  A network device providing users 
                                    with a point of entry into the network.
  EAPOL - EAP over LAN as defined in 802.1x standard.
  EAPOW - EAP over Wireless.


   +----------+        +----------+        +----------+
   |          |  EAPOL |          | RADIUS |          |
   |  EAP     |<------>|  Access  |<------>|  RADIUS  |
   |  Client  |  EAPOW |  Point   |  (EAP) |  Server  |
   |          |        |          |        |          |
   +----------+        +----------+        +----------+


   The sequence of events, for EAP-MD5, runs as follows:
    1. The end-user associates with the Access Point(AP).
    2. The supplicant specifies AP to use EAP by sending EAP-Start.
    3. AP requests the supplicant to Identify itself (EAP-Identity).
    4. Supplicant then sends its Identity (username) to the AP.
    5. AP forwards this EAP-response AS-IS to the RADIUS server.
       (The supplicant and the RADIUS server mutually authenticate via AP.
       AP just acts as a passthru till authentication is finished.)
    6. The server sends a challenge to the supplicant.
    7. The supplicant carries out a hash on the password and sends 
       this hashed password to the RADIUS server as its response.
    8. The RADIUS server performs a hash on the password for that supplicant 
       in its user database and compares the two hashed values and 
       authenticates the client if the two values match(EAP-Success/EAP-Failure)
    9. AP now opens a port to accept data from the end-user.

  Currently, EAP is widely used in wireless networks than in wired networks.
  In 802.11/wireless based networking, following sequence of events happen in 
  addition to the above EAP events.

   10. RADIUS server and the supplicant agree to a specific WEP key.
   11. The supplicant loads the key ready for logging on.
   12. The RADIUS server sends the key for this session (Session key) to the AP.
   13. The AP encrypts its Broadcast key with the Session key
   14. The AP sends the encypted key to the supplicant
   15. The supplicant decrypts the Broadcast key with the Session key and 
       the session continues using the Broadcast and Session keys until 
       the session ends.

  References:
        The Implementation of EAP over RADIUS is based on the following RFCs
        rfc2869 -- RADIUS Extensions
        rfc2284 -- PPP Extensible Authentication Protocol (EAP)
        rfc2716 -- PPP EAP TLS Authentication Protocol

  Following links help to understand HOW EAP works
        www.ieee802.org/1/mirror/8021/docs2000/ieee_plenary.PDF 


EAP CODE ORGANIZATION

  EAP is implemented as a module in freeradius 
  and the code is placed in src/modules/rlm_eap. 
  All EAP-Types are organized as subdirectories in rlm_eap/types/.
  Currently Freeradius supports only 2 EAP-Types (EAP-MD5, EAP-TLS).

  Each EAP-Type, like types/rlm_eap_md5, contains a chunk of code that 
  knows how to deal with a particular kind of authentication mechanism. 

  To add a new EAP-Type then a new directory should be created as 
  rlm_eap/types/rlm_eap_XXXX, where XXXX is EAP-Type name 
  ie for EAP-Type like ONE TIME PASSWORD (OTP) it would be rlm_eap_otp 

  src/modules/rlm_eap -- contains the basic EAP and generalized interfaces 
    to all the EAP-Types.
  rlm_eap/types -- contains all the supported EAP-Types
  rlm_eap/types/rlm_eap_md5  -- EAP-MD5 authentication.
  rlm_eap/types/rlm_eap_tls  -- EAP-TLS based authentication.
  rlm_eap/types/rlm_eap_leap -- Cisco LEAP authentication.
  rlm_eap/types/rlm_eap_sim  -- EAP-SIM (GSM) based authentication
   
CONFIGURATION

  Add the eap configuration stanza to the modules section in radiusd.conf
  to load and control rlm_eap and all the supported EAP-Types:

  For example:
        modules {
                ...
                eap {
                        default_eap_type = md5

                        md5 {
                        }
                    ...
                }
                ...
        }

  NOTE: You cannot have empty eap stanza. At least one EAP-Type sub-stanza  
  should be defined as above, otherwise the server will not know what type
  of eap authentication mechanism to be used and the server will exit 
  with error.

  All the various options and their associated default values for each
  EAP-Type are documented in the sample radiusd.conf that is provided 
  with the distribution.

  Since the EAP requests may not contain a requested EAP type, the
  'default_eap_type' configuration options is used by the EAP module
  to determine which EAP type to choose for authentication.

  NOTE: EAP cannot authorize a user. It can only authenticate.
  Other Freeradius modules authorize the user and lets EAP to authenticate.

  NOTE: There can only be one instance of the EAP module.

EAP SIM server

  To configure EAP-SIM authentication, the following attributes must be
  set in the server. This can be done in the users file, but in many cases
  will be taken from a database server, via one of the SQL interface.

  If one has SIM cards that one controls (i.e. whose share secret you know), 
  one should be able to write a module to generate these attributes
  (the triplets) in the server. 

  If one has access to the SS7 based settlement network, then a module to
  fetch appropriate triplets could be written. This module would act as
  an authorization only module.

  The attributes are:
        EAP-Sim-Rand1           16 bytes
        EAP-Sim-SRES1            4 bytes
        EAP-Sim-KC1              8 bytes
        EAP-Sim-Rand2           16 bytes
        EAP-Sim-SRES2            4 bytes
        EAP-Sim-KC2              8 bytes
        EAP-Sim-Rand3           16 bytes
        EAP-Sim-SRES3            4 bytes
        EAP-Sim-KC3              8 bytes

  EAP-SIM will send WEP attributes to the resquestor.

EAP CLIENTS

  1. XSupplicant - freeradius (EAP/TLS) notes may be found at:

   http://www.eax.com/802/
   or http://www.missl.cs.umd.edu/wireless/eaptls/

   XSupplicant is hosted by:

   http://www.open1x.org/

  2. XP - freeradius (EAP/TLS) notes may be found at: 

   http://www.denobula.com/EAPTLS.pdf

  3. Freeradius has an "radeapclient" that can do EAP-MD5 (passwords),
     as well as EAP-SIM. It is in modules/rlm_eap/radeapclient.

TESTING

  You will find several test cases in src/tests/ for the EAP-SIM code.


HOW DO I USE IT (FAQ/Examples)

  1. How can I enable EAP-MD5 authentication ?

  In radiusd.conf

        modules {
                ...
                eap {
                        default_eap_type = md5
                        md5 {
                        }
                    ...
                }
                ...
        }
 
        # eap sets the authenticate type as EAP
        authorize {
                ...
                eap
        }

        # eap authentication takes place.
        authenticate {
                eap
        }

        # If you are proxying EAP-LEAP requests
        # This is required to make LEAP work.
        post-proxy {
                eap
        }
  
  2. My Userbase is in LDAP and I want to use EAP-MD5 authentication 

  In radiusd.conf

        modules {
                ...
                eap {
                        default_eap_type = md5
                        md5 {
                        }
                    ...
                }
                ...
        }
 
        # ldap gets the Configured password.
        # eap sets the authenticate type as EAP
        authorize {
                ldap
                eap
        }

        # eap authentication takes place.
        authenticate {
                eap
        }

  3. How can I Proxy EAP messages, with/without User-Name attribute
      in the Access-Request packets 

   With User-Name attribute in Access-Request packet,
   EAP-proxying is just same as RADIUS-proxying.

   If User-Name attribute is not present in Access-Request packet,
   Freeradius can proxy the request with the following configuration
   in radiusd.conf

   # eap module should be configured as the First module in 
   # the authorize stanza

        authorize {
                eap
                ...  other modules.
        }

   With this configuration, eap_authorize creates User-Name attribute
   from EAP-Identity response, if it is not present.
   Once User-Name attribute is created, RADIUS proxying takes care
   of EAP proxying.

  4. How Freeradius can handle EAP-START messages ?

   In most of the cases this is handled by the Authenticator.

   Only if it is required then, in radiusd.conf

        authorize {
                eap
                ...  other modules.
        }

   With the above configuration, RADIUS server immediately responds with
   EAP-Identity request.
        
   NOTE: EAP doesnot check for any Identity or maintains any state in case
   of EAP-START. It blindly responds with EAP-Identity request.
   Proxying is handled only after EAP-Identity response is received.

  5. I want to enable multiple EAP-Types, how can I configure ?
  
  In radiusd.conf

        modules {
                ...
                eap {
                        default_eap_type = tls
                        md5 {
                        }
                        tls {
                                ...
                        }
                    ...
                }
                ...
        }

   The above configuration will let the server load all the EAP-Types,
   but the server can have only one default EAP-Type, as above.

   Once EAP-Identity response is received by the server, based on the
   default_eap_type, the server will send a new request (MD5-Challenge 
   request incase of md5, TLS-START request incase of tls) to the supplicant.
   If the supplicant is rfc2284 compliant and doesnot support the
   EAP-Type sent by the server then it sends EAP-Acknowledge with the
   supported EAP-Type. If this EAP-Type is supported by the server then it 
   will send the respective EAP-request.
  
   Example: If the supplicant supports only EAP-MD5 but the server
   default_eap_type is configured as EAP-TLS, as above, then the server
   will send TLS-START after EAP-Identity is received. Supplicant will
   respond with EAP-Acknowledge(EAP-MD5). Server now responds with
   MD5-Challenge.


INSTALLATION
  EAP, EAP-MD5, and Cisco LEAP do not require any additional packages.
  Freeradius contains all the required packages.

  For EAP-TLS, OPENSSL, <http://www.openssl.org/>, is required to be installed.
  Any version from 0.9.7, should fairly work with this module.

  EAP-SIM should not require any additional packages.


CAVEATS
    It probably still has bugs.  Most notably, there is a small memory
    leak somewhere in the eap_tls code.  I suspect it's because of my 
    misuse of OPENSSL libraries, but I have no proof yet.

IMPLEMENTATION (For Developers)

  The rlm_eap module only deals with EAP specific authentication mechanism
  and the generic interface to interact with all the EAP-Types. 

  Currently, these are the existing interfaces,
        int     attach(CONF_SECTION *conf, void **type_arg);
        int     initiate(void *type_arg, EAP_HANDLER *handler);
        int     authenticate(void *type_arg, EAP_HANDLER *handler);
        int     detach(void **type_arg);

  attach() and detach() functions allocate and deallocate all the 
  required resources.

  initiate() function begins the conversation when EAP-Identity response 
  is received. Incase of EAP-MD5, initiate() function sends the challenge.

  authenticate() function uses specific EAP-Type authentication mechanism
  to authenticate the user. During authentication many EAP-Requests and
  EAP-Responses takes place for each authentication. Hence authenticate()
  function may be called many times. EAP_HANDLER contains the complete 
  state information required.


HOW EAP WORKS
  as posted to the list, by John Lindsay <jlindsay@internode.com.au>

  To make it clear for everyone, the supplicant is the software on the
  client (machine with the wireless card).

  The EAP process doesn't start until the client has associated with
  the Access Point using Open authentication.  If this process isn't
  crystal clear you need to go away and gain understanding.

  Once the association is made the AP blocks all traffic that is not
  802.1x so although associated the connection only has value for EAP.
  Any EAP traffic is passed to the radius server and any radius traffic
  is passed back to the client.

  So, after the client has associated to the Access Point, the
  supplicant starts the process for using EAP over LAN by asking the
  user for their logon and password.

  Using 802.1x and EAP the supplicant sends the username and a one-way
  hash of the password to the AP.

  The AP encapsulates the request and sends it to the RADIUS server.

  The radius server needs a plaintext password so that it can perform
  the same one-way hash to determine that the password is correct.  If
  it is, the radius server issues an access challenge which goes back
  via to the AP to the client. (my study guide says client but my
  brain says 'supplicant')

  The client sends the EAP response to the challenge via the AP to the
  RADIUS server.

  If the response is valid the RADIUS server sends a success message
  and the session WEP key (EAP over wireless) to the client via the
  AP.  The same session WEP key is also sent to the AP in the success
  packet.

  The client and the AP then begin using session WEP keys. The WEP key
  used for multicasts is then sent from the AP to the client.  It is
  encrypted using the session WEP key.

ACKNOWLEDGEMENTS
   Primary author - Raghu <raghud@mail.com>

   EAP-SIM       - Michael Richardson <mcr@sandelman.ottawa.on.ca>
                    The development of the EAP/SIM support was funded by
                    Internet Foundation Austria (http://www.nic.at/ipa).