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)
    • 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)
• /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):
      1. Connect through UDP to port p+1 (one port higher than the server port)
      2. Send 1 non-NULL byte
      3. Receive at least 1 byte back
    • a human-readable response not starting with the control character * must be returned
• /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
    • 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
• /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
  • 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 only
          • 0 deban
          • 1 master
          • 2 admin
          • 3 owner/highest
        • [name] is the full username (string)