netcode 1.4.5: the connect token lifecycle, and the fixes around it (#184)

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

A connect token history entry now carries a state. It is created pending when the server
accepts a connection request for a connect token it has not seen, admits retransmitted
requests from that same address while the handshake runs, and becomes consumed when the
client is installed in a client slot. A consumed entry admits nothing, whatever the source
address, 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 tokens refuses a
new connect token instead of evicting one. 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 without anything new on the wire.

The server refuses any connect token that could have been issued before it started:
max_connect_token_lifetime in the server config is the longest lifetime the backend issues,
and a connection request whose connect token expire timestamp minus that lifetime is earlier
than the server start time is ignored, alongside the existing expiry check and before the
decrypt. The field defaults to NETCODE_DEFAULT_MAX_CONNECT_TOKEN_LIFETIME, and the examples
and harnesses set it to the lifetime they issue.

Also in this release:

- Key material is erased with sodium_memzero rather than memset: 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 its configured private key on destroy.
- IPv4 addresses are converted through ntohl and htonl and IPv6 halves through memcpy, so
  address conversion is correct on big endian machines, and CI proves it on s390x under QEMU.
- netcode_packet_queue_clear pops until the queue is empty rather than freeing the first
  num_packets slots, so a partially drained queue is cleared correctly. The drain loops its
  two callers ran first are gone.
- The soak harness formats addresses with snprintf.
- The default static install is self contained: the vendored sodium objects are compiled into
  libnetcode, and the install carries an exported CMake package that consumers find with
  find_package(netcode CONFIG) and link as netcode::netcode. The system libsodium build
  exports its libsodium instead. CI links a program against both from a clean prefix.
- Shared library builds are refused on Windows, where netcode.h declares no export macro.

Tests: test_connect_token_entries covers the pending and consumed rules, the unrefreshed
entry time, the full history refusal and reuse after expiry; a client and server wired
directly through the send and receive overrides drive
test_client_server_connection_request_retransmission, which drops the first server packets so
the client retransmits its connection request, test_client_server_replay_across_sessions,
which replays a first-session datagram into a second session, and
test_client_reconnect_with_used_connect_token and
test_client_error_connect_token_predates_server_start, which pin the two refusals. Building
the test runner with -DNETCODE_NONCE_AUDIT=ON records the key and nonce of every packet the
suite encrypts and fails on a repeat; it is a CI leg.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* The test wire drops packets once either end is being destroyed

netcode_server_destroy and netcode_client_destroy each send disconnect packets on the way
out, and the wire handed them straight to the other end, which the first destroy had already
freed. The wire is down once teardown starts, which is what an application shutting down
finds too.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* The connect token entry fields say what they are

The entry time is created-at, not last-seen, and the expire timestamp is the connect token's,
which is what bounds the entry's life. Both read as ordinary bookkeeping without that.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: gafferongames

.github/workflows/ci.yml

@@ -83,6 +83,99 @@ jobs:
           test -f stage/lib/libnetcode.so || test -L stage/lib/libnetcode.so
           echo "install layout ok"
 
+  # the installed library is what a package manager ships, so CI links a program against it
+  # from a clean prefix: the default vendored build carries its own crypto into libnetcode,
+  # and the system libsodium build exports the libsodium it found.
+  consumer:
+    name: consumer (${{ matrix.name }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: vendored sodium
+            options: ""
+            system_sodium: false
+          - name: system sodium
+            options: "-DNETCODE_SYSTEM_SODIUM=ON"
+            system_sodium: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install libsodium
+        if: matrix.system_sodium
+        run: sudo apt-get update && sudo apt-get install -y libsodium-dev
+
+      - name: Configure
+        run: cmake -B build -DCMAKE_BUILD_TYPE=Release -DNETCODE_BUILD_TESTS=OFF ${{ matrix.options }}
+
+      - name: Build
+        run: cmake --build build --parallel
+
+      - name: Install to a clean prefix
+        run: cmake --install build --prefix "${{ github.workspace }}/prefix"
+
+      - name: Build and run the consumer
+        run: |
+          cmake -S tools/consumer -B consumer-build -DCMAKE_PREFIX_PATH="${{ github.workspace }}/prefix"
+          cmake --build consumer-build --parallel
+          ./consumer-build/consumer
+
+  # the only big endian coverage in the matrix: the address conversions read and write
+  # network byte order for real here, where host order is not a synonym for it
+  big-endian:
+    name: big endian s390x / ${{ matrix.config }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        config: [ Debug, Release ]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install s390x cross toolchain and qemu
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-s390x-linux-gnu g++-s390x-linux-gnu qemu-user-static
+
+      # static linking so the emulated binaries need no s390x sysroot at runtime
+      - name: Configure
+        run: >
+          cmake -B build
+          -DCMAKE_BUILD_TYPE=${{ matrix.config }}
+          -DCMAKE_SYSTEM_NAME=Linux
+          -DCMAKE_SYSTEM_PROCESSOR=s390x
+          -DCMAKE_C_COMPILER=s390x-linux-gnu-gcc
+          -DCMAKE_CXX_COMPILER=s390x-linux-gnu-g++
+          -DCMAKE_C_FLAGS="-static"
+          -DCMAKE_CXX_FLAGS="-static"
+          -DCMAKE_CROSSCOMPILING_EMULATOR=qemu-s390x-static
+
+      - name: Build
+        run: cmake --build build --parallel
+
+      - name: Test
+        run: ctest --test-dir build --output-on-failure --timeout 600
+
+  # every packet the suite encrypts is recorded by key and nonce, and a repeat fails the run
+  nonce-audit:
+    name: nonce audit
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure
+        run: cmake -B build -DCMAKE_BUILD_TYPE=Release -DNETCODE_NONCE_AUDIT=ON
+
+      - name: Build
+        run: cmake --build build --parallel
+
+      - name: Test
+        run: ctest --test-dir build --output-on-failure --timeout 600
+
   sanitizers:
     name: sanitizers (asan+ubsan)
     runs-on: ubuntu-24.04

BUILDING.md

@@ -35,8 +35,15 @@ By default netcode builds as a static library against the vendored libsodium sub
     cmake --install build --prefix /some/prefix
 
 - `NETCODE_SYSTEM_SODIUM=ON` links the system libsodium instead of the vendored copy (they are interchangeable — the vendored subset is a byte-identical slice of upstream).
-- `BUILD_SHARED_LIBS=ON` builds `libnetcode` as a shared library.
-- `cmake --install` installs `netcode.h` and the library (`NETCODE_INSTALL=OFF` disables the install target, e.g. when embedding netcode as a subproject).
+- `BUILD_SHARED_LIBS=ON` builds `libnetcode` as a shared library. Shared builds are not supported on Windows: `netcode.h` declares no export macro, so a DLL built from these sources exports nothing, and CMake refuses the combination. On Windows link the static library or compile `netcode.c` into your application.
+- `cmake --install` installs `netcode.h`, the library, and a CMake package. In the default vendored build the sodium objects are compiled into `libnetcode`, so the installed library is self contained; the system libsodium build exports the libsodium it found instead.
+
+A consumer picks the installed library up with:
+
+    find_package(netcode CONFIG REQUIRED)
+    target_link_libraries(your_app PRIVATE netcode::netcode)
+
+pointing CMake at the install prefix with `-DCMAKE_PREFIX_PATH=/some/prefix`. `NETCODE_INSTALL=OFF` disables the install target, e.g. when embedding netcode as a subproject.
 
 ## Floating point: netcode builds with -ffp-contract=off
 
@@ -65,6 +72,8 @@ To build everything with AddressSanitizer and UndefinedBehaviorSanitizer, config
 
 Fuzz harnesses for the untrusted-input surface live in `fuzz/` and are built with `-DNETCODE_FUZZ=ON`. See [fuzz/README.md](fuzz/README.md) for details.
 
+`-DNETCODE_NONCE_AUDIT=ON` builds the test runner with the key and nonce of every packet it encrypts recorded, and adds a test that fails if any pair repeats. It is a test-only option: nothing it adds is compiled into the library.
+
 ## Building on Windows
 
 You need Visual Studio to build the source code. If you don't have Visual Studio you can [download the community edition for free](https://visualstudio.microsoft.com/downloads/).

CLAUDE.md

@@ -27,6 +27,14 @@ DECISIONS THAT READ AS BUGS (they are not — do not "fix" them)
   BOTH start and stop. Nonce-space separation: pre-connection and per-client packets share
   a key, so their nonces must not collide. Seeding on create only was the AEAD nonce-reuse
   bug fixed in 1.4.0. Keep every seeding site.
+- **A connect token is single use.** Its history entry is created pending on the first
+  connection request, admits retransmitted requests from that same address while the
+  handshake runs, and becomes consumed when the client is installed in a slot. A consumed
+  entry admits nothing, whatever the address, so the keys inside a connect token encrypt
+  exactly one session. Entries live until their token expires and a full history refuses new
+  tokens rather than evicting one. The server also refuses any connect token that could have
+  been issued before it started, using `max_connect_token_lifetime` in the server config.
+  STANDARD.md's *Connect Token History* and *Nonce Reuse and Server Restarts* are the contract.
 - **Replay protection advances the window only AFTER authentication** (netcode.c:1863,
   1907). The cheap pre-decrypt reject is an optimisation; moving the window advance before
   auth would let spoofed plaintext sequence numbers poison it.
@@ -90,16 +98,23 @@ independent implementations (C#, Go, Rust, TypeScript).
 - `sodium/` — vendored subset of libsodium, amalgamated into a single `sodium.h` +
   `sodium.c` pair (see `sodium/NOTES.md` for how it is generated and validated).
 - Build: CMake. `cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel`,
-  then `ctest --test-dir build --output-on-failure` runs the suite (42 tests). The
+  then `ctest --test-dir build --output-on-failure` runs the suite (51 tests). The
   `netcode_test` target compiles netcode.c into itself with `NETCODE_ENABLE_TESTS`, so it
   links only sodium. `-DNETCODE_SANITIZE=ON` adds ASan+UBSan (sodium gets ASan only);
   `-DNETCODE_FUZZ=ON` builds the `fuzz/` harnesses (libFuzzer where available, else a
-  standalone file replayer). For packaging: `-DNETCODE_SYSTEM_SODIUM=ON` links the
-  system libsodium instead of the vendored copy, `-DBUILD_SHARED_LIBS=ON` builds
-  libnetcode shared, and `cmake --install` installs netcode.h + the library
-  (this is the homebrew configuration, covered by a CI leg). CI (`.github/workflows/ci.yml`) builds and tests Debug +
+  standalone file replayer); `-DNETCODE_NONCE_AUDIT=ON` records the key and nonce of every
+  packet the tests encrypt and fails the run on a repeat (test-only, nothing enters the
+  library). For packaging: `-DNETCODE_SYSTEM_SODIUM=ON` links the system libsodium instead
+  of the vendored copy, `-DBUILD_SHARED_LIBS=ON` builds libnetcode shared everywhere except
+  Windows, where CMake refuses it because netcode.h declares no export macro, and
+  `cmake --install` installs netcode.h, the library and a CMake package consumers find with
+  `find_package(netcode CONFIG)` and link as `netcode::netcode` (the vendored build folds the
+  sodium objects into libnetcode, so the installed static library is self contained; the
+  system-sodium build, the homebrew configuration, exports its libsodium instead).
+  CI (`.github/workflows/ci.yml`) builds and tests Debug +
   Release on Linux x64, Linux arm64, macOS Apple Silicon, and Windows x64 (MSVC + a
-  MinGW leg), plus a Linux ASan+UBSan leg and a bounded smoke-fuzz leg. A separate
+  MinGW leg), plus a Linux ASan+UBSan leg, a bounded smoke-fuzz leg, a big endian s390x leg
+  under QEMU, a clean-prefix consumer leg for both install shapes, and the nonce audit leg. A separate
   nightly workflow (`.github/workflows/scheduled.yml`) runs deep fuzzing with an
   accumulating cached corpus, a 15-minute ASan soak, and a libsodium-upstream-release
   check that opens a tracking issue when the vendored version falls behind.

CMakeLists.txt

@@ -11,7 +11,7 @@ if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
     set(CMAKE_TARGET_MESSAGES OFF)
 endif()
 
-project(netcode VERSION 1.4.4 LANGUAGES C CXX)
+project(netcode VERSION 1.4.5 LANGUAGES C CXX)
 
 set(CMAKE_C_STANDARD 99)
 set(CMAKE_C_STANDARD_REQUIRED ON)
@@ -69,6 +69,17 @@ option(NETCODE_FUZZ "Build the fuzz targets" OFF)
 option(NETCODE_BUILD_TESTS "Build netcode tests and examples" ${NETCODE_TOP_LEVEL})
 option(NETCODE_SYSTEM_SODIUM "Link against the system libsodium instead of the vendored copy" OFF)
 option(NETCODE_INSTALL "Generate the install target (netcode.h and the netcode library)" ON)
+option(NETCODE_NONCE_AUDIT "Record the key and nonce of every packet the tests encrypt and fail on a repeat" OFF)
+
+# netcode.h declares no export macro, so a Windows DLL built from these sources exports
+# nothing and every consumer fails to link. Static is the supported shape on Windows: link
+# the static library, or compile netcode.c straight into your application.
+
+if(BUILD_SHARED_LIBS AND WIN32)
+    message(FATAL_ERROR "netcode does not support shared library builds on Windows. Build the static library (the default), or compile netcode.c into your application.")
+endif()
+
+include(GNUInstallDirs)
 
 # sanitizers apply to the whole build. the vendored crypto is exempted from UBSan
 # below (third-party SIMD code uses intentional type punning / unaligned access that
@@ -102,7 +113,7 @@ else()
     # vendored libsodium subset, amalgamated into a single header + source pair.
     # see sodium/NOTES.md for how it is generated and validated.
 
-    add_library(sodium STATIC sodium/sodium.c sodium/sodium.h)
+    add_library(sodium OBJECT sodium/sodium.c sodium/sodium.h)
     target_include_directories(sodium PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/sodium)
     set_target_properties(sodium PROPERTIES POSITION_INDEPENDENT_CODE ON)
     if(NOT MSVC)
@@ -120,13 +131,28 @@ else()
 
 endif()
 
-# the netcode library. static by default; -DBUILD_SHARED_LIBS=ON builds it shared
-# (the vendored sodium objects are position independent, so they fold in either way)
+# the netcode library. static by default; -DBUILD_SHARED_LIBS=ON builds it shared on the
+# platforms that support it (the vendored sodium objects are position independent, so they
+# fold in either way).
+#
+# in the default vendored build the sodium objects are compiled into libnetcode itself, so
+# the installed library is self contained: a consumer links netcode and nothing else. the
+# system-sodium build exports the libsodium it found instead, because that libsodium is the
+# package manager's to supply and update.
 
-add_library(netcode netcode.c netcode.h)
-target_include_directories(netcode PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
+if(NETCODE_SYSTEM_SODIUM)
+    add_library(netcode netcode.c netcode.h)
+    target_include_directories(netcode PRIVATE ${NETCODE_SODIUM_INCLUDE_DIR})
+    target_link_libraries(netcode PUBLIC ${NETCODE_SODIUM_LIBRARY})
+else()
+    add_library(netcode netcode.c netcode.h $<TARGET_OBJECTS:sodium>)
+    target_include_directories(netcode PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/sodium)
+endif()
+
+target_include_directories(netcode PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
 target_compile_options(netcode PRIVATE ${NETCODE_WARNINGS})
-target_link_libraries(netcode PUBLIC sodium)
 set_target_properties(netcode PROPERTIES
     VERSION ${PROJECT_VERSION}
     SOVERSION ${PROJECT_VERSION_MAJOR})
@@ -135,12 +161,31 @@ if(WIN32)
 endif()
 
 if(NETCODE_INSTALL)
-    include(GNUInstallDirs)
-    install(TARGETS netcode
+    include(CMakePackageConfigHelpers)
+
+    install(TARGETS netcode EXPORT netcodeTargets
             LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
             ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
-            RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+            RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+            INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
     install(FILES netcode.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+
+    install(EXPORT netcodeTargets
+            FILE netcodeTargets.cmake
+            NAMESPACE netcode::
+            DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/netcode)
+
+    configure_package_config_file(cmake/netcodeConfig.cmake.in
+                                  ${CMAKE_CURRENT_BINARY_DIR}/netcodeConfig.cmake
+                                  INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/netcode)
+
+    write_basic_package_version_file(${CMAKE_CURRENT_BINARY_DIR}/netcodeConfigVersion.cmake
+                                     VERSION ${PROJECT_VERSION}
+                                     COMPATIBILITY SameMajorVersion)
+
+    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/netcodeConfig.cmake
+                  ${CMAKE_CURRENT_BINARY_DIR}/netcodeConfigVersion.cmake
+            DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/netcode)
 endif()
 
 if(NETCODE_BUILD_TESTS)
@@ -166,6 +211,9 @@ if(NETCODE_BUILD_TESTS)
     if(WIN32)
         target_link_libraries(netcode_test PRIVATE ws2_32 iphlpapi)
     endif()
+    if(NETCODE_NONCE_AUDIT)
+        target_compile_definitions(netcode_test PRIVATE NETCODE_ENABLE_NONCE_AUDIT=1)
+    endif()
 
     add_test(NAME netcode_test COMMAND netcode_test)
 

README.md

@@ -46,6 +46,7 @@ char * server_address = "127.0.0.1:40000";
 
 struct netcode_server_config_t server_config;
 netcode_default_server_config( &server_config );
+server_config.max_connect_token_lifetime = 30;
 memcpy( &server_config.private_key, private_key, NETCODE_KEY_BYTES );
 
 struct netcode_server_t * server = netcode_server_create( server_address, &server_config, time );
@@ -56,6 +57,8 @@ if ( !server )
 }
 ```
 
+`max_connect_token_lifetime` is the longest lifetime in seconds your backend issues connect tokens with. The server refuses any connect token that could have been issued before it started, and this is how it knows which those are, so set it to the lifetime your backend uses.
+
 Then start the server with the number of client slots you want:
 
 ```c

client_server.c

@@ -77,6 +77,7 @@ int main( int argc, char ** argv )
     struct netcode_server_config_t server_config;
     netcode_default_server_config( &server_config );
     server_config.protocol_id = PROTOCOL_ID;
+    server_config.max_connect_token_lifetime = CONNECT_TOKEN_EXPIRY;
     memcpy( &server_config.private_key, private_key, NETCODE_KEY_BYTES );
 
     char * server_address = "[::1]:40000";

cmake/netcodeConfig.cmake.in

@@ -0,0 +1,5 @@
+@PACKAGE_INIT@
+
+include("${CMAKE_CURRENT_LIST_DIR}/netcodeTargets.cmake")
+
+check_required_components(netcode)

fuzz/fuzz_read_packet.c

@@ -46,6 +46,7 @@ static void * fuzz_call_read_packet( uint8_t * buffer, int buffer_length, uint64
                                 packet_key,
                                 FUZZ_PROTOCOL_ID,
                                 0,                      // current timestamp: zero so fuzz-chosen expire timestamps pass
+                                0,                      // minimum expire timestamp: zero so no connect token is refused for predating the server start
                                 private_key,
                                 allowed_packets,
                                 replay_protection,