====== Generic RADIUS Driver ======

**Contact:** [[jan@iptel.org|Jan Janak]]

===== Abstract =====
The sip-router server contains several modules that can talk to a RADIUS server. We have acc
module that implements RADIUS accounting (when enabled at compile time), we have auth_radius module 
which implementes digest authentication against a RADIUS server, we have a couple of other modules 
that can be used to retrieve bits of information from a RADIUS server. All these modules depend on 
a RADIUS client library and these is some portion of code that needs to be duplicated in those modules.

The goal of this task is to develop a generic RADIUS module called db_radius which can be then reused
from all other RADIUS-modules. Instead of having acc_radius we will simply use acc_db to do RADIUS
accounting, instead of acc_radius we will use acc_db to perform RADIUS digest authentication, and so
on.

A RADIUS server is in fact nothing else than a special type of database running on a remote host and
speaking the RADIUS protocol, thus we can develop a generic RADIUS database driver which will
convert database operations performed by other sip-router modules through the database abstraction
layer to RADIUS queries.

===== State of the Art =====
RADIUS related functionality is currently scattered across a number of sip-router modules. We have
  * **acc_radius** for RADIUS based accounting.
  * **auth_radius** for RADIUS based digest authentication.
  * **misc_radius** for miscelanous RADIUS based operations (mostly used to retrieve a set of attributes from the RADIUS server).

All three modules share some parts of RADIUS related code. All the modules have similar parameters,
for example, they all need to be configured with a path to the configuration file of the radius
client library. They all need to be provided with the radius attribute dictionary, and so on.

===== Goals =====
The primary goal of this work is to develop a new modules for the sip-router project which will
translate database queries into RADIUS queries and back. How the request are going to be translated
will be driven by a plain-text configuration file. Among other things, the configuration file should:

  * Map database names to RADIUS servers
  * Specify how to translate database table names to RADIUS query types
  * Specify how to translate names of database columns to RADIUS attributes

The module should support at least the following three types of operations:

==== Accounting ====
Accounting is implemented in the acc module of sip-router. The module executed (roughly) the following
SQL query to add a new accounting record to the database:
<code>
insert into acc server_id, from_uid, to_uid, to_did, from_did...
</code>
The generic RADIUS driver should translate this query into a RADIUS accounting request as described in
RFC 2866.

==== Digest Authentication ====
The digest authentication algorithm is implemented in auth_db (which works with database backends) and
auth_radius (which works with RADIUS only). Our goal here is to make auth_db module work with RADIUS
and get rid of auth_radius. 

The module needs to retrieve the password of the user being authenticated. This done by executing a 
"select from credentials" type of query. The generic RADIUS driver should translate queries that select 
data from credentials table into RADIUS digest authentication queries as decribed RFC 4590.

==== Get Attributes from RADIUS Server ====
Most configuration information in sip-router is stored in form of so called AVPs (attribute-value pairs).
The AVPs are simple variables which are accessible in routing sections of the configuration file and they
can be used to store all kinds of information. AVPs are typically stored all kinds of configuration
for a particular subscriber in the database. Whenever a subscriber makes a call, the server retrieves
his/her set of AVPs from the database and processes the request based on his/her preferences stored in
those AVPs.

This is implemented in module avp_db for all kinds of regular databases and in misc_radius for RADIUS.
Our goal here is to make avp_db module work with RADIUS and get rid of misc_radius module.

==== Configuration File ====
The operation of the module will be driven by a plain-text configuration file. We have taken similar
approach with the generic LDAP module already. The configuration file of the generic LDAP module
is used to translate database table names to nodes in the LDAP data tree and also to translate
database column names to LDAP attributes. The configuration file of the generic LDAP module looks
roughly like this:
<code>
[connection:ldap_server1]
host=127.0.0.1
port=389
username=ser
password=heslo

[table:credentials]
base = "ou=Digest Credentials,dc=iptel,dc=org"
field_map = password : (Binary) digestPassword
field_map = realm : digestRealm
</code>
We would like to have a similar configuration file also for the generic RADIUS database driver.

===== Reading List =====
  - RFC 2865: [[http://www.ietf.org/rfc/rfc2865.txt|Remote Authentication Dial In User Service (RADIUS)
]]
  - RFC 2866: [[http://www.ietf.org/rfc/rfc2866.txt|RADIUS Accounting]]
  - RFC 2869: [[http://www.ietf.org/rfc/rfc2869.txt|RADIUS Extensions]]
  - RFC 4590: [[http://www.ietf.org/rfc/rfc4590.txt|RADIUS Extension for Digest Authentication]]
  - Documentation for the following sip-router modules:
     * [[http://www.kamailio.org/docs/modules/devel/acc.html|acc]]
     * [[http://www.kamailio.org/docs/modules/devel/auth_radius.html|auth_radius]]
     * [[http://www.kamailio.org/docs/modules/devel/misc_radius.html|misc_radius]]
  - [[http://freeradius.org/freeradius-client/|Freeradius-client]]