Navigation


Changes between Version 1 and Version 2 of TBEAP


Ignore:
Timestamp:
Mar 3, 2011, 4:55:26 PM (12 years ago)
Author:
Administrator
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TBEAP

    v1 v2  
    1 [[PageOutline(2-5)]]
    2 == EAP Testbed ==
     1[[PageOutline(2-4)]]
     2= EAP Testbed =
    33
    44This testbed demonstrates a complete EAP authentication system, using a standard RADIUS-capable access point (hostapd), a RADIUS/Diameter translation agent, and Diameter EAP backend.
     
    3737----
    3838
    39 === Configuration files ===
     39== Configuration files ==
    4040
    41 ==== supauth.eap.testbed.aaa ====
     41=== supauth.eap.testbed.aaa ===
    4242
    43 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}}}.
     43This 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}}}.
    4444
    4545In order to use this virtual wireless link, you need to enable the support for this module in your kernel with:
    4646{{{
    47 modprobe mac80211_hwsim
     47#!sh
     48$ sudo modprobe mac80211_hwsim
    4849}}}
    4950
    5051Then, 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.
    5152
    52 ===== hostapd (virtual link part) =====
     53==== hostapd (virtual link part) ====
    5354 [source:VirtualTestbed/conf/supauth.eap.testbed.aaa/hostapd/build.config build.config]::
    5455     The configuration file we use to build our {{{hostapd}}} daemon. The next file shows how we use it.
     
    5859
    5960 [source:VirtualTestbed/scripts/hostapd-run.sh hostapd-run.sh]::
    60      We use this script to start the {{{hostapd}}} daemon on the virtual machine.
     61     We use this script to start the {{{hostapd}}} daemon on the machine.
    6162
    62 ===== wpasupplicant (virtual link part) =====
     63==== wpasupplicant (virtual link part) ====
    6364 [source:VirtualTestbed/conf/supauth.eap.testbed.aaa/wpasupplicant/build.config build.config]::
    64      The configuration file we use to build our {{{wpasupplicant}}} daemon. The next file shows how we use it.
     65     The configuration file we use to build the {{{wpasupplicant}}} daemon.
    6566
    6667 [source:VirtualTestbed/scripts/wpasupplicant-install.sh wpasupplicant-install.sh]::
     
    6869
    6970 [source:VirtualTestbed/scripts/wpasupplicant-run.sh wpasupplicant-run.sh]::
    70      We use this script to start the {{{wpasupplicant}}} daemon on the virtual machine.
     71     We use this script to start the {{{wpasupplicant}}} daemon on the machine.
    7172
    72 Now, we use the following setup files for the daemons.
     73==== hostapd (configuration) ====
    7374
    74 ===== hostapd (configuration) =====
     75These are the configuration files we use with these daemons.
     76
    7577 [source:VirtualTestbed/conf/supauth.eap.testbed.aaa/hostapd/hostapd.conf hostapd.conf]::
    76    This is the configuration for running hostapd. Note the following:
     78   This is the configuration for hostapd. The following are important:
    7779    * {{{ieee8021x=1}}} : Use 802.1X authentication (EAP) for authenticating the clients.
    7880    * {{{auth_server_addr=192.168.105.30}}} : The adress of the RADIUS server, in our case the translation agent ({{{gw.eap.testbed.aaa}}}).
    79     * {{{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.
    80     * {{{wpa=2; wpa_key_mgmt=WPA-EAP; wpa_pairwise=CCMP}}} : We have configured our testbed to use WPA2.
    81     * you may also have a look at the other parameters in the file, it provides a working setup for us.
     81    * {{{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.
     82    * {{{wpa=2; wpa_key_mgmt=WPA-EAP; wpa_pairwise=CCMP}}} : We use WPA2 in our testbed.
     83    * You may also have a look at the other parameters in our example file, they provide a working setup for us.
    8284
    83 ===== wpasupplicant (configuration) =====
     85==== wpasupplicant (configuration) ====
    8486 [source:VirtualTestbed/conf/supauth.eap.testbed.aaa/wpasupplicant/wpa_supplicant.conf wpa_supplicant.conf]::
    8587   The configuration of our wireless client daemon.
    8688    * {{{ssid="mac80211 test"; key_mgmt=WPA-EAP; proto=WPA2; pairwise=CCMP; group=CCMP}}} : These parameters must match the configuration of your {{{hostapd}}}.
    87     * {{{eap=TLS}}} : We are using EAP-TLS method with the server. This must match the configuration of the backend {{{app_diameap.fdx}}} extension.
    88     * {{{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.
    89     * {{{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.
     89    * {{{eap=TLS}}} : We are using EAP-TLS method with the server. This must match the configuration of the backend [wiki:app_diameap.fdx] extension.
     90    * {{{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.
     91    * {{{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.
    9092
    91 ==== gw.eap.testbed.aaa ====
     93=== gw.eap.testbed.aaa ===
    9294
    93 This peer runs {{{freeDiameter}}} with the {{{app_radgw.fdx}}} extension:
     95This peer runs {{{freeDiameter}}} with the [wiki:app_radgw.fdx] extension.
    9496 [source:VirtualTestbed/conf/gw.eap.testbed.aaa/freeDiameter/CMakeFlags CMakeFlags]::
    95   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.
     97  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.
    9698
    9799 [source:VirtualTestbed/conf/gw.eap.testbed.aaa/freeDiameter/freeDiameter.conf freeDiameter.conf]::
    98   The main configuration of freeDiameter. Most notable directive is {{{LoadExtension = "/root/freeDiameter/extensions/app_radgw.fdx" : "/root/conf/freeDiameter/rgw.conf";}}}.
    99   Note also that we need the dictionary objects of RFC4005 and RFC4072. The extension receives the {{{rgw.conf}}} configuration file described bellow.
     100  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.
     101  Note also that we need the dictionary objects of RFC4005 and RFC4072 to be loaded ([wiki:dict_nasreq.fdx] and [wiki:dict_eap.fdx]).
    100102
    101103 [source:VirtualTestbed/conf/gw.eap.testbed.aaa/freeDiameter/rgw.conf rgw.conf]::
    102104  The configuration file for RADIUS/Diameter translation extension.
    103    * {{{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.
    104    * {{{RGWX = "/root/freeDiameter/extensions/acct.rgwx" : acct : 4;}}} : We also convert RADIUS Accounting messages to Diameter Base Accounting.
    105    * 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.
     105   * {{{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.
     106   * {{{RGWX = "acct.rgwx" : acct : 4;}}} : We also convert RADIUS Accounting messages to Diameter Base Accounting, using the "acct.rgwx" module.
     107   * 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.
    106108   * {{{cli = 192.168.105.10 / "radiusecret" ;}}} : We declare here the accepted RADIUS clients. The shared secret must match the one from {{{hostapd}}} configuration.
    107109
    108110
    109 ==== backend.eap.testbed.aaa ====
     111=== backend.eap.testbed.aaa ===
    110112
    111 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.
     113We use two different extensions at the same time on this machine:
     114 * [wiki:app_diameap.fdx] implements the Diameter EAP application server, and allows the authentication and authorization of the clients.
     115 * [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]).
    112116
    113 ===== app_diameap.fdx =====
     117The [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.
     118
     119==== app_diameap.fdx ====
    114120
    115121This extension uses a MySQL backend database to lookup clients information. In order to setup the database, the following steps should be followed:
    116122 * 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:
    117123{{{
     124#!sql
    118125CREATE USER diameap@localhost IDENTIFIED BY 'eapdiam';
    119126CREATE DATABASE diameap;
     
    122129 * Then, create the database structure. The file [source:extensions/app_diameap/diameap.sql] contains the SQL code to use for this purpose:
    123130{{{
     131#!sh
    124132mysql -u diameap -p -D diameap < ./extensions/app_diameap/diameap.sql
    125133}}}
    126  * 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).
     134 * 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).
    127135
    128136 [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/app_diameap.conf app_diameap.conf]::
    129137  The configuration file for the {{{app_diameap.fdx}}} extension:
    130138   * {{{DiamEAP_MySQL = "diameap", "eapdiam", "localhost", "diameap";}}} : how to connect to the MySQL database.
    131   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.
    132    * {{{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.
    133    * {{{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.
     139  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.
     140   * {{{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.
     141   * {{{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).
    134142
    135143 [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/eap_tls.conf eap_tls.conf]::
    136   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'''.
     144  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.
    137145
    138 ===== app_acct.fdx =====
     146==== app_acct.fdx ====
    139147
    140 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).
     148The 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).
    141149
    142 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.
     150This 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.
    143151
    144 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:
     152The 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.
    145153 [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/app_acct.sql app_acct.sql]::
    146    The structure of the table we are using in our test.
     154   The structure of the table we are using in our testbed.
    147155
    148 Once this table is created, the following configuration file can be used with the {{{app_acct.fdx}}} extension:
     156Once this table is created, the following configuration file can be used with the [wiki:app_acct.fdx] extension:
    149157 [source:VirtualTestbed/conf/backend.eap.testbed.aaa/freeDiameter/app_acct.conf app_acct.conf]::
    150    * {{{ConnInfo = "user=root dbname=root";}}} : the connection string used to connect to the database. See PostgreSQL manual for more information.
    151    * {{{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.
     158   * {{{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.
     159   * {{{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.
    152160   * {{{"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.
    153161