netcode 1.4.5: the connect token lifecycle, and the fixes around it

[gafferongames]

The implementation of the rules the STANDARD.md PR states (#183), plus the build, portability and hygiene fixes that ride with the release. Version 1.4.5 in netcode.h and CMake.

Nothing on the wire moves.

The connect token lifecycle

A connect token history entry carries a state:

• pending on the first connection request presenting a connect token the server has not seen. A pending entry admits a retransmitted connection request from that same address, so a handshake that loses a packet still completes, and refuses every other address.
• consumed when the server accepts the connection response and installs the client in a slot. A consumed entry admits nothing, whatever the source address and whether or not the client is still in its slot, so the keys inside a connect token encrypt exactly one session.

Entries live until their connect token expires, and a history whose entries all hold unexpired connect tokens refuses a new connect token instead of evicting one, so a flood of connect tokens cannot reopen a token that has been used. An entry's time is set at creation and never refreshed.

The encryption mapping carries the index of the history entry its handshake belongs to, so installing a client consumes the right entry with nothing extra on the wire.

The restart rule

max_connect_token_lifetime in the server config is the longest lifetime the backend issues connect tokens with. The server ignores any connection request whose connect token expire timestamp minus that lifetime is earlier than the time it started, next to the existing expiry check and before the decrypt. The field defaults to NETCODE_DEFAULT_MAX_CONNECT_TOKEN_LIFETIME (30 seconds, the lifetime the examples issue), a zero or negative value takes that default, and the examples and harnesses set it to the lifetime they actually issue.

Also in this release

• Key erasure. sodium_memzero rather than memset for the encryption manager's keys on reset and on removal, the client's connect token and context, the server's challenge key on stop, and the private key in the server config at destroy.
• Byte order. IPv4 addresses convert through ntohl and htonl, IPv6 halves through memcpy instead of a uint16_t pointer cast. A big endian s390x job under QEMU runs the suite in Debug and Release.
• netcode_packet_queue_clear pops until the queue is empty instead of freeing the first num_packets slots, which frees the wrong pointers once start_index has moved. The drain loops its two callers ran beforehand are gone, and netcode_client_destroy is covered as a caller.
• snprintf in the soak harness.
• The install. The default static install is self contained: the vendored sodium objects are compiled into libnetcode, and the install carries an exported CMake package. A consumer writes find_package(netcode CONFIG REQUIRED) and links netcode::netcode. The system libsodium build exports the libsodium it found instead. A CI job installs both to a clean prefix and links a program that calls netcode_init against them.
• Shared builds on Windows are refused by CMake and documented as unsupported: netcode.h declares no export macro, so a DLL built from these sources exports nothing.

Tests

• test_connect_token_entries — the pending and consumed acceptance rules, the entry time that is never refreshed, the full history refusal, and reuse of an entry once its connect token has expired.
• test_client_server_connection_request_retransmission — a client and server wired directly to each other through the send and receive overrides, with the first three packets the server sends dropped, so the client retransmits its connection request into a handshake the server already holds a pending entry for, and still connects.
• test_client_server_replay_across_sessions — a payload datagram captured from a first session is replayed into a second one and delivers nothing.
• test_client_reconnect_with_used_connect_token — presenting a spent connect token again, from the address that used it, connects nothing.
• test_client_error_connect_token_predates_server_start — a connect token that expires earlier than any the backend could have issued after the start is refused, and one with the full lifetime connects.
• -DNETCODE_NONCE_AUDIT=ON builds the test runner with the key and nonce of every packet it encrypts recorded, and test_nonce_audit fails the run if any pair repeats. 3716 pairs, zero repeats. It is a test-only build option and a CI leg; nothing it adds is compiled into the library.

Each test was run against a build with the rule it covers reverted, and each goes red:

test	reverted	result
test_connect_token_entries	consumed entries admit their old address	check failed: ... == NETCODE_CONNECT_TOKEN_ENTRY_REFUSED
test_connect_token_entries	the full history evicts the oldest entry	check failed: ... == NETCODE_CONNECT_TOKEN_HISTORY_FULL
test_client_server_connection_request_retransmission	entries are created consumed, so a pending entry admits nothing	check failed: ... == NETCODE_CLIENT_STATE_CONNECTED
test_client_server_replay_across_sessions	the second session reuses the first connect token	check failed: netcode_server_receive_packet( ... ) == NULL
test_client_reconnect_with_used_connect_token	consumed entries admit their old address	check failed: ... == NETCODE_CLIENT_STATE_CONNECTION_REQUEST_TIMED_OUT
test_client_error_connect_token_predates_server_start	the minimum expire timestamp check	check failed: ... == NETCODE_CLIENT_STATE_CONNECTION_REQUEST_TIMED_OUT
test_nonce_audit	consumed entries admit their old address, second session on the used token	13 repeated key and nonce pairs, check failed: netcode_nonce_audit_repeats() == 0

Built and tested Debug and Release locally, and both install shapes were installed to a clean prefix and linked by the consumer program.

🤖 Generated with Claude Code