proto_ipsec Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. port (integer)
              1.3.2. min_spi (integer)
              1.3.3. max_spi (integer)
              1.3.4. temporary_timeout (integer)
              1.3.5. default_client_port (integer)
              1.3.6. default_server_port (integer)
              1.3.7. allowed_algorithms (string)
              1.3.8. disable_deprecated_algorithms (integer)

        1.4. Exported Functions

              1.4.1. ipsec_create([port_server], [port_client],
                      [algos])

        1.5. Exported Pseudo-Variables

              1.5.1. $ipsec
              1.5.2. $ipsec_ue

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set port parameter
   1.2. Set min_spi parameter
   1.3. Set max_spi parameter
   1.4. Set temporary_timeout variable
   1.5. Set default_client_port parameter
   1.6. Set default_server_port parameter
   1.7. Set allowed_algorithms parameter
   1.8. Set disable_deprecated_algorithms parameter
   1.9. ipsec_create() usage
   1.10. $ipsec(field) usage
   1.11. $ipsec_ue(field) usage

Chapter 1. Admin Guide

1.1. Overview

   The proto_ipsec module provides IPSec sockets for establishing
   secure communication channels. It relies on RFC 3329 (Security
   Mechanism Agreement for the Session Initiation Protocol (SIP))
   to establish the IPSec parameters necessary for creating
   dynamic Security Associations (SAs) for each connection.

   This module has been developed to fully comply with the VoLTE
   specification (GSMA PRD IR.92) and implements the extensions
   defined in TS 33.203 (3G Security: Access Security for IP-based
   Services).

   It allows creation of both UDP and TCP secure connections on
   the same IP:port pair, defined as sockets. Essentially, when
   defining a socket using the proto_ipsec protocol, two new
   internal/hidden sockets are created on the specified port. For
   example, defining the following socket:

...
socket=ipsec:127.0.0.1:5100
...

   Internally, two different sockets are created:

...
socket=udp:127.0.0.1:5100
socket=tcp:127.0.0.1:5100
...

   Communication through these sockets should be done over IPSec,
   thus appropriate security associations (SAs) should be made
   prior to using these listeners, as defined in RFC 3329.

   NOTE that this means that you can no longer define these
   sockets in your config, otherwise they will overlap with the
   internally defined ones.

   IPSec communication requires each participant to define at
   least two ports for each connection: one when the entity
   behaves as a client and another when it behaves as a server.
   Consequently, it's typically necessary to define at least two
   IPSec sockets for the module to function correctly.

   The module implements the entire logic of keeping track of the
   registration status by hooking into the usrloc module and
   listening for contact changes updates. It also ensures the
   persistency of the tunnels by restoring them after a restart.

   When a request is received over an IPSec tunnel, the module
   provides two variables, $ipsec(field) and $ipsec_ue(field) to
   inspect details about it.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * tm - used to keep track of IPSec SA context between
       requests and replies.
     * usrloc - used to identify when a successful
       registration/de-registration happens.
     * proto_udp - used for handling IPSec UDP connections
       operations.
     * proto_tcp - used for handling IPSec TCP connections
       operations.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * libmnl - Minimalistic Netlink Library used to create IPSec
       SA using the XFRM kernel interface.

1.3. Exported Parameters

1.3.1. port (integer)

   Default IPSec port used when no prot is being specified in the
   socket global parameter.

   Default value is 5062.

   Example 1.1. Set port parameter
...
modparam("proto_ipsec", "port", 5100)
...

1.3.2. min_spi (integer)

   This parameter represents the minimum value for the Security
   Association's (SA) SPI parameter. In conjunction with the
   max_spi setting, it defines the SPI range [min_spi, max_spi]
   that must be unique within the system.

   Default value is 65536.

   Example 1.2. Set min_spi parameter
...
modparam("proto_ipsec", "min_spi", 10000)
...

1.3.3. max_spi (integer)

   This parameter represents the maximum value for the Security
   Association's (SA) SPI parameter. In conjunction with the
   min_spi setting, it defines the SPI range [min_spi, max_spi]
   that must be unique within the system.

   Default value is 262144.

   Example 1.3. Set max_spi parameter
...
modparam("proto_ipsec", "max_spi", 20000)
...

1.3.4. temporary_timeout (integer)

   Sets the timeout (in seconds) a temporary security association
   can be stored in memory until in is confirmed (or used) by the
   remote endpoint.

   The timeout signifies the duration elapsed after sending the
   Security Association's (SA) parameters in the 401 reply and
   when the User Equipment (UE) transmits the initial message over
   the new secure channel.

   Default value is 30.

   Example 1.4. Set temporary_timeout variable

param("proto_ipsec", "temporary_timeout", 10) # number of seconds


1.3.5. default_client_port (integer)

   Default port value to be used when we act as clients in the
   IPSec communication.

   Default value is not defined - a random socket is being used,
   but needs to be different from the server socket.

   Example 1.5. Set default_client_port parameter
...
modparam("proto_ipsec", "default_client_port", 5100)
...

1.3.6. default_server_port (integer)

   Default port value to be used when we act as server in the
   IPSec communication.

   Default value is not defined - a random socket is being used,
   but needs to be different from the client socket.

   Example 1.6. Set default_server_port parameter
...
modparam("proto_ipsec", "default_server_port", 6100)
...

1.3.7. allowed_algorithms (string)

   Whitelists the authentication and encryption algorithms that
   can be used for IPSec.

   Its format is: alg|ealg|alg=ealg

   Multiple algorithms pairs can be specified separated by comma.

   Currently supported algorithms are: <itemizedList> <listitem>

   Authentication algorithms: <itemizedList>
   <listitem>hmac-md5-96</listitem> - deprecated by TS 33.203 V13
   <listitem>hmac-sha-1-96</listitem> - not recomended by TS
   33.203 V17 <listitem>aes-gmac</listitem>
   <listitem>null</listitem> - must only be used with aes-gcm
   encryption </itemizedList>
   </listitem> <listitem>

   Encryption algorithms: <itemizedList>
   <listitem>des-ede3-cbc</listitem> - not recommended
   <listitem>aes-cbc</listitem> - not recomended by TS 33.203 V17
   <listitem>aes-gcm</listitem> <listitem>null</listitem> - no
   encryption </itemizedList>
   </listitem>
   </itemizedList>

   Default value is none - this means that all algorithms can be
   used.

   Example 1.7. Set allowed_algorithms parameter
...
modparam("proto_ipsec", "allowed_algorithms", "null")
modparam("proto_ipsec", "allowed_algorithms", "hmac-sha-1-96=null")
modparam("proto_ipsec", "allowed_algorithms", "hmac-sha-1-96=null,aes-gm
ac=aes-gcm")
...

1.3.8. disable_deprecated_algorithms (integer)

   Indicates whether we should ignore deprecated algorithms, as
   defined in TS 33.203 (3G Security: Access Security for IP-based
   Services). At the moment, this disables the following
   algorithms: <itemizedList> <listitem>

   hmac-md5-96 and hmac-sha-1-96 authentication algorithms
   </listitem> <listitem>

   des-ede3-cbc and aes-cbc encryption algorithms
   </listitem>
   </itemizedList>

   Default value is false - all algorihms can be used.

   Example 1.8. Set disable_deprecated_algorithms parameter
...
modparam("proto_ipsec", "disable_deprecated_algorithms", yes)
...

1.4. Exported Functions

1.4.1.  ipsec_create([port_server], [port_client], [algos])

   Creates an IPSec SA/tunnel according to the Security-Client
   header and the AKA information received in the 401 reply.

   This function should only be called on a 401 reply for a
   REGISTER message.

   Upon successful creation of the IPSec tunnel, it builds the
   Security-Server header and appends it to the reply.

   Meaning of the parameters is as follows:
     * port_server (integer, optional) - the server port to be
       used in the IPSec communication. It should be an existing
       IPSec port and is advertised in the Security-Server header.
       If missing, the default_client_port is considered.
     * port_client (integer, optional) - the client port to be
       used in the IPSec communication. It should be an existing
       IPSec port and is advertised in the Security-Server header.
       If missing, the default_server_port is considered.
     * algos (string, optional) - a list of algorithms that should
       be used for creating this security association. It has the
       same format as disable_allowed_algorithms and overwrites
       its value when used. If missing, the
       disable_allowed_algorithms is considered.

   This function can be used from REPLY_ROUTE.

   Example 1.9. ipsec_create() usage
...
onreply_route[ipsec] {
        if ($T_reply_code == 401)
                if (ipsec_create())
}
...

1.5. Exported Pseudo-Variables

1.5.1. $ipsec

   Populated for a request that is being received over an IPSec
   tunnel, it contains information about the local IPSec endpoint.

   The following fields can be retrieved:
     * ik - integrity key being used by the IPSec tunnel.
     * ck - confidentiality key being used by the IPSec tunnel.
     * alg - authentication algorithm being used.
     * ealg - encryption algorithm being used.
     * ip - local IP bound for this tunnel.
     * spi-c - local SPI chosen for receiving messages through the
       client channel.
     * spi-s - local SPI chosen for receiving messages through the
       server channel.
     * port-c - local port chosen for communicating through the
       client channel.
     * port-c - local port chosen for communicating through the
       server channel.

   Example 1.10. $ipsec(field) usage
...
xlog("Using $ipsec(ip):$ipsec(port-c) and $ipsec(ip):$ipsec(port-s) sock
et\n");
...

1.5.2. $ipsec_ue

   Populated for a request that is being received over an IPSec
   tunnel, it contains information about the remote IPSec
   endpoint.

   The following fields can be retrieved:
     * ik - integrity key being used by the IPSec tunnel.
     * ck - confidentiality key being used by the IPSec tunnel.
     * alg - authentication algorithm being used.
     * ealg - encryption algorithm being used.
     * ip - remote IP of the UE that uses this tunnel.
     * spi-c - remote SPI chosen for sending messages through the
       client channel.
     * spi-s - remote SPI chosen for sending messages through the
       server channel.
     * port-c - remote port chosen for communicating through the
       client channel.
     * port-c - remote port chosen for communicating through the
       server channel.

   Example 1.11. $ipsec_ue(field) usage
...
xlog("Using $ipsec_ue(ip):$ipsec_ue(port-c) and $ipsec_ue(ip):$ipsec_ue(
port-s) socket\n");
...

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
                   Name               DevScore Commits Lines ++ Lines --
   1. Razvan Crainea (@razvancrainea)    62      17      4491     373
   2. Liviu Chircu (@liviuchircu)        4        2       23       15
   3. Alexandra Titoc                    3        1       1        1

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                   Name                 Commit Activity
   1. Razvan Crainea (@razvancrainea) Apr 2024 - Apr 2025
   2. Alexandra Titoc                 Sep 2024 - Sep 2024
   3. Liviu Chircu (@liviuchircu)     May 2024 - May 2024

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Razvan Crainea (@razvancrainea).

   Documentation Copyrights:

   Copyright © 2024 OpenSIPS Solutions;
