Erlang/OTC - Open Telecom Codec

This library tries to implement encoding and decoding for different (3GPP) telecom protocols. The aim is to support the newest release of each spec, if not stated otherwise.

Encoded format is a binary, and decoded format is a map.

If a field or message is not supported, the library should not crash but instead return some error-tuple or atom.

Decoding should preferably be strict, and follow the rules from the specification. Encoding on the other hand, should be lenient, but if format is incorrect, then log a warning. The idea behind this is that the user knows best what to send, but might need guidance.

Usage

otc can be called with both `decode/2`, `decode/3`, as well as `decapsulate/2`, `decapsulate/3` functions. The differens is that decapsulate will crash on errors while decode returns an error-tuple.

`decode/1` and `decapsulate/1` assumes SCTP packets.

In successful cases `decode` will return an ok-tuple containing either (only) a list of headers if the binary was fully decoded, or both a list of decoded headers, and a binary containing the parts it was not able to decode.

1> otc:decode(m2pa, UserBinary).
{ok, {[#{protocol := m2pa, ..}, #{protocol := mtp3, ..}, #{protocol := sccp, ..}], <<SCCPPayload>>}}

2> otc:decode(m2pa, UserBinary, #{stop_after => mtp3}).
{ok, {[#{protocol := m2pa, ..}, #{protocol := mtp3, ..}], <<MTP3Payload>>}}

3> otc:decode(m2pa, LinkBinary).
{ok, [#{protocol := m2pa, ..}]}

4> otc:decapsulate(m2pa, UserBinary).
{[#{protocol := m2pa, ..}, #{protocol := mtp3, ..}, #{protocol := sccp, ..}], <<SCCPPayload>>}

5> otc:decapsulate(m2pa, UserBinary, #{stop_after => mtp3}).
{[#{protocol := m2pa, ..}, #{protocol := mtp3, ..}], <<MTP3Payload>>}

6> otc:decapsulate(m2pa, LinkBinary).
[#{protocol := m2pa, ..}]

7> otc:decode(SctpBinary).
{ok, [#{protocol := sctp, ..}]}

For encoding there is only one function encode/1, but it can take multiple different types of inputs.

11> otc:encode(#{protocol => m2pa, ..}).
<<M2PABinary>>

12> otc:encode([#{protocol => m2pa, ..}, #{protocol => mtp3, ..}]).
<<M2PABinary>>

13> otc:encode({[#{protocol => m2pa, ..}], <<M2PAPayload>>}).
<<M2PABinary>>

Examples are given with m2pa codec, but could be used with any of the supported protocols. See [tests](test/otc_tests.erl)

Linguistics

decode - function that converts from binary format to an Erlang map

decapsulate - as decode, but crashes on errors.

parse - function that converts from UMTS magic number to Erlang atom

encode - function that converts from Erlang map to binary format

compose - function that converts from Erlang atom to UMTS magic number

*_codec - modules used as helpers, does not comply with the pkt-style codecs.

Codecs

Name	Spec	Decode	Encode	Production Tested (Decode/Encode)	Notes
SCTP	IETF RFC 2960 October 2000	X	X
M3UA	IETF RFC 4666 September 2006	X	X	DE
M2PA	IETF RFC 4165 September 2005	X	X	DE
MTP3	ITU-T Q.704 (07/96) July 1996	X	X	DE
SCCP	ITU-T Q.713 (03/2001)	X	X	DE
L3	3GPP TS 24.007 v16.5.0	X	X
NAS EPS	3GPP TS 24.301 v16.8.0	X	X		Parameters might be binary decoded (i.e. passthrough)
NAS 5GS	3GPP TS 24.501 v16.10.0	X	X		Parameters might be binary decoded (i.e. passthrough)
SGSAP	3GPP TS 29.118 v17.0.0	X	X		Parameters might be binary decoded (i.e. passthrough)
GTPv1-C	3GPP TS 29.060 v17.3.0	X	X		Parameters might be binary decoded (i.e. passthrough)
GTPv2-C	3GPP TS 29.274 v17.7.0	X	X		Parameters might be binary decoded (i.e. passthrough)

Diameter interfaces

Interfaces	Spec	Notes
Gi/Sgi	3GPP TS 29061
Gmb	3GPP TS 29061
SGmb	3GPP TS 29061
Zh	3GPP TS 29109
Zn	3GPP TS 29109
Zpn	3GPP TS 29109
T6a/T6b	3GPP TS 29128
MM10	3GPP TS 29140
Ns	3GPP TS 29153
Nta	3GPP TS 29154
Nt	3GPP TS 29154
SLg	3GPP TS 29172
SLh	3GPP TS 29173
Gq	3GPP TS 29209
Rx	3GPP TS 29211
Gx	3GPP TS 29212
Gxx	3GPP TS 29212
S15	3GPP TS 29212
Sd	3GPP TS 29212
St	3GPP TS 29212
Rx	3GPP TS 29214
S9a	3GPP TS 29215
S9a*	3GPP TS 29215
S9	3GPP TS 29215
Np	3GPP TS 29217
Sy	3GPP TS 29219
Cx	3GPP TS 29229
Pr	3GPP TS 29234
Wx	3GPP TS 29234
S13/S13’	3GPP TS 29272
S6a/S6d	3GPP TS 29272
S7a/S7d	3GPP TS 29272
S6b	3GPP TS 29273
STa	3GPP TS 29273
SWm	3GPP TS 29273
SWx	3GPP TS 29273
Diameter Data Management	3GPP TS 29283
Sh	3GPP TS 29329
S6m/S6n	3GPP TS 29336
S6t	3GPP TS 29336
T4	3GPP TS 29337
S6c	3GPP TS 29338
SGd/Gdd	3GPP TS 29338
PC4a	3GPP TS 29344
PC6/PC7	3GPP TS 29345
Tsp	3GPP TS 29368
V4	3GPP TS 29388
V6	3GPP TS 29389
MB2-C	3GPP TS 29468
Rq	ETSI ES 283 026
e4	ETSI ES 283 034	Circular dependency/does not compile
e2	ETSI ES 283 035	Circular dependency/does not compile
GOCAP	ETSI ES 283 039-2
Gq	ETSI TS 183 017
e4	ETSI TS 183 059-1
Re	ETSI TS 183 060	Circular dependency/does not compile
a4	ETSI TS 183 066	Circular dependency/does not compile
Rr Delegated	ETSI TS 183 071
Rr Request	ETSI TS 183 071

ASN.1

Name	Spec	Note
MAP v1	GSM 09.02 v4.9.1/ETS 300.599 01-60	correct spec?
MAP v2	GSM 09.02 v4.19.1/ETS 300.599 09-60	correct spec?
MAP v3
MAP v4	3GPP TS 29.002 v16.3.0
CAP v1	GSM Phase 2+ R96
CAP v2	GSM 03.78/3GPP TS 01.441 v7.8.1
CAP v3	3GPP TS 23.078 v4.11.1
CAP v4	3GPP TS 23.078 v16.0.0