The goal of the Session Traversal Utilities for NAT (STUN) library is to provide STUN Serializer and Deserializer functionalities.
Session Traversal Utilities for NAT (STUN), described in RFC8489, is a protocol that helps an endpoint behind the NAT to determine the IP address and port allocated to it by NAT.
A STUN message consist of 20 bytes header followed by zero or more attributes.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0 0| STUN Message Type | Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Magic Cookie |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| Transaction ID (96 bits) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Format of STUN Message Header
A STUN attribute is TLV encoded with a 16-bit type, 16-bit length and value.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Value (variable) ....
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Format of STUN Attributes
This STUN library provides standalone implementation of STUN serializer and STUN deserializer.
- Call
StunSerializer_Init()to start creating an STUN message. - Keep appending attributes by calling corresponding APIs of the form
StunSerializer_AddAttribute<AttributeName>:- To append priority attribute, call
StunSerializer_AddAttributePriority(). - To append Username attribute, call
StunSerializer_AddAttributeUsername(). - etc.
- To append priority attribute, call
- After appending all attributes, Call
StunSerializer_Finalize()to get the serialized STUN message.
- Call
StunDeserializer_Init()to start deserializing an STUN message. - Keep calling
StunDeserializer_GetNextAttribute()to get next attribute in the STUN message. - Call corresponding parse APIs to parse the attribute string, obtained using
StunDeserializer_GetNextAttribute(), into a structure:- If attribute type is
STUN_ATTRIBUTE_TYPE_PRIORITY, callStunDeserializer_ParseAttributePriority(). - If attribute type is
STUN_ATTRIBUTE_TYPE_USERNAME, callStunDeserializer_ParseAttributeUsername(). - etc.
- If attribute type is
- Repeat step 2 and 3 till
StunDeserializer_GetNextAttribute()returnsSTUN_RESULT_NO_MORE_ATTRIBUTE_FOUND.
- For running unit tests:
- C99 compiler like gcc.
- CMake 3.13.0 or later.
- Ruby 2.0.0 or later (It is required for the CMock test framework that we use).
- For running the coverage target, gcov and lcov are required.
By default, the submodules in this repository are configured with update=none
in .gitmodules to avoid increasing clone time and disk space
usage of other repositories.
To build unit tests, the submodule dependency of CMock is required. Use the following command to clone the submodule:
git submodule update --checkout --init --recursive test/CMock-
Go to the root directory of this repository. (Make sure that the CMock submodule is cloned as described in Checkout CMock Submodule).
-
Run the following command to generate Makefiles:
cmake -S test/unit-test -B build/ -G "Unix Makefiles" \ -DCMAKE_BUILD_TYPE=Debug \ -DBUILD_CLONE_SUBMODULES=ON \ -DCMAKE_C_FLAGS='--coverage -Wall -Wextra -Werror -DNDEBUG'
-
Run the following command to build the library and unit tests:
make -C build all
-
Run the following command to execute all tests and view results:
cd build && ctest -E system --output-on-failure
-
Run Unit Tests in Steps to build Unit Tests.
-
Generate coverage report in 'build/coverage' folder:
make coverage
This project is licensed under the Apache-2.0 License.