Otc

• 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.

#+BEGIN_SRC erlang 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, ..}]} #+END_SRC

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

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

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

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

Examples are given with m2pa codec, but could be used with any of the supported protocols. See tests

Due to ASN.1-files and Diameter dictionaries taking long time to compile, one could set either or both of environment variables OTC_NO_ASN1=true, OTC_NO_DIA=true before compiling otc (not that the value doesn't matter).

• Options

  Options are given as a map.

  Parameters:

  stop_after - the value is given as an atom; the protocol after which to stop decoding. If not given, will try to decode as much as possible.

  Protocol - where Protocol is the atom name of the codec, e.g. m2pa, mtp3, sccp, nas_eps, sgsap, gtpv1_c, gtpv2_c. The Value should be the option map for the specified Protocol.

#+BEGIN_SRC erlang otc:codec({m3ua, Bin}, #{stop_after => sccp, sccp => #{address_type => ansi}}). #+END_SRC

** sccp options

Parameters:

address_type - used to determine if the SCCP address is ANSI or ITU formatted. Default is ITU.

#+BEGIN_SRC erlang #{address_type => ansi} #+END_SRC

** nas_eps options

Parameters:

direction - used to determine if the message is UE originating or UE terminating, which is needed for for instance detach-requests. Without this option OTC will try to determine it itself.

#+BEGIN_SRC erlang #{direction := 'id-downlinkNASTransport' | 'id-uplinkNASTransport'} #+END_SRC

• 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) | | SMPP | SMS Forum SMPP V5.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 |