auth_ims Module

Dragos Vingarzan

FhG Fokus

Jason Penton

Smile Communications

Richard Good

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. name (string)
3.3. auth_data_hash_size (integer)
3.4. auth_vector_timeout (integer)
3.5. auth_data_timeout (int)
3.6. av_request_at_once (integer)
3.7. av_request_at_sync (integer)
3.8. registration_default_algorithm (string)
3.9. registration_qop (string)
3.10. cxdx_forced_peer (string)
3.11. cxdx_dest_realm (string)
4. Functions
4.1. I_scscf_select(initial)
4.2. I_scscf_drop()
4.3. I_perform_user_authorization_request(capabalities)
4.4. I_perform_location_information_request()
5. Statistics
5.1. Average UAR Response Time (uar_avg_response_time)
5.2. UAR Timeouts (uar_timeouts)
5.3. Average LIR Response Time (lir_avg_response_time)
5.4. LIR Timeouts (lir_timeouts)

List of Examples

1.1. name parameter usage
1.2. name parameter usage
1.3. auth_data_hash_size parameter usage
1.4. auth_vector_timeout parameter usage
1.5. password_column parameter usage
1.6. av_request_at_once parameter usage
1.7. av_request_at_sync parameter usage
1.8. registration_default_algorithm parameter usage
1.9. load_credentials parameter usage
1.10. cxdx_forced_peer parameter usage
1.11. version_table parameter usage
1.12. I_scscf_select usage
1.13. I_scscf_drop usage
1.14. I_perform_user_authorization_request usage
1.15. proxy_authorize usage

Chapter 1. Admin Guide

1. Overview

This module provides all functionality to build an ICSCF.

2. Dependencies

2.1. Kamailio Modules

The Following mouldes must be loaded before this module:

  • TM - Transaction Manager

  • SL - Stateless Reply

  • CDP - C Diameter Peer

  • CDP_AVP - CDP AVP Applications

2.2. External Libraries or Applications

This modules requires the Kamailio internal IMS library.

3. Parameters

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

Example 1.1. name parameter usage

modparam("auth_ims", "name", "")

3.2. name (string)

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

Default value is ''.

Example 1.2. name parameter usage

modparam("auth_ims", "name", "")

3.3. 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.3. auth_data_hash_size parameter usage

modparam("auth_ims", "auth_data_hash_size", 1024)

3.4. 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.4. auth_vector_timeout parameter usage

modparam("auth_ims", "auth_vector_timeout", "domain")

3.5. auth_data_timeout (int)

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

Default value is “60”.

Example 1.5. password_column parameter usage

modparam("auth_ims", "auth_data_timeout", 60)

3.6. av_request_at_once (integer)

How many auth vectors to request in MAR.

Default value is 1

Example 1.6. av_request_at_once parameter usage

modparam("auth_ims", "av_request_at_once", 1)

3.7. av_request_at_sync (integer)

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

Example 1.7. av_request_at_sync parameter usage

modparam("auth_ims", "av_request_at_sync", 1)

3.8. 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.8. registration_default_algorithm parameter usage

modparam("auth_ims", "registration_default_algorithm", "HSS-Selected")

3.9. registration_qop (string)

The QOP options to put in the authorisation challenges.

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

Example 1.9. load_credentials parameter usage

modparam("auth_ims", "load_credentials", "auth-int")

3.10. cxdx_forced_peer (string)

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

Default value is “”.

Example 1.10. cxdx_forced_peer parameter usage

modparam("auth_ims", "cxdx_forced_peer", "")

3.11. cxdx_dest_realm (string)

Destination realm to be used in Diameter messags to HSS

Default value is “”.

Example 1.11. version_table parameter usage

modparam("auth_ims", "cxdx_dest_realm", "")

4. Functions

4.1. I_scscf_select(initial)

This function is used to retrieve the next unused SCSCF from thelist for this request (based on callid).

A positive return code (1) means an SCSCF was found and is armed for routing.

Meaning of the parameters is as follows:

  • initial - Signal whether or not this is an original or subsequent.

This function can be used from REQUEST_ROUTE | FAILURE_ROUTE.

Example 1.12. I_scscf_select usage

if (I_scscf_select("0")) {
     #there is an S-CSCF list - no need to do a UAR

4.2. I_scscf_drop()

Drop the list of SCSCFs for this request (based on callid).

This function can be used from REQUEST_ROUTE | FAILURE_ROUTE | REPLY_ROUTE

Example 1.13. I_scscf_drop usage



4.3. I_perform_user_authorization_request(capabalities)

Perform a UAR on Diameter CXDX interface. This function will build a list of SCSCFs to be used and populate the SCSCF list for the request. On a succesful return of this message you can get the next available SCSCF by using the I_scscf_select functoin in 4.1.

  • capabilities - whether to request capabilities or not "1" - with capabilities, "0" - no capabilities.

This function can be used from REQUEST_ROUTE.

p.s. this is executed asynchronously. See example on how to retrieve return value

Example 1.14. I_perform_user_authorization_request usage

            I_perform_user_authorization_request("0"); #0=REG/DEREG; 1=REG+Capabilities
            #this is async so to know status we have to check the reply avp
            switch ($avp(s:uaa_return_code)){
                case 1: #success
                    if (I_scscf_select("0")){
                        if (!t_relay()) {
                            t_reply("500", "Error forwarding to SCSCF");
                    } else {#select failed
                        t_reply("500", "Server error on SCSCF Select (UAR)");
                case -1: #failure
                    xlog("L_ERR", "UAR failure - error response sent from module");
                case -2: #error
                    xlog("L_ERR", "UAR error - sending error response now");
                    t_reply("500", "UAR failed");
                    xlog("L_ERR", "Unknown return code from UAR, value is [$avp(s:uaa_return_code)]");
                    t_reply("500", "Unknown response code from UAR"); 

4.4. I_perform_location_information_request()

This function can be used from REQUEST_ROUTE.

Example 1.15. proxy_authorize usage

if (!proxy_authorize("$fd", "subscriber)) {
proxy_challenge("$fd", "1");  # Realm will be autogenerated

5. Statistics

5.1. Average UAR Response Time (uar_avg_response_time)

The average response time in milliseconds for UAR-UAA transaction.

5.2. UAR Timeouts (uar_timeouts)

The number of UAR timeouts.

5.3. Average LIR Response Time (lir_avg_response_time)

The average response time in milliseconds for LIR-LIA transaction.

5.4. LIR Timeouts (lir_timeouts)

The number of LIR timeouts.