otc

otc copied to clipboard

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

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

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