STIR/SHAKEN Service

Table of Contents

1. Overview & Architecture
2. Business & Operational Significance
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Layout
5. Field & Configuration Reference
6. Cryptographic Mechanics & PASSporT Token Specification
7. Kamailio SecSIPID & STIR/SHAKEN Routing Logic
8. Security Best Practices & Operational Hardening
9. Model Context Protocol (MCP) AI Integration
10. Troubleshooting & Verification
11. 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.

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.

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.

---

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: • A (Full): Signer authenticated the caller and owns the caller ID number. • B (Partial): Signer authenticated the caller but cannot verify caller ID ownership. • 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

{
  "alg": "ES256",
  "ppt": "shaken",
  "typ": "passport",
  "x5u": "https://certs.ring2all.com/cert.pem"
}

2. JWS Payload

{
  "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:

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

---

7. Kamailio SecSIPID & STIR/SHAKEN Routing Logic

Database Schema

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

# 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

{
  "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:

{
  "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

{
  "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:

{
  "success": true,
  "data": {
    "message": "STIR/SHAKEN configuration updated successfully.",
    "signingEnabled": true,
    "verifyEnabled": true,
    "defaultAttestation": "A",
    "onVerifyFail": "allow_with_header"
  }
}

verify_caller_identity

{
  "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:

{
  "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

# 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

# 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

# Filter live calls and verify presence of Identity header
sngrep "Identity:"

Kamailio Engine Diagnostics

# 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.