The IMS IPSec-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>

Tsvetomir Dimitrov

   <tsv.dimitrov@gmail.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. ipsec_listen_addr (string)
              3.2. ipsec_listen_addr6 (string)
              3.3. ipsec_client_port (int)
              3.4. ipsec_server_port (int)
              3.5. ipsec_listen_name (string)
              3.6. ipsec_listen_agname (string)
              3.7. ipsec_max_connections (int)
              3.8. ipsec_reuse_server_port (int)
              3.9. ipsec_spi_id_start (int)
              3.10. ipsec_spi_id_range (int)
              3.11. ipsec_preferred_alg (string)
              3.12. ipsec_preferred_ealg (string)

        4. Functions

              4.1. ipsec_create(domain)
              4.2. ipsec_forward(domain, flags)
              4.3. ipsec_destroy(domain [, aor])
              4.4. ipsec_destroy_by_contact(domain, aor, recv_host,
                      recv_port)

   List of Examples

   1.1. Systemd override configuration
   1.2. ipsec_listen_addr parameter usage
   1.3. ipsec_listen_addr6 parameter usage
   1.4. ipsec_client_port parameter usage
   1.5. ipsec_server_port parameter usage
   1.6. ipsec_listen_name parameter usage
   1.7. ipsec_listen_agname parameter usage
   1.8. ipsec_max_connections parameter usage
   1.9. ipsec_reuse_server_port parameter usage
   1.10. ipsec_spi_id_start parameter usage
   1.11. ipsec_spi_id_range parameter usage
   1.12. ipsec_preferred_alg parameter usage
   1.13. ipsec_preferred_ealg parameter usage
   1.14. ipsec_create
   1.15. ipsec_forward
   1.16. ipsec_destroy
   1.17. ipsec_destroy_by_contact()

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. ipsec_listen_addr (string)
        3.2. ipsec_listen_addr6 (string)
        3.3. ipsec_client_port (int)
        3.4. ipsec_server_port (int)
        3.5. ipsec_listen_name (string)
        3.6. ipsec_listen_agname (string)
        3.7. ipsec_max_connections (int)
        3.8. ipsec_reuse_server_port (int)
        3.9. ipsec_spi_id_start (int)
        3.10. ipsec_spi_id_range (int)
        3.11. ipsec_preferred_alg (string)
        3.12. ipsec_preferred_ealg (string)

   4. Functions

        4.1. ipsec_create(domain)
        4.2. ipsec_forward(domain, flags)
        4.3. ipsec_destroy(domain [, aor])
        4.4. ipsec_destroy_by_contact(domain, aor, recv_host, recv_port)

1. Overview

   This module contains methods for IPSec initialisation/deinitialisation
   related for usage of Kamailio as a Proxy-CSCF.

   Kamailio process needs specific permssions in order to manage IPSec
   tunnels, if executed by non-root user be sure to allow needed
   capabilities.

   Example 1.1. Systemd override configuration
[Service]
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW

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
     * TM

2.2. External Libraries or Applications

   This module requires the internal IMS library and libmnl for operating
   with netlink sockets.

3. Parameters

   3.1. ipsec_listen_addr (string)
   3.2. ipsec_listen_addr6 (string)
   3.3. ipsec_client_port (int)
   3.4. ipsec_server_port (int)
   3.5. ipsec_listen_name (string)
   3.6. ipsec_listen_agname (string)
   3.7. ipsec_max_connections (int)
   3.8. ipsec_reuse_server_port (int)
   3.9. ipsec_spi_id_start (int)
   3.10. ipsec_spi_id_range (int)
   3.11. ipsec_preferred_alg (string)
   3.12. ipsec_preferred_ealg (string)

3.1. ipsec_listen_addr (string)

   IP address which the Proxy-CSCF will use for incoming/outgoing SIP
   traffic over IPSec.

   Default value is empty string (null) - IPv4 listen interface will not
   be added

   Example 1.2. ipsec_listen_addr parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_listen_addr", "")
...

3.2. ipsec_listen_addr6 (string)

   IPv6 address which the Proxy-CSCF will use for incoming/outgoing SIP
   traffic over IPSec.

   Default value is empty string (null) - IPv6 listen interface will not
   be added

   Example 1.3. ipsec_listen_addr6 parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_listen_addr6", "")
...

3.3. ipsec_client_port (int)

   Port number which will be bound for incoming (server) IPSec traffic.

   Default value is 5062.

   Example 1.4. ipsec_client_port parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_client_port", 5062)
...

3.4. ipsec_server_port (int)

   Port number which will be bound for incoming (server) IPSec traffic.

   Default value is 5063.

   Example 1.5. ipsec_server_port parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_server_port", 5063)
...

3.5. ipsec_listen_name (string)

   Set a common prefix to build listen socket names. Default value: not
   set.

   Example 1.6. ipsec_listen_name parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_listen_name", "ims")
...

3.6. ipsec_listen_agname (string)

   Set async (action) workers group name for udp sockets for
   multi-threaded reading. Default value: not set.

   Example 1.7. ipsec_listen_agname parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_listen_agname", "imsudp")
...

3.7. ipsec_max_connections (int)

   Maximum simultaneous IPSec connections

   Default value is 2.

   Example 1.8. ipsec_max_connections parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_max_connections", 10)
...

3.8. ipsec_reuse_server_port (int)

   Reuse (1) or not (0) the P-CSCF IPSec information for Re-registration
   for one UA. When set to 0 - During Re-registration P-CSCF will create
   new IPSec tunnels. When set to 1 - During Re-registration P-CSCF will
   reuse the old IPSec tunnels.

   Default value is 1.

   Example 1.9. ipsec_reuse_server_port parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_reuse_server_port", 1)
...

3.9. ipsec_spi_id_start (int)

   Each IPSec tunnel has a unique system-wide identifier. This and the
   following option allows to tune the SPIs used by Kamailio in order to
   avoid collisions with other IPSec useres. If Kamailio is the only
   process on the system which uses IPSec, don't bother with this option.

   Default value is 100.

   Example 1.10. ipsec_spi_id_start parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_spi_id_start", 100)
...

3.10. ipsec_spi_id_range (int)

   How many SPIs to be allocated for the process. E.g. if
   ipsec_spi_id_start = 100 and ipsec_spi_id_range = 1000, SPIs between
   100 and 1100 will be used.

   Default value is 1000.

   Example 1.11. ipsec_spi_id_range parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_spi_id_range", 1000)
...

3.11. ipsec_preferred_alg (string)

   A name of an authentication algorithm which the Proxy-CSCF will prefer
   when creating IPSec tunnels.

   Default value is empty string (null) - the last algorithm in the
   Sec-Agree header will be used.

   Example 1.12. ipsec_preferred_alg parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_preferred_alg", "hmac-sha-1-96")
...

3.12. ipsec_preferred_ealg (string)

   A name of an encrytion algorithm which the Proxy-CSCF will prefer when
   creating IPSec tunnels.

   Default value is empty string (null) - the last algorithm in the
   Sec-Agree header will be used. Note that the possibility of it being
   the "null" algorithm is not insignificant.

   Example 1.13. ipsec_preferred_ealg parameter usage
...
modparam("ims_ipsec_pcscf", "ipsec_preferred_ealg", "aes-cbc")
...

4. Functions

   4.1. ipsec_create(domain)
   4.2. ipsec_forward(domain, flags)
   4.3. ipsec_destroy(domain [, aor])
   4.4. ipsec_destroy_by_contact(domain, aor, recv_host, recv_port)

4.1. ipsec_create(domain)

   This function creates IPSec SA and Policy based on the parameters sent
   in Security-Client header in the REGISTER message. It's called when OK
   is received. The function also adds Security-Server header to the
   REGISTER.

   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.
       flags - bitwise flag: 0x01 - if set - delete unused tunnels before
       every registration. This is an optional parameter, default value -
       0.

   Example 1.14. ipsec_create
...
ipsec_create("location");
# or
ipsec_create("location", "1");
...

4.2. ipsec_forward(domain, flags)

   The function processes redirects outgoing message via the IPSec tunnel
   initiated with ipsec_create().

   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.
       flags - bitwise flag:
          + 0x01 (1) - set force socket for request messages. Useful for
            ipsec and TCP/TLS.
          + 0x02 (2) - reverse search for a contact in the memory. Useful
            when contact alias is disabled.
          + 0x04 (4) - use destination URI for IPSec tunnel search. Useful
            for routing requests within dialog.
          + 0x08 (8) - use new R-URI for IPSec tunnel search.
          + 0x10 (16) - do not look for alias parameter to set received
            details.
          + 0x20 (32) - do not reset the destination URI.
          + 0x40 (64) - use user equipment client port as target for
            TCP/TLS requests (try to reuse the UE client connection).
          + 0x80 (128) - set transport parameter in the new dst uri for
            TCP/TLS requests.
          + 0x100 (256) - use Via attributes (port and protocol) for
            routing UDP reply, and protocol from next hop address for
            request (otherwise it taken from saved contact).
          + 0x200 (512) - try TCP if corresponding UDP socket is not
            found.
       This is an optional parameter, default value - 0.

   Example 1.15. ipsec_forward
...
ipsec_forward("location");
# or
ipsec_forward("location", "1");
...

4.3. ipsec_destroy(domain [, aor])

   The function destroys IPSec tunnel, created with ipsec_create.

   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.
       aor - SIP URI to match the record. If not provided, then R-URI is
       used.

   Example 1.16. ipsec_destroy
...
ipsec_destroy("location");
...

4.4. ipsec_destroy_by_contact(domain, aor, recv_host, recv_port)

   The function destroys IPSec tunnel, created with ipsec_create.

   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.
       aor - SIP URI to match the record.
       recv_host - received host to match the record.
       recv_port - received port to match the record.

   The last three parameters have to be string values and can contain
   variables.

   Example 1.17. ipsec_destroy_by_contact()
...
ipsec_destroy_by_contact("location", "...", "...", "...");
...
