Key the local cache to the identity, not to the door it was opened through

Groundwork for a device key, and a spec change rather than a feature. ADR 0007
records the decision it clears the way for: a Windows Hello gesture guarding a
protected blob, with the passphrase kept as a permanent fallback.

The reason that decision needed this first is that a device key cannot open a
session on its own. SessionOpener derived two things from the passphrase master
key — the bundle, and the local cache key — and a device wrap is
SealTo(device_x25519_pk), which yields the bundle and never computes a master key
at all. A device unlock could therefore have opened the identity and still not
read the cache it had itself written.

So LocalCacheKey now derives from the bundle: dsh1/localcache/v1 → v2, specified
in crypto.md §3.2. Every wrap that opens a vault ends up holding the bundle, so
every door reaches the same cache.

Extract-and-expand, not expand alone. Everything derived from the master key uses
HKDF-Expand directly, which is sound because an Argon2id output is uniformly
random over its whole length. The bundle's encoding is not — it opens with a
fixed 14-byte label and carries a version, a generation and a timestamp before
reaching any key material — so it needs the extract step to become a pseudorandom
key first.

Two consequences fell out, both improvements and neither the point:

- A passphrase change no longer discards the local cache. The bundle is unchanged
  by a re-wrap, so the cache key is too. Under v1 changing a passphrase silently
  orphaned every cached row and the next launch re-pulled the whole vault.
- Recovery-code unlock is fixed before it ships. It derives a different master key
  from a different secret and a different salt, so under v1 it would have had the
  same defect as the device path, and nobody would have noticed until it landed.

The cache becomes unreadable exactly when the identity is rotated, which is the
correct moment to discard it. Existing caches are discarded and re-pulled on
upgrade — already the specified behaviour for a stale cache, and the reason the
label is versioned rather than reused: a v1 cache must fail to open rather than
decrypt to nonsense.

One stated guarantee got weaker and now says so. crypto.md §10 claimed locking
meant "nothing on disk can be read again without the passphrase." Where a device
wrap exists that is no longer true, and it would have been untrue under either
candidate design — the alternative was storing a copy of the cache key in the
device blob, which is the same door with an extra key lying next to it. The
wording now points at ADR 0007, because what guards the device key is a platform
decision and not a property of this specification.

A golden vector was quietly lying, which is the part worth reading twice. The
"local-cache" entry pinned HKDF-SHA512-Expand over a fixed PRK — a construction
the cache key no longer uses. Regenerating it would have produced a green suite
describing a derivation this code does not perform. It is replaced by a vector
over a bundle whose every byte is pinned: the label, version 1, generation 1, a
fixed timestamp and two recognisable key scalars, all visible in the fixture so a
second implementation can check itself against it. UserSecretBundle.TryDecode is
internal for this, because Create draws fresh randomness and so can never produce
a reproducible input.

Mutation tested, and this one earns its keep: dropping the extract step now fails
CommittedVectors_MatchCurrentImplementation. The vector it replaced could not
have caught that, because it never touched the bundle at all.

One test became false and says so. ARecordSealedUnderAnotherPassphrase is now
ARecordSealedByAnotherIdentity: a different passphrase deliberately no longer
changes the cache key, and TheLocalCacheKey_SurvivesAPassphraseChange pins that.
What must still be unreadable is another user's cache. CacheHarness therefore
generates an identity rather than deriving from a passphrase, and has no
passphrase parameter left — the cache key is not a question about passphrases any
more.

SyncHarness's two simulated machines now derive the same cache key, which is what
keying on the bundle means: they are the same user holding the same identity. They
still have separate cache databases, so nothing is shared between them but the key
that would open either. Both harnesses lost a MasterKey field that existed only to
make a protector.

858 tests green. Zero warnings, dotnet format clean.

Not done: the device key itself. Three pieces remain, and the middle one was a
discovery rather than a plan — EnrollmentService.AddDevice runs only during
enrollment, so every already-enrolled account, which is all of them, needs an
endpoint to add a device wrap while unlocked. The client proves possession by
producing the wrap, so that shape falls out of the crypto. After that: the
protector seam with the wrap cached locally for offline unlock, then the Hello
implementation and the unlock-screen UI, which is where the Windows TFM lands and
where automated testing stops.
This commit is contained in:
2026-07-30 12:46:55 +02:00
parent c5dec2d68e
commit 7016ce36f1
14 changed files with 412 additions and 78 deletions
+12 -2
View File
@@ -166,8 +166,18 @@ public static class CryptoSpec
/// <summary>Derives the key-encryption key that wraps the secret bundle.</summary>
public static ReadOnlySpan<byte> PassphraseKek => "dsh1/kek/passphrase/v1"u8;
/// <summary>Derives the key that encrypts the client's on-disk cache.</summary>
public static ReadOnlySpan<byte> LocalCache => "dsh1/localcache/v1"u8;
/// <summary>
/// Derives the key that encrypts the client's on-disk cache.
/// </summary>
/// <remarks>
/// <b>v2 derives from the secret bundle, where v1 derived from the passphrase master key.</b> The
/// cache key has to be reachable through every door that opens the vault — passphrase, device,
/// recovery code, escrow — and only the bundle is common to all of them. Under v1 a device unlock
/// could open the identity and still not read the cache it had written, and a recovery-code unlock
/// would silently derive a different key and orphan the whole cache. Bumping the label rather than
/// reusing it is what makes an old cache fail to open instead of decrypting to nonsense.
/// </remarks>
public static ReadOnlySpan<byte> LocalCache => "dsh1/localcache/v2"u8;
/// <summary>Prefix of the SealTo key-derivation info, concatenated with the AAD.</summary>
public static ReadOnlySpan<byte> SealTo => "dsh1/sealto/v1|"u8;
+3 -10
View File
@@ -62,16 +62,9 @@ public sealed class MasterKey : IDisposable
}
}
/// <summary>
/// Derives the key that encrypts the client's on-disk cache.
/// </summary>
/// <remarks>
/// Domain-separated from the bundle's key-encryption key by its HKDF info label, so a cache
/// record can never be opened with the wrap key or the reverse — the two live in very different
/// threat models and must not share a key.
/// </remarks>
public void DeriveLocalCacheKey(Span<byte> destination) =>
DeriveSubkey(CryptoSpec.DerivationLabels.LocalCache, destination);
// The local cache key used to be derived here. It now derives from the secret bundle — see
// UserSecretBundle.DeriveLocalCacheKey — because a passphrase is only one of four ways to open a
// vault, and the cache key has to be the same one whichever was used.
/// <summary>Wraps a bundle under the passphrase-derived key-encryption key.</summary>
/// <remarks>
+56 -1
View File
@@ -115,6 +115,56 @@ public sealed class UserSecretBundle : IDisposable
KeyLogChain.TruncateTimestamp(createdAt));
}
/// <summary>
/// Derives the key that encrypts this client's on-disk cache. See docs/crypto.md §3.2.
/// </summary>
/// <remarks>
/// <para>
/// Derived from the bundle rather than from the passphrase master key, because the bundle is the one
/// thing every unlock path ends up holding. A device unlock opens a <see cref="SealTo"/> wrap and never
/// sees a master key at all, so under the old derivation it could open the identity and still not read
/// the cache it had itself written; a recovery-code unlock would derive a different key from a different
/// master and silently orphan every cached row. Keying on the bundle makes the cache readable through
/// whichever door was used, and unreadable exactly when the identity itself has been rotated — which is
/// the correct time to discard it.
/// </para>
/// <para>
/// <b>Extract-and-expand, not expand alone.</b> <see cref="MasterKey"/> can expand directly because an
/// Argon2id output is already uniformly random over its whole length. The bundle's encoding is not: it
/// opens with a fixed 14-byte label and carries a version, a generation and a timestamp before it
/// reaches any key material. HKDF's extract step is what turns that into a pseudorandom key, and
/// skipping it would be feeding structured input to a function that assumes it has none.
/// </para>
/// </remarks>
public void DeriveLocalCacheKey(Span<byte> destination)
{
Alive();
if (destination.Length != CryptoSpec.SymmetricKeySize)
{
throw new ArgumentException(
$"The cache key is {CryptoSpec.SymmetricKeySize} bytes, got {destination.Length}.",
nameof(destination));
}
Span<byte> encoded = stackalloc byte[EncodedLength];
try
{
Encode(encoded);
HKDF.DeriveKey(
HashAlgorithmName.SHA512,
encoded,
destination,
salt: default,
info: CryptoSpec.DerivationLabels.LocalCache);
}
finally
{
CryptographicOperations.ZeroMemory(encoded);
}
}
/// <summary>
/// Wraps the bundle under a symmetric key-encryption key.
/// </summary>
@@ -261,7 +311,12 @@ public sealed class UserSecretBundle : IDisposable
&& BinaryPrimitives.ReadUInt16BigEndian(encoded[OffsetVersion..]) == CurrentVersion
&& BinaryPrimitives.ReadUInt32BigEndian(encoded[OffsetKeyGeneration..]) >= 1;
private static UserSecretBundle? TryDecode(ReadOnlySpan<byte> encoded)
/// <remarks>
/// Internal rather than private so the golden-vector generator can build a bundle from fixed bytes.
/// The cache key derives from this encoding, and a vector for it is worth nothing unless the input is
/// pinned — <see cref="Create"/> draws fresh randomness, so it cannot produce a reproducible one.
/// </remarks>
internal static UserSecretBundle? TryDecode(ReadOnlySpan<byte> encoded)
{
if (!IsWellFormed(encoded))
{