mirror of
https://github.com/tangerineturtle1/NX2navi.git
synced 2026-11-16 18:09:58 -04:00
Each player keeps their own game and save. One player makes a room, the others join it with its secret, and story flags and, by the room's rules, items, songs, quest items, small keys (a shared pool), rupees and ammunition reach every save. The layer is a host thread with one UDP socket to a relay the players run themselves (tools/coop_relay.py, Python's standard library only); the messages between the players are sealed with a key from the room's secret (XChaCha20-Poly1305, Monocypher 4.0.2 vendored with its licence and a row in THIRD_PARTY_NOTICES.md), every change is signed by the player who made it, a player accepts a room by its members' keys and the key of its rules, the save is copied to coop-backup before anything is applied, and values are set through the game's own routines between frames. The Co-op tab makes, joins, accepts, removes and leaves, and the menu takes typed text for the name, the relay and the secret. This is the contributor's pull request #518 on this line. Nothing reaches the network while co-op is off: the socket is opened, and the relay's name looked up, only after co-op is on, a relay is set and a room is made or joined. There is no default relay. Left out of the pull request: the other players drawn in the world (the "puppets") with the copied engine they need. They were unfinished, added two patch sites to the game's per-frame update that could not be put through the differential tests here, and their file helpers clashed with the ones this line already has. So no position is sent: the POS message's codec stays, nothing sends it. Changed against the pull request: - The menu's test hook drives the Co-op tab only when it comes from the environment. From nx2navi.ini it could turn co-op on, join a room and accept its offer. - The log's label for a room is hashed from the secret instead of being its first three characters. - A game that has not saved yet has no save to copy, and takes nothing from the room until it has saved once; that used to count as a copy made. - A PING's token no longer carries the PC's uptime. - On Windows the maker's key file and its folder get an access list with the player's account alone. - The tests that link the platform layer get the socket library, and the save test a stand-in for the title screen's hook. Checked on Windows, where the pull request had never been compiled: the runtime builds and links; --probe-coop passes (sockets on 127.0.0.1, the codec against its byte vectors, a fuzz of every parser, two sessions through a hostile mock relay, a relay restart, the sync engine); tests/coop_relay_test.py passes its 61 tests, with the probe through the real relay on 127.0.0.1 at 0 and 30 % loss; tests/coop_page_check.py passes and its deliberate fault fails 48 checks. Not checked: two games in one room (one game runs at a time here), any real network, the tab in the game. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
210 lines
15 KiB
C
210 lines
15 KiB
C
// The co-op wire format, as pure functions on bytes: no sockets, no threads, no game state. docs/coop.md ("The room's
|
|
// secret and the wire") is the description a reviewer checks this file against.
|
|
//
|
|
// A room is named by a secret the players share out of band: 18 characters of a 27-symbol alphabet (85 bits), shown
|
|
// XXXXXX-XXXXXX-XXXXXX. The relay never sees it. Two values are derived from it with keyed BLAKE2b (the key is the
|
|
// secret's 18 canonical characters): the room's locator (16 bytes), which the relay knows the room by and which keys
|
|
// the tag of every datagram between a client and the relay, and the message key (32 bytes), which seals every message
|
|
// between the players (XChaCha20-Poly1305), so that the relay and anyone on the path can neither read nor change nor
|
|
// make one.
|
|
//
|
|
// A datagram is a 24-byte header (little-endian) and a payload; the header carries an 8-byte tag, the start of an
|
|
// HMAC-SHA256 over the first 16 header bytes and the payload, keyed with the locator. The client and relay messages
|
|
// are CONNECT .. LEAVE and KICK (tools/coop_relay.py, the same format in Python); DATA carries a sealed player message:
|
|
// the envelope (sender's session, counter) and, sealed, one kind byte and the message bytes the layers above coop.c
|
|
// define. tests/coop_vectors.txt holds byte vectors that this file and the relay's Python are checked against
|
|
// (--probe-coop, tests/coop_relay_test.py). Every parser checks every length against the bytes it was given and fails
|
|
// closed.
|
|
#pragma once
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
|
|
enum {
|
|
COOP_MAGIC = 0x434E, // bytes 4E 43
|
|
COOP_PROTO = 2, // protocol major: a relay and a client talk only when it is equal
|
|
COOP_HDR_LEN = 24,
|
|
COOP_MAX_DGRAM = 1200, // a datagram's size at most: it crosses any path without fragmenting
|
|
COOP_MAX_PAYLOAD = COOP_MAX_DGRAM - COOP_HDR_LEN,
|
|
COOP_TAG_LEN = 8,
|
|
COOP_KEY_LEN = 16, // the locator, which keys the tags
|
|
COOP_MSG_KEY_LEN = 32,
|
|
COOP_DST_ALL = 0xFF, // dst: every other member of the room
|
|
COOP_SECRET_LEN = 18, // characters of a room secret
|
|
COOP_SECRET_TEXT = COOP_SECRET_LEN + 2, // shown with two '-'
|
|
COOP_MAX_MEMBERS = 8,
|
|
COOP_NAME_MAX = 24, // a player's name in bytes of UTF-8
|
|
COOP_COOKIE_LEN = 16,
|
|
COOP_CONNECT_MIN = 64, // a CONNECT datagram's smallest size, so that no answer to it is larger
|
|
COOP_ENV_V1 = 1, // the envelope of a player message
|
|
COOP_ENV_HDR = 13, // u8 envelope version, u64 session, u32 counter
|
|
COOP_ENV_MAC = 16,
|
|
COOP_ENV_OVERHEAD = COOP_ENV_HDR + COOP_ENV_MAC,
|
|
COOP_MAX_MESSAGE = COOP_MAX_PAYLOAD - COOP_ENV_OVERHEAD - 1, // a player message's bytes after its kind, at most
|
|
};
|
|
|
|
// Datagram types. CONNECT .. LEAVE and KICK are between a client and the relay, DATA carries the players' messages.
|
|
enum { COOP_T_CONNECT = 1, COOP_T_CHALLENGE = 2, COOP_T_JOINED = 3, COOP_T_ERROR = 5, COOP_T_ROSTER = 6, COOP_T_PING = 7,
|
|
COOP_T_PONG = 8, COOP_T_LEAVE = 9, COOP_T_KICK = 11, COOP_T_DATA = 0x10 };
|
|
enum { COOP_INTENT_CREATE = 1, COOP_INTENT_JOIN = 2 }; // CONNECT: make the room of a locator or join it
|
|
enum { COOP_E_NO_ROOM = 1, COOP_E_ROOM_FULL = 2, COOP_E_PROTO = 3, COOP_E_RATE = 4, COOP_E_BAD_TAG = 5, COOP_E_SERVER_FULL = 6,
|
|
COOP_E_ROOM_EXISTS = 7, COOP_E_REMOVED = 8, COOP_E_SESSION_USED = 9 }; // 9: a session used in the room before
|
|
enum { COOP_FLAG_AWAY = 1, COOP_FLAG_MAKER = 2 }; // roster flags: not heard from for a while; made the room
|
|
|
|
// The kinds of player messages (the first byte of a sealed message). coop.c only carries them; HELLO, POS, DIGEST,
|
|
// SECTION, SYNC_NEED and NOTICE belong to the layers that send them. A kind of 0xF0 and above is free for tests.
|
|
enum { COOP_K_HELLO = 1, COOP_K_POS = 2, COOP_K_DIGEST = 3, COOP_K_SECTION = 4, COOP_K_SYNC_NEED = 5, COOP_K_NOTICE = 6,
|
|
COOP_K_BYE = 7, COOP_K_TEST = 0xF0 };
|
|
|
|
typedef struct {
|
|
uint8_t ver, type;
|
|
uint8_t src, dst; // member ids 1..8; src 0 is the relay; dst COOP_DST_ALL: every other member
|
|
uint16_t len; // payload bytes
|
|
uint32_t room, seq; // room 0 until joined; seq counts the sender's datagrams
|
|
} CoopHdr;
|
|
|
|
// ---- room secrets: 18 characters of "23456789BCDFGHJKMNPRSTVWXYZ" (27 symbols, 85.6 bits; no vowels, 0/1/O/I/L, Q or
|
|
// E, so a secret spoken or typed does not read as a word), shown as XXXXXX-XXXXXX-XXXXXX. Any ASCII case, '-' and spaces
|
|
// ignored. 1 and the canonical 18 characters plus a NUL in out when text is a secret.
|
|
int coop_secret_normalize(const char *text, char out[COOP_SECRET_LEN + 1]);
|
|
void coop_secret_format(const char secret[COOP_SECRET_LEN], char out[COOP_SECRET_TEXT + 1]);
|
|
// A new secret from 32 random bytes (each symbol from one byte below 243, the rest skipped); 0 when they ran out.
|
|
int coop_secret_from_random(const uint8_t random[32], char out[COOP_SECRET_LEN + 1]);
|
|
// The secret's first characters and an ellipsis, for logs: "XXX…".
|
|
void coop_secret_short(const char secret[COOP_SECRET_LEN], char out[8]);
|
|
|
|
// ---- keys. BLAKE2b keyed with the secret's canonical characters: locator = BLAKE2b-128("nx2navi-coop/2 room"),
|
|
// message key = BLAKE2b-256("nx2navi-coop/2 messages"). The tag of a datagram: HMAC-SHA256(locator, header[0:16] +
|
|
// payload)[0:8].
|
|
void coop_hmac_sha256(const void *key, size_t klen, const void *a, size_t an, const void *b, size_t bn, uint8_t out[32]);
|
|
void coop_room_keys(const char secret[COOP_SECRET_LEN], uint8_t locator[COOP_KEY_LEN], uint8_t msg_key[COOP_MSG_KEY_LEN]);
|
|
|
|
// ---- datagrams
|
|
// The datagram of hdr (its len is ignored: n is the payload length) and payload into out. key NULL: a zero tag (what a
|
|
// relay of another protocol version answers). Bytes written, 0 when it does not fit cap or n is too long.
|
|
size_t coop_dgram_pack(uint8_t *out, size_t cap, const CoopHdr *hdr, const void *payload, size_t n,
|
|
const uint8_t key[COOP_KEY_LEN]);
|
|
// 1 when d is exactly one datagram of this format (magic, a length that matches); *payload points into d. The version
|
|
// and the tag are not checked here.
|
|
int coop_dgram_parse(const uint8_t *d, size_t n, CoopHdr *hdr, const uint8_t **payload);
|
|
// 1 when the tag of the parsed datagram d (n bytes) is the one key makes; time independent of where they differ.
|
|
int coop_dgram_verify(const uint8_t *d, size_t n, const uint8_t key[COOP_KEY_LEN]);
|
|
int coop_dgram_tag_zero(const uint8_t *d);
|
|
|
|
// ---- names: a player's name from untrusted bytes. At most COOP_NAME_MAX bytes of valid UTF-8; a control character
|
|
// (C0, DEL, C1) and each byte that is not valid UTF-8 become '?', and so do the characters that reorder text (bidi
|
|
// controls). out is NUL-terminated (cap at least COOP_NAME_MAX + 1); the length.
|
|
size_t coop_name_clean(char *out, size_t cap, const uint8_t *raw, size_t n);
|
|
|
|
// ---- client and relay messages
|
|
// CONNECT: u8 intent, u8 flags, u8[16] locator, u64 client id, u64 session, u64 nonce, u8 name length, name,
|
|
// u8[16] cookie (zero, or the CHALLENGE's), u8[16] rejoin token (zero, or the JOINED's of this room).
|
|
typedef struct {
|
|
uint8_t intent, flags;
|
|
uint8_t locator[COOP_KEY_LEN];
|
|
uint64_t client_id; // random for each start of the game; the relay knows a rejoin of the same member by it
|
|
uint64_t session; // random for each join: the others take messages only of the session the roster names
|
|
uint64_t nonce; // random for each attempt: every answer carries it
|
|
char name[COOP_NAME_MAX + 1];
|
|
uint8_t cookie[COOP_COOKIE_LEN], token[COOP_COOKIE_LEN];
|
|
} CoopConnect;
|
|
size_t coop_connect_pack(uint8_t *out, size_t cap, const CoopConnect *c); // zero-padded to COOP_CONNECT_MIN as a datagram
|
|
int coop_connect_parse(const uint8_t *p, size_t n, CoopConnect *c);
|
|
|
|
// CHALLENGE: u64 nonce, u8[16] cookie.
|
|
size_t coop_challenge_pack(uint8_t *out, size_t cap, uint64_t nonce, const uint8_t cookie[COOP_COOKIE_LEN]);
|
|
int coop_challenge_parse(const uint8_t *p, size_t n, uint64_t *nonce, uint8_t cookie[COOP_COOKIE_LEN]);
|
|
|
|
// ROSTER: u8 n, n x (u8 id, u8 flags, u64 session, u8 name length, name).
|
|
typedef struct { uint8_t id, flags; uint64_t session; char name[COOP_NAME_MAX + 1]; } CoopMemberInfo;
|
|
typedef struct { uint8_t n; CoopMemberInfo m[COOP_MAX_MEMBERS]; } CoopRoster;
|
|
size_t coop_roster_pack(uint8_t *out, size_t cap, const CoopRoster *r);
|
|
// used (may be NULL): the bytes the roster took.
|
|
int coop_roster_parse(const uint8_t *p, size_t n, CoopRoster *r, size_t *used);
|
|
|
|
// JOINED: u8 member, u64 nonce, u8[16] rejoin token, roster.
|
|
typedef struct { uint8_t member; uint64_t nonce; uint8_t token[COOP_COOKIE_LEN]; CoopRoster roster; } CoopJoined;
|
|
size_t coop_joined_pack(uint8_t *out, size_t cap, const CoopJoined *j);
|
|
int coop_joined_parse(const uint8_t *p, size_t n, CoopJoined *j);
|
|
|
|
// ERROR: u8 reason, u64 nonce (of the CONNECT it answers, 0 else), u8 text length, text.
|
|
typedef struct { uint8_t reason; uint64_t nonce; char text[61]; } CoopError; // text for the log, at most 60 bytes
|
|
size_t coop_error_pack(uint8_t *out, size_t cap, const CoopError *e);
|
|
int coop_error_parse(const uint8_t *p, size_t n, CoopError *e);
|
|
|
|
// KICK (the room's maker to the relay): u8 member, u64 its session.
|
|
size_t coop_kick_pack(uint8_t *out, size_t cap, uint8_t member, uint64_t session);
|
|
int coop_kick_parse(const uint8_t *p, size_t n, uint8_t *member, uint64_t *session);
|
|
|
|
size_t coop_u32_pack(uint8_t *out, size_t cap, uint32_t v); // PING and PONG: the token
|
|
int coop_u32_parse(const uint8_t *p, size_t n, uint32_t *v);
|
|
|
|
// ---- player messages: the payload of a DATA datagram, sealed with the message key.
|
|
// u8 envelope version (COOP_ENV_V1), u64 sender's session, u32 counter, ciphertext of (u8 kind, bytes), u8[16] tag
|
|
// XChaCha20-Poly1305: nonce = session (8 bytes LE), counter (4 LE), src (1), 11 zero bytes; associated data = dst and
|
|
// the envelope version. A session and counter are used once (a new session for every join, the counter from 1), so a
|
|
// nonce never repeats under the room's key. A later envelope version can carry other fields; the kind byte and the
|
|
// message inside stay as they are, so a new kind (a pose, say) only needs a number.
|
|
// Seal: the payload into out (cap); its length, 0 when n is above COOP_MAX_MESSAGE or it does not fit.
|
|
size_t coop_seal(uint8_t *out, size_t cap, const uint8_t key[COOP_MSG_KEY_LEN], uint8_t src, uint8_t dst, uint64_t session,
|
|
uint32_t counter, uint8_t kind, const void *bytes, size_t n);
|
|
// The envelope's clear fields; 0 when p is not an envelope of a version this build reads.
|
|
int coop_envelope_peek(const uint8_t *p, size_t n, uint64_t *session, uint32_t *counter);
|
|
// Open: 1 and the kind and bytes (into out, cap at least n) when the tag is right for this key, src and dst.
|
|
int coop_open(const uint8_t *p, size_t n, const uint8_t key[COOP_MSG_KEY_LEN], uint8_t src, uint8_t dst, uint8_t *kind,
|
|
uint8_t *out, size_t cap, size_t *nout);
|
|
|
|
// ---- signatures: EdDSA over Curve25519 with BLAKE2b (the library's crypto_eddsa). The room's message key cannot tell
|
|
// one member from another, and the sync layer's state travels through every member, so what only one member may make
|
|
// is signed with that member's key: its identity in the room, the maker's rules, and each pool contributor's counts
|
|
// (coop_state.c). Every member can then pass them on, and nobody but the key's holder can make or change them.
|
|
enum { COOP_PK_LEN = 32, COOP_SK_LEN = 64, COOP_SIG_LEN = 64 };
|
|
void coop_sign_keypair(const uint8_t seed[32], uint8_t sk[COOP_SK_LEN], uint8_t pk[COOP_PK_LEN]);
|
|
void coop_sign(uint8_t sig[COOP_SIG_LEN], const uint8_t sk[COOP_SK_LEN], const void *msg, size_t n);
|
|
int coop_sign_check(const uint8_t sig[COOP_SIG_LEN], const uint8_t pk[COOP_PK_LEN], const void *msg, size_t n); // 1: valid
|
|
// BLAKE2b of msg keyed with key (klen at most 64, 0 for none), outlen bytes (1 to 64): the sync layer's derivations.
|
|
void coop_blake2b(uint8_t *out, size_t outlen, const void *key, size_t klen, const void *msg, size_t n);
|
|
|
|
// ---- POS (COOP_K_POS): where a player is and what Link plays, for showing the other players (nothing sends it in this build), meant to be sent about 15
|
|
// times a second as a sealed player message (above). The bytes after the kind, little endian: u8 version
|
|
// (COOP_POS_VERSION), u32 pseq (the sender's counter: one more for each POS it sends), u32 t_ms (the sender's clock), u8
|
|
// flags, u8 area length (<= COOP_POS_TEXT) and the area's name (the game's current-area text), f32 x y z, f32 yaw
|
|
// (radians, 0 facing +z), u8 slot count (<= COOP_POS_SLOTS), per AS slot u8 node name length (<= COOP_POS_TEXT), the
|
|
// node's name, f32 frame. A parser takes exactly one message of its version: another version is another format this
|
|
// build cannot read (version 1 had a u16 pseq). The names come from another player's game and reach this one's log and
|
|
// its animation lookup, so a name with a byte outside printable ASCII (0x20..0x7e) is refused, and so is a number that
|
|
// is not finite.
|
|
#define COOP_POS_VERSION 2
|
|
#define COOP_POS_TEXT 47
|
|
#define COOP_POS_SLOTS 4
|
|
enum { COOP_POS_ADULT = 1, COOP_POS_IN_WORLD = 2 };
|
|
typedef struct {
|
|
uint32_t pseq;
|
|
uint32_t t_ms;
|
|
uint8_t flags, nslots;
|
|
char area[COOP_POS_TEXT + 1];
|
|
float pos[3], yaw;
|
|
struct { char node[COOP_POS_TEXT + 1]; float frame; } slot[COOP_POS_SLOTS];
|
|
} CoopPos;
|
|
size_t coop_pos_pack(uint8_t *out, size_t cap, const CoopPos *p); // 0 when it does not fit cap
|
|
int coop_pos_parse(const uint8_t *p, size_t n, CoopPos *out);
|
|
|
|
// The receiver's counter of one POS sender (coop.h: a handler is not called once only). A pose is taken only above the
|
|
// last one taken from the same member id in the same session, so neither a pose sent again nor one recorded earlier
|
|
// in the session moves the puppet back while that sender's poses keep being taken; the first pose of another session
|
|
// (another player given the id, the member back in a new session, or a roster that lists an earlier session) starts the
|
|
// counter again. After COOP_POS_QUIET_MS with none taken (below), whoever holds the sender's datagrams back that long can
|
|
// send its recorded poses of the session again (no secret needed), and they are taken: only the puppet moves. Someone
|
|
// with the room's secret can seal a POS in a member's name with a counter far ahead: it becomes the newest pose, so the
|
|
// puppet stands where it says (or is hidden, if it names another area) and the member's own poses are kept out until
|
|
// nothing was taken from the sender for COOP_POS_QUIET_MS; then the next pose is taken whatever its counter and starts
|
|
// the counter again. One forged pose every COOP_POS_QUIET_MS keeps the member's own out while the forger goes on.
|
|
// session: the one the roster lists for the member (CoopView). Returns 0 to drop the pose, 1 to take it, 2 to take it
|
|
// and drop what was kept of the sender's earlier poses.
|
|
#define COOP_POS_QUIET_MS 3000
|
|
typedef struct {
|
|
uint64_t session, at_ms; // the session of the last pose taken, and when it was taken
|
|
uint32_t last; // its counter
|
|
int any; // a pose was taken
|
|
} CoopPosSeen;
|
|
int coop_pos_fresh(CoopPosSeen *s, uint64_t session, uint32_t pseq, uint64_t now_ms);
|