Almuqeet Sigtran Stack

Introduction

SigtranStack is a carrier-grade C#/.NET 9 implementation of the complete SIGTRAN and SS7 protocol stack. It provides native Linux SCTP transport, all five SIGTRAN adaptation layers (M3UA, M2UA, M2PA, SUA, IUA), and the full SS7 upper layer suite (SCCP, TCAP, ISUP, MAP, CAP).

Architecture

Stack Initialization Order

// 1. Transport
var transport = new SctpTransport(sctpConfig);

// 2. Adaptation layer (M3UA shown)
var m3ua = new M3uaLayer(m3uaConfig, transport, logger);

// 3. SCCP
var sccp = new SccpLayer(m3ua, loggerFactory);

// 4. TCAP
var tcap = new TcapLayer(sccp, SubsystemNumber.Msc, loggerFactory);

// 5. Application layer (MAP shown)
var map = new MapLayer(tcap, localAddress, loggerFactory);

Quick Start

Connect to a remote STP/SGP and send an SRI-SM query:

using SigtranStack.Configuration;
using SigtranStack.Transport;
using SigtranStack.M3UA;
using SigtranStack.SCCP;
using SigtranStack.TCAP;
using SigtranStack.MAP;

// Transport
var transport = new SctpTransport(new SctpConfig {
    RemoteAddresses = ["10.0.0.1"], RemotePort = 2905,
    LocalAddresses = ["10.0.0.2"], LocalPort = 2905,
    PayloadProtocolId = PayloadProtocolIdentifier.M3UA,
});

// M3UA
var m3ua = new M3uaLayer(new M3uaConfig {
    OperationMode = OperationMode.Asp,
    AutoActivate = true,
    DefaultRoutingContext = 100,
}, transport);

// SCCP + TCAP
var sccp = new SccpLayer(m3ua);
var tcap = new TcapLayer(sccp, SubsystemNumber.Msc);

// MAP
var localAddr = SccpAddress.FromGlobalTitle("441234000001", SubsystemNumber.Msc);
var map = new MapLayer(tcap, localAddr);

// Wire events
map.ResultReceived += (_, e) => {
    var (imsi, msc, _) = SmsUtils.DecodeSriSmResult(e.Parameter);
    Console.WriteLine($"IMSI={imsi}, MSC={msc}");
};

// Start stack and send SRI-SM
await m3ua.StartAsync();
var hlr = SccpAddress.FromGlobalTitle("441234000002", SubsystemNumber.Hlr);
await map.SendRoutingInfoForSmAsync(hlr, "919990206824", "441234000001");

SCTP Transport class

Native Linux kernel SCTP transport using P/Invoke. Supports one-to-one style sockets with multi-homing via sctp_bindx.

Constructor

new SctpTransport(SctpConfig config, ILogger? logger = null, int maxConcurrentSends = 64)

Properties

Methods

Events

SCTP Listener class

Server-side SCTP listener for SGP operation. Accepts incoming associations from ASPs.

var listener = new SctpListener(config);
listener.ConnectionAccepted += (_, transport) => { /* handle new ASP */ };
listener.Start();

Multi-Association Transport class

Manages a pool of SCTP associations with configurable load distribution. Supports Round-Robin, Active-Standby, Least-Loaded, and Weighted distribution.

Constructor

new MultiAssociationTransport(ILoggerFactory? loggerFactory,
    LoadDistribution distribution = LoadDistribution.RoundRobin)

Load Distribution Modes

Key Methods

SCTP Configuration class

SctpConfig holds all SCTP socket parameters per RFC 4960.

M3UA Layer class

MTP3 User Adaptation Layer per RFC 4666. Handles ASP state machine (Down → Inactive → Active), heartbeats, protocol data transfer, and signalling network management (SSNM).

Constructor

new M3uaLayer(M3uaConfig config, ISctpTransport transport, ILogger? logger = null)

Configuration (M3uaConfig)

Methods

Events

M2UA Layer class

MTP2 User Adaptation per RFC 3331. Provides MTP2 backhauling over IP for signalling links.

new M2uaLayer(M2uaConfig config, ISctpTransport transport, ILogger? logger)

Events: LinkEstablished, LinkReleased, LinkStateChanged

M2PA Layer class

MTP2 Peer-to-Peer Adaptation per RFC 4165. Peer-to-peer MTP2 replacement with proving timers (T1, T2, T3, T4/T4E) per Q.703.

new M2paLayer(M2paConfig config, ISctpTransport transport, ILogger? logger)

SUA Layer class

SCCP User Adaptation per RFC 3868. Provides both connectionless and connection-oriented SCCP services over SCTP.

new SuaLayer(SuaConfig config, ISctpTransport transport, ILogger? logger)

IUA Layer class

ISDN User Adaptation per RFC 4233. Transports Q.921 LAPD frames over SCTP. Supports BRI/PRI interfaces and multiple ISDN variants (EuroISDN, ITU-T, DMS-100, 5ESS, NTT INS-Net).

new IuaLayer(IuaConfig config, ISctpTransport transport, ILogger? logger)

ASP Manager class

Manages Application Servers and their ASPs with traffic distribution per RFC 4666.

Traffic Modes

Key Methods

SCCP Layer class

Signalling Connection Control Part per ITU-T Q.711-Q.714. Provides connectionless (UDT/XUDT) and connection-oriented (CR/CC/DT1) services with Global Title Translation (GTT).

Constructor

new SccpLayer(M3uaLayer? m3ua, ILoggerFactory? loggerFactory = null)

Properties

Methods

GTT (Global Title Translation)

sccp.Gtt.AddRule(new GttRule {
    Name = "HLR",
    DigitPattern = "44123",      // Match GT prefix
    TranslationType = 0,
    DestinationPointCode = 2,
    DestinationSsn = SubsystemNumber.Hlr,
    RouteOnDpcSsn = true,
    Priority = 100,
});

SCCP Addressing class

SccpAddress represents an SCCP Called/Calling Party Address with optional Point Code, SSN, and Global Title.

Factory Methods

// Route on DPC + SSN
var addr = SccpAddress.FromDpcSsn(pointCode: 2, ssn: SubsystemNumber.Hlr);

// Route on Global Title
var addr = SccpAddress.FromGlobalTitle(
    digits: "441234567890",
    ssn: SubsystemNumber.Msc,
    nai: NatureOfAddress.InternationalNumber,
    np: NumberingPlan.IsdnTelephony);

Subsystem Numbers

TCAP Layer class

Transaction Capabilities Application Part per ITU-T Q.771-Q.772. Manages structured dialogues (Begin/Continue/End) with invoke-level timeout tracking.

Constructor

new TcapLayer(SccpLayer? sccp, byte ssn, ILoggerFactory? loggerFactory = null)

Properties

Methods

Events

TCAP Component Types

// Invoke
var invoke = new TcapInvoke {
    InvokeId = 1, OperationCode = 45, // SRI-SM
    Parameter = encodedArg, TimeoutMs = 10000,
};

// Return Result
var result = new TcapReturnResult {
    InvokeId = 1, OperationCode = 45,
    Parameter = encodedResult, IsLast = true,
};

// Return Error
var error = new TcapReturnError {
    InvokeId = 1, ErrorCode = 34,
};

ASN.1 BER Utilities static

Asn1Ber provides BER encoding/decoding primitives used throughout the stack.

MAP Layer class

GSM Mobile Application Part per 3GPP TS 29.002. Provides dialogue management, operation encoding, and high-level service methods for all MAP operations.

Constructor

new MapLayer(TcapLayer tcap, SccpAddress localAddress, ILoggerFactory? loggerFactory = null)

Properties

Events

MAP Service Methods

High-level async methods that build parameters, open dialogues, and send MAP operations. All return the dialogue ID (uint) for correlation.

Responding to Incoming Operations

map.OperationReceived += async (_, e) => {
    if (e.OperationCode == MapOperationCode.SendRoutingInfoForSM) {
        var (msisdn, _, _) = SmsUtils.DecodeSriSmArg(e.Parameter);
        var result = SmsUtils.BuildSriSmResult(imsi, mscAddress);
        await map.SendResultAndCloseAsync(
            e.DialogueId, e.InvokeId,
            MapOperationCode.SendRoutingInfoForSM, result);
    }
};

SMS Utilities static

SmsUtils provides encoding and decoding for SMS TPDUs, MAP SMS parameters, and GSM 7-bit packing.

SRI-SM (Send Routing Info for SM)

SMS TPDU Building

SMS TPDU Decoding

MT/MO ForwardSM

Other

SMS Home Router class

Intercepts SRI-SM requests, queries the HLR for real subscriber data, stores IMSI-to-MSC mappings, and relays MT-Forward-SM to the real MSC. Provides carrier-grade SMS home routing with congestion control and retry logic.

Architecture

Foreign SMSC ──SRI-SM──> [Home Router] ──SRI-SM──> HLR
                              │
                         stores IMSI→MSC mapping
                         returns local MSC address
                              │
Foreign SMSC ──MT-FSM──> [Home Router] ──MT-FSM──> Real MSC

Configuration

var config = new SmsHomeRouterConfig {
    LocalMscAddress = "441234000001",
    HlrAddress = SccpAddress.FromGlobalTitle("441234000002", 6),
    MappingTtl = TimeSpan.FromMinutes(5),
    MaxStoredMappings = 500_000,
    HlrQueryTimeoutMs = 10_000,
    MtForwardTimeoutMs = 15_000,
    MaxRetries = 2,
    RetryDelayMs = 500,
    HomeImsiPrefixes = new HashSet<string> { "23415", "23410" },
    RemoveMappingOnDelivery = false,
    Enabled = true,
};

Usage

var hr = new SmsHomeRouter(mapLayer, config, congestionController, loggerFactory);
hr.SriSmInterceptedEvent += (_, e) =>
    Console.WriteLine($"Intercepted: MSISDN={e.Msisdn} IMSI={e.Imsi}");
hr.Start();

// Query stats
var stats = hr.GetStats();
Console.WriteLine($"Intercepted: {stats.SriSmIntercepted}, Active: {stats.MappingsActive}");

// Lookup a mapping
var entry = hr.LookupMapping("234150123456789");

// Shutdown
hr.Stop();
hr.Dispose();

Public API

Events

ISUP Layer class

ISDN User Part per ITU-T Q.761-Q.764. Manages circuit-switched call setup/release with timer supervision.

Constructor

new IsupLayer(M3uaLayer? m3ua, ILoggerFactory? loggerFactory = null)

Call Control Methods

Events

ISUP Number Encoding

var called = new IsupNumber {
    Digits = "441234567890",
    NatureOfAddress = 0x04,  // International
    NumberingPlan = 0x01,    // ISDN/E.164
};
byte[] encoded = called.EncodeCalledParty();

CAP / CAMEL Layer class

CAMEL Application Part per 3GPP TS 29.078. Supports CAMEL Phase 1-4 for call control, SMS control, and GPRS control from Service Control Functions (SCF).

Constructor

new CapLayer(TcapLayer tcap, SccpAddress localAddress,
    CapLayerConfig? config = null, ILoggerFactory? loggerFactory = null)

Call Control Methods (gsmSCF → gsmSSF)

SMS Control Methods

BCSM Event Types

Application Contexts

Congestion Controller class

Adaptive sliding-window congestion controller with rate control. Adjusts window size and inter-send delay based on success/failure/timeout signals.

Constructor

new CongestionController(
    maxConcurrent: 50,
    minConcurrent: 5,
    initialDelayMs: 50,
    minDelayMs: 10,
    maxDelayMs: 2000)

Usage Pattern

if (await cc.AcquireSlot(ct)) {
    try {
        await SendOperation();
        cc.OnSuccess();
    } catch (TimeoutException) {
        cc.OnTimeout();
    } catch {
        cc.OnError();
    } finally {
        cc.ReleaseSlot();
    }
}

Signal Methods

Rate Limiter class

Token bucket rate limiter for inbound message protection.

TokenBucketRateLimiter

var limiter = new TokenBucketRateLimiter(maxTokens: 1000, refillPerSecond: 100.0);
if (limiter.TryConsume()) { /* process message */ }

PerPeerRateLimiter

var limiter = new PerPeerRateLimiter(maxTokensPerPeer: 100, refillPerSecond: 50.0);
if (limiter.TryConsume(peerId: originatingPointCode)) { /* allow */ }

Point Code class

SS7 Point Code supporting ITU (14-bit: 3-8-3) and ANSI (24-bit: 8-8-8) formats.

Factory Methods

var itu = PointCode.CreateItuInternational(zone: 3, area: 8, spId: 3);
var nat = PointCode.CreateItuNational(1234);
var ansi = PointCode.CreateAnsi(network: 10, cluster: 20, member: 30);
var generic = PointCode.FromValue(1234, PointCodeFormat.ITU_National);

SIGTRAN Message class

Common SIGTRAN message format (8-byte header + TLV parameters) per RFC 4666 Section 3.1. Used by all adaptation layers.

var msg = new SigtranMessage(MessageClass.Transfer, M3uaMessageType.DATA);
msg.AddParameter(new TlvParameter(ParameterTag.ProtocolData, protocolData));
byte[] wire = msg.Encode();

// Decode
var decoded = SigtranMessage.Decode(wire);
var pd = decoded.FindParameter(ParameterTag.ProtocolData);

Enumerations Reference

AspState

OperationMode

TrafficMode

ServiceIndicator

NetworkIndicator

PointCodeFormat

Constants Reference

Payload Protocol Identifiers

Default SCTP Ports

MAP Operation Codes

CAP Operation Codes

Q.850 Cause Values