doc/STUN_RFC5389_CNL113778_FD.adoc

---
Author: Endre Kulcsár
Version: 1551-CNL 113 778, Rev. B
Date: 2016-11-17

---
= STUN RFC5389 Protocol Modules for TTCN-3 Toolset with TITAN, Function Description
:author: Endre Kulcsár
:revnumber: 1551-CNL 113 778, Rev. B
:revdate: 2016-11-17
:toc:

*Copyright*

Copyright (c) 2000-2019 Ericsson Telecom AB. +
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 that accompanies this distribution, and is available at +
http://www.eclipse.org/legal/epl-v10.html.

== How to Read This Document

This is the Function Specification for the set of STUN protocol module. STUN protocol module is developed for the TTCN-3 Toolset with TITAN.

== Scope

The purpose of this document is to specify the content of the STUN protocol module. Basic knowledge of TTCN-3 <<_2, [2]>> and TITAN TTCN-3 Test Executor <<_4, [4]>> is valuable when reading this document.

== System Requirements

Protocol modules are a set of TTCN-3 source code files that can be used as part of TTCN-3 test suites only. Hence, protocol modules alone do not put specific requirements on the system used. However, in order to compile and execute a TTCN-3 test suite using the set of protocol modules the following system requirements must be satisfied:

* TITAN TTCN-3 Test Executor version R7A (1.7.pl0) or higher installed. For installation guide see <<_4, [4]>>

NOTE: This version of the protocol module is not compatible with TITAN releases earlier than R7A

== Overview

Protocol modules implement the messages structure of the related protocol in a formalized way, using the standard specification language TTCN-3. This allows defining of test data (templates) in the TTCN-3 language and correctly encoding/decoding messages when executing test suites using the TITAN TTCN-3 test environment <<_4, [4]>>.

Protocol modules are using TITAN’s RAW encoding attributes and hence are usable with the TITAN test toolset only <<_3, [3]>>.

There are useful functions in the file __STUN_Functions.ttcn__ to create messages easily, but templates can also be defined to send and receive a given message.

== Installation

The set of protocol modules can be used in developing TTCN-3 test suites using any text editor. However to make the work more efficient a TTCN-3-enabled text editor is recommended. Since the STUN protocol is used as a part of a TTCN-3 test suite, this requires TTCN-3 Test Executor be installed before the module can be compiled and executed together with other parts of the test suite. For more details on the installation of TTCN-3 Test Executor see the relevant section of <<_4, [4]>>.

= General

Protocol modules implement the message structures of the related protocol in a formalized way, using the standard specification language TTCN-3. This allows defining of test data (templates) in the TTCN-3 language <<_2, [2]>> and correctly encoding/decoding messages when executing test suites using the TITAN TTCN-3 test environment <<_4, [4]>>.

Protocol modules are using TITAN’s RAW encoding attributes <<_3, [3]>> and hence are usable with the TITAN test toolset only.

= Functional Specification

== Protocol Version Implemented

This set of protocol modules implements protocol messages and constants of the STUN protocol. The module is based on https://tools.ietf.org/html/rfc5389[RFC 5389]. The following messages are implemented:

* Binding Request
* Binding Indication
* Binding Success Response
* Binding Error Response

=== Unimplemented Messages, Information Elements and Constants

None.

[[protocol-modifications-deviations]]
=== Protocol Modifications/Deviations

In addition to attributes in https://tools.ietf.org/html/rfc5389[RFC 5389] the attributes described in https://tools.ietf.org/html/rfc5245[RFC 5245] are also implemented. These additional attributes are:

* `PRIORITY`
* `USE_CANDIDATE`
* `ICE_CONTROLLED`
* `ICE_CONTROLLING`

The error code `ROLE_CONFLICT` is also implemented from https://tools.ietf.org/html/rfc5245[RFC 5245].

[[encoding-decoding-and-other-related-functions]]
== Encoding/Decoding and Other Related Functions

This product also contains encoding/decoding functions, which assure correct RAW encoding of messages when sent from TITAN and correct RAW decoding of messages when received by TITAN. Implemented encoding/decoding functions:

[width="100%",cols="34%,33%,33%",options="header",]
|===
|Name |Type of formal parameters |Return
|`ef_STUN_enc` |in PDU_STUN `pl_pdu`,in OCT16 pl_key,in STUN_Attribute_Typepl_last_attribute_type, out octetstring `pl_result`, in Boolean `pl_calculate_HMAC_CRC` |-
|`ef_STUN_dec` |in octetstring `pl_stream out`  PDU_STUN `pl_result` |-
|`ef_STUN_Check_Message_Integrity` |in octetstring `pl_stream`, in OCT16 pl_key,in STUN_Attribute_Type `pl_last_attribute_type` |Boolean
|`ef_STUN_Generate_Transaction_Id` |- |OCT12
|`ef_STUN_get_Message_Length` |in octetstring `pl_stream` |Integer
|===

The `message_integrity` and the fingerprint field will be calculated while encode (when `pl_calculate_HMAC_CRC` encode parameter equals `_true_`) so dummy values are allowed.

== _Makefile_

The _Makefile_ has to link crypto and z libraries.

[source]
----
-lttcn3-parallel *-lcrypto* *-lz* +
-lxml2 +
----

= Terminology

No specific terminology is used.

= Abbreviations

STUN:: Session Traversal Utilities for NAT

UDP:: User Datagram Protocol

NAT:: Network Address Translators

TTCN-3:: Testing and Test Control Notation version 3

= References

[[_1]]
[1] https://tools.ietf.org/html/rfc5389[RFC 5389] +
STUN - Session Traversal Utilities for NAT

[[_2]]
[2] ETSI ES 201 873-1 v4.5.1 (2013-02) +
The Testing and Test Control Notation version 3; Part 1: Core Language

[[_3]]
[3] Programmer’s Technical Reference for the TITAN TTCN-3 Test Executor

[[_4]]
[4] User Guide for the TITAN TTCN-3 Test Executor

[[_5]]
[5] https://tools.ietf.org/html/rfc5245[RFC 5245] +
Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT)Traversal for Offer/Answer Protocols