M4 STIR/SHAKEN
About
M4 supports STIR/SHAKEN authentication (constructing 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://xxx.xxx.xxx.xxx/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.
- stirshaken_attest_level - the default attestation level (used when specific attestation level is not set in Termination 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://xxx.xxx.xxx.xxx/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 should be enabled in Origination or Termination Point Advanced settings:
- 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 (only for Origination Point) A, B, C or Default (use stirshaken_attest_level from /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://xxx.xxx.xxx.xxx/billing/cert.pem>alg=ES256;ppt=shaken
