Select and pin the M10.2 QUIC transport (msquic with OpenSSL)
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 2m28s
Foundation / checks (network) (push) Successful in 8m16s
Foundation / checks (client) (push) Successful in 12m14s
Foundation / checks (tsan) (push) Successful in 7m50s
Foundation / checks (checks) (push) Successful in 31m45s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 25m13s

ADR-0090 records the maintainer's selection of msquic 2.6.2 with OpenSSL 3.5.9 LTS
built from pinned, checksum-verified sources on Windows and Linux (plus the
xdp-for-windows headers msquic needs on Windows), the trust, threading and
channel model, and the known gap that OpenSSL's verifier also trusts its default
paths. Adds the opt-in quic preset, explicit preparation, and a loopback smoke
test (datagram, stream, untrusted CA and wrong name refused) passing on MSVC and
GCC. windows-check picks up newly installed Perl/NASM and pins cl.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-03 15:07:16 -04:00
co-authored by Claude Opus 5.5
parent 819137c1df
commit 3c421cd0cf
15 changed files with 604 additions and 4 deletions
+16
View File
@@ -28,6 +28,7 @@ option(EVO_BUILD_UI_PROBE "Build the isolated M9.8a Dear ImGui compatibility pro
option(EVO_BUILD_CLIENT_PROBE "Build the isolated M9.1 SDL dependency probe" OFF)
option(EVO_BUILD_CLIENT "Build the native M9 engineering client" OFF)
option(EVO_BUILD_NETWORK "Build the M9.6 dev session protocol and TLS adapter (explicit Mbed TLS preparation required)" OFF)
option(EVO_BUILD_QUIC "Build the M10.2 msquic transport (explicit msquic preparation required)" OFF)
# M9.8e Windows package (ADR-0086): identity printed by `evo-client --version`, set by
# tools/client/package-windows.ps1; deterministic MSVC objects/binaries for packaging.
set(EVO_BUILD_IDENTITY "unpackaged" CACHE STRING "evo-client build identity")
@@ -132,6 +133,21 @@ endif()
if(EVO_BUILD_NETWORK)
include(cmake/Network.cmake)
endif()
if(EVO_BUILD_QUIC)
# M10.2 (ADR-0090). Tests reuse the dev credential generator from the network build.
if(NOT EVO_BUILD_NETWORK)
message(FATAL_ERROR "EVO_BUILD_QUIC requires EVO_BUILD_NETWORK")
endif()
include(cmake/Quic.cmake)
if(BUILD_TESTING)
add_executable(evo-quic-smoke-tests tests/quic_smoke.cpp)
target_link_libraries(evo-quic-smoke-tests PRIVATE evo_msquic evo_network_tls)
evo_owned_target(evo-quic-smoke-tests)
evo_msquic_runtime(evo-quic-smoke-tests)
add_test(NAME quic-smoke COMMAND evo-quic-smoke-tests)
set_tests_properties(quic-smoke PROPERTIES TIMEOUT 60 LABELS "quic")
endif()
endif()
if(EVO_BUILD_CLIENT_PROBE OR EVO_BUILD_CLIENT OR EVO_BUILD_UI_PROBE)
include(cmake/ClientProbe.cmake)
endif()
+3
View File
@@ -12,6 +12,7 @@
{"name": "client-probe", "inherits": "release", "cacheVariables": {"EVO_BUILD_CLIENT_PROBE": "ON"}},
{"name": "network", "inherits": "release", "cacheVariables": {"EVO_BUILD_NETWORK": "ON"}},
{"name": "client-network", "inherits": "release", "cacheVariables": {"EVO_BUILD_CLIENT": "ON", "EVO_BUILD_NETWORK": "ON"}},
{"name": "quic", "inherits": "network", "cacheVariables": {"EVO_BUILD_QUIC": "ON"}},
{"name": "client-package", "inherits": "client-network", "cacheVariables": {"CMAKE_MSVC_RUNTIME_LIBRARY": "MultiThreaded", "EVO_REPRODUCIBLE": "ON"}}
],
"buildPresets": [
@@ -23,6 +24,7 @@
{"name": "client", "configurePreset": "client", "targets": ["evo-client-state-tests", "evo-client", "evo-client-lifecycle-tests", "evo-client-environment-tests", "evo-client-organism-tests", "evo-client-ui-model-tests", "evo-client-panel-tests", "evo-client-bindings-tests"]},
{"name": "client-probe", "configurePreset": "client-probe", "targets": ["evo-client-probe"]},
{"name": "network", "configurePreset": "network", "targets": ["evo-client-state-tests", "evo-network-tests", "evo-dev-session"]},
{"name": "quic", "configurePreset": "quic", "targets": ["evo-quic-smoke-tests", "evo-network-tests"]},
{"name": "client-network", "configurePreset": "client-network", "targets": ["evo-client-state-tests", "evo-client", "evo-client-lifecycle-tests", "evo-client-environment-tests", "evo-client-organism-tests", "evo-client-ui-model-tests", "evo-client-panel-tests", "evo-client-bindings-tests", "evo-network-tests", "evo-dev-session"]},
{"name": "client-package", "configurePreset": "client-package", "targets": ["evo-client-state-tests", "evo-client", "evo-client-lifecycle-tests", "evo-client-environment-tests", "evo-client-organism-tests", "evo-client-ui-model-tests", "evo-client-panel-tests", "evo-client-bindings-tests", "evo-network-tests", "evo-dev-session"]}
],
@@ -35,6 +37,7 @@
{"name": "client", "configurePreset": "client", "filter": {"include": {"label": "client"}}, "output": {"outputOnFailure": true}},
{"name": "client-probe", "configurePreset": "client-probe", "filter": {"include": {"label": "client"}}, "output": {"outputOnFailure": true}},
{"name": "network", "configurePreset": "network", "filter": {"include": {"label": "network"}}, "output": {"outputOnFailure": true}},
{"name": "quic", "configurePreset": "quic", "filter": {"include": {"label": "quic|network"}}, "output": {"outputOnFailure": true}},
{"name": "client-network", "configurePreset": "client-network", "filter": {"include": {"label": "client|network"}}, "output": {"outputOnFailure": true}},
{"name": "client-package", "configurePreset": "client-package", "filter": {"include": {"label": "client|network"}}, "output": {"outputOnFailure": true}}
]
+5
View File
@@ -212,3 +212,8 @@ low-spec qualification work.
M9.8e Windows x64 tester ZIP (static runtime, notices, identity, checksums; ADR-0086):
`tools\client\package-windows.ps1`, then `tools\client\verify-windows-package.ps1
-Zip build\packages\<name>.zip`. See [CLIENT_PACKAGING](docs/engineering/CLIENT_PACKAGING.md).
M10.2 QUIC transport (ADR-0090, opt-in): `cmake -P tools/prepare-mbedtls.cmake`,
`cmake -P tools/prepare-msquic.cmake`, then preset `quic`
(`cmake --preset quic && cmake --build --preset quic && ctest --preset quic`). Windows
needs Strawberry Perl and NASM for the OpenSSL build; use `tools/windows-check.ps1 -Preset quic`.
+55
View File
@@ -0,0 +1,55 @@
# M10.2 QUIC transport (ADR-0090): pinned msquic 2.6.2 with its OpenSSL TLS provider
# (OpenSSL 3.5.9 LTS, TLS 1.3 only, built static inside the msquic shared library).
# Explicit preparation only: cmake -P tools/prepare-msquic.cmake. Windows builds need a
# native Perl (Strawberry Perl) and NASM for OpenSSL, plus nmake from the MSVC shell.
include_guard(GLOBAL)
include("${PROJECT_SOURCE_DIR}/tools/msquic-pin.cmake")
set(msquic_source "${PROJECT_SOURCE_DIR}/build/external/msquic/msquic-${EVO_MSQUIC_VERSION}")
if(NOT EXISTS "${msquic_source}/evo-verified.sha256")
message(FATAL_ERROR "Prepare msquic explicitly: cmake -P tools/prepare-msquic.cmake")
endif()
file(STRINGS "${msquic_source}/evo-verified.sha256" verified_msquic)
if(NOT verified_msquic STREQUAL "${EVO_MSQUIC_SHA256} ${EVO_OPENSSL_SHA256} ${EVO_XDP_SHA256}")
message(FATAL_ERROR "Prepared msquic/OpenSSL do not match the reviewed pins")
endif()
if(WIN32)
find_program(EVO_NATIVE_PERL perl)
find_program(EVO_NASM nasm)
if(NOT EVO_NATIVE_PERL OR NOT EVO_NASM)
message(FATAL_ERROR "msquic's OpenSSL build needs a native Perl (Strawberry Perl) and NASM on PATH")
endif()
endif()
enable_language(C)
foreach(setting IN ITEMS "QUIC_TLS_LIB=openssl" "QUIC_BUILD_SHARED=ON" "QUIC_BUILD_TEST=OFF"
"QUIC_BUILD_TOOLS=OFF" "QUIC_BUILD_PERF=OFF" "QUIC_ENABLE_LOGGING=OFF" "QUIC_EMBED_GIT_HASH=OFF"
"QUIC_SOURCE_LINK=OFF" "QUIC_USE_EXTERNAL_OPENSSL=OFF" "QUIC_CODE_CHECK=OFF")
string(REPLACE "=" ";" pair "${setting}")
list(GET pair 0 name)
list(GET pair 1 value)
set(${name} "${value}" CACHE STRING "Pinned by AEvolution (ADR-0090)" FORCE)
endforeach()
add_subdirectory("${msquic_source}" "${PROJECT_BINARY_DIR}/msquic" EXCLUDE_FROM_ALL SYSTEM)
# Upstream compiles itself with warnings as errors (and MSVC /analyze). As for Mbed TLS,
# compiler-version-specific diagnostics must not fail unmodified upstream sources
# (MSVC 19.44 /analyze reports C28020 in crypto_tls.c); owned code keeps its policy.
if(MSVC)
target_compile_options(warnings INTERFACE /WX-)
else()
target_compile_options(warnings INTERFACE -Wno-error)
endif()
# Consumer target: the public C API header and the shared library.
add_library(evo_msquic INTERFACE)
target_include_directories(evo_msquic SYSTEM INTERFACE "${msquic_source}/src/inc")
target_link_libraries(evo_msquic INTERFACE msquic)
if(WIN32)
# msquic.h's inline address helpers (QuicAddrFromString) call Rtl* functions in ntdll.
target_link_libraries(evo_msquic INTERFACE ntdll)
endif()
# The shared library must sit next to Windows executables that load it.
function(evo_msquic_runtime target)
if(WIN32)
add_custom_command(TARGET ${target} POST_BUILD
COMMAND "${CMAKE_COMMAND}" -E copy_if_different "$<TARGET_FILE:msquic>" "$<TARGET_FILE_DIR:${target}>"
VERBATIM)
endif()
endfunction()
+3 -1
View File
@@ -516,7 +516,9 @@ bounded replication and recovery under loss, overload and region transfer.
**Status (2026-10-03):** 10.1 ratified (ADR-0089, schemas/network/m10-budgets-v1.md,
networking/M10_TIMING_TRACES.md); targets are not yet qualified on the reference
hardware (10.9). 10.2-10.9 planned.
hardware (10.9). 10.2 split: 10.2a selection, pins and build of msquic/OpenSSL done
(ADR-0090); 10.2b bounded channels, exact CA pinning and the impairment relay, and 10.2c
loss/head-of-line measurements follow. 10.3-10.9 planned.
**Entry:** M9 client/session evidence and M7/M8 dev/stage durability. Read
NETWORK_ARCHITECTURE, PERSISTENCE_ARCHITECTURE and ADR-0017. The M9 transport is
+3 -1
View File
@@ -9,7 +9,9 @@ budgets on one RKE2 worker and client budgets on the low-spec VM. Development-re
traces (`evo-dev-session trace`, networking/M10_TIMING_TRACES.md) measured admission
p99 <= 5.2 ms, durable p95 about 1.4 s and 50 ms view cadence. Finding: genome v1 and
metabolism use per-tick rates, so the quantum fixes biological rates until M11.1
converts or ratifies them. Next: M10.2 transport selection against these budgets.
converts or ratifies them. M10.2a selects QUIC with msquic 2.6.2 and OpenSSL 3.5.9 LTS
(ADR-0090), pinned and building on Windows and Linux with a loopback smoke test. Next:
M10.2b bounded channels, exact CA pinning and the owned impairment relay.
## Previous gate - 2026-10-02
+94
View File
@@ -0,0 +1,94 @@
# ADR-0090: M10 transport — QUIC with msquic and OpenSSL
## Status
Accepted for M10.2 (2026-10-03). The selection, pins and build integration (10.2a) are
decided here; bounded channels with the impairment relay (10.2b) and loss/head-of-line
measurements (10.2c) implement and test it and may amend the channel parameters.
Resolves the transport half of ADR-0017; its no-custom-cryptography rule stands.
## Context
ADR-0089 fixes the budgets the transport must meet: 1,200-byte realtime payloads,
superseding state separate from reliable actions, 1 s heartbeat, 5 s liveness and
handshake, bounded queues. The M9 dev session is TLS 1.3 over TCP (ADR-0082), where one
lost segment delays everything behind it.
Candidates surveyed 2026-10-03 (GitHub releases and licences):
| Candidate | Latest release | Licence | Fit |
|---|---|---|---|
| msquic (Microsoft) | v2.6.2, 2026-09-30 (v2.6.1 2026-08-28) | MIT | Complete QUIC: TLS 1.3, streams, RFC 9221 DATAGRAM, congestion control, PMTUD, own threads; C API; Windows and Linux |
| ngtcp2 | v1.25.0, 2026-07-26 | MIT | Protocol library; we own UDP I/O, timers, loop and a crypto backend |
| picoquic | date-tagged builds (2026-10-01) | MIT | Research-oriented, picotls |
| lsquic | v4.10.0, 2026-09-20 | MIT | Requires BoringSSL |
| quiche | 0.30.0, 2026-09-17 | BSD-2-Clause | Rust toolchain dependency |
| GameNetworkingSockets | v1.6.1, 2026-10-03 | BSD-3-Clause | Game messages and fragmentation; its own non-TLS encryption and certificates |
| Mbed TLS DTLS + owned reliability | 4.2.0 / 4.1.1 | Apache-2.0 option | DTLS 1.2 only here; we would own reliability, fragmentation and congestion |
| wolfSSL | v5.9.4 | GPL-3.0 | Excluded by licence |
## Decision (maintainer, 2026-10-03)
- **msquic 2.6.2** (commit 819ab74f, MIT) with its **OpenSSL TLS provider on Windows
and Linux**, **OpenSSL 3.5.9 LTS** (Apache-2.0), both from pinned, checksum-verified
release archives (`tools/msquic-pin.cmake`, `tools/prepare-msquic.cmake`). msquic's
OpenSSL submodule points at an untagged openssl-3.5 commit (453eaaa9, 2026-07-29);
the official 3.5.9 release on the same branch replaces it for provenance and later
fixes, and the smoke test proves the combination.
- msquic builds OpenSSL statically into its shared library with TLS 1.3 only and legacy
protocols/algorithms disabled (`no-tls1_2`, `no-dtls`, `no-legacy`, `no-deprecated`
and others in msquic's submodule build). Logging, tests, tools and perf are off; the
library is `msquic.dll` / `libmsquic.so`. Windows builds need Strawberry Perl and NASM
(installed with winget on the development host, 2026-10-03; `tools/windows-check.ps1`
reads them from the registry PATH and pins `CC`/`CXX` to `cl` because Strawberry also
puts MinGW compilers on PATH) plus `nmake`.
- msquic always compiles its Windows XDP datapath (optional at run time), which needs the
headers of its `xdp-for-windows` submodule: pinned at msquic's commit d372b525 (MIT),
archive SHA-256 9a52e1b5..., only those headers are used.
- Upstream builds itself with warnings as errors and MSVC `/analyze`; MSVC 19.44 reports
C28020 in unmodified `crypto_tls.c`. As for Mbed TLS, `cmake/Quic.cmake` appends
`/WX-` (`-Wno-error` elsewhere) to msquic's own `warnings` interface; owned code keeps
warnings as errors. Windows consumers also link `ntdll` for msquic.h's inline address
helpers.
- **Trust:** servers present a certificate chain from environment provisioning (dev: the
ADR-0083 dev CA). Clients load the environment CA with `CaCertificateFile` and use
OpenSSL's verifier on every platform (`USE_TLS_BUILTIN_CERTIFICATE_VALIDATION`; msquic
forces it on Linux, and on Windows its default platform verifier ignores the CA file),
verify the server name, and never set `NO_CERTIFICATE_VALIDATION`. ALPN `evo-m10`.
**Known gap:** OpenSSL's built-in verification also loads its default verify paths
(`OPENSSLDIR`, `SSL_CERT_FILE`, `SSL_CERT_DIR`), so trust is the pinned CA plus those
locations, not the pinned CA alone. 10.2b closes this with exact pinning: the adapter
requests the peer chain (`INDICATE_CERTIFICATE_RECEIVED`/deferred validation) and
accepts only a chain to the configured CA with the expected name, checked in owned
code. Grants and session admission stay application-level (ADR-0083/10.3).
- **Threading:** msquic calls back on its own worker threads. The transport adapter only
copies bounded data into bounded queues owned by the region host's thread; callbacks
never touch simulation or presentation state and never block.
- **Channels (implemented in 10.2b):** realtime intentions and superseding snapshots on
QUIC DATAGRAM frames (unreliable, congestion-controlled, payload <= 1,200 bytes,
newest-wins, never retransmitted by us); reliable actions and outcomes on
bidirectional streams with bounded send/receive windows; liveness from QUIC
keep-alive (1 s) and idle timeout (5 s); handshake idle timeout 5 s; congestion
control msquic's default (CUBIC) unless 10.2c measurements justify BBR.
- **M9 path:** the TLS-over-TCP dev session remains the dev/engineering fallback; M10
features build on QUIC only.
- **Impairment tests:** an owned, seeded user-space UDP relay (loss, reorder,
duplication, delay, jitter, MTU), no root; packet-level TCP comparison is not run.
## Evidence (10.2a, 2026-10-03)
`evo-quic-smoke-tests` (label `quic`, preset `quic`): loopback handshake with the dev CA,
one DATAGRAM and one stream message with FIN delivered, an untrusted CA refused (TLS
alert 51) and a wrong server name refused (alert 42), on Windows MSVC 19.44 and Linux
GCC 14; clang-tidy clean; repeated runs stable. Linux standalone build 280 s; full
results in engineering/VALIDATION.md.
## Alternatives considered
See the table. ngtcp2 needs more owned networking code; GameNetworkingSockets uses
non-TLS cryptography; DTLS plus owned reliability carries the retransmission and
congestion risk ADR-0017 warns about; Schannel would split TLS stacks by platform and
exclude older Windows; prebuilt msquic binaries are not built from reviewed sources.
## Consequences
Two TLS stacks exist while the M9 fallback remains (Mbed TLS in the session library,
OpenSSL inside msquic). Clean builds take about 5 minutes longer on Linux (OpenSSL).
When the client adopts QUIC, the Windows package (ADR-0086) adds `msquic.dll` to its
allowlist and the msquic (MIT) and OpenSSL (Apache-2.0) notices. OpenSSL and msquic
security releases update the pin, checksums and this ADR. UDP-blocked networks are
served only by the dev fallback for now.
+2
View File
@@ -17,6 +17,8 @@ Maintenance statements are shortlist evidence, not measured suitability.
| prometheus-cpp / Otel C++ | Client vs broad SDK; upstream stability docs | Export overhead/cardinality/size/failure measurement | MIT / Apache-2.0; deferred |
| mp-units | Modern dimensional APIs; test compiler diagnostics | Compile time/binary footprint and conversion clarity | MIT; deferred |
| Mbed TLS 4.1 LTS | Supported to March 2029; CMake build without Perl/Python from release tarballs; PSA crypto API | ~2.7 MB static archives (MSVC Release); TLS 1.2/DTLS/PSK/tickets compiled out | Apache-2.0 OR GPL-2.0-or-later (Apache taken); adopted for M9 dev session only (ADR-0082) |
| msquic 2.6.2 + OpenSSL 3.5.9 LTS | Microsoft, monthly releases (2.6.1 2026-08, 2.6.2 2026-09); OpenSSL 3.5 LTS; Windows and Linux from pinned source; Perl+NASM on Windows | ~6.8 MB libmsquic.so with static TLS 1.3-only OpenSSL (Linux GCC Release); +~5 min clean build | MIT / Apache-2.0; adopted for M10 transport (ADR-0090) |
| kustomize 5.8.1 | kubernetes-sigs releases (5.8.0 2025-11, 5.8.1 2026-02, 5.8.2 2026-09); Linux x86_64 binary, checksum-verified | CI-only tool, renders overlays for the policy check | Apache-2.0; adopted for deploy policy (ADR-0088) |
| SplitMix64 algorithm | Author's published fixed transition; explicit state | Small constant work, 8-byte state; noncryptographic | Reference attribution in ADR0007; proof only |
Every experiment records version/hash, compiler/OS, representative workload,
+1
View File
@@ -97,6 +97,7 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0083: Dev region sessions](0083-dev-region-sessions.md) - session server in evo-server, durable no-effect intentions on synthetic carriers, empty organism presentation, reconnect with fresh baselines, loopback-only drill-time dev deployment.
- [ADR-0084: Engineering UI toolkit](0084-engineering-ui-toolkit.md) - Dear ImGui 1.92.9b pinned (M9.8a) and integrated as the engineering client overlay with toolkit-first input routing (M9.8c).
- [ADR-0090: M10 QUIC transport](0090-m10-quic-transport.md) - msquic 2.6.2 with OpenSSL 3.5.9 LTS (TLS 1.3 only) from pinned sources on Windows and Linux; DATAGRAM frames for superseding state, streams for reliable actions; M9 TLS/TCP kept as dev fallback; owned impairment relay; exact CA pinning due in 10.2b.
- [ADR-0089: M10 timing and budgets](0089-m10-timing-and-budgets.md) - ratified 50 ms tick, 1 s flush with final outcomes p95 <= 1.5 s, responsiveness LAN p95 <= 150 ms / 100 ms RTT <= 250 ms, reference hardware; derived scheduling, sequence, baseline, queue/byte/work budgets and the exact/tolerant determinism contract; records the per-tick biology coupling.
- [ADR-0088: Rendered deployment policy](0088-rendered-deployment-policy.md) - the deploy policy check renders every overlay with pinned kustomize v5.8.1 (checksum-verified, explicit preparation) and validates effective objects; unsupported kustomize features refused.
- [ADR-0087: Dev session route](0087-dev-session-route.md) - evolution-dev only: void.aeternalisgames.com:7400 via a dedicated internal MetalLB VIP to the region pod, TLS end to end, CIDR-limited, operator-opened windows enforced by evo-server; committed disabled with fail-closed policy tests.
+2 -1
View File
@@ -2,7 +2,8 @@
Status: locked server authority and untrusted clients; transport/reliability are
proposals for M10. M10 timing and workload budgets: ADR-0089 and
[m10-budgets-v1](../../schemas/network/m10-budgets-v1.md). The scoped M9 dev session (TLS 1.3, protocol v1, dev-only grants)
[m10-budgets-v1](../../schemas/network/m10-budgets-v1.md). M10 transport: QUIC via msquic
with OpenSSL (ADR-0090); channels and impairment tests follow in M10.2b. The scoped M9 dev session (TLS 1.3, protocol v1, dev-only grants)
is specified in [DEV_SESSION_PROTOCOL](../networking/DEV_SESSION_PROTOCOL.md) and
ADR-0082. M0 has no networking. Steam distribution follows later through
an identity-provider adapter; core account IDs are independent of Steam IDs.
+28
View File
@@ -4011,3 +4011,31 @@ network tests and evo-dev-session build; Clang ASan/UBSan network tests; clang-t
the session client, evo-dev-session and network_session tests; format check.
Not covered: emulated RTT/loss, multiple clients, the reference worker and low-spec VM,
movement/prediction; the targets are therefore not yet qualified (10.9).
## 2026-10-03 — M10.2a QUIC transport selection and build (ADR-0090)
Maintainer decisions: msquic; OpenSSL from source on Windows and Linux; M9 TLS/TCP kept as
dev/engineering fallback; owned UDP impairment relay for loss testing. Survey (GitHub
API, 2026-10-03): msquic v2.6.2 MIT, ngtcp2 v1.25.0 MIT, picoquic MIT, lsquic v4.10.0
MIT, quiche 0.30.0 BSD-2, GameNetworkingSockets v1.6.1 BSD-3, wolfSSL GPL-3.0 (excluded).
Pins (`tools/msquic-pin.cmake`, explicit `tools/prepare-msquic.cmake`): msquic 2.6.2
tag archive 206e4604... (two downloads identical); OpenSSL 3.5.9 603f5602... equal to the
release's published .sha256; xdp-for-windows d372b525 headers 9a52e1b5... (two downloads
identical). Strawberry Perl 5.42.3.1 and NASM 3.02 installed on the development host
with winget (installer hashes verified by winget, per the maintainer's go-ahead).
Executed: Linux standalone msquic build (GCC 14, 280 s, libmsquic.so 6.8 MB); preset
`quic` on Linux GCC 14 and Windows MSVC 19.44: `evo-quic-smoke-tests` and network tests
2/2 on both; smoke test repeated 5 times on each without failure; clang-tidy (clang 19)
on the smoke test clean; format check; Windows `network` 1/1 and `client-network` 10/10
after the windows-check PATH/compiler changes.
Found and fixed on Windows: a build-directory clash with the Linux run (separate
directories now), msquic's own `/WX` with MSVC `/analyze` C28020 in crypto_tls.c
(upstream-only `/WX-`), missing XDP headers (pinned), `ntdll` for msquic.h helpers, and
the Windows platform verifier ignoring `CaCertificateFile` (OpenSSL verifier selected
explicitly). Security finding recorded in ADR-0090: OpenSSL's built-in verification also
trusts its default verify paths; exact pinning is 10.2b work.
Not done: bounded channels, impairment relay, loss/HOL measurements, CI integration of
the quic preset, sanitizer builds of msquic, packaging of msquic.dll.
+327
View File
@@ -0,0 +1,327 @@
// M10.2a msquic integration smoke test (ADR-0090): loopback TLS 1.3 handshake with the
// dev CA pinned through the OpenSSL provider, one unreliable DATAGRAM and one reliable
// stream message delivered, and refusal of an untrusted CA and of a wrong server name.
// msquic calls back on its own threads; events are recorded under one mutex.
#include "evo/network/dev_credentials.hpp"
#include <array>
#include <chrono>
#include <condition_variable>
#include <cstdint>
#include <cstdio>
#include <filesystem>
#include <fstream>
#include <functional>
#include <msquic.h>
#include <mutex>
#include <source_location>
#include <stdexcept>
#include <string>
namespace {
void check(bool ok, std::source_location at = std::source_location::current()) {
if (!ok)
throw std::runtime_error("quic smoke line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
const QUIC_API_TABLE* api = nullptr;
constexpr std::string_view server_name = "dev-region.evolution.test";
std::array<std::uint8_t, 7> alpn_bytes{'e', 'v', 'o', '-', 'm', '1', '0'};
const QUIC_BUFFER alpn{static_cast<std::uint32_t>(alpn_bytes.size()), alpn_bytes.data()};
struct Shared {
std::mutex mutex;
std::condition_variable changed;
bool client_connected{}, datagrams_enabled{}, client_closed{}, server_connected{};
QUIC_STATUS client_failure{QUIC_STATUS_SUCCESS};
std::string datagram, stream;
bool stream_finished{};
HQUIC server_config{};
void update(const std::function<void(Shared&)>& change) {
{
const std::scoped_lock lock{mutex};
change(*this);
}
changed.notify_all();
}
bool wait(const std::function<bool(const Shared&)>& done) {
std::unique_lock lock{mutex};
return changed.wait_for(lock, std::chrono::seconds{10}, [&] { return done(*this); });
}
};
QUIC_STATUS QUIC_API server_stream(HQUIC stream, void* context, QUIC_STREAM_EVENT* event) {
auto& shared = *static_cast<Shared*>(context);
switch (event->Type) {
case QUIC_STREAM_EVENT_RECEIVE:
shared.update([&](Shared& s) {
for (std::uint32_t i = 0; i < event->RECEIVE.BufferCount; ++i)
s.stream.append(reinterpret_cast<const char*>(event->RECEIVE.Buffers[i].Buffer),
event->RECEIVE.Buffers[i].Length);
});
break;
case QUIC_STREAM_EVENT_PEER_SEND_SHUTDOWN:
shared.update([](Shared& s) { s.stream_finished = true; });
break;
case QUIC_STREAM_EVENT_SHUTDOWN_COMPLETE:
api->StreamClose(stream);
break;
default:
break;
}
return QUIC_STATUS_SUCCESS;
}
QUIC_STATUS QUIC_API server_connection(HQUIC connection, void* context,
QUIC_CONNECTION_EVENT* event) {
auto& shared = *static_cast<Shared*>(context);
switch (event->Type) {
case QUIC_CONNECTION_EVENT_CONNECTED:
shared.update([](Shared& s) { s.server_connected = true; });
break;
case QUIC_CONNECTION_EVENT_DATAGRAM_RECEIVED: {
const auto* buffer = event->DATAGRAM_RECEIVED.Buffer;
shared.update([&](Shared& s) {
s.datagram.assign(reinterpret_cast<const char*>(buffer->Buffer), buffer->Length);
});
break;
}
case QUIC_CONNECTION_EVENT_PEER_STREAM_STARTED:
api->SetCallbackHandler(event->PEER_STREAM_STARTED.Stream,
reinterpret_cast<void*>(server_stream), context);
break;
case QUIC_CONNECTION_EVENT_SHUTDOWN_COMPLETE:
api->ConnectionClose(connection);
break;
default:
break;
}
return QUIC_STATUS_SUCCESS;
}
QUIC_STATUS QUIC_API listener_callback(HQUIC /*listener*/, void* context,
QUIC_LISTENER_EVENT* event) {
if (event->Type != QUIC_LISTENER_EVENT_NEW_CONNECTION)
return QUIC_STATUS_SUCCESS;
auto& shared = *static_cast<Shared*>(context);
api->SetCallbackHandler(event->NEW_CONNECTION.Connection,
reinterpret_cast<void*>(server_connection), context);
return api->ConnectionSetConfiguration(event->NEW_CONNECTION.Connection, shared.server_config);
}
QUIC_STATUS QUIC_API client_stream(HQUIC stream, void* /*context*/, QUIC_STREAM_EVENT* event) {
if (event->Type == QUIC_STREAM_EVENT_SHUTDOWN_COMPLETE)
api->StreamClose(stream);
return QUIC_STATUS_SUCCESS;
}
QUIC_STATUS QUIC_API client_connection(HQUIC connection, void* context,
QUIC_CONNECTION_EVENT* event) {
auto& shared = *static_cast<Shared*>(context);
switch (event->Type) {
case QUIC_CONNECTION_EVENT_CONNECTED:
shared.update([](Shared& s) { s.client_connected = true; });
break;
case QUIC_CONNECTION_EVENT_DATAGRAM_STATE_CHANGED:
shared.update([&](Shared& s) {
s.datagrams_enabled = event->DATAGRAM_STATE_CHANGED.SendEnabled != 0;
});
break;
case QUIC_CONNECTION_EVENT_SHUTDOWN_INITIATED_BY_TRANSPORT:
shared.update(
[&](Shared& s) { s.client_failure = event->SHUTDOWN_INITIATED_BY_TRANSPORT.Status; });
break;
case QUIC_CONNECTION_EVENT_SHUTDOWN_COMPLETE:
shared.update([](Shared& s) { s.client_closed = true; });
api->ConnectionClose(connection);
break;
default:
break;
}
return QUIC_STATUS_SUCCESS;
}
QUIC_SETTINGS settings() {
QUIC_SETTINGS s{};
s.IdleTimeoutMs = 5000;
s.IsSet.IdleTimeoutMs = TRUE;
s.HandshakeIdleTimeoutMs = 5000;
s.IsSet.HandshakeIdleTimeoutMs = TRUE;
s.KeepAliveIntervalMs = 1000;
s.IsSet.KeepAliveIntervalMs = TRUE;
s.DatagramReceiveEnabled = TRUE;
s.IsSet.DatagramReceiveEnabled = TRUE;
s.PeerBidiStreamCount = 4;
s.IsSet.PeerBidiStreamCount = TRUE;
return s;
}
void write_file(const std::filesystem::path& path, const std::string& text) {
std::ofstream out{path, std::ios::binary | std::ios::trunc};
out << text;
CHECK(out.good());
}
struct Outcome {
bool connected{}, closed{};
QUIC_STATUS failure{QUIC_STATUS_SUCCESS};
};
// One client attempt against the listener; on success also sends a datagram and a stream.
Outcome attempt(HQUIC registration, Shared& shared, std::uint16_t port,
const std::filesystem::path& ca, std::string_view name, bool exchange) {
auto s = settings();
HQUIC config = nullptr;
CHECK(QUIC_SUCCEEDED(
api->ConfigurationOpen(registration, &alpn, 1, &s, sizeof(s), nullptr, &config)));
const auto ca_text = ca.string();
QUIC_CREDENTIAL_CONFIG credential{};
credential.Type = QUIC_CREDENTIAL_TYPE_NONE;
// msquic flag sets are enums whose valid values are bit combinations (the API's
// own operator| casts the same way).
// OpenSSL's own verifier on every platform (msquic forces it on Linux; on Windows the
// default platform verifier ignores CaCertificateFile). It also trusts OpenSSL's
// default verify paths; exact pinning is ADR-0090 / 10.2b work.
constexpr auto flags =
static_cast<std::uint32_t>(QUIC_CREDENTIAL_FLAG_CLIENT) |
static_cast<std::uint32_t>(QUIC_CREDENTIAL_FLAG_SET_CA_CERTIFICATE_FILE) |
static_cast<std::uint32_t>(QUIC_CREDENTIAL_FLAG_USE_TLS_BUILTIN_CERTIFICATE_VALIDATION);
credential.Flags = static_cast<QUIC_CREDENTIAL_FLAGS>(
flags); // NOLINT(clang-analyzer-optin.core.EnumCastOutOfRange)
credential.CaCertificateFile = ca_text.c_str();
CHECK(QUIC_SUCCEEDED(api->ConfigurationLoadCredential(config, &credential)));
shared.update([](Shared& x) {
x.client_connected = x.datagrams_enabled = x.client_closed = x.server_connected =
x.stream_finished = false;
x.client_failure = QUIC_STATUS_SUCCESS;
x.datagram.clear();
x.stream.clear();
});
HQUIC connection = nullptr;
CHECK(
QUIC_SUCCEEDED(api->ConnectionOpen(registration, client_connection, &shared, &connection)));
QUIC_ADDR remote{};
CHECK(QuicAddrFromString("127.0.0.1", port, &remote));
CHECK(QUIC_SUCCEEDED(
api->SetParam(connection, QUIC_PARAM_CONN_REMOTE_ADDRESS, sizeof(remote), &remote)));
const std::string target{name};
CHECK(QUIC_SUCCEEDED(
api->ConnectionStart(connection, config, QUIC_ADDRESS_FAMILY_INET, target.c_str(), port)));
Outcome out;
// Connected, or refused and closed: whichever comes first decides.
out.connected =
shared.wait([](const Shared& x) { return x.client_connected || x.client_closed; }) && [&] {
const std::scoped_lock lock{shared.mutex};
return shared.client_connected;
}();
static std::array<std::uint8_t, 9> datagram{'e', 'v', 'o', '-', 'd', 'g', 'r', 'a', 'm'};
static std::array<std::uint8_t, 10> stream_bytes{'e', 'v', 'o', '-', 's',
't', 'r', 'e', 'a', 'm'};
static QUIC_BUFFER datagram_buffer{static_cast<std::uint32_t>(datagram.size()),
datagram.data()};
static QUIC_BUFFER stream_buffer{static_cast<std::uint32_t>(stream_bytes.size()),
stream_bytes.data()};
if (out.connected && exchange) {
CHECK(shared.wait([](const Shared& x) { return x.datagrams_enabled; }));
CHECK(QUIC_SUCCEEDED(
api->DatagramSend(connection, &datagram_buffer, 1, QUIC_SEND_FLAG_NONE, nullptr)));
HQUIC stream = nullptr;
CHECK(QUIC_SUCCEEDED(api->StreamOpen(connection, QUIC_STREAM_OPEN_FLAG_NONE, client_stream,
&shared, &stream)));
CHECK(QUIC_SUCCEEDED(api->StreamStart(stream, QUIC_STREAM_START_FLAG_NONE)));
CHECK(QUIC_SUCCEEDED(
api->StreamSend(stream, &stream_buffer, 1, QUIC_SEND_FLAG_FIN, nullptr)));
CHECK(shared.wait(
[](const Shared& x) { return x.stream_finished && x.datagram == "evo-dgram"; }));
CHECK(shared.wait(
[](const Shared& x) { return x.stream == "evo-stream" && x.server_connected; }));
}
if (out.connected)
api->ConnectionShutdown(connection, QUIC_CONNECTION_SHUTDOWN_FLAG_NONE,
0); // Graceful close.
out.closed = shared.wait([](const Shared& x) { return x.client_closed; });
{
const std::scoped_lock lock{shared.mutex};
out.failure = shared.client_failure;
}
api->ConfigurationClose(config);
return out;
}
void smoke() {
const auto now = std::chrono::system_clock::now();
const auto good = evo::network::generate_dev_credentials(
evo::network::DeploymentEnvironment::dev, server_name, 1, now);
const auto other = evo::network::generate_dev_credentials(
evo::network::DeploymentEnvironment::dev, server_name, 1, now);
CHECK(good && other);
const auto dir = std::filesystem::temp_directory_path() / "evo-quic-smoke";
std::filesystem::remove_all(dir);
std::filesystem::create_directories(dir);
write_file(dir / "ca.pem", good->authority_pem);
write_file(dir / "other-ca.pem", other->authority_pem);
write_file(dir / "server.pem", good->server_certificate_pem);
write_file(dir / "server.key", good->server_key_pem);
CHECK(QUIC_SUCCEEDED(MsQuicOpen2(&api)));
const QUIC_REGISTRATION_CONFIG registration_config{"evo-quic-smoke",
QUIC_EXECUTION_PROFILE_LOW_LATENCY};
HQUIC registration = nullptr;
CHECK(QUIC_SUCCEEDED(api->RegistrationOpen(&registration_config, &registration)));
Shared shared;
auto s = settings();
CHECK(QUIC_SUCCEEDED(api->ConfigurationOpen(registration, &alpn, 1, &s, sizeof(s), nullptr,
&shared.server_config)));
const auto key = (dir / "server.key").string();
const auto certificate = (dir / "server.pem").string();
QUIC_CERTIFICATE_FILE file{key.c_str(), certificate.c_str()};
QUIC_CREDENTIAL_CONFIG server_credential{};
server_credential.Type = QUIC_CREDENTIAL_TYPE_CERTIFICATE_FILE;
server_credential.CertificateFile = &file;
CHECK(
QUIC_SUCCEEDED(api->ConfigurationLoadCredential(shared.server_config, &server_credential)));
HQUIC listener = nullptr;
CHECK(QUIC_SUCCEEDED(api->ListenerOpen(registration, listener_callback, &shared, &listener)));
QUIC_ADDR local{};
CHECK(QuicAddrFromString("127.0.0.1", 0, &local));
CHECK(QUIC_SUCCEEDED(api->ListenerStart(listener, &alpn, 1, &local)));
std::uint32_t size = sizeof(local);
CHECK(
QUIC_SUCCEEDED(api->GetParam(listener, QUIC_PARAM_LISTENER_LOCAL_ADDRESS, &size, &local)));
const std::uint16_t port = QuicAddrGetPort(&local);
CHECK(port != 0);
const auto ok = attempt(registration, shared, port, dir / "ca.pem", server_name, true);
if (!ok.connected || !ok.closed)
std::fprintf(stderr, "quic: trusted attempt connected=%d closed=%d status=0x%lx\n",
ok.connected ? 1 : 0, ok.closed ? 1 : 0,
static_cast<unsigned long>(ok.failure));
CHECK(ok.connected && ok.closed);
std::printf("quic: handshake, datagram and stream delivered with the pinned dev CA\n");
const auto untrusted =
attempt(registration, shared, port, dir / "other-ca.pem", server_name, false);
CHECK(!untrusted.connected && untrusted.closed && QUIC_FAILED(untrusted.failure));
std::printf("quic: untrusted CA refused (status 0x%lx)\n",
static_cast<unsigned long>(untrusted.failure));
const auto wrong_name =
attempt(registration, shared, port, dir / "ca.pem", "wrong.evolution.test", false);
CHECK(!wrong_name.connected && wrong_name.closed && QUIC_FAILED(wrong_name.failure));
std::printf("quic: wrong server name refused (status 0x%lx)\n",
static_cast<unsigned long>(wrong_name.failure));
api->ListenerClose(listener);
api->ConfigurationClose(shared.server_config);
api->RegistrationClose(registration); // Waits for every connection and stream to close.
MsQuicClose(api);
std::filesystem::remove_all(dir);
}
} // namespace
int main() try {
smoke();
std::puts("quic smoke tests passed");
return 0;
} catch (const std::exception& e) {
std::fprintf(stderr, "%s\n", e.what());
return 1;
}
+15
View File
@@ -0,0 +1,15 @@
# M10.2 QUIC transport (ADR-0090): msquic with its OpenSSL TLS provider.
# The OpenSSL 3.5 LTS release replaces msquic's untagged submodule commit (453eaaa9,
# openssl-3.5 branch, 2026-07-29) with the next official release on that branch.
set(EVO_MSQUIC_VERSION "2.6.2")
set(EVO_MSQUIC_COMMIT "819ab74f851ee168504cbc392ec32e7bed1d82e9")
set(EVO_MSQUIC_SHA256 "206e4604eb7ffbc496eb4df804afaaba4814c2bbfdb18fdb142172301b74c8c0")
set(EVO_MSQUIC_URL "https://github.com/microsoft/msquic/archive/refs/tags/v${EVO_MSQUIC_VERSION}.tar.gz")
# msquic always compiles its Windows XDP datapath (optional at run time); the build
# needs only the headers of its pinned xdp-for-windows submodule (MIT).
set(EVO_XDP_COMMIT "d372b52577a724e04fa4c06acb90bbfa4719fc25")
set(EVO_XDP_SHA256 "9a52e1b5fc31ae3825fa67bd8aabd2c7b969a79ad6ec6bb5b884aad9e6688d3c")
set(EVO_XDP_URL "https://github.com/microsoft/xdp-for-windows/archive/${EVO_XDP_COMMIT}.tar.gz")
set(EVO_OPENSSL_VERSION "3.5.9")
set(EVO_OPENSSL_SHA256 "603f5602e2eef00d77fbd429d34dcd5822bb301757a1bc9cdb24c670f1eb859a")
set(EVO_OPENSSL_URL "https://github.com/openssl/openssl/releases/download/openssl-${EVO_OPENSSL_VERSION}/openssl-${EVO_OPENSSL_VERSION}.tar.gz")
+41
View File
@@ -0,0 +1,41 @@
# Explicit preparation of msquic and its OpenSSL (ADR-0090):
# cmake -P tools/prepare-msquic.cmake
# Downloads both pinned archives (or uses MSQUIC_ARCHIVE / OPENSSL_ARCHIVE), verifies
# SHA-256 before extraction, places OpenSSL where msquic builds its submodule, and
# records the verified pair. Normal configure never downloads.
cmake_minimum_required(VERSION 3.28)
include("${CMAKE_CURRENT_LIST_DIR}/msquic-pin.cmake")
set(root "${CMAKE_CURRENT_LIST_DIR}/../build/external/msquic")
file(MAKE_DIRECTORY "${root}")
function(evo_fetch variable url sha name)
if(NOT DEFINED ${variable})
set(${variable} "${root}/${name}")
if(NOT EXISTS "${${variable}}")
file(DOWNLOAD "${url}" "${${variable}}" TLS_VERIFY ON EXPECTED_HASH "SHA256=${sha}" STATUS result)
list(GET result 0 code)
if(NOT code EQUAL 0)
message(FATAL_ERROR "${name} download failed: ${result}")
endif()
endif()
endif()
file(SHA256 "${${variable}}" actual)
if(NOT actual STREQUAL sha)
message(FATAL_ERROR "${name} checksum mismatch; refusing extraction")
endif()
set(${variable} "${${variable}}" PARENT_SCOPE)
endfunction()
evo_fetch(MSQUIC_ARCHIVE "${EVO_MSQUIC_URL}" "${EVO_MSQUIC_SHA256}" "msquic-${EVO_MSQUIC_VERSION}.tar.gz")
evo_fetch(OPENSSL_ARCHIVE "${EVO_OPENSSL_URL}" "${EVO_OPENSSL_SHA256}" "openssl-${EVO_OPENSSL_VERSION}.tar.gz")
evo_fetch(XDP_ARCHIVE "${EVO_XDP_URL}" "${EVO_XDP_SHA256}" "xdp-for-windows-${EVO_XDP_COMMIT}.tar.gz")
set(source "${root}/msquic-${EVO_MSQUIC_VERSION}")
file(REMOVE_RECURSE "${source}" "${root}/openssl-${EVO_OPENSSL_VERSION}" "${root}/xdp-for-windows-${EVO_XDP_COMMIT}")
file(ARCHIVE_EXTRACT INPUT "${MSQUIC_ARCHIVE}" DESTINATION "${root}")
file(ARCHIVE_EXTRACT INPUT "${OPENSSL_ARCHIVE}" DESTINATION "${root}")
file(ARCHIVE_EXTRACT INPUT "${XDP_ARCHIVE}" DESTINATION "${root}")
file(REMOVE_RECURSE "${source}/submodules/openssl")
file(RENAME "${root}/openssl-${EVO_OPENSSL_VERSION}" "${source}/submodules/openssl")
file(REMOVE_RECURSE "${source}/submodules/xdp-for-windows")
file(RENAME "${root}/xdp-for-windows-${EVO_XDP_COMMIT}" "${source}/submodules/xdp-for-windows")
file(WRITE "${source}/evo-verified.sha256" "${EVO_MSQUIC_SHA256} ${EVO_OPENSSL_SHA256} ${EVO_XDP_SHA256}\n")
message(STATUS "Prepared msquic ${EVO_MSQUIC_VERSION} (MIT) with OpenSSL ${EVO_OPENSSL_VERSION} (Apache-2.0) "
"and xdp-for-windows headers ${EVO_XDP_COMMIT} (MIT)")
+9 -1
View File
@@ -1,5 +1,5 @@
param(
[ValidateSet('debug', 'release', 'analysis', 'asan', 'tsan', 'client', 'client-probe', 'network', 'client-network', 'client-package')]
[ValidateSet('debug', 'release', 'analysis', 'asan', 'tsan', 'client', 'client-probe', 'network', 'client-network', 'client-package', 'quic')]
[string]$Preset = 'debug',
[ValidateSet('configure', 'build', 'test', 'format', 'check')]
[string]$Action = 'check',
@@ -29,6 +29,14 @@ if (!$env:VSCMD_VER -or $env:VSCMD_ARG_TGT_ARCH -ne 'x64' -or $configuredRoot -n
$cmakeRoot = Join-Path $visualStudioRoot 'Common7\IDE\CommonExtensions\Microsoft\CMake'
$llvmRoot = Join-Path $visualStudioRoot 'VC\Tools\Llvm\x64\bin'
$env:Path = ((@("$cmakeRoot\CMake\bin", "$cmakeRoot\Ninja", $llvmRoot) + $env:Path.Split(';')) | Select-Object -Unique) -join ';'
# Tools installed after this shell started (Strawberry Perl and NASM for the msquic
# OpenSSL build, ADR-0090) come from the registry PATH, appended after the MSVC tools.
$registryPath = @([Environment]::GetEnvironmentVariable('Path', 'Machine'), [Environment]::GetEnvironmentVariable('Path', 'User')) -join ';'
$nasmDirectories = @("$env:LOCALAPPDATA\bin\NASM", "$env:ProgramFiles\NASM") | Where-Object { Test-Path -LiteralPath $_ }
$env:Path = (($env:Path.Split(';') + $registryPath.Split(';') + $nasmDirectories) | Where-Object { $_ } | Select-Object -Unique) -join ';'
# Strawberry Perl puts MinGW gcc/g++ on PATH: new build directories must still use MSVC.
$env:CC = 'cl'
$env:CXX = 'cl'
Push-Location -LiteralPath $repositoryRoot
try {
if ($Action -in @('configure', 'check')) {