SimTX API v24/Packets/Handshake - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:15:09Z

Archive the v24 protocol reference: use the v24 templates, links and categories

← Older revision		Revision as of 16:15, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	{{SimTX packet		{{SimTX packet v24
	\| name = Handshake		\| name = Handshake
	\| id = —		\| id = —
	\| direction = c2s		\| direction = c2s
	\| session = [[SimTX API/Connection and handshake\|All roles]]		\| session = [[SimTX API v24/Connection and handshake\|All roles]]
	\| size = 12 bytes + credential		\| size = 12 bytes + credential
	\| permission = None		\| permission = None
	\| reply = [[SimTX API/Packets/HandshakeResult\|HandshakeResult]]		\| reply = [[SimTX API v24/Packets/HandshakeResult\|HandshakeResult]]
	\| group = handshake		\| 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/Game tickets\|game ticket]]. Unlike every other packet, it has no packet ID byte.		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 ==		== Layout ==
Line 47:		Line 47:
	* <code>authKind = 0</code> requires an empty credential; <code>authKind = 1</code> requires a non-blank one.		* <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 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/Packets/HandshakeResult\|HandshakeResult]] status <code>VERSION_UNSUPPORTED</code>.		* 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).		* The handshake and the first session request must arrive within 5 seconds through the public gateway (15 seconds on a direct server).

Line 63:		Line 63:

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

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

Clanker: Clanker moved page SimTX API/Packets/Handshake to SimTX API v24/Packets/Handshake: Archive the v24 protocol reference

2026-10-24T16:15:07Z

Clanker moved page SimTX API/Packets/Handshake to SimTX API v24/Packets/Handshake: Archive the v24 protocol reference

← Older revision	Revision as of 16:15, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:57:49Z

SimTX API documentation

New page

{{SimTX API navigation}}
{{SimTX packet
| name = Handshake
| id = —
| direction = c2s
| session = [[SimTX API/Connection and handshake|All roles]]
| size = 12 bytes + credential
| permission = None
| reply = [[SimTX API/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/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/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/Connection and handshake]]
* [[SimTX API/Game tickets]]

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