# &adminguide;

## Overview

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

## Dependencies

### &kamailio; Modules

The Following modules must be loaded before this module:

- Usrloc PCSCF

- PUA - if reginfo is used.

### External Libraries or Applications

This module requires the internal IMS library.

## Parameters

### `pcscf_uri` (string)

URI of this Proxy-CSCF.

#### `pcscf_uri` parameter usage

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

### `pending_reg_expires` (int)

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

Default value is 30.

#### `pending_reg_expires` parameter usage

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

### `received_avp` (string)

AVP, holding the received information (optional)

#### `received_avp` parameter usage

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

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

#### `is_registered_fallback2ip` parameter usage

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

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

#### `publish_reginfo` parameter usage

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

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

#### `subscribe_to_reginfo` parameter usage

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

### `subscription_expires` (int)

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

Default value is 3600.

#### `subscription_expires` parameter usage

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

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

#### `ignore_contact_rxport_check` parameter usage

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

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

#### `ignore_contact_rxproto_check` parameter usage

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

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

#### `ignore_reg_state` parameter usage

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

### `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.

#### `force_icscf_uri` parameter usage

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

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

#### `reginfo_queue_size_threshold` parameter usage

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

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

#### `delete_delay` parameter usage

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

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

#### `trust_bottom_via` parameter usage

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

## Functions

### `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.

#### pcscf_save

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

### `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;

  }

### `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.

### `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.

### `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.