kamailio/modules/ims_auth

ims_auth Module

Dragos Vingarzan

   FhG Fokus
   <Dragos.Vingarzan@fokus.fraunhofer.de>

Jason Penton

   Smile Communications
   <jason.penton@smilecoms.com>

Richard Good

   Smile Communications
   <richard.good@smilecoms.com>

   Copyright © 2007 FhG FOKUS

   Copyright © 2012 Smile Communications
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. name (string)
              3.2. auth_data_hash_size (integer)
              3.3. auth_vector_timeout (integer)
              3.4. auth_data_timeout (int)
              3.5. av_request_at_once (integer)
              3.6. av_request_at_sync (integer)
              3.7. registration_default_algorithm (string)
              3.8. registration_qop (string)
              3.9. cxdx_forced_peer (string)
              3.10. cxdx_dest_realm (string)

        4. Functions

              4.1. ims_www_authorize(realm, table)
              4.2. ims_www_authenticate(realm, table)
              4.3. ims_www_challenge(realm, table)
              4.4. ims_proxy_challenge(realm, table)
              4.5. ims_proxy_authenticate(realm, table)

        5. Statistics

              5.1. MAR Timeouts (mar_timeouts)
              5.2. Average MAR Response Time (mar_avg_response_time)

   List of Examples

   1.1. name parameter usage
   1.2. auth_data_hash_size parameter usage
   1.3. auth_vector_timeout parameter usage
   1.4. password_column parameter usage
   1.5. av_request_at_once parameter usage
   1.6. av_request_at_sync parameter usage
   1.7. registration_default_algorithm parameter usage
   1.8. load_credentials parameter usage
   1.9. cxdx_forced_peer parameter usage
   1.10. version_table parameter usage
   1.11. www_authorize usage
   1.12. proxy_authorize usage
   1.13. proxy_authorize 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. name (string)
        3.2. auth_data_hash_size (integer)
        3.3. auth_vector_timeout (integer)
        3.4. auth_data_timeout (int)
        3.5. av_request_at_once (integer)
        3.6. av_request_at_sync (integer)
        3.7. registration_default_algorithm (string)
        3.8. registration_qop (string)
        3.9. cxdx_forced_peer (string)
        3.10. cxdx_dest_realm (string)

   4. Functions

        4.1. ims_www_authorize(realm, table)
        4.2. ims_www_authenticate(realm, table)
        4.3. ims_www_challenge(realm, table)
        4.4. ims_proxy_challenge(realm, table)
        4.5. ims_proxy_authenticate(realm, table)

   5. Statistics

        5.1. MAR Timeouts (mar_timeouts)
        5.2. Average MAR Response Time (mar_avg_response_time)

1. Overview

   This module contains all authentication related functions for an IMS
   environment. The module does not depend on the base Kamailio auth
   modules as other auth modules do. Instead ims_auth is dependent on the
   CDP (C Diameter Peer) modules for communicating with HSS as specified
   in 3GPP specs.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The Following mouldes must be loaded before this module:
     * TM - Transaction Manager
     * CDP - C Diameter Peer
     * CDP_AVP - CDP AVP Applications

2.2. External Libraries or Applications

   This modules requires the internal IMS library.

3. Parameters

   3.1. name (string)
   3.2. auth_data_hash_size (integer)
   3.3. auth_vector_timeout (integer)
   3.4. auth_data_timeout (int)
   3.5. av_request_at_once (integer)
   3.6. av_request_at_sync (integer)
   3.7. registration_default_algorithm (string)
   3.8. registration_qop (string)
   3.9. cxdx_forced_peer (string)
   3.10. cxdx_dest_realm (string)

3.1. name (string)

   This is the name of the SCSCF as identified in communication with the
   HSS (Server-Name AVP of MAR).

   Default value is 'sip:scscf.ims.smilecoms.com:6060'.

   Example 1.1. name parameter usage
...
modparam("ims_auth", "name", "sip:scscf3.ims.smilecoms.com:6060")
...

3.2. auth_data_hash_size (integer)

   This is the size of the hash table used to store auth vectors (AV).
   Default value is fine for most people. Use the parameter if you really
   need to change it.

   Default value is “1024”.

   Example 1.2. auth_data_hash_size parameter usage
...
modparam("ims_auth", "auth_data_hash_size", 1024)
...

3.3. auth_vector_timeout (integer)

   This is the time, in seconds, that a SENTauth vector is valid for. If
   there is no response ...

   Default value is “60”.

   Example 1.3. auth_vector_timeout parameter usage
...
modparam("ims_auth", "auth_vector_timeout", "domain")
...

3.4. auth_data_timeout (int)

   Time, in seconds, an used auth vector is valid for.

   Default value is “60”.

   Example 1.4. password_column parameter usage
...
modparam("ims_auth", "auth_data_timeout", 60)
...

3.5. av_request_at_once (integer)

   How many auth vectors to request in MAR.

   Default value is 1

   Example 1.5. av_request_at_once parameter usage
...
modparam("ims_auth", "av_request_at_once", 1)
...

3.6. av_request_at_sync (integer)

   How many auth vectors to request at sync. Default value is 1.

   Example 1.6. av_request_at_sync parameter usage
...
modparam("ims_auth", "av_request_at_sync", 1)
...

3.7. registration_default_algorithm (string)

   The default authentication algorithm to use for registration if one is
   not specified.

   Options are:
     * AKAV1-MD5
     * AKAV2-MD5
     * MD5
     * HSS-Selected - HSS will decide on auth algorithm

   Default value is “AKAv1-MD5”.

   Example 1.7. registration_default_algorithm parameter usage
...
modparam("ims_auth", "registration_default_algorithm", "HSS-Selected")
...

3.8. registration_qop (string)

   The QOP options to put in the authorisation challenges.

   Default value of this parameter is “auth,auth-int”.

   Example 1.8. load_credentials parameter usage
...
modparam("ims_auth", "load_credentials", "auth-int")
...

3.9. cxdx_forced_peer (string)

   FQDN of Diameter Peer (HSS) to use for communication (MAR)

   Default value is “”.

   Example 1.9. cxdx_forced_peer parameter usage
...
modparam("ims_auth", "cxdx_forced_peer", "hss.ims.smilecoms.com")
...

3.10. cxdx_dest_realm (string)

   Destination realm to be used in Diameter messags to HSS

   Default value is “ims.smilecoms.com”.

   Example 1.10. version_table parameter usage
...
modparam("ims_auth", "cxdx_dest_realm", "ims.smilecoms.com")
...

4. Functions

   4.1. ims_www_authorize(realm, table)
   4.2. ims_www_authenticate(realm, table)
   4.3. ims_www_challenge(realm, table)
   4.4. ims_proxy_challenge(realm, table)
   4.5. ims_proxy_authenticate(realm, table)

4.1. ims_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) - valid user, but wrong password;
     * -3 (invalid user) - authentication user does not exist.

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

   This function can be used from REQUEST_ROUTE.

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

4.2. ims_www_authenticate(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. ims_www_challenge(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 strinh, 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.12. proxy_authorize usage
...
if (!proxy_authorize("$fd", "subscriber)) {
        proxy_challenge("$fd", "1");  # Realm will be autogenerated
};
...

4.4. ims_proxy_challenge(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 strinh, 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.13. proxy_authorize usage
...
if (!proxy_authorize("$fd", "subscriber)) {
        proxy_challenge("$fd", "1");  # Realm will be autogenerated
};
...

4.5. ims_proxy_authenticate(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.

5. Statistics

   5.1. MAR Timeouts (mar_timeouts)
   5.2. Average MAR Response Time (mar_avg_response_time)

5.1. MAR Timeouts (mar_timeouts)

   The number of timeouts on sending a MAR. i.e. no response to MAR.

5.2. Average MAR Response Time (mar_avg_response_time)

   The average response time in milliseconds for MAR-MAA transaction.