The IMS PCSCF-Registrar 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>

Carsten Bock

   ng-voice GmbH
   <carsten@ng-voice.com>

Dragos Vingarzan

   <vingarzan -at- gmail dot com>

   Copyright © 2007 FhG FOKUS

   Copyright © 2012 Smile Communications

   Copyright © 2015 ng-voice GmbH
     __________________________________________________________________

   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

   Table of Contents

   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)

1. Overview

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

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

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

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.or
g")
...

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.3gpp
network.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,
   unfortunately 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)
   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)

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.
