5.8 KiB
[Reviewed]
ADR-0082: Narrow secure dev-session protocol and transport security
Status
Accepted for M9.6/M9.7 engineering development sessions only. It is a scoped
application of ADR-0017; the M10 realtime transport (QUIC/DATAGRAM vs DTLS plus
owned reliability) remains open. The dev identity is never valid outside dev.
Context
M9 must connect a desktop client to one authoritative dev region. NETWORK_ARCHITECTURE locks server authority, untrusted clients, no custom cryptography, explicit wire decoding, short-lived scoped grants, replay windows and rate/byte caps, and requires the maintained implementation, exact version, license, cipher configuration and threat review to be named. Production identity (M10.3) does not exist yet; a test identity must not be able to escape into stage or World0.
Decision
Transport security. TLS 1.3 over a reliable byte stream (TCP in M9.7) with
Mbed TLS 4.1.1 (LTS branch supported until March 2029; upstream BRANCHES.md and
release notes checked 2026-10-01), used under the Apache-2.0 option of its dual
license. The release tarball (bundling TF-PSA-Crypto) is pinned by SHA-256
3359a349…375c98c, matching upstream's published checksum file (same GitHub release
origin, so this proves integrity of what was reviewed, not independent provenance).
tools/prepare-mbedtls.cmake prepares it explicitly; EVO_BUILD_NETWORK opts in;
static libraries only; headless/server/client builds never evaluate it otherwise.
Owned build restriction (third_party/mbedtls/evo_mbedtls_config.h, enforced by a
compile-time check): TLS 1.2, DTLS, renegotiation, session tickets and TLS 1.3 PSK
modes are compiled out. Runtime profile: TLS 1.3 only; suites
TLS_AES_128_GCM_SHA256 and TLS_CHACHA20_POLY1305_SHA256; groups X25519 and
secp256r1; ephemeral key exchange only; no early data or resumption. The client
requires a server certificate chaining to a pinned dev CA and matching the
configured server name; the system trust store is not used. Clients present no
certificate: identity is the dev grant inside the channel.
Dev identity. A fixed 108-byte grant: EVO-DEV-ONLY marker, version, a dev
environment byte, grant id, subject, world/frame, region, issued/expiry seconds,
and an HMAC-SHA256 tag computed and checked (constant time) by PSA with a 32-byte
non-exportable key. DevGrantKey::import refuses any environment but dev.
VerifiedGrant is constructible only by verification. Admission enforces
world/region scope, maximum lifetime (default one hour), clock skew, single use
(remembered until expiry; fail closed when full) and one session per subject.
Reconnect needs a fresh grant. This is not an account system.
Protocol v1 (schemas/view/dev-session-v1.md, include/evo/network/protocol.hpp):
12-byte header (magic, version, type, zero flags, length <= 256 KiB) and seven
messages: Hello, Welcome (session, world/frame, region, epoch, server tick, commit
watermark, limits), Intent (session, epoch, sequence, tick, bounded vector),
IntentResult, EnvironmentView and OrganismView (session, epoch, server tick, commit
watermark, baseline plus the M9.4/9.5 presentations), Close. Fields are explicit
little-endian; decoders are bounds-checked and views are rebuilt through validated
presentation constructors. Unknown versions, types, flags, required features and
enum values reject. A streaming FrameReader validates headers before buffering
payloads. Admission orders checks: rate (every attempt counts), epoch, expiry,
vector norm <= 1000, strictly increasing sequence, tick window. "Admitted" means
eligible for scheduling, never simulated or durable.
Alternatives considered
| Option | Disposition |
|---|---|
| System OpenSSL 3 (already linked by the Linux persistence adapter) | Strong option for Linux servers; no equivalent on the Windows client without a separate Perl/NASM build or a second TLS stack (Schannel). One stack on both ends is simpler for this scope. |
| Mbed TLS 3.6.7 LTS | Support ends March 2027, within the expected M9-M10 lifetime. |
| QUIC library (e.g. msquic) | Fits M10's datagram questions; large dependency and its own TLS integration before any realtime measurements exist. Deferred to M10.1. |
| libsodium primitives with an owned handshake | Requires designing key exchange/authentication: rejected by ADR-0017. |
| Plain TCP for dev | Unauthenticated protocol could escape into production; rejected. |
| Protobuf/FlatBuffers codec | Codegen dependency for seven small messages; explicit codec is reviewable and fuzzed. |
No performance comparison was measured; the choice rests on maintenance window, platform build (CMake, no Perl/Python needed for release tarballs), license and attack-surface reduction.
Benefits
Maintained AEAD/ECDHE implementation with a reduced compiled surface; explicit, fuzzed, canonical codec; replay/rate/epoch admission testable without sockets; dev identity unusable outside dev by construction.
Costs
Static crypto library build (~2.7 MB of static archives on MSVC), certificate/key management for the dev region, TCP head-of-line behaviour (acceptable for one dev engineering client, not measured for M10).
Risks
Dev CA/HMAC key leakage allows dev impersonation (dev only; rotate by redeploying secrets). Session ids identify but do not authenticate; M9.7 must bind a session to its TLS connection. Rate limits are per message, not per byte; M9.7 adds connection byte/time limits. Upstream advisories require prompt pin updates (the July 2026 releases fixed several TLS issues, some in code compiled out here).
Consequences
Amended by ADR-0083 before deployment: v1 also carries IntentOutcome (type 8) and
close reason capacity. M9.7 adds sockets, server/client session adapters, dev secret provisioning and
reconnect semantics. Pin upgrades change version, hash and this ADR together and
rerun the network suite. M10 reopens transport selection with measurements.