[[PageOutline(2-4)]]
= 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 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:
{{{
#!sh
$ sudo 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 machine.

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

 [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 machine.

==== hostapd (configuration) ====

These are the configuration files we use with these daemons.

 [source:VirtualTestbed/conf/supauth.eap.testbed.aaa/hostapd/hostapd.conf hostapd.conf]::
   This is the configuration for hostapd. The following are important:
    * {{{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}}} [wiki:app_radgw.fdx] configuration.
    * {{{wpa=2; wpa_key_mgmt=WPA-EAP; wpa_pairwise=CCMP}}} : We use WPA2 in our testbed.
    * You may also have a look at the other parameters in our example file, they provide 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 [wiki: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. Note that EAP-TLS does not support anonymous identity. You will need EAP-TTLS for this.
    * {{{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 [wiki:app_diameap.fdx] extension. These credentials are not related to freeDiameter TLS parameters, and should not use the same CA at all.

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

This peer runs {{{freeDiameter}}} with the [wiki: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 + its extensions.

 [source:VirtualTestbed/conf/gw.eap.testbed.aaa/freeDiameter/freeDiameter.conf freeDiameter.conf]::
  The main configuration file of freeDiameter. Most notable directive is {{{LoadExtension = "app_radgw.fdx" : "rgw.conf";}}} that show how {{{app_radgw.fdx}}} receives the {{{rgw.conf}}} configuration file described bellow.
  Note also that we need the dictionary objects of RFC4005 and RFC4072 to be loaded ([wiki:dict_nasreq.fdx] and [wiki:dict_eap.fdx]).

 [source:VirtualTestbed/conf/gw.eap.testbed.aaa/freeDiameter/rgw.conf rgw.conf]::
  The configuration file for RADIUS/Diameter translation extension.
   * {{{RGWX = "auth.rgwx" : auth : 1;}}} : We use the "auth" module to convert Access-Request messages (code 1) received on the RADIUS ''auth''entication port (1812 by defaut). This "auth.rgwx" module is suitable for NASREQ and EAP authentications. In order to convert different RADIUS messages (for example SIP -- RFC5090), a different module would be loaded instead here.
   * {{{RGWX = "acct.rgwx" : acct : 4;}}} : We also convert RADIUS Accounting messages to Diameter Base Accounting, using the "acct.rgwx" module.
   * The "echo_drop.rgwx" module might be used to handle some attributes that do not need to be translated to Diameter, and either discard these (drop) or send them back in the RADIUS answer (echo). 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:
 * [wiki:app_diameap.fdx] implements the Diameter EAP application server, and allows the authentication and authorization of the clients.
 * [wiki:app_acct.fdx] provides the accounting part (Diameter Base Accounting application) and stores accounting records into a database, for offline processing (see [freeDiameter/contrib/app_acct_tools/README this example]). 

The [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/CMakeFlags CMakeFlags] and [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/freeDiameter.conf freeDiameter.conf] files 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:
{{{
#!sql
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:
{{{
#!sh
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] (see 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.
  The [wiki:app_diameap.fdx] extension is extensible to reflect the EAP protocol. We therefore need to load the different EAP methods that we want our backend to support. See the [wiki:app_diameap.fdx extension's page] for more details.
   * {{{Load_plugin = "EAP Identity":1:0:"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:"eap_tls.emp":"eap_tls.conf";}}} : We use the EAP-TLS method in our testbed. This method requires an additional configuration file (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 for authenticating the users. 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''' -- and should not use the same CA.

==== 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 [wiki:app_acct.fdx] extension (that could reside on a different server) provides the server part of the Diameter Base 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, it can be adapted to any accounting requirements easily.

The first step is to create the PostgreSQL database that will 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 on this in the [source:freeDiameter/INSTALL.FreeBSD INSTALL.FreeBSD] and [source:freeDiameter/contrib/nightly_tests/README contrib/nightly_tests/README] files. Once the database is created, you will need to create a table for receiving the data. The structure of the table depends on the accounting data you will be collecting. The following is what we use in our testbed.
 [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/app_acct.sql app_acct.sql]::
   The structure of the table we are using in our testbed.

Once this table is created, the following configuration file can be used with the [wiki: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 [http://www.postgresql.org/docs/8.4/interactive/libpq-connect.html PostgreSQL manual] for more information on this string.
   * {{{Timestamp_field = "recorded_on";}}} : optional. When present, this field in the database will receive the timestamp of when the accounting record has been received by the freeDiameter 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.


----