The IMS PCSCF-Registrar Module

Dragos Vingarzan

FhG Fokus

Jason Penton

Smile Communications

Richard Good

Smile Communications

Carsten Bock

ng-voice GmbH

Dragos Vingarzan


Table of Contents

1. Admin Guide
1. Overview
2. Dependencies
2.1. Kamailio Modules
2.2. External Libraries or Applications
3. Parameters
3.1. pcscf_uri (string)
3.2. pending_reg_expires (int)
3.3. received_avp (string)
3.4. is_registered_fallback2ip (int)
3.5. publish_reginfo (int)
3.6. subscribe_to_reginfo (int)
3.7. subscription_expires (int)
3.8. ignore_contact_rxport_check (int)
3.9. ignore_contact_rxproto_check (int)
3.10. ignore_reg_state (int)
3.11. force_icscf_uri (string)
3.12. reginfo_queue_size_threshold (int)
3.13. delete_delay (int)
3.14. trust_bottom_via (int)
4. Functions
4.1. pcscf_save(domain)
4.2. pcscf_save_pending(domain)
4.3. pcscf_follows_service_routes(domain)
4.4. pcscf_force_service_routes(domain)
4.5. pcscf_is_registered(domain)

List of Examples

1.1. pcscf_uri parameter usage
1.2. pending_reg_expires parameter usage
1.3. received_avp parameter usage
1.4. is_registered_fallback2ip parameter usage
1.5. publish_reginfo parameter usage
1.6. subscribe_to_reginfo parameter usage
1.7. subscription_expires parameter usage
1.8. ignore_contact_rxport_check parameter usage
1.9. ignore_contact_rxproto_check parameter usage
1.10. ignore_reg_state parameter usage
1.11. force_icscf_uri parameter usage
1.12. reginfo_queue_size_threshold parameter usage
1.13. delete_delay parameter usage
1.14. trust_bottom_via parameter usage
1.15. pcscf_save

Chapter 1. Admin Guide

1. Overview

This module contains all methods related for usage of Kamailio as a Proxy-CSCF.

2. Dependencies

2.1. Kamailio Modules

The Following modules must be loaded before this module:

  • Usrloc PCSCF

  • PUA - if reginfo is used.

2.2. External Libraries or Applications

This module requires the internal IMS library.

3. Parameters

3.1. pcscf_uri (string)

URI of this Proxy-CSCF.

Example 1.1. pcscf_uri parameter usage

...
modparam("ims_registrar_pcscf", "pcscf_uri", "pcscf.mnc001.mcc001.3gppnetwork.org")
...

3.2. pending_reg_expires (int)

How long (in seconds), until pending (uncomplete) Registrations expire

Default value is 30.

Example 1.2. pending_reg_expires parameter usage

...
modparam("ims_registrar_pcscf", "pending_reg_expires", 15)
...

3.3. received_avp (string)

AVP, holding the received information (optional)

Example 1.3. received_avp parameter usage

...
modparam("ims_registrar_pcscf", "received_avp", "$avp(i:42)")
...

3.4. is_registered_fallback2ip (int)

Defines, whether a contact should be searched by its Contact: only or alternatively by the received IP-Address.

The option may have the following values:

  • 0 Search by Contact-Header only

  • 1 Search by Contact-Header, if this fails, search by Received Information (IP, Port, Proto)

  • 2 Search by Received Information (IP, Port, Proto), if this fails, Search by Contact Header

This Parameter is primarily used by the "is_registered" function.

Default value is 0 (Contact only).

Example 1.4. is_registered_fallback2ip parameter usage

...
modparam("ims_registrar_pcscf", "is_registered_fallback2ip", 2)
...

3.5. publish_reginfo (int)

If set to "1", the module will send PUBLISH regarding changes of the registration (e.g. due to Rx-Information) towards the network core.

Default value is 0 (Do not send PUBLISH).

Example 1.5. publish_reginfo parameter usage

...
modparam("ims_registrar_pcscf", "publish_reginfo", 1)
...

3.6. subscribe_to_reginfo (int)

If set to "1", the module will send a SUBSCRIBE for the registration status towards the network core.

Default value is 0 (Do not send SUBSCRIBE).

Example 1.6. subscribe_to_reginfo parameter usage

...
modparam("ims_registrar_pcscf", "subscribe_to_reginfo", 1)
...

3.7. subscription_expires (int)

How long should the subscription of reg-info towards the packet-core be valid?

Default value is 3600.

Example 1.7. subscription_expires parameter usage

...
modparam("ims_registrar_pcscf", "subscription_expires", 7200)
...

3.8. ignore_contact_rxport_check (int)

Validate, if the port, from which the request was received, is the same as used during registration.

This Parameter is primarily used by the "is_registered" function.

Default value is 0 (do not ignore Ports).

Example 1.8. ignore_contact_rxport_check parameter usage

...
modparam("ims_registrar_pcscf", "ignore_contact_rxport_check", 1)
...

3.9. ignore_contact_rxproto_check (int)

Validate, if the protocol, from which the request was received, is the same as used during registration. Note: with IMS, the UE opens IPsec Security Associations between IPs and ports with the P-CSCF. These are for both UDP and TCP, with a single negotiation, which does not need to specify the protocol.

(Before the introduction of this parameter, the similar one for port was used to also ignore the protocol. But that might've been a type/mistake.)

This Parameter is primarily used by the "is_registered" function.

Default value is 1 (ignore protocol, for best compliance).

Example 1.9. ignore_contact_rxproto_check parameter usage

...
modparam("ims_registrar_pcscf", "ignore_contact_rxproto_check", 1)
...

3.10. ignore_reg_state (int)

Validate, if the found contact is really and completely registered.

This Parameter is primarily used by the "is_registered" function.

Default value is 0 (do not ignore registration state).

Example 1.10. ignore_reg_state parameter usage

...
modparam("ims_registrar_pcscf", "ignore_reg_state", 1)
...

3.11. force_icscf_uri (string)

Instead of doing a DNS-Lookup on the domain, always send the requests to a specific I-CSCF.

Default value is not set, do the DNS-Lookup.

Example 1.11. force_icscf_uri parameter usage

...
modparam("ims_registrar_pcscf", "force_icscf_uri", "sip:icscf.mnc001.mcc001.3gppnetwork.org")
...

3.12. reginfo_queue_size_threshold (int)

As reginfo operations are processed asynchronously, this parameter defines at what length of the queue, the length should be logged (in order to determine overload)

Default value is 0 (do not log queue length).

Example 1.12. reginfo_queue_size_threshold parameter usage

...
modparam("ims_registrar_pcscf", "reginfo_queue_size_threshold", 42)
...

3.13. delete_delay (int)

If set greater than 0, the delete of a pcontact record is delayed with its value instead of being done immediately.

Default value is 0 (delete immediately).

Example 1.13. delete_delay parameter usage

...
modparam("ims_registrar_pcscf", "delete_delay", 10)
...

3.14. trust_bottom_via (int)

If set to 1 it will trust the bottom Via as the UE IP/port/transport when doing client identification.

Normally, the UE identification should be done on IPsec SPIs and source IP/port of the packets. In some cases the ims_* modules trust the top Via on requests and the bottom Via on responses. In some (better) cases this module trusts the received-from IP (or the alias in the Contact header).

This parameter allows for an external-to-Kamailio IPsec functionality to be used. That will be in charge of guaranteeing that the bottom Via header is always correct (on requests; on responses the P-CSCF itself should guarantee unmodified Via headers stack). Then the code here will always use the bottom Via as the source of truth for IMS UE identification.

Note: this will prefer the standard received and rport values, if present, over the actual Via sent-by host and port.

Note: !! trusting the Via header has security drawbacks, as it might be easily spoofed by an attacker. Hence, without extra security, the P-CSCF shouldn't trust the Via header for client identification on and this module would require a fix or extension for this. Currently only pcscf_save() is safe from this issue, while pcscf_save_pending() and pcscf_is_registered() seem to be using by default the top/first Via on requests, or the bottom/last Via on responses !!

See also the same parameter in the ims_qos module.

Default value is 0 (trust received-from IP and alias in Contact, and, unfortunaly somewhat wrongly top/bottom Via on requests/responses).

Example 1.14. trust_bottom_via parameter usage

...
modparam("ims_registrar_pcscf", "trust_bottom_via", 1)
...

4. Functions

4.1. pcscf_save(domain)

The function processes a reply to a REGISTER message. It can add, remove or modify location records (in usrloc) depending on Contact and Expires HFs in the REGISTER message.

Meaning of the parameters is as follows:

  • domain - Logical domain within the registrar. If a database is used then this must be name of the table which stores the contacts.

Example 1.15. pcscf_save

...
pcscf_save("location");
...

4.2. pcscf_save_pending(domain)

Same as pcscf_save(), but it will store the registration in a "Pending" state.

Meaning of the parameters is as follows:

  • domain - Logical domain within the registrar. If a database is used then this must be name of the table which stores the contacts.

The return code may have the following values:

  • ( 1) OK

  • (-1) Parsing of contact data failed

  • (-2) Deregistration in progress

For db_mode = DB_ONLY (3) setting for ims_usrloc_pcscf module modparam following logic is implemented:

  • To avoid race time conditions between a REREGISTER and the expiry handler state machine in the scscf an approach is chosen to refuse a REREGISTER in time window of 20 seconds after pcontact expiry on the pcscf (thus allowing expiry handling to finish). REREGISTER is refused in this scenario with return code -2.

  • In case a REREGISTER arrives at pcscf and the respective pcontact is expired longer than time window of 20 seconds registration also is refused with return code -2 and additionaly PUBLISH is sent to scscf with expiry = 0.

  • The rc -2 shall be handled in register.cfg script as follows:

    pcscf_save_pending("location");

    switch ($retcode) {

    case -1:

    .......

    case -2:

    send_reply("500", "Deregister in progress - Please try again");

    exit;

    break;

    }

4.3. pcscf_follows_service_routes(domain)

Returns true, if the request is following the "learned" service-routes during registration.

Meaning of the parameters is as follows:

  • domain - Logical domain within the registrar. If a database is used then this must be name of the table which stores the contacts.

4.4. pcscf_force_service_routes(domain)

Remove existing route-headers and force the Service-Routes, that were learned during registration.

Meaning of the parameters is as follows:

  • domain - Logical domain within the registrar. If a database is used then this must be name of the table which stores the contacts.

4.5. pcscf_is_registered(domain)

Returns true, if the request is coming from a "registered" endpoint.

Meaning of the parameters is as follows:

  • domain - Logical domain within the registrar. If a database is used then this must be name of the table which stores the contacts.