Access Control Lists (ACL) & Trusted SIP Peers

Overview & Permissions Architecture
Business & Operational Significance
🎯 User Roles & Key Capabilities
Visual Interface & Layout
Field Reference: Trusted IPs & Address Groups
Kamailio Permissions Module & Routing Logic
Address Group Numbering & Telephony Roles
Operational Hardening & Best Practices
Verification & Diagnostics
Model Context Protocol (MCP) AI Integration
Glossary

1. Overview & Permissions Architecture

In Ring2All SBC, the Access Control List (ACL) module delivers telecom-grade trust governance and IP authorization for SIP signaling. Directly backed by Kamailio’s native permissions module, the ACL engine manages two fundamental database tables: kamailio.trusted (IP-based authentication for PBX core nodes and carrier gateways) and kamailio.address (group-based IP/subnet routing classifications).

       ┌─────────────────────────────────────────────────────────────┐
       │                 INCOMING SIP SIGNALING PACKET               │
       │                   (Source IP, Protocol, Port)               │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
       ┌──────────────────────────────▼──────────────────────────────┐
       │          KAMAILIO PERMISSIONS MODULE EVALUATION             │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
              ┌───────────────────────┴───────────────────────┐
              ▼                                               ▼
       ┌──────────────────────────────┐                ┌──────────────────────────────┐
       │   check_source_address(grp)  │                │     allow_trusted() CHECK    │
       │    (Table: kamailio.address) │                │    (Table: kamailio.trusted) │
       ├──────────────────────────────┤                ├──────────────────────────────┤
       │ • Group 1: Trusted SBC Node  │                │ • Core Telephony Cluster    │
       │ • Group 8: PBX Auth (Bypass) │                │ • Carrier Wholesale Gateways │
       │ • Group 9: CPS Rate Limits   │                │ • RTPEngine Media Relays     │
       └──────────────────────────────┘                └──────────────────────────────┘
                                      │
                                      ▼
       ┌─────────────────────────────────────────────────────────────┐
       │         AUTHENTICATION BYPASS & ROUTING DISPATCH            │
       │ (Trusted traffic skips SIP 401/407 digest challenges;       │
       │  Untrusted traffic strictly requires digest challenge)      │
       └─────────────────────────────────────────────────────────────┘

By maintaining pre-compiled in-memory hash tables of trusted peers, Kamailio evaluates incoming SIP packets in zero clock cycles, bypassing digest authentication challenges for authorized carrier trunks while strictly enforcing password authentication for remote endpoints.

2. Business & Operational Significance

Carrier IP-Based Authentication: Enables seamless SIP trunking with Tier-1 wholesale telecom operators that rely on static IP peering rather than SIP registration or Digest (MD5/SHA) credentials.
Core PBX Cluster Interconnect: Authorizes internal Ring2All Telephony cluster nodes and RTPEngine media proxies to dispatch calls through the SBC perimeter without authentication overhead.
Elimination of Auth Overhead on High CPS: Eliminates the latency, packet round-trips, and CPU load of sending SIP 407 Proxy Authentication Required messages on high-volume inbound wholesale DID trunks.
Zero-Downtime Cache Reloading: Changes committed in the web interface automatically trigger Kamailio permissions.addressReload and permissions.trustedReload via RPC, updating routing permissions instantaneously without restarting SIP daemons.

3. 🎯 User Roles & Key Capabilities

Role	Primary Use Case	Key Capabilities
SBC Telephony Engineer	Carrier Interconnect Provisioning	Register trusted carrier IP addresses, allocate address groups, specify port and transport protocols, and assign routing tags.
Core PBX Administrator	Cluster Node Authorization	Add newly provisioned Telephony nodes and media relays to the Trusted IPs table to ensure unimpeded internal signaling.
NOC Systems Operator	Peering Verification	Inspect active ACL groups, verify subnet mask lengths, and trigger on-demand permissions reloads.
Security Auditor	Trust Relationship Review	Review all authorized IP addresses to ensure no stale, unauthorized, or overly permissive subnets bypass SIP authentication.
AI Peering & ACL Engineer / NOC Copilot	Automated Trunk Whitelisting & Cache Verification	Query trusted peer records, add or remove authorized gateway IPs, and trigger atomic in-memory permissions cache reloads via MCP.

4. Visual Interface & Layout

The ACL console provides an organized dual-section view featuring Trusted IPs at the top and Address Groups at the bottom, complete with instant creation dialogues and deletion protection for core loopback addresses.

4.1 ACL & Trusted Peers View

Displays authorized trusted peer IPs (e.g., Telephony nodes, RTPEngine media engines) and group-based subnet address definitions.

Access Control List (ACL) View

5. Field Reference: Trusted IPs & Address Groups

5.1 Trusted IPs (`kamailio.trusted`) Parameters

Field	Type	Constraint	Description
IP Address	String (IPv4/IPv6)	Required	The static IP address or CIDR subnet of the trusted telecom partner, PBX node, or carrier gateway.
Protocol	Dropdown	`any`, `udp`, `tcp`, `tls`	Transport protocol constraint. Selecting `any` authorizes signaling across all transport types.
Label	String	Optional	Descriptive identification tag (e.g., `Core PBX Telephony Node 01`, `RTPEngine Media Node 02`).
Actions	Action Icon	Trash Can	Removes the peer from the trusted table and triggers an automatic cache reload.

5.2 Address Groups (`kamailio.address`) Parameters

Field	Type	Constraint	Description
Group	Dropdown / Int	Numeric Group ID	The functional routing classification group (e.g., `1 — Trusted SBC`, `8 — PBX Auth`, `9 — CPS Limits`).
IP Address	String (IPv4/IPv6)	Required	IP address or network boundary associated with the group.
Mask	Number (0–32)	Default `32`	Subnet bitmask (e.g., `32` for a single host, `24` for a `/24` subnet block).
Port	Number (0–65535)	Default `0`	Port constraint. A value of `0` matches all source ports.
Label / Tag	String	Optional	Custom telemetry metadata or functional configuration string (e.g., `name:VitalPBX Casa-ip,gwgroup:1`).

6. Kamailio Permissions Module & Routing Logic

When incoming SIP requests enter Kamailio’s main request route, they are evaluated against the permissions cache:

# kamailio.cfg snippet
route[REQINIT] {
    # 1. Evaluate Trusted Peers (IP Auth)
    if (allow_trusted()) {
        xlog("L_INFO", "ACL: Authorized trusted peer $si:$sp [$proto]\n");
        setflag(FLAG_TRUSTED_PEER);
        route(DISPATCH_INTERNAL);
        exit;
    }

    # 2. Evaluate Address Groups
    if (check_source_address("1")) {
        xlog("L_INFO", "ACL: Source $si matched Group 1 (Trusted SBC)\n");
        setflag(FLAG_SBC_INTERCONNECT);
    }
}

7. Address Group Numbering & Telephony Roles

Ring2All SBC adopts a standardized group numbering taxonomy across the kamailio.address table:

Group ID	Functional Purpose	Operational Behavior
1	Trusted SBC Interconnect	High-priority inter-SBC cluster signaling and management links.
8	PBX Auth Bypass (FLT_PBX)	Certified Core PBX nodes authorized to originate calls without challenge.
9	CPS Rate Limit Rules	Carrier endpoints with custom Calls-Per-Second rate exception thresholds (`tag: cps:50`).
10	Emergency Dispatch	Public Safety Answering Point (PSAP) and E911 high-priority trunks.

8. Operational Hardening & Best Practices

Always Specify Subnet Masks Explicitly: Use /32 for individual server nodes rather than accepting broad defaults, preventing entire cloud hosting provider subnets from gaining trusted status.
Protect Loopback Addresses: Ring2All SBC automatically blocks deletion of 127.0.0.1, ::1, or localhost from permissions tables to prevent breaking internal RPC communication.
Avoid Tag Clashes in Group 9: When configuring CPS rate exceptions in Group 9, always format the tag as cps:<number> (e.g., cps:50) so the Pike rate limiting parser can extract the integer value accurately.
Verify Cache Reloads: Ensure that every insertion or modification is followed by a successful permissions.addressReload to prevent drift between PostgreSQL and Kamailio memory.

9. Verification & Diagnostics

9.1 Query Active Permissions in Database

Inspect all entries in both tables:

# Query Trusted Peers
sudo -u postgres psql -d kamailio -c "SELECT id, src_ip, proto, pattern, tag FROM trusted;"

# Query Address Groups
sudo -u postgres psql -d kamailio -c "SELECT id, grp, ip_addr, mask, port, tag FROM address ORDER BY grp;"

9.2 Trigger In-Memory Cache Reload via RPC

Manually refresh Kamailio’s in-memory permissions tables:

kamcmd permissions.addressReload
kamcmd permissions.trustedReload

9.3 Dump In-Memory Permissions Cache

Inspect the live routing tables in Kamailio memory:

kamcmd permissions.addressDump
kamcmd permissions.trustedDump

10. Model Context Protocol (MCP) AI Integration

The Ring2All SBC MCP Server exposes dedicated carrier peering and whitelist management tools under the acl category. Autonomous telephony agents and the Ring2All SBC NOC Copilot can audit trusted partner lists, provision new carrier IP endpoints, and trigger immediate Kamailio memory reloads.

10.1 Available MCP Tools

Tool Name	Operation Type	Risk Level	Description
`list_trusted_ips`	Read-only	`read_only`	Lists all trusted IP subnets, PBX core nodes, and carrier whitelist entries with transport protocols and labels.
`add_trusted_ip`	Mutating / Operational	`critical`	Adds a new trusted IP or subnet to the Kamailio ACL permissions table, bypassing digest challenges and flood filtering.
`remove_trusted_ip`	Mutating / Operational	`critical`	Removes a trusted IP address from Kamailio permissions (protected against deleting loopback or management addresses).
`reload_acl_permissions`	Operational / Sync	`operational`	Triggers Kamailio RPC commands (`permissions.addressReload`, `permissions.trustedReload`) to synchronize memory with PostgreSQL.

10.2 Tool Schemas & Parameter Definitions

`list_trusted_ips`

Description: List all trusted IP subnets and carrier whitelist entries configured in Kamailio ACL permissions.
Input Schema:

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Filter by IP address or tag/description"
    }
  }
}

`add_trusted_ip`

Description: Add a new trusted IP address or subnet to Kamailio ACL permissions.
Input Schema:

{
  "type": "object",
  "properties": {
    "ipAddress": {
      "type": "string",
      "description": "IPv4 address or subnet (e.g., '198.51.100.50')"
    },
    "proto": {
      "type": "string",
      "enum": ["any", "udp", "tcp", "tls"],
      "description": "Transport protocol (default: any)"
    },
    "tag": {
      "type": "string",
      "description": "Descriptive label (e.g., 'Telnyx Carrier Gateway 01')"
    }
  },
  "required": ["ipAddress"]
}

`remove_trusted_ip`

Description: Remove a trusted IP address from Kamailio ACL permissions.
Input Schema:

{
  "type": "object",
  "properties": {
    "ipAddress": {
      "type": "string",
      "description": "IP address to remove from trusted permissions"
    }
  },
  "required": ["ipAddress"]
}

`reload_acl_permissions`

Description: Reload Kamailio ACL permissions and address tables from database into RAM memory.
Input Schema:

{
  "type": "object",
  "properties": {}
}

10.3 Sample Tool Execution Payloads

Example 1: Listing Trusted Carrier Gateways

Request Payload:

{
  "tool": "list_trusted_ips",
  "parameters": {
    "search": "Telnyx"
  }
}

Response Payload:

{
  "success": true,
  "data": {
    "total": 2,
    "trustedIps": [
      {
        "id": 12,
        "srcIp": "192.76.120.10",
        "proto": "any",
        "tag": "Telnyx Primary Interconnect"
      },
      {
        "id": 13,
        "srcIp": "192.76.120.11",
        "proto": "any",
        "tag": "Telnyx Secondary Interconnect"
      }
    ]
  }
}

Example 2: Authorizing a New PBX Media Relay Node