docs/crypto.md is now the normative, frozen specification. This had to land before
anything else in M1: the server holds ciphertext and no keys, so it can never
re-encrypt, and a format change after users hold data is a coordinated client rewrite
with no rollback.
Specification:
- DSH1 envelope layout, canonical 64-byte AAD encoding, SealTo construction, key
hierarchy, Argon2id profiles, fingerprints, and the change rules for each version field.
- AAD encoding is fixed-width binary rather than delimited string concatenation, so no
field value can forge a field boundary. This supersedes the illustrative form sketched
in ADR 0001, which now points here.
- UUIDs are RFC 4122 big-endian. Guid.ToByteArray() emits the first three groups
little-endian and would have made our ciphertext unreadable by any other implementation
of this spec, failing only at a cross-implementation boundary.
Verified rather than assumed:
- PrimitiveAvailabilityTests proves X25519, Ed25519, XChaCha20-Poly1305, Argon2id and
HKDF-SHA512 all function on net10.0. NSec 26.4.0 targets net9.0 and is consumed by
forward compatibility; this closes one of the two package questions the plan flagged.
- Argon2Profile exists because NSec's MemorySize is in KIBIBYTES, not bytes. Passing bytes
gives either a 256 GiB allocation or a 256 KiB KDF that cracks instantly. The type takes
mebibytes so the unit cannot be got wrong at a call site. Found by benchmarking: the
first measurements were ~1000x too slow, which turned out to be 19 GiB of work.
- Parameters measured, not guessed: 256 MiB/t=4 is 323 ms on this machine; the table of
candidates is in the spec.
Implementation and tests (83 total, up from 17):
- AadDescriptor, DshEnvelope, DshCrypto (Seal/Open/SealTo/OpenSealed/fingerprints).
- Decryption returns null rather than throwing: ciphertext comes from a server that is
explicitly not trusted, so a failed tag is an expected outcome.
- Envelope readers reject unknown algorithms and any non-zero flag bit, so an envelope
that is not fully understood fails closed.
- Executable form of the spec's substitution claims: a server cannot move ciphertext
between resources, roll back a key generation or item version, repurpose a payload as
metadata, or confuse the two constructions.
- Golden vectors in tests/fixtures/crypto/vectors.json guard the format. Mutation-checked:
a one-byte schema version change trips four tests including the guard.
Two build-infrastructure bugs found and fixed along the way:
- .editorconfig forced camelCase on const and static readonly fields. PascalCase is the
.NET convention for both; the config was wrong, not the code.
- The golden fixture was resolved with [CallerFilePath], which ContinuousIntegrationBuild
rewrites to /_/... under deterministic source paths. It passed locally and would have
failed only in CI. Now copied to the output directory and read from there.
Records the decisions the milestone plan already made, with their costs stated rather
than only their benefits:
- 0001 e2ee-trust-model: key hierarchy, the AAD-to-row binding that stops the server
moving ciphertext between rows, and the four-layer public-key trust story. States
plainly that revocation is not retroactive, that Connect cannot be a security
boundary, and that the IdP becomes a key-distribution trust root.
- 0002 minimal-apis: feature modules with explicit registration; capability negotiation
instead of Asp.Versioning, since client and server upgrade independently when
self-hosted.
- 0003 sync-protocol: single write path, revision cursors, and the bigserial
pre-commit sequence gap that silently corrupts sync — plus the per-vault advisory
lock that fixes it and the test that must prove it.
- 0004 relay-authorization: relay forwards bytes rather than terminating SSH, so
zero-knowledge survives; server-resolved target IPs in the ticket to defeat DNS
rebinding; why host addresses must be plaintext when relay is enabled.
- 0005 no-application-layer: why the usual Application/mediator layer earns nothing
here, with the trigger that would make us revisit it.
- 0006 observability-stack: OTel plus built-in ILogger; liveness excludes dependencies
so a database blip cannot restart the container and kill live SSH sessions.
Also adds a README covering layout, build, enforced conventions and milestones.
jaap-jan