---
title: "TLS Profiles"
description: "Documentation for TLS Profiles"
---

## Table of Contents
1. [Overview & Cryptographic Architecture](#1-overview--cryptographic-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & Profile Parameters](#5-field-reference--profile-parameters)
6. [Kamailio `tls_mgm` Module Mechanics](#6-kamailio-tls_mgm-module-mechanics)
7. [Microsoft Teams Direct Routing & Carrier mTLS Requirements](#7-microsoft-teams-direct-routing--carrier-mtls-requirements)
8. [Troubleshooting & Verification](#8-troubleshooting--verification)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Cryptographic Architecture

In **Ring2All SBC**, the **TLS Profiles** module centralizes the governance, assignment, and renewal of SSL/TLS cryptographic profiles for secure SIP signaling (SIP-TLS over port 5061) and WebRTC signaling (WSS over port 443). Powered by Kamailio's `tls_mgm` and `tls` modules, the SBC supports multi-domain Server Name Indication (SNI), modern elliptic-curve cipher suites, automated Certificate Authority (CA) chain validation, and Mutual TLS (mTLS) client verification.

```
External Endpoint (MS Teams / Carrier / PBX)                Ring2All SBC (Kamailio Core)
                     │                                                   │
                     │─────── TLS Client Hello (with SNI) ──────────────>│
                     │        "sbc.ring2all.com"                         │─── Match TLS Profile (SNI) ───┐
                     │                                                   │    Load cert.pem & key.pem    │
                     │<────── TLS Server Hello + Server Certificate ─────│<──────────────────────────────┘
                     │                                                   │
                     │─── (Optional mTLS) Client Certificate ───────────>│─── Verify against CA Bundle ─┐
                     │                                                   │<──────────────────────────────┘
                     │<────── TLS Handshake Complete (AES-256-GCM) ──────│
                     │                                                   │
                     │═══════ Encrypted SIP Signaling (Port 5061) ═══════│
```

Profiles can be dynamically updated and hot-reloaded into Kamailio shared memory via JSON-RPC, preventing dropped calls or service interruptions when renewing TLS certificates.

---

## 2. Business & Operational Significance

* **End-to-End Signaling Confidentiality**: Protects voice metadata, subscriber passwords, and routing details from perimeter eavesdropping and packet sniffing.
* **Regulatory Compliance**: Satisfies strict encryption mandates required by HIPAA, PCI-DSS Level 1, and European GDPR data transmission frameworks.
* **Microsoft Teams Direct Routing Certification**: Delivers the exact cryptographic parameters (TLS 1.2+, ECDHE ciphers, and public commercial CA trust) required for Microsoft Direct Routing interconnects.
* **Carrier Mutual Authentication (mTLS)**: Enforces bi-directional cryptographic verification on high-volume SIP trunking interconnects, ensuring that only authenticated carrier partners can inject traffic.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **Security Architect** | Cryptographic Policy & Ciphers | Enforce modern cipher suites, deprecate legacy SSL/TLS versions, and mandate forward secrecy (PFS). |
| **Cryptographic Key Manager** | Certificate Lifecycle Governance | Provision new TLS certificates, upload Let's Encrypt or commercial certificates, and configure renewal alerts. |
| **SBC Operations Specialist** | Live Profile Reloading | Bind TLS profiles to specific network listening sockets and execute hot reloads without engine restarts. |
| **Voice Interconnect Engineer** | Carrier mTLS Onboarding | Configure trusted CA bundles and client verification modes for enterprise partners and Microsoft Teams trunks. |
| **AI Security Copilot / Cryptographic Auditor** | Certificate & Cipher Governance | Inspect TLS profile expiration, audit client verification modes, and issue atomic TLS memory reloads via MCP. |

---

## 4. Visual Interface & Layout

The TLS Profiles interface presents a catalog of all configured security profiles, along with a modal configuration form for defining cryptographic parameters, certificates, and ciphers.

### 4.1 TLS Profiles List View
Displays all available TLS profiles, their associated domain/SNI names, TLS protocol versions, verification modes, and validity status.

![TLS Profiles List View](/screenshots/sbc/settings/technology/tls-profiles/tls-profiles-list.png)

### 4.2 TLS Profile Configuration Form
Form modal used to configure certificate paths, private keys, CA trust stores, and cipher strings.

![TLS Profile Configuration Form](/screenshots/sbc/settings/technology/tls-profiles/tls-profile-form.png)

---

## 5. Field Reference & Profile Parameters

| Field Name | Data Type | Default | Description |
| :--- | :--- | :--- | :--- |
| **Profile Name** | String | `tls_standard` | Unique internal identifier for the TLS profile (e.g., `tls_standard`, `tls_msteams`). |
| **TLS Method** | Select | `TLSv1.2+` | Permitted TLS protocol versions: `TLSv1.2+` (recommended) or `TLSv1.3 only`. Older versions (SSLv3, TLS 1.0, 1.1) are strictly blocked. |
| **Server Name (SNI)** | String | `sbc.ring2all.com` | Fully qualified domain name (FQDN) matched against the incoming client's SNI extension. |
| **Certificate Path** | String / File | `/etc/kamailio/certs/cert.pem` | Absolute path or file upload of the PEM-encoded X.509 server certificate (including full chain). |
| **Private Key Path** | String / File | `/etc/kamailio/certs/key.pem` | Absolute path or file upload of the unencrypted RSA or ECDSA private key. |
| **CA List Path** | String / File | `/etc/ssl/certs/ca-certificates.crt` | Path to trusted Certificate Authority bundle used to validate client certificates in mTLS mode. |
| **Cipher Suites** | String | `ECDHE-ECDSA-AES256-GCM...` | Colon-delimited OpenSSL cipher string. Enforces forward secrecy and AEAD encryption. |
| **Verify Client** | Select | `Optional` | Client certificate verification behavior: `Disabled`, `Optional`, or `Mandatory / Enforced`. |
| **Require Client Cert** | Switch | `Off` | If enabled, the SBC abruptly terminates the TLS handshake if the remote client does not present a valid certificate. |

---

## 6. Kamailio `tls_mgm` Module Mechanics

Kamailio manages TLS contexts dynamically through the `tls_mgm` (TLS Management) module:

```text
# Sample Kamailio tls_mgm profile definition
loadmodule "tls.so"
loadmodule "tls_mgm.so"

modparam("tls_mgm", "tls_method", "TLSv1.2+")
modparam("tls_mgm", "verify_cert", "1")
modparam("tls_mgm", "require_cert", "0")
modparam("tls_mgm", "certificate", "/etc/kamailio/certs/cert.pem")
modparam("tls_mgm", "private_key", "/etc/kamailio/certs/key.pem")
modparam("tls_mgm", "ca_list", "/etc/ssl/certs/ca-certificates.crt")
modparam("tls_mgm", "ciphers_list", "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305")
```

Whenever certificates are renewed on disk, an operator triggers `tls.reload` via the RPC Console. Kamailio atomically instantiates a new OpenSSL SSL_CTX context in memory and swaps pointer references without terminating ongoing calls.

---

## 7. Microsoft Teams Direct Routing & Carrier mTLS Requirements

When interfacing with Microsoft Teams Direct Routing or tier-1 carrier interconnects, strict cryptographic requirements must be enforced:

1. **Approved Public CA**: The certificate must be issued by an approved root authority (e.g., DigiCert, Sectigo, GlobalSign). Self-signed certificates are rejected by Microsoft.
2. **FQDN Matching**: The SAN (Subject Alternative Name) of the certificate must match the exact FQDN registered in the Microsoft 365 Admin Center (e.g., `sbc.ring2all.com`).
3. **Mandatory Ciphers**: Microsoft requires TLS 1.2 with ECDHE cipher suites:
   * `ECDHE-RSA-AES256-GCM-SHA384`
   * `ECDHE-RSA-AES128-GCM-SHA256`

---

## 8. Troubleshooting & Verification

### Probing TLS Handshake from External Host
Verify certificate chains, ciphers, and protocol negotiation using OpenSSL:
```bash
openssl s_client -connect sbc.ring2all.com:5061 -servername sbc.ring2all.com -showcerts
```
Verify the output confirms:
```text
Protocol  : TLSv1.3
Cipher    : TLS_AES_256_GCM_SHA384
Verify return code: 0 (ok)
```

### Hot-Reloading TLS Contexts via RPC
After updating certificate files on the SBC file system, trigger a hot reload without restarting Kamailio:
```bash
tls.reload
```
Output:
```json
{
  "jsonrpc": "2.0",
  "result": "TLS configuration successfully reloaded",
  "id": 1
}
```

---

## 9. Model Context Protocol (MCP) AI Integration

The TLS Profiles subsystem exposes dedicated Model Context Protocol (MCP) tools enabling automated cryptographic inspection, certificate expiration auditing, and zero-downtime runtime reload triggers.

### Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `list_tls_profiles` | Status Query | `read` | List all configured TLS cryptographic profiles (server name, methods, cipher suites, certificate paths). |
| `get_tls_profile_status` | Certificate Audit | `read` | Get runtime status, validation state, and certificate expiration for a specific TLS profile. |
| `reload_tls_profiles` | Operational Reload | `operational` | Issue a runtime reload command (`tls.reload`) to Kamailio via JSON-RPC without terminating calls. |

### Tool Schemas & Payloads

#### 1. `list_tls_profiles`

##### Input Schema
```json
{
  "type": "object",
  "properties": {}
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "totalProfiles": 2,
    "profiles": [
      {
        "id": 1,
        "name": "tls_standard",
        "server_name": "sbc.ring2all.com",
        "method": "TLSv1.2+",
        "verify_client": "optional",
        "require_client_cert": false,
        "cipher_suite": "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384"
      },
      {
        "id": 2,
        "name": "tls_msteams",
        "server_name": "teams.ring2all.com",
        "method": "TLSv1.2+",
        "verify_client": "mandatory",
        "require_client_cert": true,
        "cipher_suite": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256"
      }
    ]
  }
}
```

#### 2. `get_tls_profile_status`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "profile_id": {
      "type": "number",
      "description": "Numeric identifier of the TLS profile to inspect."
    }
  },
  "required": ["profile_id"]
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "tls_standard",
    "server_name": "sbc.ring2all.com",
    "certificate_path": "/etc/kamailio/certs/cert.pem",
    "certificate_exists": true,
    "private_key_exists": true,
    "status": "VALID",
    "expires_at": "2027-01-15T00:00:00.000Z"
  }
}
```

#### 3. `reload_tls_profiles`

##### Input Schema
```json
{
  "type": "object",
  "properties": {}
}
```

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "message": "TLS profiles reloaded successfully in Kamailio core.",
    "rpc_response": "TLS configuration successfully reloaded"
  }
}
```

### Natural Language AI Prompts

#### English Examples
* *"List all configured TLS profiles on the SBC and check their client verification settings."*
* *"Check the expiration date and certificate status for TLS profile ID 1."*
* *"Hot-reload the TLS cryptographic profiles in Kamailio memory without restarting the service."*

#### Spanish Examples (Español)
* *"Lista todos los perfiles TLS configurados en el SBC y comprueba sus ajustes de verificación de cliente."*
* *"Comprueba la fecha de expiración y el estado del certificado para el perfil TLS con ID 1."*
* *"Recarga en caliente los perfiles criptográficos TLS en la memoria de Kamailio sin reiniciar el servicio."*

### Enterprise Safeguards & Access Governance
1. **Private Key Masking**: Cryptographic private key contents are never read, printed, or transmitted through MCP tools.
2. **Atomic Context Swap**: The `reload_tls_profiles` tool invokes Kamailio's memory pointer swap, ensuring zero disruption to existing encrypted calls.
3. **Strict RBAC Enforcement**: Modifying or reloading TLS cryptographic contexts is restricted to the `sbc_system_admin` or `noc_network_engineer` role.

---

## 10. Glossary

* **mTLS (Mutual TLS)**: A security process where both client and server authenticate each other simultaneously using X.509 digital certificates.
* **SNI (Server Name Indication)**: An extension to the TLS protocol that indicates which hostname the client is attempting to connect to at the start of the handshaking process.
* **Forward Secrecy (PFS)**: A feature of secure communication protocols ensuring that compromised long-term private keys cannot decrypt past session traffic.
* **X.509 Certificate**: A standard format for public key certificates that cryptographically binds an identity to a public key.