====== Integration With UNIX/Linux User Database ======

**Contacts**: [[jan@iptel.org|Jan Janak]], [[andrei@iptel.org|Andrei Pelinescu-Onciul]]

===== Abstract =====
The goal of this work is to develop an extension module for sip-router that
will provide support for authentication, authorization, and configuration **the
UNIX way**, that is ''/etc/passwd'', ''/etc/group'' and plain-text files stored in
user's home directory. With this module loaded the sip-router server will be
able to integrate with name services and databases commonly available in UNIX-like
systems.

===== State of the Art =====
Every non-trivial sip-router setup requires a database server to store all kinds 
of data particular to the operation of the SIP server. All users' data, such as
authentication usernames, passwords and user location contacts, is then stored
in the database. The administrator usually needs to populate the database with
some initial data whenever a new user is added to the system. Even simple
operations, for example when a user decides to change his/her password for SIP
digest authentication, require the use of a provisioning system (serweb,
serctl) or the administrator has to use the SQL interface of the database to
issue one or more SQL commands.

The sip-router server supports a wide variety of database systems (mysql,
postgres, oracle, berkeley db) through its internal database abstraction
layer. The database abstraction layer is flexible and adding support for a new
database type (not necessarily SQL based) is a simple and straightforward
process. Typically there is no need to modify other extension modules of the
server because most of them access the database exclusively through the
database abstraction layer.

Running a dedicated fully-featured database server for a small SIP server
setup, serving maybe no more then a couple of users, seems like an
overkill. Yet, there is currently no easy way of achieving this without
setting up something like mysql. We have support for several embedded
databases, such as the berkeley db, but even such databases require standalone
provisioning tools and maintenance.

===== Goals =====
The aim of this work is to develop an extension module for sip-router which
will interface to the database abstraction layer in sip-router on one side to
traditional UNIX/Linux facilities for user authentication and user management
on the other side. This module will then (when used instead of a traditional
database module such as db_mysql) make it possible to use the UNIX/Linux user
database in ''/etc/passwd'' for authentication, PAM (Pluggable Authentication
Modules) system for authorization, and so on.

==== Required features ====
=== Version 1 (strawman) ===
    * Use ''/etc/passwd'' as the user database
    * Digest authentication password stored in ''~/.sr''
    * User location data stored in ''~/.sr''
    * Authorization to use the service using ''/etc/group'' (i.e. only members of sip group will be allowed to register and make calls).

=== Version 2 (deluxe) ===
    * PAM-enabled authorization
    * Selected configuration for a user (a set of name-value pairs) can be stored in a plain-text file in ''~/.sr'' (like ''~/.ssh/config'')
    * Keep ''/var/log/wtmp'' up-to-date when user registers/un-registers
    * Accounting in ~
    * Tool to administer the digest password in ''~/.sr''

===== Overview of Operation =====
The administator of a Linux host installs the sip-router. The sip-router comes
with a default configuration file with all important features, such as digest
authentication and registrar, enabled. He/she configures the sip-router server
to use ''db_unix'' module as the desired database driver (instead of the default
db_mysql).

The adminstrator decides to let user jan use the newly installed SIP
server. The administrator creates a new user with adduser:

<code>  
# adduser jan
</code>

and after filling all the personal information the user is created in the
system, his home directory is set to ''/home/jan''. The administrator sets an
initial digest authentication password for the user:

<code>
# sippasswd jan
</code>

The tool saves the password in ''/home/jan/.sr/passwd'' in either plain-text or
sha1 format, along with all information necessary for digest authentication.

User ''jan'' configures his SIP phone with username ''jan'', hostname of the Linux
host and the password given to him by the adminstrator and the phone sends a
REGISTER message and after the obligatory digest authentication round-trip,
the server gets the user's password from ''/home/jan/.sr/password'' and verifies
the digest crendentials.

Optionally, the server may use PAM or consult ''/etc/group'' to verify that the
user has access to the SIP service. If the user has ''~/.sr/config'' then the SIP
server loads the contents of the file before processing the SIP message.

If the registration was successfull then the SIP server saves all the contacts
registered by the user's phone in his ''~/.sr/usrloc'' and optionally updates wtmp
if the user is registered.

When an INVITE arrives for ''jan@host'', the sip server again loads the
configuration from ''/home/jan/.sr/config'' and then the list of contacts from
''/home/jan/.sr/usrloc'' and forwards the INVITE request. The SIP server may also
record the SIP call in Jan's ''~/.sr'' if ''db_unix'' module supports accouting.

The user (jan) may ssh into the SIP server host and customize his SIP
configuration by editing ''~/.sr/config''

===== Reading List =====
  * [[http://en.wikipedia.org/wiki/Pluggable_Authentication_Modules|PAM (Pluggable Authentication Modules)]]
  * [[http://www.kernel.org/pub/linux/libs/pam/|Linux PAM]]
  * ''man 3 login''
  * ''man passwd''
  * ''man group''