src/modules/auth_db/README
31ccf6a2
 Auth_db Module
 
 Jan Janak
 
    FhG Fokus
d77df08a
    <jan@iptel.org>
31ccf6a2
 
 Jakob Schlyter
 
d77df08a
    <jakob@schlyter.se>
 
31ccf6a2
 Bogdan-Andrei Iancu
 
d9bb387b
    Voice Sistem SRL
d77df08a
    <bogdan@voice-system.ro>
31ccf6a2
 
9fc784c6
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
31ccf6a2
 Edited by
 
 Jan Janak
 
d77df08a
    <jan@iptel.org>
 
9cb2a163
    Copyright © 2002, 2003 FhG FOKUS
31ccf6a2
 
9cb2a163
    Copyright © 2005 Voice Sistem SRL
76709d2e
      __________________________________________________________________
31ccf6a2
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
31ccf6a2
 
fdd4e8ff
         1. Overview
         2. Dependencies
3d6ab631
 
fdd4e8ff
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
3d6ab631
 
ba7961bb
         3. Parameters
31ccf6a2
 
fdd4e8ff
               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)
24ba6c21
               3.9. version_table (integer)
43f6a02e
               3.10. force_generate_avps (integer)
31ccf6a2
 
ba7961bb
         4. Functions
31ccf6a2
 
76709d2e
               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)
31ccf6a2
 
    List of Examples
d77df08a
 
    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
24ba6c21
    1.9. version_table parameter usage
43f6a02e
    1.10. force_generate_avps parameter usage
    1.11. www_authorize usage
    1.12. proxy_authorize usage
    1.13. auth_check usage
    1.14. is_subscriber usage
31ccf6a2
 
9fc784c6
 Chapter 1. Admin Guide
31ccf6a2
 
fdd4e8ff
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
fdd4e8ff
 
         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)
24ba6c21
         3.9. version_table (integer)
43f6a02e
         3.10. force_generate_avps (integer)
fdd4e8ff
 
ba7961bb
    4. Functions
31ccf6a2
 
76709d2e
         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)
31ccf6a2
 
fdd4e8ff
 1. Overview
31ccf6a2
 
76709d2e
    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
fdd4e8ff
    authentication information like subscriber usernames and passwords. If
    you want to use radius authentication, then use auth_radius instead.
3d6ab631
 
fdd4e8ff
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
 
76709d2e
    The module depends on the following modules (in the other words the
fdd4e8ff
    listed modules must be loaded before this module):
31ccf6a2
      * auth -- Generic authentication functions
76709d2e
      * database -- Any database module (currently mysql, postgres, dbtext)
31ccf6a2
 
fdd4e8ff
 2.2. External Libraries or Applications
3d6ab631
 
76709d2e
    The following libraries or applications must be installed before
fdd4e8ff
    running Kamailio with this module loaded:
3d6ab631
      * none
 
ba7961bb
 3. Parameters
31ccf6a2
 
fdd4e8ff
    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)
24ba6c21
    3.9. version_table (integer)
43f6a02e
    3.10. force_generate_avps (integer)
31ccf6a2
 
fdd4e8ff
 3.1. db_url (string)
31ccf6a2
 
fdd4e8ff
    This is URL of the database to be used. Value of the parameter depends
76709d2e
    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.
fdd4e8ff
 
9cb2a163
    Default value is “mysql://kamailioro:kamailioro@localhost/kamailio”.
31ccf6a2
 
d77df08a
    Example 1.1. db_url parameter usage
6760745b
 ...
fdd4e8ff
 modparam("auth_db", "db_url", "dbdriver://username:password@dbhost/dbname")
6760745b
 ...
31ccf6a2
 
fdd4e8ff
 3.2. user_column (string)
31ccf6a2
 
76709d2e
    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.
31ccf6a2
 
9cb2a163
    Default value is “username”.
31ccf6a2
 
d77df08a
    Example 1.2. user_column parameter usage
6760745b
 ...
31ccf6a2
 modparam("auth_db", "user_column", "user")
6760745b
 ...
31ccf6a2
 
fdd4e8ff
 3.3. domain_column (string)
31ccf6a2
 
fdd4e8ff
    This is the name of the column holding domains of users. Default value
76709d2e
    is fine for most people. Use the parameter if you really need to change
    it.
31ccf6a2
 
9cb2a163
    Default value is “domain”.
31ccf6a2
 
d77df08a
    Example 1.3. domain_column parameter usage
6760745b
 ...
31ccf6a2
 modparam("auth_db", "domain_column", "domain")
6760745b
 ...
31ccf6a2
 
fdd4e8ff
 3.4. password_column (string)
31ccf6a2
 
76709d2e
    This is the name of the column holding passwords. Passwords can be
fdd4e8ff
    either stored as plain text or pre-calculated HA1 strings. HA1 strings
76709d2e
    are MD5 hashes of username, password, and realm. HA1 strings are more
    safe because the server doesn't need to know plaintext passwords and
fdd4e8ff
    they cannot be obtained from HA1 strings.
31ccf6a2
 
9cb2a163
    Default value is “ha1”.
31ccf6a2
 
d77df08a
    Example 1.4. password_column parameter usage
6760745b
 ...
31ccf6a2
 modparam("auth_db", "password_column", "password")
6760745b
 ...
31ccf6a2
 
fdd4e8ff
 3.5. password_column_2 (string)
31ccf6a2
 
76709d2e
    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
fdd4e8ff
    calculate_ha1 is set to 0 and user agent send a credentials containing
    the domain in the username.
31ccf6a2
 
    Default value of the parameter is ha1b.
 
d77df08a
    Example 1.5. password_column_2 parameter usage
6760745b
 ...
31ccf6a2
 modparam("auth_db", "password_column_2", "ha1_2")
6760745b
 ...
31ccf6a2
 
fdd4e8ff
 3.6. calculate_ha1 (integer)
31ccf6a2
 
fdd4e8ff
    This parameter tells the server whether it should use a pre-calculated
8868e624
    HA1 string or plaintext passwords for authentication.
c561bf74
 
fdd4e8ff
    If the parameter is set to 0 and the username parameter of credentials
9cb2a163
    contains also “@domain” (some user agents append the domain to the
76709d2e
    username parameter), then the server will use the HA1 values from the
9cb2a163
    column specified in the “password_column_2” parameter. If the username
fdd4e8ff
    parameter doesn't contain a domain, the server will use the HA1 values
9cb2a163
    from the column given in the “password_column”parameter.
c561bf74
 
76709d2e
    If the parameter is set to 1 then the HA1 value will be calculated from
9cb2a163
    the column specified in the “password_column” parameter.
31ccf6a2
 
9cb2a163
    The “password_column_2”column contain also HA1 strings but they should
76709d2e
    be calculated including the domain in the username parameter (as
    opposed to password_column which (when containing HA1 strings) should
fdd4e8ff
    always contains HA1 strings calculated without domain in username.
31ccf6a2
 
76709d2e
    This ensures that the authentication will always work when using
    pre-calculated HA1 strings, not depending on the presence of the domain
    in username.
31ccf6a2
 
    Default value of this parameter is 0.
 
d77df08a
    Example 1.6. calculate_ha1 parameter usage
6760745b
 ...
c561bf74
 modparam("auth_db", "calculate_ha1", 1)
6760745b
 ...
31ccf6a2
 
fdd4e8ff
 3.7. use_domain (integer)
31ccf6a2
 
76709d2e
    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
fdd4e8ff
    between domains.
31ccf6a2
 
76709d2e
    IMPORTANT: before turning on this parameter, be sure that the domain
fdd4e8ff
    column in subscriber table is properly populated.
31ccf6a2
 
9cb2a163
    Default value is “0 (false)”.
31ccf6a2
 
d77df08a
    Example 1.7. use_domain parameter usage
6760745b
 ...
31ccf6a2
 modparam("auth_db", "use_domain", 1)
6760745b
 ...
31ccf6a2
 
fdd4e8ff
 3.8. load_credentials (string)
31ccf6a2
 
fdd4e8ff
    This parameter specifies of credentials to be fetch from database when
    the authentication is performed. The loaded credentials will be stored
8868e624
    in AVPs. If the AVP name is not specifically given, it will be used a
fdd4e8ff
    NAME AVP with the same name as the column name.
31ccf6a2
 
    Parameter syntax:
76709d2e
      * load_credentials = credential (';' credential)*
      * credential = (avp_specification '=' column_name) | (column_name)
      * avp_specification = '$avp(' + 'i:'ID | 's:'NAME | alias + ')'
31ccf6a2
 
8868e624
    Default value of this parameter is “NULL” (no credentials loaded).
31ccf6a2
 
d77df08a
    Example 1.8. load_credentials parameter usage
6760745b
 ...
 # load rpid column into $avp(i:123) and email_address column
cdece58c
 # into $avp(s:email_address)
6760745b
 modparam("auth_db", "load_credentials", "$avp(i:123)=rpid;email_address")
 ...
31ccf6a2
 
24ba6c21
 3.9. version_table (integer)
 
76709d2e
    If set to 0, the module will skip checking the version for subscriber
24ba6c21
    table.
 
9cb2a163
    Default value is “1 (check for table version)”.
24ba6c21
 
    Example 1.9. version_table parameter usage
 ...
 modparam("auth_db", "version_table", 0)
 ...
 
43f6a02e
 3.10. force_generate_avps (integer)
 
    If set to different than 0, the module will fetch user DB attributes
    even if authentication failed.
 
    Default value is “0” (don't fetch user DB attributes if authentication
    failed).
 
    Example 1.10. force_generate_avps parameter usage
 ...
 modparam("auth_db", "force_generate_avps", 1)
 ...
 
ba7961bb
 4. Functions
fdd4e8ff
 
76709d2e
    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)
31ccf6a2
 
9cb2a163
 4.1.  www_authenticate(realm, table [, method])
6760745b
 
    Name alias: www_authorize(realm, table)
31ccf6a2
 
76709d2e
    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.
31ccf6a2
 
366a27a2
    Negative codes may be interpreted as follows:
d092bcab
      * -1 (generic error) - Bad credentials , couldn't parse credentials ,
        no memory left , couldn't fetch from table , couldn't get realm or
        some generic error occurred and no reply was sent out;
76709d2e
      * -2 (invalid password) - wrong password;
6760745b
      * -3 (invalid user) - authentication user does not exist.
76709d2e
      * -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).
366a27a2
 
31ccf6a2
    Meaning of the parameters is as follows:
76709d2e
      * 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.
9cb2a163
        It must not be empty string “”. In case of REGISTER requests To
bacb5704
        header field domain (e.g., variable $td) can be used (because this
76709d2e
        header field represents the user being registered), for all other
        messages From header field domain can be used (e.g., variable $fd).
cfbd60f8
        The string may contain pseudo variables.
76709d2e
      * 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.
31ccf6a2
 
1e9552b7
    This function can be used from REQUEST_ROUTE.
 
43f6a02e
    Example 1.11. www_authorize usage
31ccf6a2
 ...
ba7961bb
 if (!www_authorize("kamailio.org", "subscriber")) {
6760745b
         www_challenge("kamailio.org", "1");
31ccf6a2
 };
 ...
 
9cb2a163
 4.2.  www_authorize(realm, table)
6760745b
 
76709d2e
    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.
6760745b
 
9cb2a163
 4.3.  proxy_authenticate(realm, table)
6760745b
 
    Name alias: proxy_authorize(realm, table)
31ccf6a2
 
76709d2e
    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.
489c7fda
 
6760745b
    Negative return codes have the same meaning as for www_authenticate().
31ccf6a2
 
    Meaning of the parameters is as follows:
76709d2e
      * 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.
9cb2a163
        It must not be empty string “”. Apart of a static string, typical
bacb5704
        value is From header field domain (e.g., variable $fd).
9cb2a163
        If an empty string “” is used then the server will generate it from
76709d2e
        the request. From header field domain will be used as realm.
cfbd60f8
        The string may contain pseudo variables.
76709d2e
      * table - Table to be used to lookup usernames and passwords (usually
        subscribers table).
31ccf6a2
 
1e9552b7
    This function can be used from REQUEST_ROUTE.
 
43f6a02e
    Example 1.12. proxy_authorize usage
31ccf6a2
 ...
6760745b
 if (!proxy_authorize("$fd", "subscriber)) {
         proxy_challenge("$fd", "1");  # Realm will be autogenerated
31ccf6a2
 };
 ...
6760745b
 
9cb2a163
 4.4.  proxy_authorize(realm, table)
6760745b
 
76709d2e
    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.
812e447b
 
9cb2a163
 4.5.  auth_check(realm, table, flags)
812e447b
 
76709d2e
    The function combines the functionalities of www_authenticate and
    proxy_authenticate, first being exectuted if the SIP request is a
812e447b
    REGISTER, the second for the rest.
 
    In addition, a matter of flags parameter value, the function checks if
76709d2e
    authentication username matches From/To header username, and
31880a46
    Request-URI in case of PUBLISH.
812e447b
 
76709d2e
    Negative return codes have the same meaning as for www_authenticate().
 
812e447b
    Meaning of the parameters is as follows:
76709d2e
      * 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.
9cb2a163
        It must not be empty string “”. Apart of a static string, typical
812e447b
        value is From header field domain (e.g., variable $fd).
        The string may contain pseudo variables.
76709d2e
      * table - Table to be used to lookup usernames and passwords (usually
        subscribers table).
812e447b
        The string may contain pseudo variables.
76709d2e
      * flags - set of flags to control the behaviour of the function. If
812e447b
        it is 1, then the function will check to see if the authentication
76709d2e
        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
b96c2d43
        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
8868e624
        with anonymous caller id.
76709d2e
        Additionally all domains in the checked URIs and the realm in the
        authentication header will be checked to match the provided realm
31880a46
        parameter.
812e447b
        The string may contain pseudo variables.
 
    This function can be used from REQUEST_ROUTE.
 
43f6a02e
    Example 1.13. auth_check usage
812e447b
 ...
 if (!auth_check("$fd", "subscriber", "1")) {
     auth_challenge("$fd", "1");
     exit;
 }
 ...
a9f1f9e3
 
9cb2a163
 4.6.  is_subscriber(uri, dbtable, flags)
a9f1f9e3
 
76709d2e
    The function checks if there is a subscriber corresponding to the AoR
    in uri parameter. It uses same database connection as for
a9f1f9e3
    authentication functions.
 
76709d2e
    In addition, if the subscriber record is found, then the
a9f1f9e3
    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.
76709d2e
      * dbtable - Table to be used to lookup username and domain from URI
        (usually subscriber table). The string may contain pseudo
a9f1f9e3
        variables.
76709d2e
      * flags - set of flags to control the behaviour of the function. If
7bf4c6d7
        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).
a9f1f9e3
        The parameter may be a pseudo variable.
 
    This function can be used from ANY_ROUTE.
 
43f6a02e
    Example 1.14. is_subscriber usage
a9f1f9e3
 ...
7bf4c6d7
 if (!is_subscriber("$ru", "subscriber", "3")) {
a9f1f9e3
     # callee is not a local subscriber
     ...
 }
 ...