Protocol v1.3 - acreloaded/ms GitHub Wiki
Current
This protocol specification is the latest!
Changelog
Compared to v1.2, changes include
- IPv6 support
- shorter endpoint names to save bandwidth
Specification
The master-server provides a HTTP API for clients and servers. Every endpoint uses the GET method, which clearly does not follow REST principles.
The specification is presented as a list of GET endpoints with GET parameters and response lines separated by line feed (LF) characters. All lines are mandatory unless otherwise stated.
/c
client cube-compatible file- parameters (all optional)
build_defs
description of client build environment according to its ACR protocol implementation (uint8)guid32
client GUID (uint32, deprecated)
- response lines
masterserver_flags [flags]
flags
(uint16) is the OR result of- Group A (bits 0-1): IP status
- 0 - Unlisted
- 1 - Whitelisted
- 2 - Blacklisted: Banned
- 3 - Blacklisted: Muted
- Group B (bits 2-7)
- 0 - these bits are reserved (flags & 0xFC must be 0)
- Group A (bits 0-1): IP status
current_version [version] [protocol]
with the ACR latest game and protocol version numbers (uint32, uint32, optional)addserver [ip] [port] [weight]
multiple times[ip]
IPv4 (dotted-decimal format in RFC 1123) or IPv6 (RFC 4291) address (string)[port]
UDP port number ≠ 65535 (uint16, optional, default 28770)[weight]
(int32, optional, default 0)
- parameters (all optional)
/r
- server register- parameters
p
server port number (uint32, optional, default 28770)v
protocol version number (uint32)g
game version number (uint32, optional)guid32
server GUID (uint32, deprecated)
- response line
- a socket check should be performed (but is not required):
- Connect through UDP to port
p
+1 (one port higher than the server port) - Send 1 non-NULL byte
- Receive at least 1 byte back
- Connect through UDP to port
- a human-readable response not starting with the control character
*
must be returned
- a socket check should be performed (but is not required):
- parameters
/a
server connect auth check- parameters
p
server port number (uint16, optional, default 28770)a
client IPv6 address- a.b.c.d (IPv4) is mapped to ::ffff:a.b.c.d first.
Example: 192.0.2.127 is mapped to ::ffff:c000:027f = 0000:0000:0000:0000:0000:ffff:c000:027f
- a.b.c.d (IPv4) is mapped to ::ffff:a.b.c.d first.
guid32
client GUID (uint32, deprecated)- optional, ignored unless both are present
i
request ID for state (uint32)u
user ID (string)
- response lines
- If the
i
/u
pair is sent, one of*f
if an error occurs, possibly because of- disabled auth
- unregistered server
- invalid user ID (not found)
*c[nonce]
with[nonce]
lowercase hex-encoded cryptography-grade 1024-bit random challenge (char[256])
- IP lookup result: one of
*bw
- whitelisted IP*bi
- blacklisted IP, but also not whitelisted*bm
- muted and not allowed to speak or use /kick or /ban*a
- no matches, usual response a line feed character, followed by the regular response
- If the
- parameters
/v
server verify auth- parameters
p
server port number (uint16, optional, default 28770)i
request ID for state (uint32)c
client nonce in lowercase hex (char[96])a
lowercase hex-encoded 256-bit digest (char[64])- expected response: HMAC (RFC 2104) result with
- hashing algorithm: SHA256
- message data: (byte[176] = 1408 bits) concatenation of these in raw binary format:
- client nonce (byte[48] = 384 bits)
- master-server challenge (byte[128] = 1024 bits)
- key: pre-shared key between the client and master-server
- expected response: HMAC (RFC 2104) result with
- response line
- result of auth: one of
*f
if an error occurs, possibly because of- disabled auth
- unregistered server
- invalid request ID
*d
if authentication does not match- The server would previously disconnect the client, but not anymore.
*s[priv][name]
if auth succeeded[priv]
client privilege (char)x
for name verification only0
deban1
master2
admin3
owner/highest
[name]
is the full username (string)
- result of auth: one of
- parameters