README

Auth_db Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. db_url (string)
              1.3.2. user_column (string)
              1.3.3. domain_column (string)
              1.3.4. password_column (string)
              1.3.5. password_column_2 (string)
              1.3.6. calculate_ha1 (integer)
              1.3.7. use_domain (integer)
              1.3.8. load_credentials (string)
              1.3.9. skip_version_check (int)

        1.4. Exported Functions

              1.4.1. www_authorize(realm, table)
              1.4.2. proxy_authorize(realm, table)

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   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. skip_version_check parameter usage
   1.10. www_authorize usage
   1.11. proxy_authorize usage

Chapter 1. Admin Guide

1.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.

1.2. Dependencies

1.2.1. OpenSIPS 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)

1.2.2. External Libraries or Applications

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

1.3. Exported Parameters

1.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://opensipsro:opensipsro@localhost/opensips”.

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

1.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")

1.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")

1.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")

1.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")

1.3.6. calculate_ha1 (integer)

   This parameter tells the server whether it should considered
   the loaded password (for authentification) as plaintext
   passwords or a pre-calculated HA1 string.

   Possible meanings of this parameter are:
     * 1 (calculate HA1) - the loaded password is a plaintext
       password, so OpenSIPS will internally calculate the HA1. As
       the passwors will be loaded from the column specified in
       the “password_column” parameter, be sure this parameter
       points to a column holding a plaintext password (by
       default, this parameter points to “ha1” column);
     * 0 (do NOT calculate HA1) - the loaded password is an
       already computed HA1 value, so OpenSIPS does not have do
       any further computing (for HA1 value). Depending on the
       presence of a “@domain” part (some user agents append the
       domain to the username credentials parameter too), the
       modules will load the password (pre-computed HA1) from the
       “password_column_2” column (if domain present) or from the
       “password_column” column (if domain not present). Usually,
       most of the UAs do NOT include a domain part in the
       username credentials parameter.

   The “password_column_2” column contains 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 contain 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)

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)

1.3.8. load_credentials (string)

   This parameter specifies credentials to be fetched 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(' + NAME + ')'

   Default value of this parameter is “rpid”.

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

1.3.9. skip_version_check (int)

   This parameter specifies not to check the auth table version.
   This parameter should be set when a custom authentication table
   is used.

   Default value is “0 (false)”.

   Example 1.9. skip_version_check parameter usage
modparam("auth_db", "skip_version_check", 1)

1.4. Exported Functions

1.4.1.  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:
     * -5 (generic error) - some generic error occurred and no
       reply was sent out;
     * -4 (no credentials) - credentials were not found in
       request;
     * -3 (stale nonce) - stale nonce;
     * -2 (invalid password) - valid user, but wrong password;
     * -1 (invalid user) - authentication user does not exist.

   Meaning of the parameters is as follows:
     * realm - Realm is an opaque string that the user agent
       should present to the user so it can decide what username
       and password to use. Usually this is domain of the host the
       server is running on.
       If an empty string “” is used then the server will generate
       it from the request. In case of REGISTER requests To header
       field domain will be used (because this header field
       represents a user being registered), for all other messages
       From header field domain will be used.
       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.10. www_authorize usage
...
if (!www_authorize("siphub.net", "subscriber")) {
        www_challenge("siphub.net", "1");
};
...

1.4.2.  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 codes may be interpreted as follows:
     * -5 (generic error) - some generic error occurred and no
       reply was sent out;
     * -4 (no credentials) - credentials were not found in
       request;
     * -3 (stale nonce) - stale nonce;
     * -2 (invalid password) - valid user, but wrong password;
     * -1 (invalid user) - authentication user does not exist.

   Meaning of the parameters is as follows:
     * realm - Realm is an opaque string that the user agent
       should present to the user so it can decide what username
       and password to use. Usually this is domain of the host the
       server is running on.
       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("", "subscriber)) {
        proxy_challenge("", "1");  # Realm will be autogenerated
};
...

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Jan Janak (@janakj) 50 29 1610 424
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 39 31 332 232
   3. Daniel-Constantin Mierla (@miconda) 29 20 130 382
   4. Liviu Chircu (@liviuchircu) 12 9 37 68
   5. Henning Westerholt (@henningw) 11 9 83 49
   6. Sergio Gutierrez 7 5 13 13
   7. Andrei Pelinescu-Onciul 6 4 81 33
   8. Razvan Crainea (@razvancrainea) 6 4 26 46
   9. Dan Pascu (@danpascu) 5 3 31 6
   10. Jiri Kuthan (@jiriatipteldotorg) 5 3 5 2

   All remaining contributors: Maksym Sobolyev (@sobomax), Anatoly
   Pidruchny, Kennard White, Konstantin Bokarius, Richard Revels,
   Julián Moreno Patiño, Norman Brandinger (@NormB), Edson Gellert
   Schubert, Ionut Ionita (@ionutrazvanionita), Vlad Patrascu
   (@rvlad-patrascu).

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Liviu Chircu (@liviuchircu)         Mar 2014 - Jul 2018
   2.  Bogdan-Andrei Iancu (@bogdan-iancu) Jun 2005 - Jun 2018
   3.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - May 2017
   4.  Julián Moreno Patiño                Feb 2016 - Feb 2016
   5.  Razvan Crainea (@razvancrainea)     Jun 2011 - Aug 2015
   6.  Ionut Ionita (@ionutrazvanionita)   Jan 2015 - Jan 2015
   7.  Richard Revels                      Sep 2011 - Sep 2011
   8.  Kennard White                       Jun 2011 - Jun 2011
   9.  Dan Pascu (@danpascu)               Feb 2006 - Jul 2010
   10. Sergio Gutierrez                    Nov 2008 - Mar 2009

   All remaining contributors: Henning Westerholt (@henningw),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert, Anatoly Pidruchny, Norman Brandinger
   (@NormB), Jan Janak (@janakj), Andrei Pelinescu-Onciul, Maksym
   Sobolyev (@sobomax), Jiri Kuthan (@jiriatipteldotorg).

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu
   Chircu (@liviuchircu), Razvan Crainea (@razvancrainea), Kennard
   White, Sergio Gutierrez, Daniel-Constantin Mierla (@miconda),
   Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt
   (@henningw), Anatoly Pidruchny, Jan Janak (@janakj).

   doc copyrights:

   Copyright © 2005 Voice Sistem SRL

   Copyright © 2002-2003 FhG FOKUS