OpenSS7: SS7 Protocol

NAME	SOCKET OPTIONS	SEE ALSO	RESTRICTIONS
SYNOPSIS	IOCTLS	NOTES	AUTHOR
DESCRIPTION	ERROR HANDLING	CAVEATS	HISTORY
ADDRESS FORMATS	ERRORS	DIAGNOSTICS	REFERENCES
SYSCTLS	EXAMPLES	BUGS

ss7 - Signalling System No. 7 Protocol

#include <sys/socket.h>
#include <net/ss7.h>
ss7_socket = socket(PF_SS7, socket_type, protocol);

This is an implementation of the MTP protocol defined in the ITU-T Q.700 series recommendations, the ANSI T1.11x standards and the ETSI 300 00x specifications. ss7 contains an SS7 Level 2 (Link Level) implementation conforming to ITU-T Rec. Q.703, ANSI T1.111 and ETSI 300 008 as well as an SS7 Level 3 (Network Level) implementation conforming to ITU-T Rec. Q.704, ANSI T1.111 and ETSI 300 008 and an SS7 SCCP (Signalling Connection Control Part) implementation conforming to ITU-T Rec. Q.711-714, ANSI T1.112 and ETSI 300 009.

The programmer's interface is BSD sockets compatible. For more information on sockets, see socket(7).

An SS7 socket is created by calling the socket(2) function as

ss7_socket = socket(PF_SS7, socket_type, protocol).

Valid protocols and socket types are as follows:

SS7_PROT_LINK

This protocol setting selects a socket using the SS7 Link Level protocol conforming to ITU-T Rec. Q.703, ANSI T1.111 and ETS 300 008. The following link(7) socket types are supported:

SS7_LINK_RAW or SOCK_RAW: The socket is a raw(7) link(7) socket.

SS7_PROT_NTWK

This protocol setting selects a socket using the SS7 Network Level protocol conforming to ITU-T Rec. Q.704, ANSI T1.111 and ETS 300 008. The following mtp(7) socket types are supported:

SS7_NTWK_NSEQ or SOCK_RDM: The socket is a non-sequenced mtp(7) socket.
SS7_NTWK_ISEQ or SOCK_SEQPACKET: The socket is a sequential mtp(7) socket.
SS7_NTWK_RAW or SOCK_RAW: The socket is a raw(7) mtp(7) socket.

SS7_PROT_SCCP

This protocol setting selects a socket using the SS7 SCCP (Signalling Connection Control Part) protocol conforming to ITU-T Rec. Q.711-14, ANSI T1.112 and ETS 300 009. The following sccp(7) socket types are supported:

SS7_SCCP_CC_0 or SOCK_DGRAM: The socket is a connection class 0 sccp(7) socket.
SS7_SCCP_CC_1 or SOCK_RDM: The socket is a connection class 1 sccp(7) socket.
SS7_SCCP_CC_2 or SOCK_SEQPACKET: The socket is a connection class 2 sccp(7) socket.
SS7_SCCP_CC_3 or SOCK_STREAM: The socket is a connection class 3 sccp(7) socket.

When a process wants to receive new incoming packets or connections, it should bind a socket to a local Message Transfer Part (MTP) or Signalling Connection Control Part (SCCP) using bind(2). Only one SS7 socket may be bound to any given MTP (address, user-part) pair. When SS7ADDR_ANY is specified in the bind call, the socket will be bound to all user parts (MTP) or subsystem numbers (SCCP). When listen(2) or connect(2) are called on an unbound socket, the socket is not automatically bound and an error will result.

An SCCP connection class 2 or 3 socket address that has been bound is unavailable for some time after closing, unless the SO_REUSEADDR flag has been set. Care should be taken when using this flag as it makes SCCP Connection Class 2 and 3 less reliable.

An MTP socket address is defined as a combination of a Service Indicator (SI), a Network Indicator (NI), an optional Message Priority (MP), a Destination Point Code (DPC), and a Signalling Link Selection (SLS).

struct sockaddr_ss7 {
    sa_family_t     ss7_family;     /* address family: AF_SS7 */
    unsigned char   ss7_user_part;  /* MTP user part */
    unsigned char   ss7_sls;        /* signalling link to use */
    struct ss7_addr ss7_addr;       /* point code */
};

/* SS7 Point Code */
struct ss7_addr {
    u_int32_t   s_addr;     /* address in network byte order */
};

ss7_family is always set to AF_SS7. This is required; in Linux 2.2 most networking functions return EINVAL when this is missing. ss7_user_part contains the MTP User Part. MTP User Parts below 3 are reserved for MTP Management. Only processes with effective user id 0 or the CAP_NET_BIND_SERVICE capability may bind(2) to these sockets. Note that the raw MTP protocol as such has no concept of an MTP User Part, they are only implemented by higher protocols like sccp(7) and isup(7).

ss7_addr is the SS7 Point Code (PC). The s_addr member of struct ss7_addr contains the SS7 Point Code (PC) in network byte order. ss7_addr must be accessed using the htonl(3) library function. SS7 addresses are divided into Network, Cluster and Member addresses. Network addresses specify all signalling end points (SEPs) on a network, a cluster all SEPs within a cluster, and a member, a single SEP. Although the Signalling Point Code is placed in a 32-bit unsigned integer, the actual Point Code may be smaller depending on the SS7 Protocol Variant which is being used. For additional information, see mtp(7).

Note that the point code and user part are always stored in network order. In particular, this means that you need to call htonl(3) on the SS7 Point Code.

There are no special addresses in SS7.

These sysctls can be accessed by the /proc/sys/net/ss7/* files or with the sysctl(2) interface.

No SS7 common sysctls are supported. For LINK specific sysctls see link(7); for MTP, see mtp(7); for SCCP, see sccp(7); for ISUP, see isup(7); for TCAP, see tcap(7).

SS7 supports some protocol specific socket options that can be set with setsockopt(2) and read with getsockopt(2). The socket option level for SS7 is SOL_SS7.

SS7_OPTIONS

SS7_RECVERR

Enable extended reliable error message passing. When enabled on an MTP or SCCP connection class 0 or 1 socket, all generated errors will be queued in a per-socket error queue. When the user receives an error from a socket operation, the errors can be received by calling recvmsg(2) with the MSG_ERRQUEUE flag set. The sock_extended_err structure describing the error will be passed in an ancilliary message with the type SS7_RECVERR and the level SOL_SS7. This is useful for reliable error handling on unconnected sockets. The received data portion of the error queue contains the error packet.

SS7 uses the sock_extended_error structure as follows: ee_origin is set to SO_EE_ORIGIN_SS7 for errors received from the remote MTP or SCCP protocol level and SO_EE_ORIGIN_LOCAL for locally generated errors. ee_type and ee_code are set as follows: XXX. ee_info contains the MTU for EMSGSIZE errors. ee_data is currently not used. When the error originated from the network, all SS7 options enabled on the socket are contained in the error packet are passed as control messages. The payload of the packet causing the error is returned as normal data.

On SCCP connection class 2 and 3 sockets, SS7_RECVERR has slightly different semantics. Instead of saving the errors for the next timeout, it passes all incoming errors immediately to the user. This might be useful for very short-lived SCCP connections which need fast error handling. Use this option with care: it makes SCCP unreliable by not allowing it to recover properly from GTT routing shifts and other normal conditions and breaks the protocol specification. Note that SCCP connection class 2 and 3 has no error queue; MSG_ERRQUEUE is illegal on SS7_SCCP_CC_2 and SS7_SCCP_CC_3 sockets. Thus all errors are returned by socket function return or SO_ERROR only.

For raw sockets, SS7_RECVERR enables passing of all received errors to the application, otherwise errors are only reported on connected sockets.

It sets or retreives an integer boolean flag. SS7_RECVERR defaults to off.

SS7_SIF_MAX

Retreive the current maximum message size for the current socket. Only valid when a link selection criteria has been provided. Returns an integer. Only valid as a getsockopt(2).

All of the ioctls described in socket(7) apply to SS7. The ioctls to configure gateway screening are documented in gws(7) from the bgws package. Ioctls to configure generic device parameters and described in ss7device(7).

These ioctls can be accessed using ioctl(2). The correct syntax is:

    int value;
    error = ioctl(mtp_socket, ioctl_type, &value);

FIONREAD: Returns the amount of queued unread data in the receive buffer. Argument is a pointer to an integer.
TIOCOUTQ: Returns the amount of unsent data in the socket send queue in the passed integer value pointer.

When a network error occurs, SS7 tries to route around the failure. If MTP is unable to route around the failure, the last received error for this user part is return in the return value of the send(2) or recv(2) operation, unless the SS7_RECVERR option is set. If an SCCP packet is returned on error, the error is reported on the error queue when the SS7_RECVERR option is set.

Many of the socket options, sysctls and ioctls which are provided with the NET4 package can also be applied to the SS7 subsystem; however, many of the non-applicable socket options, sysctls and ioctls will return ENOPROTOOPT or EOPNOTSUPP.

ENOTCONN: The operation is only defined on a connected socket, but the socket wasn't connected.
EINVAL: Invalid argument passed.
EMSGSIZE: The SS7 PDU is longer than the SS7 MTU (SIF_MAX) on the link and it cannot be fragmented. This normally only applies to mtp(7) sockets. mtp(7) does not permit fragmentation of packets; sccp(7) does.
EACCES: The user tried to execute an operation without the necessary permissions.
EADDRINUSE: Tried to bind to an address already in use. For mtp(7) this means that the specified user part in the address is already bound to another socket for the specified Point Code (PC). For sccp(7) this means that the specified subsystem number in the address is already bound to another socket for the specified Point Code (PC). For isup(7) this means that the specified CIC (Circuit Identification Code) range is already bound to another socket for the specificed (local PC, remote PC) pair.
ENOMEM and ENOBUFS: Not enough free memory available. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory, but this is not 100% consistent.
ENOPROTOOPT and EOPNOTSUPP: Invalid socket options passed. Although it is possible to pass many of the socket options which correpsond to ip(7), many ip(7) options are invalid for SS7 and return one of these two errors.
EPERM: Users doesn't have permission to set high priority, change configuration, or send signals to the requested process group.
ESOCKTNOSUPPORT: The socket is not configured or an unknown socket type was requested.
EISCONN: connect(2) was called on an already connected socket. This only really applies to sccp(7) connection class 2 and 3 sockets. (Connection class 2 and 3 sccp(7) sockets are not currently implemented.)
EALREADY: A connection operation on a non-blocking socket is already in progress. This only really applies to sccp(7) connection class 2 and 3 sockets. (Connection class 2 and 3 sccp(7) sockets are not currently implemented.)
ECONNABORTED: A connection was closed during an accept(2). This only really applies to sccp(7) connection class 2 and 3 sockets. (Connection class 2 and 3 sccp(7) sockets are not currently implemented.)
EPIPE: The connection unexpectedly closed or shut down by the other end. This applies to connection-less as well as connection-oriented SS7 sockets. When a socket is bound to a destination address, when the destination address becomes unavailable (in the SS7 sense), this error will be returned and the SIG_PIPE signal raised if the socket options are appropriately set.
ENOENT: SIOCGSTAMP was called on a socket where no packet arrived.
EHOSTUNREACH: No valid routing table entry matches the destination address. This error is generated by SS7 when an attempt is made to send to a prohibited route set to a distant SEP (Signalling End Point) which is not currently accessible. This error can be caused by a transfer-prohibited message from an STP or for a prohibited route in the local routing table.
ENODEV: Network device not available or not capable of sending SS7.
ENOPKG: A kernel subsystem was not configured.

In addition to the above error codes (which are the same as the error codes returned by ip(7)), SS7 provides the following protocol specific error codes:

Other errors may be generated by the overlaying protocols; see mtp(7), sccp(7), raw(7) and socket(7)

As this is an ALPHA (experimental) release. As such, there are probably many unknown bugs.

I don't know that I ever intend to develop SCCP Connection Classes 2 and 3. These are not used very much (or at least not as much as Connection Classes 0 and 1).

The OpenSS7 package provides this BSD socket interface for SS7 and was first provided as a module for Linux 2.2.

OpenSS7, <openss7@openss7.org>.

This man page borrows literally and heavily from the ip(7) man page for Linux written by Andi Kleen <ak@muc.de>.

ss7device(7), link(7), mtp(7), sccp(7), isup(7), tcap(7), gws(7), ip(7), raw(7), socket(7), socket(2), listen(2), connect(2), accept(2), bind(2), htonl(3), recvmsg(2), sendto(2), write(2), setsockopt(2), getsockopt(2), sysctl(2), ioctl(2)