Current Implementation
======================

These are only approximate as I familiarize myself with the code and may be subject to revision as more information emerges

All multi-byte fields are in "network byte order" (big endian)

Control Packet Format
---------------------

    .. code::

        |3   2                   1                   0                  |
        |1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0|
        |---------------------------------------------------------------|
        |C|           Type              |          (unused)             |
        |---------------------------------------------------------------|
        |                          Control Data                         |
        |_______________________________________________________________|


- **C:** Control bit (this is a control packet so always 1)
- **Type:** 15-bit value identifying the type of control signal
- **Control Data:** optional 32-bit integer whose meaning is determined by the packet type

Control Signals
...............
- 0: ACK
    - Data packet received
    - Control data contains the sequence number of the received data packet
- 1: Handshake
    - Request a new connection
    - Control data contains the initial (random) sequence number for one direction in the new connection
- 2: Handshake ACK
    - Connection request received and acknowledged
    - Control data contains the initial (random) sequence number for the other direction in the new connection
- 3: Handshake Request
    - Connection is having issues, please force-reset it and renegotiate
    - No control data

Data Packet Format
------------------

    .. code::

        |3   2                   1                   0                  |
        |1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0|
        |---------------------------------------------------------------|
        |C|R|M| O |                Sequence Number                      |
        |---------------------------------------------------------------|
        | P |                  Message Number                           |
        |---------------------------------------------------------------|
        |                    Message Part Number                        |
        |---------------------------------------------------------------|
        |                                                               |
        |                Payload (described below)                      |
        |_______________________________________________________________|


- **C:** Control bit (this is a data packet so always 0)
- **R:** Reliable bit (if set then packet retry is attempted)
- **M:** Message bit (if set then this is part of a multi-packet message)
- **O:** Obfuscation (if non-zero then the contents of the message are XORed with the key)
    * 00 - no obfuscation
    * 01 - 0x6362726973736574
    * 10 - 0x7362697261726461
    * 11 - 0x72687566666d616e
- **Sequence Number:** The incrementing ID identifying this data packet within the datastream

The following fields are only present in the packet if the M (Message) bit is set:

- **P:** Position - the packet’s position within the message:
    * 00 - this is the only packet in the message
    * 10 - first packet in multi-packet message
    * 11 - middle packet in multi-packet message (i.e. neither first nor last)
    * 01 - last packet in multi-packet message
- **Message Number:** The incrementing ID identifying this message within the datastream
- **Message Part Number:** The packet number identifying this packet within its message

Reference: this was an excerpt from networking/src/udt/Packet.h:

    .. code:: C++

        //                         Packet Header Format
        //
        //     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
        //    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        //    |C|R|M| O |               Sequence Number                       |
        //    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        //    | P |                     Message Number                        |  Optional (only if M = 1)
        //    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        //    |                         Message Part Number                   |  Optional (only if M = 1)
        //    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        //
        //    C: Control bit
        //    R: Reliable bit
        //    M: Message bit
        //    O: Obfuscation level
        //    P: Position bits

STUN Packet Format
------------------
These packets follow `RFC 5389 <https://tools.ietf.org/html/rfc5389>`_:

    .. code::

        |3   2                   1                   0                  |
        |1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0|
        |---------------------------------------------------------------|
        |0 0|      Message Type         |      Message Length           |
        |---------------------------------------------------------------|
        |                        Magic Cookie                           |
        |---------------------------------------------------------------|
        |                                                               |
        |                    Transaction ID (96 bits)                   |
        |_______________________________________________________________|

The **Magic Cookie** in this packet is always the fixed value 0x2112A442 (in network byte order)

This packet if received in the middle of a UDT stream would identify itself as a data packet.
While there is no obvious logic in the code to prevent this from being interpreted as a data packet (which would be unlikely unless we had a UDT connection
with a STUN server *and* the message number matched the Cookie),
there is logic that receives all UDT packets and checks to see if they might be a STUN response packet.