ims_ipsec_pcscf: added README file
authorDaniel-Constantin Mierla <miconda@gmail.com>
Thu, 2 Aug 2018 08:43:28 +0000 (10:43 +0200)
committerDaniel-Constantin Mierla <miconda@gmail.com>
Thu, 2 Aug 2018 08:43:28 +0000 (10:43 +0200)
src/modules/ims_ipsec_pcscf/README [new file with mode: 0644]

diff --git a/src/modules/ims_ipsec_pcscf/README b/src/modules/ims_ipsec_pcscf/README
new file mode 100644 (file)
index 0000000..e33f6fc
--- /dev/null
@@ -0,0 +1,244 @@
+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_client_port (int)
+              3.3. ipsec_server_port (int)
+              3.4. ipsec_spi_id_start (int)
+              3.5. ipsec_spi_id_range (int)
+
+        4. Functions
+
+              4.1. ipsec_create(domain)
+              4.2. ipsec_forward(domain)
+              4.3. ipsec_destroy(domain)
+
+   List of Examples
+
+   1.1. ipsec_listen_addr parameter usage
+   1.2. ipsec_client_port parameter usage
+   1.3. ipsec_server_port parameter usage
+   1.4. ipsec_spi_id_start parameter usage
+   1.5. ipsec_spi_id_range parameter usage
+   1.6. ipsec_create
+   1.7. ipsec_forward
+   1.8. ipsec_forward
+
+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_client_port (int)
+        3.3. ipsec_server_port (int)
+        3.4. ipsec_spi_id_start (int)
+        3.5. ipsec_spi_id_range (int)
+
+   4. Functions
+
+        4.1. ipsec_create(domain)
+        4.2. ipsec_forward(domain)
+        4.3. ipsec_destroy(domain)
+
+1. Overview
+
+   This module contains methods for IPSec initialisation/deinitialisation
+   related for usage of Kamailio as a Proxy-CSCF.
+
+   Important notice!!! Currently the module doesn't clear the IPSec
+   tunnels( Policies and Security associations, in XFRM terms) on startup
+   and shutdown. This will be fixed in future releases. For the moment the
+   following command can be used to clear the tunnels manually:
+
+   ip xfrm state deleteall
+
+   ip xfrm policy deleteall
+
+   Please note that this will clear ALL xfrm states and policies. This
+   means that it will interfere with other IPSec applications on the
+   machine. If this is the case, Kamailio's states and policies should be
+   cleared manually.
+
+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_client_port (int)
+   3.3. ipsec_server_port (int)
+   3.4. ipsec_spi_id_start (int)
+   3.5. ipsec_spi_id_range (int)
+
+3.1. ipsec_listen_addr (string)
+
+   IP address which the Proxy-CSCF will use for incoming/outgoing SIP
+   traffic over IPSec.
+
+   Default value is "127.0.0.1"
+
+   Example 1.1. ipsec_listen_addr parameter usage
+...
+modparam("ims_ipsec_pcscf", "ipsec_listen_addr", "127.0.0.1")
+...
+
+3.2. ipsec_client_port (int)
+
+   Port number which will be bound for incoming (server) IPSec traffic.
+
+   Default value is 5963.
+
+   Example 1.2. ipsec_client_port parameter usage
+...
+modparam("ims_ipsec_pcscf", "ipsec_client_port", 5062)
+...
+
+3.3. ipsec_server_port (int)
+
+   Port number which will be bound for incoming (server) IPSec traffic.
+
+   Default value is 5063.
+
+   Example 1.3. ipsec_server_port parameter usage
+...
+modparam("ims_ipsec_pcscf", "ipsec_server_port", 5063)
+...
+
+3.4. 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.4. ipsec_spi_id_start parameter usage
+...
+modparam("ims_ipsec_pcscf", "ipsec_spi_id_start", 100)
+...
+
+3.5. 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.5. ipsec_spi_id_range parameter usage
+...
+modparam("ims_ipsec_pcscf", "ipsec_spi_id_range", 1000)
+...
+
+4. Functions
+
+   4.1. ipsec_create(domain)
+   4.2. ipsec_forward(domain)
+   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.
+
+   Example 1.6. ipsec_create
+...
+ipsec_create("location");
+...
+
+4.2. ipsec_forward(domain)
+
+   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.
+
+   Example 1.7. ipsec_forward
+...
+ipsec_forward("location");
+...
+
+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.
+
+   Example 1.8. ipsec_forward
+...
+ipsec_destroy("location");
+...