M4 STIR/SHAKEN

About

M4 supports STIR/SHAKEN authentication (construction of the SIP Identity header).

Requirements

• Kamailio 5.7 (or later)
• Private key (.pem file, encoded in ES256 algorithm, without password)
• Public certificate (.pem file or URL to certificate)

Kolmisoft does not provide private key and public certificate. These should be acquired from STIR/SHAKEN certificate authorities.

Installation

STIR/SHAKEN authentication service is not installed by default and should be installed manually, depending on OS:

On CentOS 7:

/usr/src/m4/kamailio/stirshaken/stirshaken_install.sh

On Rocky 9

/usr/src/m4/kamailio/stirshaken/stirshaken_install_r9.sh

Configuration

After the installation, STIR/SHAKEN should be configured on Kamailio server. Configuration is done in /etc/m2/system.conf.

The following settings should be added to conf file:

stirshaken_enabled = 1
stirshaken_x5u = https://m4_host/billing/cert.pem
stirshaken_attest_level = C
stirshaken_private_key = /path/to/my/private_key.pem

Here:

• stirshaken_enabled - controls if STIR/SHAKEN should be enabled or not.
• stirshaken_x5u - URL to public certificate. If the certificate is stored locally, it needs to be placed in GUI server in /var/www/html/public directory.
• stirshaken_attest_level - the default attestation level (used when specific attestation level is not set in Connection Point settings).
• stirshaken_private_key - path to private key.

After configuration is set, Kamailio needs to be reconfigured with the new settings:

/usr/src/m4/kamailio/kamailio_cfg_update.sh

The following output should be visible during Kamailio configuration update:

               ...
               ...
               Starting Stirshaken configure script v1.0.1
OK             Stirshaken is enabled in /etc/m2/system.conf
OK             Stirshaken x5u header: https://m4_host/billing/cert.pem
OK             Stirshaken attestation level: C
OK             Stirshaken private key: /path/to/my/private_key.pem
               ...
               ...

In case of an error, STIR/SHAKEN will be disabled.

Kamailio restart is required for changes to take effect:

systemctl restart kamailio

Enabling STIR/SHAKEN

STIR/SHAKEN authentication can be enabled in Origination and/or Termination Point Advanced settings. If both OP and TP have STIR/SHAKEN authentication enabled, then OP attestation level has higher priority (unless selected "By TP", see bellow):

• Add STIR/SHAKEN Identity - should we add the SIP Identity header when calling to this Termination Point?
• STIR/SHAKEN Attestation Level - set attestation level.
  • By TP - attestation level will be set by TP settings (option is visible only for Origination Points)
  • A - attestation level A
  • B - attestation level B
  • C - attestation level C
  • Default - default attestation level set in /etc/m2/system.conf

Testing

To check if the Identity header was added, sngrep could be used to inspect the outgoing Invite header:

INVITE sip:11111111@example.com:5060 SIP/2.0
Via: SIP/2.0/UDP example.com:5060
From: <sip:22222222@5.6.7.8:5060>;tag=123456789
To: <sip:11111111@1.2.3.4:5060>
Call-ID: 1-12345@5.6.7.8
CSeq: 1 INVITE
Max-Forwards: 70
Identity:  eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0aWZpY2F0ZXMuZXhhbXBsZS5jb20vMTIzNDU2Nzg5LnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxODAwMTIzNDU2NyJdfSwiaWF0IjoxNTQ4ODU5OTgyLCJvcmlnIjp7InRuIjoiMTQwNDUyNjYwNjAifSwib3JpZ2lkIjoiM2E0N2NhMjMtZDdhYi00NDZiLTgyMWQtMzNkNWRlZWRiZWQ0In0.S_vqkgCk88ee9rtk89P6a6ru0ncDfSrdb1GyK_mJj-10hsLW-dMF7eCjDYARLR7EZSZwiu0fd4H_QD_9Z5U2bg;info=<https://m4_host/billing/cert.pem>alg=ES256;ppt=shaken

Certificate update

In general, STIR/SHAKEN certificate can be updated just by replacing old certificate with the new one.

Certificate can be stored locally or externally. Check /etc/m2/system.conf configuration file for variable stirshaken_x5u to determine if certificate is local or from external source.

For example:

stirshaken_x5u = https://YOUR_SERVER_HOST/billing/cert.pem

shows that STIR/SHAKEN certificate is stored locally in your server.

stirshaken_x5u = https://SOME_EXTERNAL_HOST/path/to/cert.pem

shows that STIR/SHAKEN certificate is located in some external server.

When certificate is stored locally

To update local STIR/SHAKEN certificate, upload your certificate to server defined in stirshaken_x5u parameter to directory /var/www/html/public/.

Note: keep the old certificate name, just overwrite the existing expired certificate - this will prevent the need to reconfigure Kamailio.

When certificate is stored externally

No changes are required if the URL for STIR/SHAKEN did not change. If the URL is changed (for example the name of certificate is changed), then Kamailio reconfigure is needed.

Kamailio reconfigure

If the new STIR/SHAKEN certificate is located in the same URL with the same name and private key was not changed during certificate update, then no additional actions are needed.

Otherwise, Kamailio needs to be reconfigured for new path defined in stirshaken_x5u and/or new private key defined in stirshaken_private_key.

Reconfigure Kamailio:

/usr/src/m4/kamailio/kamailio_cfg_update.sh

Stop M4 core on Radius server:

m2 stop

Restart Kamailio on Kamailio server:

service kamailio restart

Restart M4 core on Radius server:

service radiusd restart

If there are errors during the configuration update or Kamailio restart:

• Check /var/log/syslog or /var/log/kamailio.log for details.
• Ensure the certificate and private key paths are correct and accessible.
• Verify that the certificate and private key are valid and properly formatted.

See also

• M4 Termination Points