kamailio/modules/auth_db/README

Auth_db Module

Jan Janak

   FhG Fokus
   <jan@iptel.org>

Jakob Schlyter

   <jakob@schlyter.se>

Bogdan-Andrei Iancu

   Voice Sistem SRL
   <bogdan@voice-system.ro>

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Jan Janak

   <jan@iptel.org>

   Copyright © 2002, 2003 FhG FOKUS

   Copyright © 2005 Voice Sistem SRL
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. db_url (string)
              3.2. user_column (string)
              3.3. domain_column (string)
              3.4. password_column (string)
              3.5. password_column_2 (string)
              3.6. calculate_ha1 (integer)
              3.7. use_domain (integer)
              3.8. load_credentials (string)
              3.9. version_table (integer)

        4. Functions

              4.1. www_authenticate(realm, table [, method])
              4.2. www_authorize(realm, table)
              4.3. proxy_authenticate(realm, table)
              4.4. proxy_authorize(realm, table)
              4.5. auth_check(realm, table, flags)
              4.6. is_subscriber(uri, dbtable, flags)

   List of Examples

   1.1. db_url parameter usage
   1.2. user_column parameter usage
   1.3. domain_column parameter usage
   1.4. password_column parameter usage
   1.5. password_column_2 parameter usage
   1.6. calculate_ha1 parameter usage
   1.7. use_domain parameter usage
   1.8. load_credentials parameter usage
   1.9. version_table parameter usage
   1.10. www_authorize usage
   1.11. proxy_authorize usage
   1.12. auth_check usage
   1.13. is_subscriber usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. db_url (string)
        3.2. user_column (string)
        3.3. domain_column (string)
        3.4. password_column (string)
        3.5. password_column_2 (string)
        3.6. calculate_ha1 (integer)
        3.7. use_domain (integer)
        3.8. load_credentials (string)
        3.9. version_table (integer)

   4. Functions

        4.1. www_authenticate(realm, table [, method])
        4.2. www_authorize(realm, table)
        4.3. proxy_authenticate(realm, table)
        4.4. proxy_authorize(realm, table)
        4.5. auth_check(realm, table, flags)
        4.6. is_subscriber(uri, dbtable, flags)

1. Overview

   This module contains all authentication related functions that need the
   access to the database. This module should be used together with auth
   module, it cannot be used independently because it depends on the
   module. Select this module if you want to use database to store
   authentication information like subscriber usernames and passwords. If
   you want to use radius authentication, then use auth_radius instead.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The module depends on the following modules (in the other words the
   listed modules must be loaded before this module):
     * auth -- Generic authentication functions
     * database -- Any database module (currently mysql, postgres, dbtext)

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * none

3. Parameters

   3.1. db_url (string)
   3.2. user_column (string)
   3.3. domain_column (string)
   3.4. password_column (string)
   3.5. password_column_2 (string)
   3.6. calculate_ha1 (integer)
   3.7. use_domain (integer)
   3.8. load_credentials (string)
   3.9. version_table (integer)

3.1. db_url (string)

   This is URL of the database to be used. Value of the parameter depends
   on the database module used. For example for mysql and postgres modules
   this is something like mysql://username:password@host:port/database.
   For dbtext module (which stores data in plaintext files) it is
   directory in which the database resides.

   Default value is “mysql://kamailioro:kamailioro@localhost/kamailio”.

   Example 1.1. db_url parameter usage
...
modparam("auth_db", "db_url", "dbdriver://username:password@dbhost/dbname")
...

3.2. user_column (string)

   This is the name of the column holding usernames. Default value is fine
   for most people. Use the parameter if you really need to change it.

   Default value is “username”.

   Example 1.2. user_column parameter usage
...
modparam("auth_db", "user_column", "user")
...

3.3. domain_column (string)

   This is the name of the column holding domains of users. Default value
   is fine for most people. Use the parameter if you really need to change
   it.

   Default value is “domain”.

   Example 1.3. domain_column parameter usage
...
modparam("auth_db", "domain_column", "domain")
...

3.4. password_column (string)

   This is the name of the column holding passwords. Passwords can be
   either stored as plain text or pre-calculated HA1 strings. HA1 strings
   are MD5 hashes of username, password, and realm. HA1 strings are more
   safe because the server doesn't need to know plaintext passwords and
   they cannot be obtained from HA1 strings.

   Default value is “ha1”.

   Example 1.4. password_column parameter usage
...
modparam("auth_db", "password_column", "password")
...

3.5. password_column_2 (string)

   As described in the previous section this parameter contains name of
   column holding pre-calculated HA1 string that were calculated including
   the domain in the username. This parameter is used only when
   calculate_ha1 is set to 0 and user agent send a credentials containing
   the domain in the username.

   Default value of the parameter is ha1b.

   Example 1.5. password_column_2 parameter usage
...
modparam("auth_db", "password_column_2", "ha1_2")
...

3.6. calculate_ha1 (integer)

   This parameter tells the server whether it should use a pre-calculated
   HA1 string or plaintext passwords for authentification.

   If the parameter is set to 0 and the username parameter of credentials
   contains also “@domain” (some user agents append the domain to the
   username parameter), then the server will use the HA1 values from the
   column specified in the “password_column_2” parameter. If the username
   parameter doesn't contain a domain, the server will use the HA1 values
   from the column given in the “password_column”parameter.

   If the parameter is set to 1 then the HA1 value will be calculated from
   the column specified in the “password_column” parameter.

   The “password_column_2”column contain also HA1 strings but they should
   be calculated including the domain in the username parameter (as
   opposed to password_column which (when containing HA1 strings) should
   always contains HA1 strings calculated without domain in username.

   This ensures that the authentication will always work when using
   pre-calculated HA1 strings, not depending on the presence of the domain
   in username.

   Default value of this parameter is 0.

   Example 1.6. calculate_ha1 parameter usage
...
modparam("auth_db", "calculate_ha1", 1)
...

3.7. use_domain (integer)

   If true (not 0), domain will be also used when looking up in the
   subscriber table. If you have a multi-domain setup, it is strongly
   recommended to turn on this parameter to avoid username overlapping
   between domains.

   IMPORTANT: before turning on this parameter, be sure that the domain
   column in subscriber table is properly populated.

   Default value is “0 (false)”.

   Example 1.7. use_domain parameter usage
...
modparam("auth_db", "use_domain", 1)
...

3.8. load_credentials (string)

   This parameter specifies of credentials to be fetch from database when
   the authentication is performed. The loaded credentials will be stored
   in AVPs. If the AVP name is not specificaly given, it will be used a
   NAME AVP with the same name as the column name.

   Parameter syntax:
     * load_credentials = credential (';' credential)*
     * credential = (avp_specification '=' column_name) | (column_name)
     * avp_specification = '$avp(' + 'i:'ID | 's:'NAME | alias + ')'

   Default value of this parameter is “NULL” (no credientials loaded).

   Example 1.8. load_credentials parameter usage
...
# load rpid column into $avp(i:123) and email_address column
# into $avp(s:email_address)
modparam("auth_db", "load_credentials", "$avp(i:123)=rpid;email_address")
...

3.9. version_table (integer)

   If set to 0, the module will skip checking the version for subscriber
   table.

   Default value is “1 (check for table version)”.

   Example 1.9. version_table parameter usage
...
modparam("auth_db", "version_table", 0)
...

4. Functions

   4.1. www_authenticate(realm, table [, method])
   4.2. www_authorize(realm, table)
   4.3. proxy_authenticate(realm, table)
   4.4. proxy_authorize(realm, table)
   4.5. auth_check(realm, table, flags)
   4.6. is_subscriber(uri, dbtable, flags)

4.1.  www_authenticate(realm, table [, method])

   Name alias: www_authorize(realm, table)

   The function verifies credentials according to RFC2617. If the
   credentials are verified successfully then the function will succeed
   and mark the credentials as authorized (marked credentials can be later
   used by some other functions). If the function was unable to verify the
   credentials for some reason then it will fail and the script should
   call www_challenge which will challenge the user again.

   Negative codes may be interpreted as follows:
     * -1 (generic error) - some generic error occurred and no reply was
       sent out;
     * -2 (invalid password) - wrong password;
     * -3 (invalid user) - authentication user does not exist.
     * -4 (nonce expired) - the nonce has expired
     * -5 (no credentials) - request does not contain an Authorization
       header with the correct realm.
     * -6 (nonce reused) - the nonce has already been used to authenticate
       a previous request
     * -8 (authuser mismatch) - depending on the method, th From/To/RURI
       user does not match the authentication user (see auth_check()
       function).

   Meaning of the parameters is as follows:
     * realm - Realm is a opaque string that the user agent should present
       to the user so he can decide what username and password to use.
       Usually this is domain of the host the server is running on.
       It must not be empty string “”. In case of REGISTER requests To
       header field domain (e.g., variable $td) can be used (because this
       header field represents the user being registered), for all other
       messages From header field domain can be used (e.g., variable $fd).
       The string may contain pseudo variables.
     * table - Table to be used to lookup usernames and passwords (usually
       subscribers table).
     * method - the method to be used for authentication. This parameter
       is optional and if not set is the first "word" on the request-line.

   This function can be used from REQUEST_ROUTE.

   Example 1.10. www_authorize usage
...
if (!www_authorize("kamailio.org", "subscriber")) {
        www_challenge("kamailio.org", "1");
};
...

4.2.  www_authorize(realm, table)

   It is same function as www_authenticate(realm, table). This name is
   kept for backward compatibility, since it was named this way first time
   by it actually does user authentication.

4.3.  proxy_authenticate(realm, table)

   Name alias: proxy_authorize(realm, table)

   The function verifies credentials according to RFC2617. If the
   credentials are verified successfully then the function will succeed
   and mark the credentials as authorized (marked credentials can be later
   used by some other functions). If the function was unable to verify the
   credentials for some reason then it will fail and the script should
   call proxy_challenge which will challenge the user again.

   Negative return codes have the same meaning as for www_authenticate().

   Meaning of the parameters is as follows:
     * realm - Realm is a opaque string that the user agent should present
       to the user so he can decide what username and password to use.
       Usually this is domain of the host the server is running on.
       It must not be empty string “”. Apart of a static string, typical
       value is From header field domain (e.g., variable $fd).
       If an empty string “” is used then the server will generate it from
       the request. From header field domain will be used as realm.
       The string may contain pseudo variables.
     * table - Table to be used to lookup usernames and passwords (usually
       subscribers table).

   This function can be used from REQUEST_ROUTE.

   Example 1.11. proxy_authorize usage
...
if (!proxy_authorize("$fd", "subscriber)) {
        proxy_challenge("$fd", "1");  # Realm will be autogenerated
};
...

4.4.  proxy_authorize(realm, table)

   It is same function as proxy_authenticate(realm, table). This name is
   kept for backward compatibility, since it was named this way first time
   but it actually does user authentication.

4.5.  auth_check(realm, table, flags)

   The function combines the functionalities of www_authenticate and
   proxy_authenticate, first being exectuted if the SIP request is a
   REGISTER, the second for the rest.

   In addition, a matter of flags parameter value, the function checks if
   authentication username matches From/To header username, and
   Request-URI in case of PUBLISH.

   Negative return codes have the same meaning as for www_authenticate().

   Meaning of the parameters is as follows:
     * realm - Realm is a opaque string that the user agent should present
       to the user so he can decide what username and password to use.
       Usually this is domain of the host the server is running on.
       It must not be empty string “”. Apart of a static string, typical
       value is From header field domain (e.g., variable $fd).
       The string may contain pseudo variables.
     * table - Table to be used to lookup usernames and passwords (usually
       subscribers table).
       The string may contain pseudo variables.
     * flags - set of flags to control the behaviour of the function. If
       it is 1, then the function will check to see if the authentication
       username matches either To or From header username. REGISTER
       requests: From and To must match the authentication user. PUBLISH
       requests: From, To and Request-URI must match the authentication
       user. All other requests: From header must match the authentication
       user. If bit 2 is set as well (flags==3), the ID check is skipped
       for INVITE, BYE, PRACK, UPDATE, MESSAGE - these requests can come
       with anonymoys caller id.
       Additionally all domains in the checked URIs and the realm in the
       authentication header will be checked to match the provided realm
       parameter.
       The string may contain pseudo variables.

   This function can be used from REQUEST_ROUTE.

   Example 1.12. auth_check usage
...
if (!auth_check("$fd", "subscriber", "1")) {
    auth_challenge("$fd", "1");
    exit;
}
...

4.6.  is_subscriber(uri, dbtable, flags)

   The function checks if there is a subscriber corresponding to the AoR
   in uri parameter. It uses same database connection as for
   authentication functions.

   In addition, if the subscriber record is found, then the
   load_credentials attributes are loaded. An use case can be loading the
   credential attributes for callee.

   Meaning of the parameters is as follows:
     * uri - a valid SIP URI value to identify the subscriber. The string
       may contain pseudo variables.
     * dbtable - Table to be used to lookup username and domain from URI
       (usually subscriber table). The string may contain pseudo
       variables.
     * flags - set of flags to control the behaviour of the function. If
       1st bit is set, then the function will use the domain part of the
       URI to perform the database table search. If 2nd bit is set, then
       the credentials are not loaded in variables (a simple check if
       subscriber exists).
       The parameter may be a pseudo variable.

   This function can be used from ANY_ROUTE.

   Example 1.13. is_subscriber usage
...
if (!is_subscriber("$ru", "subscriber", "3")) {
    # callee is not a local subscriber
    ...
}
...