<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;
]>
<chapter>
  <title>&adminguide;</title>

  <section>
    <title>Overview</title>

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

  </section>

  <section>
    <title>Dependencies</title>

    <section>
      <title>&kamailio; Modules</title>

      <para>The Following modules must be loaded before this module:</para>

      <itemizedlist>
        <listitem>
          <para>Usrloc PCSCF</para>
        </listitem>

        <listitem>
          <para>TM</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>External Libraries or Applications</title>

      <para>This module requires the internal IMS library and libmnl for operating with netlink sockets.</para>
    </section>
  </section>

  <section>
    <title>Parameters</title>

    <section>
      <title><varname>ipsec_listen_addr</varname> (string)</title>

      <para>IP address which the Proxy-CSCF will use for incoming/outgoing SIP traffic over IPSec.</para>
      <para><emphasis>Default value is empty string (null) - IPv4 listen interface will not be added</emphasis></para>

      <example>
        <title><varname>ipsec_listen_addr</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_listen_addr", "")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_listen_addr6</varname> (string)</title>

      <para>IPv6 address which the Proxy-CSCF will use for incoming/outgoing SIP traffic over IPSec.</para>
      <para><emphasis>Default value is empty string (null) - IPv6 listen interface will not be added</emphasis></para>

      <example>
        <title><varname>ipsec_listen_addr6</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_listen_addr6", "")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_client_port</varname> (int)</title>

      <para>Port number which will be bound for incoming (server) IPSec traffic.</para>

      <para><emphasis>Default value is 5062.</emphasis></para>

      <example>
        <title><varname>ipsec_client_port</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_client_port", 5062)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_server_port</varname> (int)</title>

      <para>Port number which will be bound for incoming (server) IPSec traffic.</para>

      <para><emphasis>Default value is 5063.</emphasis></para>

      <example>
        <title><varname>ipsec_server_port</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_server_port", 5063)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_listen_name</varname> (string)</title>

	  <para>Set a common prefix to build listen socket names.
	  Default value: not set.</para>

      <example>
        <title><varname>ipsec_listen_name</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_listen_name", "ims")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_listen_agname</varname> (string)</title>

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

      <example>
        <title><varname>ipsec_listen_agname</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_listen_agname", "imsudp")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_max_connections</varname> (int)</title>

      <para>Maximum simultaneous IPSec connections</para>

      <para><emphasis>Default value is 2.</emphasis></para>

      <example>
        <title><varname>ipsec_max_connections</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_max_connections", 10)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_reuse_server_port</varname> (int)</title>

      <para>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.</para>

      <para><emphasis>Default value is 1.</emphasis></para>

      <example>
        <title><varname>ipsec_reuse_server_port</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_reuse_server_port", 1)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_spi_id_start</varname> (int)</title>

      <para>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.</para>

      <para><emphasis>Default value is 100.</emphasis></para>

      <example>
        <title><varname>ipsec_spi_id_start</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_spi_id_start", 100)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_spi_id_range</varname> (int)</title>

      <para>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.</para>

      <para><emphasis>Default value is 1000.</emphasis></para>

      <example>
        <title><varname>ipsec_spi_id_range</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_spi_id_range", 1000)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_preferred_alg</varname> (string)</title>

      <para>A name of an authentication algorithm which the Proxy-CSCF will <emphasis>prefer</emphasis> when creating IPSec tunnels.</para>
      <para><emphasis>Default value is empty string (null) - the last algorithm in the Sec-Agree header will be used.</emphasis></para>

      <example>
        <title><varname>ipsec_preferred_alg</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_preferred_alg", "hmac-sha-1-96")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>ipsec_preferred_ealg</varname> (string)</title>

      <para>A name of an encrytion algorithm which the Proxy-CSCF will <emphasis>prefer</emphasis> when creating IPSec tunnels.</para>
      <para><emphasis>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.</emphasis></para>

      <example>
        <title><varname>ipsec_preferred_ealg</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_ipsec_pcscf", "ipsec_preferred_ealg", "aes-cbc")
...
        </programlisting>
      </example>
    </section>
  </section>

  <section>
    <title>Functions</title>

    <section>
      <title><function moreinfo="none">ipsec_create(domain)</function></title>

      <para>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.</para>

      <para>Meaning of the parameters is as follows:</para>
      <itemizedlist>
        <listitem>
          <para>
          <emphasis>domain</emphasis> - Logical domain within the registrar.
          If a database is used then this must be name of the table which
          stores the contacts.
          </para>
          <para>
          <emphasis>flags</emphasis> - bitwise flag:
          0x01 - if set - delete unused tunnels before every registration.
          This is an optional parameter, default value - 0.
          </para>
        </listitem>
		  </itemizedlist>
      <example>
        <title>ipsec_create</title>

        <programlisting format="linespecific">
...
ipsec_create("location");
# or
ipsec_create("location", "1");
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><function moreinfo="none">ipsec_forward(domain, flags)</function></title>
      <para>The function processes redirects outgoing message via the IPSec tunnel
      initiated with ipsec_create().</para>
		  <para>Meaning of the parameters is as follows:</para>
      <itemizedlist>
        <listitem>
          <para>
          <emphasis>domain</emphasis> - Logical domain within the registrar.
          If a database is used then this must be name of the table which
          stores the contacts.
          </para>
          <para>
          <emphasis>flags</emphasis> - bitwise flag:
		  <itemizedlist>
			<listitem>
			  <para>
				  <emphasis>0x01</emphasis> (1) - set force socket for request messages. Useful for ipsec and TCP/TLS.
			  </para>
			</listitem>
			<listitem>
			  <para>
				  <emphasis>0x02</emphasis> (2) - reverse search for a contact in the memory.
				  Useful when contact alias is disabled.
			  </para>
			</listitem>
			<listitem>
			  <para>
				  <emphasis>0x04</emphasis> (4) - use destination URI for IPSec tunnel search. Useful for
				  routing requests within dialog.
			  </para>
			</listitem>
			<listitem>
			  <para>
				  <emphasis>0x08</emphasis> (8) - use new R-URI for IPSec tunnel search.
			  </para>
			</listitem>
			<listitem>
			  <para>
				  <emphasis>0x10</emphasis> (16) - do not look for alias parameter to set received details.
			  </para>
			</listitem>
			<listitem>
			  <para>
				  <emphasis>0x20</emphasis> (32) - do not reset the destination URI.
			  </para>
			</listitem>
			<listitem>
			  <para>
				  <emphasis>0x40</emphasis> (64) - use user equipment client port as target for TCP/TLS requests
				  (try to reuse the UE client connection).
			  </para>
			</listitem>
			<listitem>
			  <para>
				  <emphasis>0x80</emphasis> (128) - set transport parameter in the new dst uri for TCP/TLS requests.
			  </para>
			</listitem>
			<listitem>
			  <para>
				  <emphasis>0x100</emphasis> (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).
			  </para>
			</listitem>
			<listitem>
			  <para>
				  <emphasis>0x200</emphasis> (512) - try TCP if corresponding UDP socket is not found.
			  </para>
			</listitem>
		  </itemizedlist>
          </para>
		  <para>
          This is an optional parameter, default value - 0.
          </para>
        </listitem>
      </itemizedlist>
      <example>
        <title>ipsec_forward</title>

        <programlisting format="linespecific">
...
ipsec_forward("location");
# or
ipsec_forward("location", "1");
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><function moreinfo="none">ipsec_destroy(domain [, aor])</function></title>
      <para>The function destroys IPSec tunnel, created with ipsec_create.</para>
      <para>Meaning of the parameters is as follows:</para>
      <itemizedlist>
        <listitem>
          <para>
          <emphasis>domain</emphasis> - Logical domain within the registrar.
          If a database is used then this must be name of the table which
          stores the contacts.
          </para>
          <para>
			  <emphasis>aor</emphasis> - SIP URI to match the record. If not
			  provided, then R-URI is used.
          </para>
        </listitem>
		  </itemizedlist>
      <example>
        <title>ipsec_destroy</title>

        <programlisting format="linespecific">
...
ipsec_destroy("location");
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><function moreinfo="none">ipsec_destroy_by_contact(domain, aor, recv_host, recv_port)</function></title>
      <para>The function destroys IPSec tunnel, created with ipsec_create.</para>
      <para>Meaning of the parameters is as follows:</para>
      <itemizedlist>
        <listitem>
          <para>
          <emphasis>domain</emphasis> - Logical domain within the registrar.
          If a database is used then this must be name of the table which
          stores the contacts.
          </para>
          <para>
			<emphasis>aor</emphasis> - SIP URI to match the record.
          </para>
          <para>
			<emphasis>recv_host</emphasis> - received host to match the record.
          </para>
          <para>
			<emphasis>recv_port</emphasis> - received port to match the record.
          </para>
        </listitem>
		  </itemizedlist>
		  <para>The last three parameters have to be string values and can contain
			variables.</para>
      <example>
        <title>ipsec_destroy_by_contact()</title>

        <programlisting format="linespecific">
...
ipsec_destroy_by_contact("location", "...", "...", "...");
...
        </programlisting>
      </example>
    </section>
  </section>
</chapter>
