---
title: "STIR/SHAKEN Service"
description: "Documentation for STIR/SHAKEN Service"
---

## Table of Contents
1. [Overview & Architecture](#1-overview--architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Layout](#4-visual-interface--form-layout)
5. [Field & Configuration Reference](#5-field--configuration-reference)
6. [Cryptographic Mechanics & PASSporT Token Specification](#6-cryptographic-mechanics--passport-token-specification)
7. [Kamailio SecSIPID & STIR/SHAKEN Routing Logic](#7-kamailio-secsipid--stirshaken-routing-logic)
8. [Security Best Practices & Operational Hardening](#8-security-best-practices--operational-hardening)
9. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
10. [Troubleshooting & Verification](#9-troubleshooting--verification)
11. [Glossary](#10-glossary)

---

## 1. Overview & Architecture

In **Ring2All SBC**, the **STIR/SHAKEN Service** module (`public.stir_shaken_config`) implements the industry-standard cryptographic framework designed to combat caller ID spoofing and illegal robocalling across IP telecommunications networks.

Governed by the **STIR** (Secure Telephony Identity Revisited - RFC 8224 / RFC 8588) and **SHAKEN** (Signature-based Handling of Asserted information using toKENs - ATIS-1000074) specifications, Ring2All SBC operates concurrently as both:
1. **STI-AS (Authentication Service)**: Signs outbound calls originating from trusted enterprise subscribers, generating a cryptographically signed **PASSporT** JSON Web Signature (JWS) formatted into a SIP `Identity` header.
2. **STI-VS (Verification Service)**: Inspects inbound calls arriving from upstream carriers, extracts the SIP `Identity` header, retrieves the public certificate from the carrier's repository (`x5u`), validates the cryptographic signature, and checks the certificate chain against trusted Certificate Authorities (CAs).

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │                    Outbound Call Originating from PBX                  │
 │                      INVITE sip:+17865550199...                        │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │           STI-AS: Kamailio secsipid Authentication Service             │
 │  1. Extract Calling Party ($fU) & Called Party ($rU)                   │
 │  2. Determine Attestation Level ('A', 'B', or 'C')                     │
 │  3. Build PASSporT Token (JSON Payload + Header with ES256)            │
 │  4. Sign using Private Key (ECDSA P-256 + SHA-256)                     │
 │  5. Attach SIP Header: Identity: <base64-jws>;info=<x5u>;alg=ES256     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │              Carrier PSTN Ingress (Upstream SIP Network)               │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │             STI-VS: Kamailio secsipid Verification Service             │
 │  1. Detect SIP Identity Header in Inbound INVITE                       │
 │  2. Fetch Public Certificate from x5u URL (or Local Cache)             │
 │  3. Verify X.509 Certificate Chain against Trusted CA Root Dir         │
 │  4. Check CRL (Certificate Revocation List)                            │
 │  5. Verify ECDSA Signature over Inbound Calling/Called Numbers         │
 │  6. Append Verification Results to CDR (P-Asserted-Identity / Verstat) │
 └────────────────────────────────────────────────────────────────────────┘
```

---

## 2. Business & Operational Significance

* **Regulatory Compliance**: Satisfies Federal Communications Commission (FCC) STIR/SHAKEN mandates (TRACED Act) and international telecommunications authority requirements for carrier voice interconnection.
* **Elevated Call Answer Rates**: Calls signed with **Full Attestation (Level A)** display as "Caller Verified" or checkmark indicators on consumer mobile devices (iOS, Android), drastically reducing unanswered calls for legitimate enterprise clients.
* **Robocall Mitigation & Reputation Shield**: Prevents enterprise telephone numbers from being illegitimately spoofed by bad actors, protecting company branding and caller ID reputation.
* **Carrier Interconnect Acceptance**: Major tier-1 carriers throttle, penalize, or outright block unauthenticated or spoofed SIP calls. Ring2All SBC ensures seamless call completion across all peering partners.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **SBC Administrator** | Cryptographic & Certificate Management | Configure private keys and x5u certificate URLs; assign Service Provider Code (SPC); set default attestation levels; tune caching and timeouts. |
| **Carrier NOC Engineer** | Telephony Verification Diagnostics | Inspect live 24-hour signing and verification metrics; debug failed identity validations; review raw Kamailio configuration blocks. |
| **Regulatory Compliance Officer** | Audit & Certification Verification | Verify X.509 certificate expiry dates, validate CA trust chains, and ensure compliance with STI-PA governance authority mandates. |
| **AI Platform Copilot / NOC Diagnostic Agent** | Cryptographic Verification & Audit | Execute `get_stirshaken_config`, `update_stirshaken_config`, and `verify_caller_identity` to audit signing pipelines, verify x5u public URLs, and simulate attestation levels. |

---

## 4. Visual Interface & Form Layout

The module provides four comprehensive tabs: **General**, **Signing (AS)**, **Verify (VS)**, and **Activity Log**, alongside a top-level **View Config** tool to inspect the generated Kamailio script block.

### Tab 1: General Overview & Health Status
Displays the global service master toggle and real-time operational status cards for STI-AS signing, STI-VS verification, and 24-hour transaction telemetry.

![STIR/SHAKEN General Tab](/screenshots/sbc/routing/stirshaken/stirshaken-general.png)

### Tab 2: Authentication Service (Signing - STI-AS)
Enables outbound signing, certificate file path bindings, x5u certificate URL configuration, Service Provider Code (SPC), and default attestation level assignment.

![STIR/SHAKEN Signing Tab](/screenshots/sbc/routing/stirshaken/stirshaken-signing.png)

### Tab 3: Verification Service (Verify - STI-VS)
Configures inbound identity verification, trusted CA root directories, certificate revocation lists (CRL), network timeouts, and local disk caching policies.

![STIR/SHAKEN Verification Tab](/screenshots/sbc/routing/stirshaken/stirshaken-verification.png)

---

## 5. Field & Configuration Reference

### General Tab: Service Status & Health Cards

| Field / Component | Type | Constraints / Format | Description |
| :--- | :--- | :--- | :--- |
| **STIR/SHAKEN Service** | Toggle | Active / Inactive | Master switch that globally enables or disables all STIR/SHAKEN signing and verification processing. |
| **Signing Status (STI-AS)** | Status Card | Active / Disabled / Not Configured | Displays whether outbound call signing is active and warns if certificate credentials are incomplete. |
| **Verify Status (STI-VS)** | Status Card | Active / Disabled | Displays whether inbound call identity verification is active. |
| **24h Activity Counter** | Metrics Card | Numeric counters | Aggregates successful signs, sign errors, verified calls, and signature failures over the past 24 hours. |

### Signing Tab: Authentication Service (STI-AS)

| Field | Type | Constraints / Format | Description |
| :--- | :--- | :--- | :--- |
| **Signing Enabled** | Toggle | Active / Inactive | Enables cryptographic signing of outbound calls with a SIP `Identity` header. |
| **Sign Outbound Only** | Toggle | Active / Inactive | When enabled, only calls routed to external wholesale carriers are signed, skipping internal domain extensions. |
| **Private Key Path \*** | Text | Valid absolute filesystem path | Filesystem path to the ECDSA private key PEM file (e.g., `/etc/kamailio/stirshaken/private.pem`). |
| **Certificate File Path \*** | Text | Valid absolute filesystem path | Filesystem path to the local public certificate PEM file (e.g., `/etc/kamailio/stirshaken/cert.pem`). |
| **Certificate URL (x5u) \*** | Text | Valid HTTPS URL | The public web URL where terminating carriers download your public certificate to verify signatures. |
| **SPC Token** | Text | Alphanumeric (e.g., `1234`) | Service Provider Code issued by the national STI-PA (Policy Administrator). |
| **Default Attestation \*** | Dropdown | `A`, `B`, `C` | Default attestation level applied when no specific customer tier overrides are defined: <br>• **A (Full)**: Signer authenticated the caller and owns the caller ID number.<br>• **B (Partial)**: Signer authenticated the caller but cannot verify caller ID ownership.<br>• **C (Gateway)**: Signer received call from a gateway with no caller identity verification. |
| **Cert Expiration** | Read-Only | Auto-detected date | The expiration date parsed from the configured public X.509 certificate. |

### Verification Tab: Verification Service (STI-VS)

| Field | Type | Constraints / Format | Description |
| :--- | :--- | :--- | :--- |
| **Verification Enabled** | Toggle | Active / Inactive | Enables inspection and verification of SIP `Identity` headers on inbound carrier calls. |
| **X.509 Path Validation** | Toggle | Active / Inactive | Enforces full cryptographic certificate chain validation against trusted root Certificate Authorities. |
| **CA Root Directory** | Text | Valid directory path | Path containing hashed trusted root CA certificates (e.g., `/etc/kamailio/stirshaken/ca`). |
| **CRL Directory** | Text | Valid directory path | Path containing Certificate Revocation Lists to identify revoked certificates (e.g., `/etc/kamailio/stirshaken/crl`). |
| **Identity Expire (sec)** | Number | 10–600 seconds (Default: 60) | Maximum acceptable age of a PASSporT token before it is rejected as expired or replayed. |
| **Connect Timeout (sec)** | Number | 1–30 seconds (Default: 5) | Maximum HTTP connection timeout when fetching remote public certificates from external `x5u` URLs. |
| **Enable Caching** | Toggle | Active / Inactive | Caches downloaded external certificates locally to eliminate redundant HTTP requests during call setup. |
| **Cache Expire (sec)** | Number | 30–86,400 seconds (Default: 120) | Time in seconds before cached public certificates are refreshed. |
| **Cache Directory** | Text | Valid directory path | Filesystem path where downloaded remote certificates are cached (e.g., `/etc/kamailio/stirshaken/cache`). |

---

## 6. Cryptographic Mechanics & PASSporT Token Specification

STIR/SHAKEN utilizes **PASSporT** (Personal Assertion Token - RFC 8225), which is a JSON Web Signature (JWS) structured in three base64url-encoded parts:

### 1. JWS Header
```json
{
  "alg": "ES256",
  "ppt": "shaken",
  "typ": "passport",
  "x5u": "https://certs.ring2all.com/cert.pem"
}
```

### 2. JWS Payload
```json
{
  "attest": "A",
  "dest": {
    "tn": ["17865550199"]
  },
  "iat": 1773057600,
  "orig": {
    "tn": "13055551234"
  },
  "origid": "d0a25159-4625-44ed-b327-1e6ef176833e"
}
```

### 3. Cryptographic Signature
The header and payload are concatenated with a period (`.`) and signed using the private key with the **ES256** algorithm (ECDSA using curve P-256 and SHA-256). The resulting signature string is injected into the SIP request:

```http
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0I...;info=<https://certs.ring2all.com/cert.pem>;alg=ES256;ppt=shaken
```

---

## 7. Kamailio SecSIPID & STIR/SHAKEN Routing Logic

### Database Schema

```sql
CREATE TABLE public.stir_shaken_config (
    id SERIAL PRIMARY KEY,
    enabled BOOLEAN NOT NULL DEFAULT TRUE,
    signing_enabled BOOLEAN NOT NULL DEFAULT TRUE,
    sign_outbound_only BOOLEAN NOT NULL DEFAULT TRUE,
    private_key_path VARCHAR(255),
    certificate_path VARCHAR(255),
    certificate_url VARCHAR(255),
    spc_token VARCHAR(64),
    default_attestation VARCHAR(1) NOT NULL DEFAULT 'A',
    certificate_expiry TIMESTAMPTZ,
    verify_enabled BOOLEAN NOT NULL DEFAULT TRUE,
    verify_x509_cert_path BOOLEAN NOT NULL DEFAULT TRUE,
    ca_dir VARCHAR(255) DEFAULT '/etc/kamailio/stirshaken/ca',
    crl_dir VARCHAR(255) DEFAULT '/etc/kamailio/stirshaken/crl',
    identity_expire_s INT NOT NULL DEFAULT 60,
    connect_timeout_s INT NOT NULL DEFAULT 5,
    cache_certificates BOOLEAN NOT NULL DEFAULT TRUE,
    cache_expire_s INT NOT NULL DEFAULT 120,
    cache_dir VARCHAR(255) DEFAULT '/etc/kamailio/stirshaken/cache',
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

### Kamailio Script Routing Execution

```c
# Load secsipid module in kamailio.cfg
loadmodule "secsipid.so"
loadmodule "secsipid_proc.so"

# Outbound Signing Route
route[STIR_SHAKEN_SIGN] {
    if ($sht(stirshaken=>enabled) != 1 || $sht(stirshaken=>signing_enabled) != 1) return;

    # Apply signing parameters
    $var(orig) = $fU; # Caller number
    $var(dest) = $rU; # Callee number
    $var(attest) = $sht(stirshaken=>default_attestation);

    # Generate and inject PASSporT Identity header
    if (secsipid_sign("$var(orig)", "$var(dest)", "$var(attest)")) {
        xlog("L_INFO", "STIR/SHAKEN Identity successfully generated for call from $var(orig) to $var(dest)\n");
    } else {
        xlog("L_ERR", "Failed to generate STIR/SHAKEN Identity header\n");
    }
}

# Inbound Verification Route
route[STIR_SHAKEN_VERIFY] {
    if ($sht(stirshaken=>enabled) != 1 || $sht(stirshaken=>verify_enabled) != 1) return;

    if (is_present_hf("Identity")) {
        # Verify signature against public certificate
        $var(res) = secsipid_check_identity();
        switch($var(res)) {
            case 1:
                # Valid signature
                append_hf("P-Asserted-Identity-Verstat: TN-Validation-Passed\r\n");
                break;
            default:
                # Invalid signature or expired token
                append_hf("P-Asserted-Identity-Verstat: TN-Validation-Failed\r\n");
                break;
        }
    } else {
        append_hf("P-Asserted-Identity-Verstat: No-TN-Validation\r\n");
    }
}
```

---

## 8. Security Best Practices & Operational Hardening

* **Set Fast Network Timeouts**: For inbound verification, ensure CRL and certificate HTTP retrieval timeouts are set to 1500–2000 ms to avoid introducing perceptible Post-Dial Delay (PDD) on answered calls.
* **Monitor Certificate Expiry**: Configure alerts at 30, 15, and 5 days prior to STI certificate expiration to prevent abrupt call rejection by peer terminating networks.

---

## Model Context Protocol (MCP) AI Integration

The **STIR/SHAKEN Service** module integrates with the Ring2All SBC Model Context Protocol (MCP) server, allowing AI Copilots, compliance auditing agents, and NOC diagnostics to inspect signing/verification configurations, update attestation parameters, and simulate identity validation for caller numbers.

### MCP Tools Catalog

| Tool Name | Type | Access | Description |
| :--- | :--- | :--- | :--- |
| `get_stirshaken_config` | Query | `stir_shaken` / Read | Get STIR/SHAKEN Caller ID verification & signing configuration in Ring2All SBC (attestation level A/B/C, certificate paths, verification mode). |
| `update_stirshaken_config` | Mutation | `stir_shaken` / Write | Update STIR/SHAKEN signing/verification settings, default attestation level, or certificate details. |
| `verify_caller_identity` | Query | `stir_shaken` / Read | Simulate or check STIR/SHAKEN attestation level policy for a specific calling number. |

### Tool Schemas & Execution Responses

#### `get_stirshaken_config`
```json
{
  "name": "get_stirshaken_config",
  "description": "Get STIR/SHAKEN Caller ID verification & signing configuration in Ring2All SBC (attestation level A/B/C, certificate paths, verification mode).",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}
```

**Realistic Execution Response:**
```json
{
  "success": true,
  "data": {
    "enabled": true,
    "signingEnabled": true,
    "verifyEnabled": true,
    "defaultAttestation": "A",
    "certificateUrl": "https://certs.ring2all.com/cr-p256.cer",
    "certificatePath": "/etc/kamailio/stirshaken/cert.pem",
    "privateKeyPath": "Configured (Secured)",
    "verifyCertPath": "/etc/ssl/certs",
    "onVerifyFail": "allow_with_header",
    "identityExpireSec": 60,
    "updatedAt": "2026-09-08T07:15:00Z"
  }
}
```

#### `update_stirshaken_config`
```json
{
  "name": "update_stirshaken_config",
  "description": "Update STIR/SHAKEN signing/verification settings, default attestation level, or certificate details.",
  "parameters": {
    "type": "object",
    "properties": {
      "enabled": { "type": "boolean", "description": "Enable or disable STIR/SHAKEN subsystem globally." },
      "signingEnabled": { "type": "boolean", "description": "Enable or disable outbound PASSporT JWT signing." },
      "verifyEnabled": { "type": "boolean", "description": "Enable or disable inbound Identity header verification." },
      "defaultAttestation": { "type": "string", "enum": ["A", "B", "C"] },
      "certificateUrl": { "type": "string", "description": "Public URL to the STI certificate (x5u header)." },
      "onVerifyFail": { "type": "string", "enum": ["allow_with_header", "drop_call", "strip_callerid"] }
    }
  }
}
```

**Realistic Execution Response:**
```json
{
  "success": true,
  "data": {
    "message": "STIR/SHAKEN configuration updated successfully.",
    "signingEnabled": true,
    "verifyEnabled": true,
    "defaultAttestation": "A",
    "onVerifyFail": "allow_with_header"
  }
}
```

#### `verify_caller_identity`
```json
{
  "name": "verify_caller_identity",
  "description": "Simulate or check STIR/SHAKEN attestation level policy for a specific calling number.",
  "parameters": {
    "type": "object",
    "properties": {
      "callerNumber": {
        "type": "string",
        "description": "E.164 phone number to evaluate for STIR/SHAKEN signing."
      }
    },
    "required": ["callerNumber"]
  }
}
```

**Realistic Execution Response:**
```json
{
  "success": true,
  "data": {
    "callerNumber": "+17865550199",
    "isOwnedNumber": true,
    "recommendedAttestation": "A",
    "signingEligible": true,
    "certificateActive": true,
    "x5uHeader": "https://certs.ring2all.com/cr-p256.cer",
    "notes": "Calling number matches authenticated customer DID inventory. Full attestation (Level A) granted."
  }
}
```

### Bilingual Natural Language Prompt Examples

#### English Prompts
- *"NOC Copilot, what is the current STIR/SHAKEN signing and verification status?"*
- *"Verify what attestation level will be assigned to outbound caller ID '+17865550199'."*
- *"Check the x5u public certificate URL configured for PASSporT tokens."*
- *"What action does the SBC take when inbound STIR/SHAKEN verification fails?"*

#### Spanish Prompts
- *"Copilot NOC, ¿cuál es el estado actual de firma y verificación de STIR/SHAKEN?"*
- *"Verifica qué nivel de atestación se le asignará al número saliente '+17865550199'."*
- *"Consulta la URL pública del certificado x5u configurada para los tokens PASSporT."*
- *"¿Qué acción realiza el SBC cuando falla la verificación de STIR/SHAKEN en llamadas entrantes?"*

### Enterprise Safeguards & Execution Boundaries
1. **FCC TRACED Act Governance:** The attestation policy enforces strict ATIS-1000074 standards. Full Attestation (Level A) is strictly restricted to DIDs verified in the customer's owned inventory.
2. **Private Key Masking:** Cryptographic private keys reside in secure filesystem storage (`0600` permissions). MCP tools never disclose or export private key material over API payloads.
3. **Fail-Open vs Fail-Secure Protection:** Operators can select between `allow_with_header`, `strip_callerid`, and `drop_call` when verification fails, balancing security with legitimate call completion.

---

## 9. Troubleshooting & Verification

### Inspect STIR/SHAKEN Configuration State
```bash
# Verify database parameters
psql -U softswitch -d ss_telephony -c "SELECT enabled, signing_enabled, verify_enabled, default_attestation, certificate_url FROM public.stir_shaken_config;"
```

### Validate Private Key and Public Certificate Match
```bash
# Check public key from private key
openssl ec -in /etc/kamailio/stirshaken/private.pem -pubout

# Check public key from certificate
openssl x509 -in /etc/kamailio/stirshaken/cert.pem -pubkey -noout
```

### Trace SIP Signaling for Identity Header
```bash
# Filter live calls and verify presence of Identity header
sngrep "Identity:"
```

### Kamailio Engine Diagnostics
```bash
# Reload STIR/SHAKEN configuration without Kamailio restart
kamcmd secsipid.reload
```

---

## 10. Glossary

* **STIR (RFC 8224)**: Secure Telephony Identity Revisited; protocol for end-to-end cryptographic authentication of telephone identities.
* **SHAKEN (ATIS-1000074)**: Signature-based Handling of Asserted information using toKENs; framework specifying implementation of STIR within service provider IP networks.
* **PASSporT (RFC 8225)**: Personal Assertion Token; the JSON Web Signature token format containing caller and callee numbers, attestation, and signature.
* **STI-AS (Authentication Service)**: The subsystem that validates caller identity and attaches the PASSporT token.
* **STI-VS (Verification Service)**: The subsystem that validates the PASSporT token and certificate trust chain on inbound calls.
* **Attestation Level**: Telephony trust level (A, B, or C) assigned by the originating service provider indicating confidence in caller identity.
* **x5u**: URI parameter pointing to the public X.509 certificate used by terminating carriers to verify the cryptographic signature.