Editing SimTX API v24/Packets/Handshake

{{SimTX API v24 navigation}}
{{SimTX packet v24
| name = Handshake
| id = —
| direction = c2s
| session = [[SimTX API v24/Connection and handshake|All roles]]
| size = 12 bytes + credential
| permission = None
| reply = [[SimTX API v24/Packets/HandshakeResult|HandshakeResult]]
| group = handshake
}}
The '''Handshake''' is the first data a client sends on a new connection, immediately after the TLS handshake. It identifies the protocol, states the protocol version, selects the session '''role''', and optionally carries a [[SimTX API v24/Game tickets|game ticket]]. Unlike every other packet, it has no packet ID byte.

== Layout ==
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>magic</code> || <code>i32</code> || Always <code>0x53494D54</code>, the ASCII bytes <code>SIMT</code>.
|-
| <code>version</code> || <code>i32</code> || Protocol version. Must be <code>24</code>.
|-
| <code>role</code> || <code>u8</code> || Session role. See [[#Roles|Roles]].
|-
| <code>authKind</code> || <code>u8</code> || <code>0</code> = <code>ANONYMOUS</code>, <code>1</code> = <code>GAME_TICKET</code>.
|-
| <code>credential</code> || <code>UTF</code> || Empty for anonymous connections. Otherwise the <code>stx_gt1_</code> ticket. At most 512 characters, no control characters.
|}

== Roles ==
{| class="wikitable"
! Byte !! Role !! Authentication
|-
| 1 || <code>RECEIVER</code> || Anonymous, or ticket role <code>receiver</code>
|-
| 2 || <code>TX_AUDIO</code> || Ticket role <code>tx-audio</code>
|-
| 3 || <code>TX_GENERATED</code> || Ticket role <code>tx-generated</code>
|-
| 4 || <code>CONTROL</code> || Anonymous, or ticket role <code>control</code>
|-
| 5 || <code>MODERATION</code> || Ticket role <code>moderation</code>
|-
| 6 || <code>TIMESTAMPED_RECEIVER</code> || Anonymous only
|}

== Validation ==
* <code>authKind = 0</code> requires an empty credential; <code>authKind = 1</code> requires a non-blank one.
* A wrong magic number, an unknown <code>authKind</code>, or an illegal credential (too long, control characters, or inconsistent with <code>authKind</code>) closes the connection '''without a reply'''.
* A wrong version is answered with [[SimTX API v24/Packets/HandshakeResult|HandshakeResult]] status <code>VERSION_UNSUPPORTED</code>.
* The handshake and the first session request must arrive within 5 seconds through the public gateway (15 seconds on a direct server).

== Example ==
Transmitter handshake with a ticket (ticket shortened):

<syntaxhighlight lang="text">
53 49 4D 54           magic       "SIMT"
00 00 00 18           version     24
02                    role        TX_AUDIO
01                    authKind    GAME_TICKET
00 48                 credential  length 72
73 74 78 5F 67 74 31 5F …         "stx_gt1_…"
</syntaxhighlight>

== See also ==
* [[SimTX API v24/Connection and handshake]]
* [[SimTX API v24/Game tickets]]

{{SimTX API v24 navbox}}
[[Category:SimTX API v24]]