Auth_db Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview

              1.1.1. RFC 8760 Support (Strenghtened
                      Authentication)

        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. calculate_ha1 (integer)
              1.3.3. use_domain (integer)
              1.3.4. load_credentials (string)
              1.3.5. skip_version_check (int)
              1.3.6. user_column (string)
              1.3.7. domain_column (string)
              1.3.8. password_column (string)
              1.3.9. hash_column_sha256 (string)
              1.3.10. hash_column_sha512t256 (string)
              1.3.11. uri_user_column (string)
              1.3.12. uri_domain_column (string)
              1.3.13. uri_uriuser_column (string)

        1.4. Exported Functions

              1.4.1. www_authorize(realm, table)
              1.4.2. proxy_authorize(realm, table)
              1.4.3. db_is_to_authorized(table)
              1.4.4. db_is_from_authorized(table)
              1.4.5. db_does_uri_exist(uri, table)
              1.4.6. db_get_auth_id(table, uri, auth, realm)

   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. calculate_ha1 parameter usage
   1.3. use_domain parameter usage
   1.4. load_credentials parameter usage
   1.5. skip_version_check parameter usage
   1.6. user_column parameter usage
   1.7. domain_column parameter usage
   1.8. password_column parameter usage
   1.9. password_column parameter usage
   1.10. password_column parameter usage
   1.11. Set uri_user_column parameter
   1.12. Set uri_domain_column parameter
   1.13. Set uriuser_column parameter
   1.14. www_authorize usage
   1.15. proxy_authorize usage
   1.16. db_is_to_authorized usage
   1.17. db_does_uri_exist usage
   1.18. db_get_auth_id 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.1.1. RFC 8760 Support (Strenghtened Authentication)

   Starting with OpenSIPS 3.2, the auth, auth_db and uac_auth
   modules include support for two new digest authentication
   algorithms ("SHA-256" and "SHA-512-256"), according to the RFC
   8760 specs.

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. 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 passwords 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 the “ha1” column);
     * 0 (do not calculate HA1) - the loaded password is a
       pre-computed HA1 hash (no calculation needed). The module
       will load all hashes stored in the password_column,
       hash_column_sha256 and hash_column_sha512t256 columns, then
       use the hash corresponding to the hashing algorithm
       selected for a given digest authentication challenge.
       The content of the hash columns can be generated as
       follows:
          + password_column: MD5(username:realm:password)
          + hash_column_sha256: SHA-256(username:realm:password)
          + hash_column_sha512t256:
            SHA-512-256(username:realm:password)

   Default value of this parameter is 0 (use hashed passwords).

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

1.3.3. 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.3. use_domain parameter usage
modparam("auth_db", "use_domain", 1)

1.3.4. 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.4. 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.5. 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.5. skip_version_check parameter usage
modparam("auth_db", "skip_version_check", 1)

1.3.6. user_column (string)

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

   Default value is “username”.

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

1.3.7. domain_column (string)

   This is the name of the column in a 'SUBSCRIBER' like table
   holding the 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.7. domain_column parameter usage
modparam("auth_db", "domain_column", "domain")

1.3.8. password_column (string)

   This is the name of the column in a "subscriber" like table
   holding MD5 HA1 hash strings or plaintext passwords. An MD5 HA1
   hash is an MD5 hash of username, password and realm. Storing
   hashes in the DB (as opposed to passwords directly) is much
   more secure, because the server does not need to know plaintext
   passwords and because it is computationally infeasible for an
   attacker to reverse-obtain a password from an HA1 string.

   Default value is “ha1”.

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

1.3.9. hash_column_sha256 (string)

   The name of the column holding SHA-256 HA1 hashes (RFC 8760
   support).

   Default value is “ha1_sha256”.

   Example 1.9. password_column parameter usage
modparam("auth_db", "hash_column_sha256", "ha1_sha256")

1.3.10. hash_column_sha512t256 (string)

   The name of the column holding SHA-512/256 HA1 hashes. (RFC
   8760 support).

   Default value is “ha1_sha512t256”.

   Example 1.10. password_column parameter usage
modparam("auth_db", "hash_column_sha512t256", "ha1_sha512t256")

1.3.11. uri_user_column (string)

   Column holding usernames in an 'URI' like table.

   Default value is “username”.

   Example 1.11. Set uri_user_column parameter
...
modparam("auth_db", "uri_user_column", "username")
...

1.3.12. uri_domain_column (string)

   Column holding domain in an 'URI' like table.

   Default value is “domain”.

   Example 1.12. Set uri_domain_column parameter
...
modparam("auth_db", "uri_domain_column", "domain")
...

1.3.13. uri_uriuser_column (string)

   Column holding URI username in an 'URI' like table.

   Default value is “uri_user”.

   Example 1.13. Set uriuser_column parameter
...
modparam("auth_db", "uri_uriuser_column", "uri_user")
...

1.4. Exported Functions

1.4.1.  www_authorize(realm, table)

   The function verifies the received credentials against a
   "SUBSCRIBER"-like table according to digest authentication as
   per 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 (string) - 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 (string) - Table to be used to lookup usernames and
       passwords (usually subscribers table).

   This function can be used from REQUEST_ROUTE.

   Example 1.14. www_authorize usage
...
if (!www_authorize("siphub.net", "subscriber"))
        www_challenge("siphub.net", "auth");
...

1.4.2.  proxy_authorize(realm, table)

   The function verifies the received credentials against a
   "SUBSCRIBER"-like table according to digest authentication as
   per 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 (string) - 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 (string) - Table to be used to lookup usernames and
       passwords (usually subscribers table).

   This function can be used from REQUEST_ROUTE.

   Example 1.15. proxy_authorize usage
...
if (!proxy_authorize("", "subscriber"))
        proxy_challenge("", "auth");  # Realm will be autogenerated
...

1.4.3.  db_is_to_authorized(table)

   The function checks against a 'URI' like table to see if the
   username extracted from the To header URI is allowed/authorized
   to use the credentials (authentication username) validated by
   www_authorize().

   The function is part of the mechanism that allows to create
   mapping between the SIP users (from the FROM/TO headers) and
   the authentication users (from a SUBSCRIBER-like table) that
   they use. The mapping is stored into an URI-like table.

   Meaning of the parameters is as follows:
     * table (string) - Table to be used to lookup for the
       URI/AUTH mappings (usually the URI table).

   This function can be used from REQUEST_ROUTE.

   Example 1.16. db_is_to_authorized usage
...
if (!db_is_to_authorized("uri")) {
        xlog("User $tu is not authorized to authenticate with $au creden
tial\n");
}
...

1.4.4.  db_is_from_authorized(table)

   Similar to db_is_to_authorized() but instead of checking the TO
   header URI, the FROM header URI is checked.

1.4.5.  db_does_uri_exist(uri, table)

   Checks if the username@domain from the given URI is an existing
   user in a 'SUBSCRIBER' like table.

   Meaning of the parameters is as follows:
     * uri (string) - The SIP URI to be tested. It must hold a
       username part for a valid check. Variables are allowed.
     * table (string) - Table to be used to search for the URI
       (usually the SUBSCRIBER table).

   This function can be used from REQUEST_ROUTE.

   Example 1.17. db_does_uri_exist usage
...
if (db_does_uri_exist($ru, "subscriber")) {
        ...
}
...

1.4.6.  db_get_auth_id(table, uri, auth, realm)

   Checks given uri-string username against an 'URI' like table.
   Returns true if the user exists in the database, and sets the
   given variables to the authentication id and realm
   corresponding to the given uri.

   Meaning of the parameters is as follows:
     * table (string) - Table to be used to search for the URI
       (usually the URI table).
     * uri (string) - The input SIP URI to be tested. It must hold
       a username part for a valid check. Variables are allowed.
     * auth (var) - an output variable to store the found
       authentication id matching the given SIP URI.
     * realm (var) - an output variable to store the found
       authentication realm matching the given SIP URI.

   This function can be used from REQUEST_ROUTE ,FAILURE_ROUTE and
   LOCAL_ROUTE.

   Example 1.18. db_get_auth_id usage
...
if (db_get_auth_id("uri", $ru, $avp(auth_id), $avp(auth_realm))) {
        ...
}
...

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. Bogdan-Andrei Iancu (@bogdan-iancu) 51 37 783 380
   2. Jan Janak (@janakj) 50 29 1610 424
   3. Daniel-Constantin Mierla (@miconda) 29 20 130 382
   4. Liviu Chircu (@liviuchircu) 23 18 161 137
   5. Henning Westerholt (@henningw) 11 9 83 49
   6. Razvan Crainea (@razvancrainea) 10 8 30 48
   7. Maksym Sobolyev (@sobomax) 10 5 307 116
   8. Vlad Patrascu (@rvlad-patrascu) 8 4 69 163
   9. Sergio Gutierrez 7 5 13 13
   10. Andrei Pelinescu-Onciul 6 4 81 33

   All remaining contributors: Dan Pascu (@danpascu), Jiri Kuthan
   (@jiriatipteldotorg), Walter Doekes (@wdoekes), Anatoly
   Pidruchny, Kennard White, Konstantin Bokarius, Richard Revels,
   Julián Moreno Patiño, Norman Brandinger (@NormB), Peter
   Lemenkov (@lemenkov), Edson Gellert Schubert, Ionut Ionita
   (@ionutrazvanionita).

   (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 - May 2024
   2.  Razvan Crainea (@razvancrainea)     Jun 2011 - Jan 2024
   3.  Maksym Sobolyev (@sobomax)          Oct 2004 - Feb 2023
   4.  Bogdan-Andrei Iancu (@bogdan-iancu) Jun 2005 - Jul 2021
   5.  Walter Doekes (@wdoekes)            Apr 2021 - Apr 2021
   6.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Jul 2019
   7.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   8.  Julián Moreno Patiño                Feb 2016 - Feb 2016
   9.  Ionut Ionita (@ionutrazvanionita)   Jan 2015 - Jan 2015
   10. Richard Revels                      Sep 2011 - Sep 2011

   All remaining contributors: Kennard White, Dan Pascu
   (@danpascu), Sergio Gutierrez, Henning Westerholt (@henningw),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert, Anatoly Pidruchny, Norman Brandinger
   (@NormB), Jan Janak (@janakj), Andrei Pelinescu-Onciul, Jiri
   Kuthan (@jiriatipteldotorg).

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

Chapter 3. Documentation

3.1. Contributors

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

   Documentation Copyrights:

   Copyright © 2005 Voice Sistem SRL

   Copyright © 2002-2003 FhG FOKUS
