Deploying STIR/SHAKEN with Kamailio

Martini Security

Deploying STIR/SHAKEN with Kamailio

Version 1.1

© Copyright 2023

This work is licensed under the Creative

Commons Aribution-NoDerivatives 4.0

International License.

Deploying STIR/SHAKEN with Kamailio

Background

The recommended approach involves using Vermouth, an application that operates as a separate

service alongside Kamailio. Vermouth provides a REST API for signing and verifying SIP calls within

Kamailio and includes its own lightweight ACME client for automatic certicate renewal.

Sample Conguration Notes

The information provided in this document has been tested on Ubuntu Server 22 LTS, using the

latest packages available as of April 4, 2023. While not guaranteed, it is assumed that other

Debian-based distributions or RHEL/Fedora systems may also be compatible.

Conguration snippets were validated using Kamailio 5.6 congured with MySQL 8. Tests were

conducted with both static Debian packages and binaries compiled from the source. Alternative

database engines can be used in place of MySQL, as Kamailio supports several options. However, a

This guide assumes that the reader possesses a strong understanding of Kamailio, its ecosystem,

and SIP. Familiarity with the ATIS STIR/SHAKEN specications is also benecial.

Geing Started

Before deploying, you must rst create an account with Martini Security and obtain an API key. This

process involves four steps:

1. Register for an account with Martini Security and acquire an API key.

2. Submit your FCC 499 ler ID.

3. Select a subscription plan and complete payment.

4. Have the registered 499 ler approve the request to represent their organization.

Account creation typically takes only a few minutes.

4. Locate the sections labeled“Key ID”and “API Key”and copy these somewhere. You will need

them soon regardless of which mechanism you will use to implement STIR/SHAKEN.

For more information, watch this video: https://www.youtube.com/watch?v=CXvR-jyJVx4&t=1s

Additionally, you will need your STI-PA API credentials and OCN, which can be found in the

credentials you created at iConectiv’s STIR/SHAKEN provider portal.

General Kamailio + STIR/SHAKEN Guidance

All STIR/SHAKEN implementations require the following information:

• X5U

• Public STIR/SHAKEN certicate HTTP URL

• Attestation Level

• Call identier specied by signer (unspecied OrigIDs cause most signing engines to

generate and use a UUID)

• Private Key Path

• Signing key used to sign calls

Kamailio offers numerous built-in pseudo variables. In the examples provided, from user ($fU) and

to user ($tU) are used for signing requests. Note that for US-based calling and called parties, signing

requests must use the 11-digit format –i.e., “1NXXNXXXXXX”.

Testing was conducted with SIP To and From User data formatted as “+1NXXNXXXXXX”, so string

manipulation was performed to remove the “+”. Keep in mind that the sources of origTN and

destTN are specic to your VoIP environment.

requests, providing appropriate responses. It offers various services, including ACME operations for

requesting and renewing signing certicates.

Installation

Vermouth can be installed from a package or built from the source. After downloading the current

release (or manually building the package), install it using dpkg -i vermouth-X.X.X.deb. By default,

/etc/vermouth is the YAML master conguration le that must be modied before starting

Vermouth.

Vermouth Conguration

First, open /etc/vermouth in your preferred text editor. Most of the default elds already contain the

recommended values and can be left unchanged. However, the following lines need to be modied: