Routing Guide¶

MSP and SIP Thor platforms are based on a SIP Proxy/Registrar/Presence Agent design. Each SIP server node maintains transaction and dialog state for each session and is able to terminate each of them based on various criteria. The platform handles and controls the RTP and MSRP media planes and is able to take decisions related to authorization, authentication, accounting, NAT traversal and session termination based on the media flow behavior. The design eliminates the need of separate session border controller elements which just add costs, hurt scalability and add no end-user features.

The platform has rich telephony functions equivalent with traditional Class 4 switches (routing inter-carrier calls) and Class 5 switches (routing last-mile calls to end-users).

The platform can be equally used to perform SIP services that include and are not limited to Residential VoIP, Prepaid Cards, Video Calling, Presence and IM, Trunking, Least Cost Routing and ENUM Peering.

Logical Architecture¶

SIP Entities¶

This document describes routing logic between several SIP entities defined as follows:

1. SIP Proxy: the platform core that performs the logic described in this document
2. End-Point: a SIP end-user device that is configured with the credentials of a SIP account for which the platform is responsable
3. PBX: a SIP end-point or intermediary that is configured under a foreign SIP domain not handled by the platform
4. PSTN gateway: a SIP end-point or intermediary that is handling the translation between IP (using SIP protocol) and PSTN networks

Supported Signaling¶

The platform supports SIP protocol over UDP/TCP/TLS transports. Additional, a gateway to and from XMPP remote domains can be configured.

Supported Media¶

The platform supports sessions containing the following media types:

• Audio (RTP and sRTP)
• Video (RTP and sRTP)
• FAX (RTP and T.38)
• Instant messaging (MSRP and its relay extension)
• File transfer (MSRP and its relay extension)
• Page mode messaging (SIP MESSAGE method)
• Presence (PIDF XML)

The platform is codec agnostic, the negotiation of the codecs depends entirely on the end-points. The MediaProxy component that relays the RTP media between the end-points, for NAT traversal and accounting purposes, relays all packets at IP layer 3 (UDP protocol that encapsulates the RTP/RTCP streams). The actual payload with the particular codecs used inside the RTP streams is transparently passed between end-points without interference from MediaProxy.

Other payloads are supported as long as they are embedded into a supported stream, for example any payload that is embedded within the RTP streams (zRTP, DTMF tones) or MSRP streams (file transfer, multy-party chat service, desktop sharing).

Primitives¶

The routing of SIP sessions is governed by two main protocols:

1. Domain based SIP routing based on RFC3261 and RFC3263
2. ENUM lookups based on RFC3761

The routing logic of the platform can be configured by changing its database tables and configuration files. The primitives used for routing are:

Registrar database	Used to translate a SIP address into a SIP contact address
ENUM	Used to translate an E.164 telephone number into a SIP address
SIP alias	Used for adding aliases to existing SIP accounts
Emergency numbers	Translation between 911 and 112 into closest emergency access points
Call diversion	Translate a SIP address into another based on signaling conditions or end-user preferences
DNS lookups	Translate a SIP domain/hostname into an protocol:IP:port combination
LCR	Used for selection of outgoing PSTN gateway

Server Location¶

To locate the SIP Proxy/Registrar for a domain, SIP endpoints must perform DNS lookups based on RFC3263 that return the IP:port combination for which the server is configured.

Configuration Files¶

Index of SIP Proxy configuration files located in/etc/opensips/:

config/settings.m4	Contains the settings that can customize the routing logic
config/opensips.m4	Contains the proxy routing logic (should not be modified)
config/siteconfig/handle-incoming-pstn.m4	Used to customize routing logic for incoming PSTN calls
config/siteconfig/handle-local-extensions.m4	Used to define installation specific custom local extensions
config/siteconfig/handle-outgoing-peers.m4	Used to customize routing for outgoing calls to non-local domains
config/siteconfig/postprocess-request.m4	Used to customize outgoing requests before they leave the proxy
config/siteconfig/preprocess-pstn.m4	Used to customize outgoing PSTN requests before applying LCR routing
config/siteconfig/preprocess-request.m4	Used to apply custom pre-processing to a request before anything else
config/siteconfig/preprocess-uri.m4	Used to apply custom pre-processing to the request URI before converting to E164

The settings.m4 file is used to customize the existing routing logic defined in opensips.m4 using the predefined routing options.
The files under the siteconfig/ directory can contain installation specific routing logic, which will be included by opensips.m4 and will allow for the routing logic to be adapted to the specific requirements of a given installation. The opensips.m4 file will always be overwritten on upgrades, so it should never be modified, while the files under the siteconfig/ directory will never be overwritten and can be modified without restrictions.

NAT Traversal¶

NAT traversal methods encountered in the field and their properties:

• SIP server based (Relay) - reliable server side technology that works with all SIP clients, this method is used by the platform
• SIP client based (ICE) - client and server technology where client may negotiate media paths, is supported by the platform
• Intermediates based:
  • NAT routers with SIP Application Level Gateway (SIP ALG) - located in customer premises network and the most unreliable technique
  • Sessions Border Controllers (SBC) - located in service provider network - reliable with high cost and high complexity

The most reliable way to solve NAT issues with SIP is server based, by relaying packets using servers visible by both end-points. A new methodology under development is ICE, which relies partially on the SIP clients. NAT traversal applied in intermediates only introduce problems and SBCs add costs without adding value to the SIP service.

Below is a display of all possible NAT traversal techinques used for SIP and related media.

The platform handles the NAT traversal for all its end-points by relaying all traffic, signaling and media through its servers that have public IP address and are visible for both end-points involved in a call flow.

Optional, ICE can be deployed when supported by the end-points. The media relay acts like a TURN candidate and the operator may choose on a per call basis when and how this relay is to be used. When using ICE, SIP sessions that do not have a BYE cannot be accounted for.

NAT traversal is not the same thing as Firewall traversal. A firewall has an administrative policy, which must be set to support SIP and associated media traffic.

Platform Ports¶

See the Firewall Setup section for a list of ports used by the platform software.

Make sure that NAT traversal functions related to SIP known as SIP ALG functionality in the NAT routers are disabled.

AAA¶

Authentication, Authorization and Accounting are performed depending on particular call flows as follows:

Authentication¶

The trust relationship between SIP subscribers and SIP Proxy is based on DIGEST algorithm, both have a database with shared credentials.

Sessions¶

Authentication for INVITE requests based on two methods:

1. SIP credentials, when the From header contains a domain served by the platform. The From header presented by the device must match the credentials used for authentication.
2. Trusted peer identified by IP address, used when the From header contains a remote domain and the request URI is not a local SIP address.

By default, incoming SIP sessions from remote domains to local SIP accounts served by the platform are not authenticated and always authorized.

For Instant Messaging and File transfers, MSRP relay reservations are authenticated using the same credentials for each SIP account.

Register¶

Authentication for REGISTER methods is based on SIP credentials, this method can be used only by local SIP accounts and will not be relayed outside the platform. The From header presented by the SIP device must match the credentials used for authentication.

Presence¶

The platform provides a Presence Agent that handles PUBLISH, SUBSCRIBE and NOTIFY methods based on SIP SIMPLE standards. The following event packages are supported:

• presence
• presence.winfo
• xcap-diff

Authentication for PUBLISH is based on SIP credentials, this methods can be used only by local SIP accounts and will not be relayed outside the platform. The From header presented by the SIP device must match the credentials used for authentication. Authentication for SUBSCRIBE requests are based on SIP credentials, when the From header contains a domain served by the SIP Proxy.

SUBSCRIBE requests from remote domains are allowed without authentication when the request URI is a local SIP address served by the platform.

SUBSCRIBE for the events message-summary and presence.winfo are allowed only for local users.

XCAP requests are authenticated using the same credentials for each SIP account.

The following XCAP documents are supported:

http://www.openxcap.org/projects/openxcap/wiki/Features

Authorization¶

Sessions¶

Authorization for outgoing SIP sessions can be performed for local SIP accounts based on:

1. Access to PSTN
2. Administrative blocking
3. Monthly quota usage
4. Prepaid balance
5. Concurrent number of calls
6. Call barring (user driven)
7. Custom SIP Proxy logic

Authorization for incoming SIP sessions can be performed for local SIP accounts based on:

1. Source IP address
2. Administrative blocking
3. Accept based on caller
4. Accept based on time of day
5. Reject based on caller id
6. Custom SIP Proxy logic

Automatic session cut-off

SIP sessions can be terminated forcefully by the platform based on the following conditions:

1. Prepaid balance exceeded (in real time)
2. Monthly quota exceeded (on the next call)
3. Maximum call duration exceeded
4. RTP media timeout
5. Signaling path lost

Presence¶

Authorization for SUBSCRIBE for the presence event can be performed for local SIP accounts based on:

1. XCAP pres-rules document
2. Trusted peers

Accounting¶

All SIP and RTP sessions are accounted by using RADIUS requests. See accounting guide for more information.

End-Point to End-Point¶

Authentication	SIP account A
Authorization	SIP account A
Billing party	SIP account A
Accounting	Postpaid, Prepaid
Media types	RTP (audio and video), Presence, MSRP (Instant messaging and file transfers)
Address resolution	SIP address, SIP alias, Quickdial, ENUM
From header	Must contain a local SIP domain
Fraud Control	PIKE, ACL, Call control

Quick Dial¶

Quick dial is a per SIP account feature that allows to dial short numbers to match other SIP accounts in the same number range. The SIP Proxy will try to autocomplete the number to form a full address. To use this feature:

1. The username part of the SIP account must be numeric (example 31208005169@ag-projects.com)
2. The quickdial attribute of the SIP account must be set to a substring matching the beginning of the username (e.g. 312080051).
3. When user dials 60 the example above, the SIP Proxy will concatenate the quickdial set to 312080051 with the dialed number 60 and try 31208005160@ag-projects.com as destination.

End-Point to PBX¶

Authentication	SIP account A
Authorization	SIP account A
Caller Id	Asserted by the platform
Billing party	SIP account A
Accounting	Postpaid, Prepaid
Media types	RTP (audio)
Address resolution	ENUM
From header	Must contain a local SIP domain
Fraud Control	PIKE, ACL, Call control

PBX to PBX¶

The PBX has its own accounts and connected devices. Requests originating from a PBX cannot be therefore authorized based on username/password combinations as they are not provisioned in the platform subscriber database, they are locally managed by the PBX owner. The traffic generated by the PBX can be only identified by its source IP address(es). To allow traffic from a PBX, the platform uses the concept of trusted peers. A trusted peer is an IP address that is allowed to route SIP calls through the platform without digest authorization. Beware that, no checks are done by the proxy related to the incoming caller identity, as long as the SIP sessions originate from the trusted IP address. Once you trust an IP address, you trust all traffic generated by it.

Authentication	None
Authorization	Trusted peer A
Caller Id	Supplied by trusted peer A
Billing party	Trusted peer A
Accounting	Postpaid
Media types	RTP (audio)
Address resolution	ENUM
From header	Must contain a non-local SIP domain
Fraud Control	None

• The domain name used by the PBX in the From field must be different than any domain served by the SIP Proxy otherwise the Proxy will challenge the session for credentials as it does for any other locally registered SIP account.
• To route incoming traffic for a number block assigned to the PBX, create ENUM entries that point to the hostname (or IP address) of the PBX.

End-Point to PSTN¶

For interconnection with PSTN, a SIP trunking service must be setup between the SIP Proxy and the PSTN gateway provider. The authorization of SIP requests is based on transitive trust. The SIP Proxy has a trust relationship with each SIP subscriber and the PSTN gateway has a trust relation with the SIP Proxy. The trust relation between the SIP Proxy and the PSTN gateway is based on the IP addresses. The PSTN gateway cannot use DIGEST authentication in the relation with the SIP Proxy because it does not have access to the SIP accounts database of the SIP Proxy.

PSTN Gateway Requirements¶

Must have:

• SIP signaling based on RFC 3261
• DNS lookups based on RFC 3263
• Support for SIP extensions for caller id and privacy (P headers)
• RTP active mode (send RTP data as soon as call setup is completed)
• Use public routable IP addresses for both signaling and media

Recommended:

• ENUM lookups based on RFC 3761

Routing to PSTN destinations is realized by provisioning the PSTN carriers, gateways and routes (also known as Least Cost Routing engine or LCR). The structure of the PSTN provisioning is as follows:

Route ->  Carriers -> Gateways -> Rules

For each PSTN prefix (called a PSTN route) a set of carriers can be assigned with an optional priority. Each carrier can have one or more gateways and each gateway can have optional rules for converting the number. For more information see the provisioning guide.

Once the SIP request is authenticated, the SIP Proxy authorizes the request based on the rights associated with the subscriber account and decides whether a SIP session to the PSTN gateway is allowed or not. If the session is allowed, the SIP Proxy asserts an identity associated to the SIP account, which can be the telephone number presented as caller ID to the destination, locates a PSTN gateway for the dialed number (by using least cost routing or other configured logic) and forwards the request to the PSTN gateways inserting itself in the path of subsequent messages.

Authentication	SIP account A
Authorization	SIP account A
Caller Id	Asserted by the platform
Billing party	SIP account A
Accounting	Postpaid, Prepaid
Media types	RTP (audio)
Address resolution	ENUM, LCR
From header	Must contain a local SIP domain
Fraud Control	PIKE, ACL, Call limit

Caller id indication¶

The platform generates a Caller ID indication by appending Remote-Party-Id or P-Asserted identity headers, depending on its configuration. The content of the headers is generated with the SipAccount->rpid attribute associated with the SIP account.

PSTN to End-Point¶

The platform is designed to accept traffic from outside SIP end-points (this includes remote PSTN gateways) to any local user. This means that a PSTN gateway that initiates a session to a correct SIP address user@domain belonging to the platform will be accepted and routed to the SIP devices belonging to the user with no extra configurations. When a SIP session originates from the PSTN, only the dialed telephone (a.k.a. E.164) number is known. For routing sessions from the PSTN to the SIP Proxy of the platform the gateway must translate the telephone number into a valid SIP address.

ENUM Routing¶

The ideal way to achieve this number translation with minimum configuration is for the PSTN gateway to perform an ENUM lookup (RFC 3761). All popular open source software gateways like Asterisk and OpenSIPS are able to perform ENUM lookups and commercial gateways have started adding this support into their commercial products.

The ENUM look-up queries the DNS server provisioned with E.164 numbers by the operator, which is always kept up to date by the operator. The result of a successful ENUM lookup is a SIP address. Once the ENUM lookup is complete, the PSTN gateway can initiate the SIP session to the SIP address returned by the ENUM lookups.

The only setting required in the PSTN gateway for this setup is the top level domain used to perform ENUM lookups. The ENUM top level domain must be the same used by the SIP Proxy lookup and NGNPro provisioning.

Manual Routing¶

For PSTN gateways that are not able to perform ENUM lookups and from which we need to accept incoming sessions, the SIP Proxy can be configured to accept any traffic, manipulate the number format based on custom rules and help performing the ENUM lookup in the behalf of the gateway.

The PSTN gateway must be configured for the E.164 number ranges to be routed to the MSP platform and the hostname of the SIP Proxy machine (e.g. sip.example.com). Do not use static IP addresses in the PSTN configuration, use the DNS name configured by the operator so that when the IP addresses of the SIP Proxy change or when multiple SIP Proxies are used by default (like in SIP Thor) the gateway does not need to be re-configured.

You must setup the following SIP Proxy configuration file:

sipproxy:/etc/opensips/config/siteconfig/handle-incoming-pstn.m4

Example:

if (FROM_TRUSTED_PARTY) {
    DINFO("Call from trusted party");

    $var(need_transit) = 0;
    if (uri =~ "^sip:PSTN_REGEXP@.*") {
        $rd = "SERVER_DOMAIN";
        strip(2);
        prefix("+");
        set_billing_party();
        DINFO("Performing ENUM lookup");
        route(__ENUM_LOOKUP);

        if ($retcode==-1) {
            DINFO("ENUM number not found. PSTN transit");
            revert_uri();
            $var(need_transit) = 1;
        }
    } else if (uri =~ "^sip:LOCAL_PSTN_REGEXP@.*") {
        $rd = "SERVER_DOMAIN";
        strip(1);
        prefix("+COUNTRY_CODE");
        set_billing_party();
        DINFO("Performing ENUM lookup");
        route(__ENUM_LOOKUP);

        if ($retcode==-1) {
            DINFO("ENUM number not found. PSTN transit");
            revert_uri();
            $var(need_transit) = 1;
        }
    } else if (uri =~ "^sip:COUNTRY_CODE[1-9][0-9]{4,}@.*") {
        $rd = "SERVER_DOMAIN";
        prefix("+");
        set_billing_party();
        DINFO("Performing ENUM lookup");
        route(__ENUM_LOOKUP);

        if ($retcode==-1) {
            DINFO("ENUM number not found. PSTN transit");
            revert_uri();
            $var(need_transit) = 1;
        }
    } else if (uri =~ "^sip:\+[0-9]{7,}@.*") {
        $rd = "SERVER_DOMAIN";
        set_billing_party();
        DINFO("Performing ENUM lookup");
        route(__ENUM_LOOKUP);
        if ($retcode==-1) {
            DINFO("ENUM number not found. PSTN transit");
            strip(1);
            prefix("00");
            $var(need_transit) = 1;
        }
    }
    if ($var(need_transit) == 1) {
        DINFO("Transit call from trusted peer $si");
        route(__PSTN_TRANSIT);
        exit;
    }

    # Check if it's a local user
    if (!is_uri_host_local()) {
        set_billing_party();
        setflag(ACCOUNTING_FLAG);
        $avp(can_uri) = $ru;
        t_on_reply("__INVITE_REPLY");
        if (!isflagset(NO_MEDIAPROXY_FLAG)) {
            DINFO("Engaging mediaproxy for SIP transit call");
            engage_media_proxy();
        }
        $avp(invite_timeout) = OUTGOING_TIMEOUT;
        DINFO("Set timeout to OUTGOING_TIMEOUT");
        route(__SEND_OUT);
        exit;
    }
}

Authentication	None
Authorization	Custom SIP Proxy logic
Billing party	Trusted peer
Accounting	Postpaid
Media types	RTP (audio)
From header	Must contain a non-local SIP domain
Address resolution	ENUM, Custom SIP Proxy logic

PBX to PSTN¶

The IP address(es) of the PBX must be added in the trusted table using the SOAP/XML provisioning API. To allow trusted parties to transit your SIP Proxy edit sip:/etc/opensips/config/siteconfig/handle-incoming-pstn.m4 and add to it:

Authentication	Based on source IP address
Authorization	Trusted peer A
Caller Id	Supplied by trusted peer A
Billing party	Trusted peer A
Accounting	Postpaid only
Media types	RTP (audio)
Address resolution	ENUM, LCR, Custom SIP Proxy logic
From header	Must contain a non-local SIP domain
Request URI	Must NOT contain a local SIP domain
Fraud control	Source IP only

• The domain name used by the PBX in the From field must be different than any domain served by the SIP Proxy otherwise the Proxy will challenge the session for credentials as it does for any other locally registered SIP account.
• The domain name used by the PBX in the Request URI must be different than any domain served by the SIP Proxy otherwise the Proxy will try to lookup a local user.
• To rate the traffic, add an entry in CDRTool customers table where Trusted peer is set to the same value

Rating¶

To rate the traffic generated by trusted peers you must add a rating plan in CDRTool rating engine based on the source IP address (the gateway field in rating customers table). Beware that no quota can be imposed on the traffic of a trusted peer.

Caller Id Indication¶

Traffic generated by the trusted peers and any header thereof containing caller id indication is also trusted. When allowing traffic to transit from PBXs to PSTN gateways connected to the, make sure that the way caller ID indication is provided by the trusted party is compatible with what the PSTN gateway expects.

PSTN to PBX¶

Authentication	None
Authorization	Trusted peer PSTN gateway
Caller Id	Supplied by PSTN gateway
Billing party	Trusted peer PSTN gateway
Accounting	Postpaid
Media types	RTP (audio)
From header	Must contain a non-local SIP domain
Address resolution	ENUM, Custom SIP Proxy logic

Call Diversion¶

A user may chose to divert his/her calls based on various conditions (like unconditional, busy or not online) to another SIP address including PSTN destinations. Diverted calls are always charged to the user who enabled them. For every call diversion, a new Diversion header is appended to the original SIP request.

Authentication	SIP account A
Authorization	SIP account A
Billing party	SIP account B
Accounting	Postpaid, Prepaid
Address resolution	SIP address, SIP alias, Quickdial, ENUM, LCR
Fraud control	Forwarding destinations can be limited

Presence¶

Multiple watchers are subscribed to a publisher. The Publisher authorizes the watchers to subscriber to presence notifications by updating pres-rules XCAP document. The Publisher must subscribe to event presence.winfo to receive notifications from the Presence Agent about the watcher list.

Authorization	XCAP pres-rules
Address resolution	SIP address, SIP alias, Quickdial, ENUM
Accounting	None

Presence using RLS¶

A subscriber uploads to the XCAP server a resource list. Then it subscribes to the list by sending a SUBSCRIBE for event presence with extra header Supported: eventlist, the Presence agent then subscribes to all recipients from the resource lists and returns consolidated NOTIFY with the state of all lists.

Authorization	XCAP org.openmobilealliance.pres-rules
Contacts Storage	XCAP rls-services and resource-lists
Signaling	RLS SUBSCRIBE RFC4662 and RLMI NOTIFY RFC4662
Address resolution	SIP address, SIP alias, Quickdial, ENUM
Accounting	None

IM using MSRP Relay¶

Instant Messaging based on MSRP protocol is similar to a regular SIP audio session. Instead of RTP media , MSRP is used for establishing a media channel. Instead of MediaProxy, A MSRP relay is used to traverse the NAT. The called party reserves a session in the MSRP relay and offeres it in the response to the SIP INVITE. The calling party the initiates a TCP/TLS connection to the relay reserved address and the called party does the same. By using the relay both parties can establish a TCP flow from behind their NAT routers.

IM using MSRP ACM¶

MSRP ACM is an alternative method for traversing NAT that is standardized by 3GPP that is interoperable with the IETF MSRP relay specification. The SBC mangles the SDP and stays in the SIP signaling and MSRP media path and forces the end-points to be both active (that is starting the outbound MSRP connection) when behind NAT.

IM using MSRP ACM and Relay¶

MSRP ACM and Relay methodologies can interoperate.

File Transfer¶

File transfer based on MSRP protocol is similar to a regular SIP audio session. Instead of RTP media , MSRP is used for establishing a media channel. A MSRP relay is used to traverse the NAT.

Emergency Calls¶

Emergency calls refer to dialing short numbers usually associated with emergency services like police or fire-brigade (e.g. 112 or 911). When a session is setup to a short number designated as an emergency number (in the SIP Proxy configuration), a database lookup is performed by the proxy in the emergency_mapping table. Based on the region attribute provisioned with the SIP account, the final destination corresponding with the emergency number is looked up. Only local users can dial an emergency number.

See "Provisioning the emergency numbers" section for more information.

XMMP gateway¶

The platform can be setup to federate with remote XMPP domains using a gateway function. The functionality is described at:

http://sylkserver.ag-projects.com/projects/sylkserver/wiki/DesignXMPP

PBX Media Functions¶

Functions involving playing media in the middle of a call setup are not possible by the design of a SIP Proxy. Features like:

• IVR
• Auto-attendant
• Call queues and ACD
• Listen-in and barge-in
• Call parking
• Music on hold (MoH)

are not performed by a SIP Proxy. Such functions can be implemented only by dedicated IP-PBX added to the platform. The platform is used to route calls between such PBXs, from the MSP perspective these PBX are seen as SIP trunks connected to the platform.