====== 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: # adduser jan 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: # sippasswd jan 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''