Table of Contents
List of Tables
List of Examples
port parametermin_spi parametermax_spi parametertemporary_timeout variabledefault_client_port parameterdefault_server_port parameterallowed_algorithms parameterdisable_deprecated_algorithms parameteripsec_create() usage$ipsec(field) usage$ipsec_ue(field) usageThe 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.
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.
Default IPSec port used when no prot is being specified in the socket global parameter.
Default value is 5062.
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.
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.
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
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)
...
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)
...
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>
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>
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-gmac=aes-gcm")
...
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
des-ede3-cbc and aes-cbc encryption algorithms
Default value is false - all algorihms can be used.
Example 1.8. Set disable_deprecated_algorithms parameter
...
modparam("proto_ipsec", "disable_deprecated_algorithms", yes)
...
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())
}
...
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) socket\n");
...
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");
...
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) | 61 | 16 | 4483 | 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
Table 2.2. Most recently active contributors(1) to this module
| Name | Commit Activity | |
|---|---|---|
| 1. | Razvan Crainea (@razvancrainea) | Apr 2024 - Sep 2024 |
| 2. | Alexandra Titoc | Sep 2024 - Sep 2024 |
| 3. | Liviu Chircu (@liviuchircu) | May 2024 - May 2024 |
(1) including any documentation-related commits, excluding merge commits
Last edited by: Razvan Crainea (@razvancrainea).
Documentation Copyrights:
Copyright © 2024 OpenSIPS Solutions;