[[PageOutline(2-5)]]
== EAP Testbed == 

This testbed demonstrates a complete EAP authentication system, using a standard RADIUS-capable access point (hostapd), a RADIUS/Diameter translation agent, and Diameter EAP backend. 

The following scheme shows the components (blue link is RADIUS, green is Diameter).

{{{
#!graphviz
graph G { 
    graph [bgcolor="#E8E8E8C8"];
    node [shape=box];
    supauth [ 
         shape=plaintext
         label=<
 <TABLE BORDER="1" CELLBORDER="0" CELLSPACING="1">
 <TR><TD>supauth.eap.testbed.aaa</TD></TR>
 <TR><TD>
  <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
    <TR><TD>wpasupplicant</TD><TD PORT="hap">hostapd</TD></TR> </TABLE>
  </TD></TR></TABLE>
>
         URL="#supauth.eap.testbed.aaa"]
    gw [ 
         label="gw.eap.testbed.aaa"
         URL="#gw.eap.testbed.aaa"
    ]
    backend [ 
         label="backend.eap.testbed.aaa"
         URL="#backend.eap.testbed.aaa"
    ]
    supauth:hap -- gw [color=blue]; 
    gw -- backend [color=green]; 
}
}}}

----

=== Configuration files ===

==== supauth.eap.testbed.aaa ====

This virtual machine runs both the wpa_supplicant (wireless client) and hostapd (access point) software. It uses a virtual wireless link provided by the Linux kernel, called {{{mac80211_hwsim}}}. 

In order to use this virtual wireless link, you need to enable the support for this module in your kernel with:
{{{
modprobe mac80211_hwsim
}}}

Then, you must configure your {{{hostapd}}} and {{{wpasupplicant}}} to use this virtual link. The following files show how we do it in our testbed. Your mileage may vary, of course, especially if you use a real wireless interface.

===== hostapd (virtual link part) =====
 [source:VirtualTestbed/conf/supauth.eap.testbed.aaa/hostapd/build.config build.config]::
     The configuration file we use to build our {{{hostapd}}} daemon. The next file shows how we use it.

 [source:VirtualTestbed/scripts/hostapd-install.sh hostapd-install.sh]::
     This script installs the dependencies and then builds {{{hostapd}}} from source, using our configuration. You will probably need to change some parts of the script for your own setup.

 [source:VirtualTestbed/scripts/hostapd-run.sh hostapd-run.sh]::
     We use this script to start the {{{hostapd}}} daemon on the virtual machine.

===== wpasupplicant (virtual link part) =====
 [source:VirtualTestbed/conf/supauth.eap.testbed.aaa/wpasupplicant/build.config build.config]::
     The configuration file we use to build our {{{wpasupplicant}}} daemon. The next file shows how we use it.

 [source:VirtualTestbed/scripts/wpasupplicant-install.sh wpasupplicant-install.sh]::
     This script installs the dependencies and then builds {{{wpasupplicant}}} from source, using our configuration. You will probably need to change some parts of the script for your own setup.

 [source:VirtualTestbed/scripts/wpasupplicant-run.sh wpasupplicant-run.sh]::
     We use this script to start the {{{wpasupplicant}}} daemon on the virtual machine.

Now, we use the following setup files for the daemons.

===== hostapd (configuration) =====
 [source:VirtualTestbed/conf/supauth.eap.testbed.aaa/hostapd/hostapd.conf hostapd.conf]::
   This is the configuration for running hostapd. Note the following:
    * {{{ieee8021x=1}}} : Use 802.1X authentication (EAP) for authenticating the clients.
    * {{{auth_server_addr=192.168.105.30}}} : The adress of the RADIUS server, in our case the translation agent ({{{gw.eap.testbed.aaa}}}).
    * {{{auth_server_shared_secret=radiusecret}}} : The shared secret with the translation agent; it can be anything but you must set the same secret in the {{{gw.eap.testbed.aaa}}} configuration.
    * {{{wpa=2; wpa_key_mgmt=WPA-EAP; wpa_pairwise=CCMP}}} : We have configured our testbed to use WPA2.
    * you may also have a look at the other parameters in the file, it provides a working setup for us.

===== wpasupplicant (configuration) =====
 [source:VirtualTestbed/conf/supauth.eap.testbed.aaa/wpasupplicant/wpa_supplicant.conf wpa_supplicant.conf]::
   The configuration of our wireless client daemon.
    * {{{ssid="mac80211 test"; key_mgmt=WPA-EAP; proto=WPA2; pairwise=CCMP; group=CCMP}}} : These parameters must match the configuration of your {{{hostapd}}}.
    * {{{eap=TLS}}} : We are using EAP-TLS method with the server. This must match the configuration of the backend {{{app_diameap.fdx}}} extension.
    * {{{identity="client@eap.testbed.aaa"}}} : The identity we are presenting to EAP. It is used by the server to select the appropriate EAP method, and verify our credentials. Since the identity contains a domain part (...@eap.testbed.aaa) the message may be routed to a different realm in Diameter, if needed.
    * {{{ca_cert, client_cert, private_key}}} : those are the credentials we use for the EAP-TLS authentication. It must also match the configuration of the backend's {{{app_diameap.fdx}}} extension.

==== gw.eap.testbed.aaa ====

This peer runs {{{freeDiameter}}} with the {{{app_radgw.fdx}}} extension:
 [source:VirtualTestbed/conf/gw.eap.testbed.aaa/freeDiameter/CMakeFlags CMakeFlags]::
  The flags used to compile freeDiameter. Note the use of {{{-DBUILD_APP_RADGW:BOOL=ON}}} and all {{{-DBUILD_RGWX_*}}} directives, pertaining to the RADIUS/Diameter gateway.

 [source:VirtualTestbed/conf/gw.eap.testbed.aaa/freeDiameter/freeDiameter.conf freeDiameter.conf]::
  The main configuration of freeDiameter. Most notable directive is {{{LoadExtension = "/root/freeDiameter/extensions/app_radgw.fdx" : "/root/conf/freeDiameter/rgw.conf";}}}. 
  Note also that we need the dictionary objects of RFC4005 and RFC4072. The extension receives the {{{rgw.conf}}} configuration file described bellow.

 [source:VirtualTestbed/conf/gw.eap.testbed.aaa/freeDiameter/rgw.conf rgw.conf]::
  The configuration file for RADIUS/Diameter translation extension.
   * {{{RGWX = "/root/freeDiameter/extensions/auth.rgwx" : auth : 1;}}} : We use the "auth" module to convert Access-Request messages (code 1) received on the RADIUS authentication port (1812 by defaut). This "auth" module is suitable for NASREQ and EAP authentications. In order to convert different RADIUS messages (for example SIP -- RFC5090), one would load a different module here.
   * {{{RGWX = "/root/freeDiameter/extensions/acct.rgwx" : acct : 4;}}} : We also convert RADIUS Accounting messages to Diameter Base Accounting.
   * The echo_drop extension might be used to handle some attributes that do not need to be translated to Diameter, and either discarded or sent back in the RADIUS answer. The file [source:VirtualTestbed/conf/gw.eap.testbed.aaa/freeDiameter/echo_drop.rgwx.conf echo_drop.rgwx.conf] gives an example of such configuration.
   * {{{cli = 192.168.105.10 / "radiusecret" ;}}} : We declare here the accepted RADIUS clients. The shared secret must match the one from {{{hostapd}}} configuration.


==== backend.eap.testbed.aaa ====

We use two different extensions at the same time on this machine. The first one is {{{app_diameap.fdx}}}, which provides support for Diameter EAP application, and allows the authentication and authorization of the clients. The second one is {{{app_acct.fdx}}} which provides the accounting part, by storing the accounting records into a database, for further processing (not provided in our system at this time). The [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/CMakeFlags CMakeFlags] and [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/freeDiameter.conf freeDiameter.conf] are trivial.

===== app_diameap.fdx =====

This extension uses a MySQL backend database to lookup clients information. In order to setup the database, the following steps should be followed:
 * Create a new empty database "diameap", and grant priviledges to a new user "diameap" (password "eapdiam"), as follow -- of course, you must replace these values with your own database / user / password:
{{{
CREATE USER diameap@localhost IDENTIFIED BY 'eapdiam';
CREATE DATABASE diameap;
GRANT ALL PRIVILEGES ON diameap.* TO diameap@localhost;
}}}
 * Then, create the database structure. The file [source:extensions/app_diameap/diameap.sql] contains the SQL code to use for this purpose:
{{{
mysql -u diameap -p -D diameap < ./extensions/app_diameap/diameap.sql
}}}
 * Finally, we will create our users in the database. The following file shows our test user, matching the {{{wpasupplicant}}} configuration we created earlier: [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/app_diameap.sql app_diameap.sql]. This entry simply tells the EAP subsystem that for a user presenting an EAP identity of "client@eap.testbed.aaa" we will use the EAP method 13, i.e. EAP-TLS. Then, the EAP-TLS specific configuration is stored in the file [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/eap_tls.conf eap_tls.conf] (details bellow).

 [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/app_diameap.conf app_diameap.conf]::
  The configuration file for the {{{app_diameap.fdx}}} extension:
   * {{{DiamEAP_MySQL = "diameap", "eapdiam", "localhost", "diameap";}}} : how to connect to the MySQL database.
  This {{{app_diameap.fdx}}} extension is by it-self extensible (reflecting the EAP protocol), so we then need to load the different EAP methods that our backend does support. See the extension documentation for more details.
   * {{{Load_plugin = "EAP Identity":1:0:"/root/freeDiameter/extensions/eap_identity.emp":"";}}} : You'll probably always need the EAP Identity method, since it is the first method involved.
   * {{{Load_plugin = "EAP TLS":13:0:"/root/freeDiameter/extensions/eap_tls.emp":"/root/conf/freeDiameter/eap_tls.conf";}}} : We use also the EAP-TLS method in our testbed. This method requires an additional configuration file, as explained bellow.

 [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/eap_tls.conf eap_tls.conf]::
  Configuration file for the EAP-TLS method extension. This contains the credentials of the server and the Certificate Authority that we are using. These parameters must match the contents of the wpasupplicant configuration of the client. '''These parameters are unrelated to and independent from the TLS configuration in the main freeDiameter.conf file'''.

===== app_acct.fdx =====

The NAS (hostapd) can optionally send accounting messages to a RADIUS server. We have configured it to send the messages to the gateway, and configured that gateway to translate these messages to Diameter. The {{{app_acct.fdx}}} extension (that could run on a different server) provides the server part of the Diameter Accounting application (RFC3588, application with identity 3). 

This extension stores the accounting data received into a PostgreSQL database, in a very configurable way. The following is a simple example of such configuration, one should be able to adapt to its own accounting requirements easily.

The first step is to create the PostgreSQL database to receive the data. Please check your system documentation for how to create a new database in PostgreSQL and grant access to this database to the user running freeDiameter. You may find some information also in the [source:INSTALL.FreeBSD] file. Once the database is created, we need to create a table for our test:
 [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/app_acct.sql app_acct.sql]::
   The structure of the table we are using in our test.

Once this table is created, the following configuration file can be used with the {{{app_acct.fdx}}} extension:
 [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/app_acct.conf app_acct.conf]::
   * {{{ConnInfo = "user=root dbname=root";}}} : the connection string used to connect to the database. See PostgreSQL manual for more information.
   * {{{Timestamp_field = "recorded_on";}}} : an optional field. When present, it receives a timestamp of when the Accouting Record has been received by the Diameter backend.
   * {{{"Accounting-Record-Type"; "Accounting-Record-Number"; ...}}} : all the AVP from the Accounting-Request that should be saved to the database. Unless specified otherwise, the system assumes the table contains a field with the same name. See the [source:doc/app_acct.conf.sample extension's configuration] for more details.


----