src/modules/ims_ipsec_pcscf/README
38ff06af
 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>
 
5bd5df36
    Copyright © 2007 FhG FOKUS
38ff06af
 
5bd5df36
    Copyright © 2012 Smile Communications
38ff06af
 
5bd5df36
    Copyright © 2015 ng-voice GmbH
38ff06af
      __________________________________________________________________
 
    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)
5bd5df36
               3.5. ipsec_max_connections (int)
8d55c6eb
               3.6. ipsec_reuse_server_port (int)
               3.7. ipsec_spi_id_start (int)
               3.8. ipsec_spi_id_range (int)
d001dc00
               3.9. ipsec_preferred_alg (string)
               3.10. ipsec_preferred_ealg (string)
38ff06af
 
         4. Functions
 
               4.1. ipsec_create(domain)
cb8b582f
               4.2. ipsec_forward(domain, flags)
38ff06af
               4.3. ipsec_destroy(domain)
 
    List of Examples
 
    1.1. ipsec_listen_addr parameter usage
    1.2. ipsec_listen_addr6 parameter usage
    1.3. ipsec_client_port parameter usage
    1.4. ipsec_server_port parameter usage
5bd5df36
    1.5. ipsec_max_connections parameter usage
8d55c6eb
    1.6. ipsec_reuse_server_port parameter usage
    1.7. ipsec_spi_id_start parameter usage
    1.8. ipsec_spi_id_range parameter usage
d001dc00
    1.9. ipsec_preferred_alg parameter usage
    1.10. ipsec_preferred_ealg parameter usage
    1.11. ipsec_create
    1.12. ipsec_forward
    1.13. ipsec_destroy
38ff06af
 
 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)
5bd5df36
         3.5. ipsec_max_connections (int)
8d55c6eb
         3.6. ipsec_reuse_server_port (int)
         3.7. ipsec_spi_id_start (int)
         3.8. ipsec_spi_id_range (int)
d001dc00
         3.9. ipsec_preferred_alg (string)
         3.10. ipsec_preferred_ealg (string)
38ff06af
 
    4. Functions
 
         4.1. ipsec_create(domain)
cb8b582f
         4.2. ipsec_forward(domain, flags)
38ff06af
         4.3. ipsec_destroy(domain)
 
 1. Overview
 
    This module contains methods for IPSec initialisation/deinitialisation
    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
      * TM
 
 2.2. External Libraries or Applications
 
    This modules 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)
5bd5df36
    3.5. ipsec_max_connections (int)
8d55c6eb
    3.6. ipsec_reuse_server_port (int)
    3.7. ipsec_spi_id_start (int)
    3.8. ipsec_spi_id_range (int)
d001dc00
    3.9. ipsec_preferred_alg (string)
    3.10. ipsec_preferred_ealg (string)
38ff06af
 
 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.1. 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.2. ipsec_listen_addr6 parameter usage
 ...
 modparam("ims_ipsec_pcscf", "ipsec_listen_addr6", "")
 ...
 
 3.3. ipsec_client_port (int)
 
d001dc00
    Port number which will be bound for incoming (server) IPSec traffic.
38ff06af
 
5bd5df36
    Default value is 5062.
38ff06af
 
    Example 1.3. ipsec_client_port parameter usage
 ...
 modparam("ims_ipsec_pcscf", "ipsec_client_port", 5062)
 ...
 
 3.4. ipsec_server_port (int)
 
d001dc00
    Port number which will be bound for incoming (server) IPSec traffic.
38ff06af
 
    Default value is 5063.
 
    Example 1.4. ipsec_server_port parameter usage
 ...
 modparam("ims_ipsec_pcscf", "ipsec_server_port", 5063)
 ...
 
5bd5df36
 3.5. ipsec_max_connections (int)
 
d001dc00
    Maximum simultanious IPSec connections
5bd5df36
 
    Default value is 2.
 
    Example 1.5. ipsec_max_connections parameter usage
 ...
 modparam("ims_ipsec_pcscf", "ipsec_max_connections", 10)
 ...
 
8d55c6eb
 3.6. ipsec_reuse_server_port (int)
 
d001dc00
    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.
8d55c6eb
 
    Default value is 1.
 
    Example 1.6. ipsec_reuse_server_port parameter usage
 ...
 modparam("ims_ipsec_pcscf", "ipsec_reuse_server_port", 1)
 ...
 
 3.7. ipsec_spi_id_start (int)
38ff06af
 
    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.
 
8d55c6eb
    Example 1.7. ipsec_spi_id_start parameter usage
38ff06af
 ...
 modparam("ims_ipsec_pcscf", "ipsec_spi_id_start", 100)
 ...
 
8d55c6eb
 3.8. ipsec_spi_id_range (int)
38ff06af
 
    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.
 
8d55c6eb
    Example 1.8. ipsec_spi_id_range parameter usage
38ff06af
 ...
 modparam("ims_ipsec_pcscf", "ipsec_spi_id_range", 1000)
 ...
 
d001dc00
 3.9. 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.9. ipsec_preferred_alg parameter usage
 ...
 modparam("ims_ipsec_pcscf", "ipsec_preferred_alg", "hmac-sha-1-96")
 ...
 
 3.10. 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.10. ipsec_preferred_ealg parameter usage
 ...
 modparam("ims_ipsec_pcscf", "ipsec_preferred_ealg", "aes-cbc")
 ...
 
38ff06af
 4. Functions
 
    4.1. ipsec_create(domain)
cb8b582f
    4.2. ipsec_forward(domain, flags)
38ff06af
    4.3. ipsec_destroy(domain)
 
 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.
232df1a7
        flags - bitwise flag: 0x01 - if set - delete unused tunnels before
        every registration. This is an optional parameter, default value -
        0.
38ff06af
 
d001dc00
    Example 1.11. ipsec_create
38ff06af
 ...
 ipsec_create("location");
232df1a7
 # or
 ipsec_create("location", "1");
38ff06af
 ...
 
cb8b582f
 4.2. ipsec_forward(domain, flags)
38ff06af
 
    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.
bd0a236a
        flags - bitwise flag: 0x01 - set force socket for request messages.
        Useful for ipsec and TCP. 0x02 - reverse search for a contact in
        the memory. Useful when contact alias is disabled. This is an
        optional parameter, default value - 0.
38ff06af
 
d001dc00
    Example 1.12. ipsec_forward
38ff06af
 ...
 ipsec_forward("location");
cb8b582f
 # or
 ipsec_forward("location", "1");
38ff06af
 ...
 
 4.3. ipsec_destroy(domain)
 
    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.
 
d001dc00
    Example 1.13. ipsec_destroy
38ff06af
 ...
 ipsec_destroy("location");
 ...