Specify the key statement encoding and key log chain (crypto.md 7.1, 7.2)

Section 7 always required "a canonical, length-prefixed encoding" for
signatures without ever specifying one. That gap had to be closed before
enrollment could exist: the client hashes the key statement and uses the
result as an OIDC nonce, so the provider signs over those exact bytes. Two
implementations disagreeing by one byte produce two nonces and an
enrollment nobody can verify -- and it only shows up against a real
provider, never in a local test.

JSON cannot be the hashed form. Property order, number formatting, Unicode
escaping and whitespace all vary between serialisers. So the statement is
transmitted as JSON and hashed as a fixed binary encoding, and the two are
independent by construction.

Three details are load-bearing rather than stylistic:

- The presence byte before each string is what makes the encoding
  injective. Without it an absent email and an empty one encode
  identically, and two different statements share a binding.
- Timestamps truncate to milliseconds. PostgreSQL stores microseconds, so
  a statement that has been through the database must still hash to what
  the client hashed. The same applies to the key log, where an entry that
  cannot reproduce its own hash after being read back makes the chain
  unverifiable.
- The key log entry hash deliberately excludes the database sequence. It
  is unknown until the insert runs, and order already follows the hash
  links -- so a renumbered or gapped sequence column cannot silently
  reorder history.

KeyStatementFields is separate from Contracts.KeyStatement on purpose: one
may gain JSON fields freely, the other cannot change without invalidating
every stored binding, and Crypto must not depend on the contract assembly.
KeyStatementDriftTests makes a field added to one and not the other a
build failure, because a wire field outside the binding is unauthenticated
data the server can change undetected.

54 new tests and two new golden vector sections. The vectors pin the
absent-versus-empty email case and confirm that an offset-bearing
sub-millisecond timestamp encodes identically to its truncated UTC form.
Only additions to vectors.json; nothing existing moved.
This commit is contained in:
2026-07-28 16:06:11 +02:00
parent e6673f0bf2
commit d2a2ed8a29
13 changed files with 1363 additions and 1 deletions
@@ -0,0 +1,102 @@
using NSec.Cryptography;
namespace DodoSSH.Crypto.Tests;
/// <summary>Key statement signing and verification. See docs/crypto.md §7.</summary>
public sealed class DshSignaturesTests
{
[Fact]
public void AFreshSignature_Verifies()
{
using var key = CreateSigningKey();
var statement = Canonical(key);
var signature = DshSignatures.SignKeyStatement(key, statement);
signature.Length.ShouldBe(CryptoSpec.SignatureSize);
DshSignatures.VerifyKeyStatement(PublicKeyBytes(key), statement, signature).ShouldBeTrue();
}
[Fact]
public void ATamperedStatement_DoesNotVerify()
{
using var key = CreateSigningKey();
var statement = Canonical(key);
var signature = DshSignatures.SignKeyStatement(key, statement);
var tampered = statement.ToArray();
tampered[^1] ^= 0x01;
DshSignatures.VerifyKeyStatement(PublicKeyBytes(key), tampered, signature).ShouldBeFalse();
}
[Fact]
public void AnotherKeysSignature_DoesNotVerify()
{
using var key = CreateSigningKey();
using var other = CreateSigningKey();
var statement = Canonical(key);
var signature = DshSignatures.SignKeyStatement(other, statement);
DshSignatures.VerifyKeyStatement(PublicKeyBytes(key), statement, signature).ShouldBeFalse();
}
[Fact]
public void ASignatureMissingTheSigningContext_DoesNotVerify()
{
// Domain separation. A signature over the bare canonical encoding must not be accepted as a
// key statement signature, or the same bytes could be replayed into another role.
using var key = CreateSigningKey();
var statement = Canonical(key);
var contextless = SignatureAlgorithm.Ed25519.Sign(key, statement);
DshSignatures.VerifyKeyStatement(PublicKeyBytes(key), statement, contextless).ShouldBeFalse();
}
[Theory]
[InlineData(0)]
[InlineData(31)]
[InlineData(33)]
public void AMalformedPublicKey_ReturnsFalseRatherThanThrowing(int length)
{
// These values arrive from an untrusted server, so rejection has to be an ordinary outcome.
using var key = CreateSigningKey();
var statement = Canonical(key);
var signature = DshSignatures.SignKeyStatement(key, statement);
DshSignatures.VerifyKeyStatement(new byte[length], statement, signature).ShouldBeFalse();
}
[Theory]
[InlineData(0)]
[InlineData(63)]
[InlineData(65)]
public void AMalformedSignature_ReturnsFalseRatherThanThrowing(int length)
{
using var key = CreateSigningKey();
DshSignatures.VerifyKeyStatement(PublicKeyBytes(key), Canonical(key), new byte[length])
.ShouldBeFalse();
}
private static Key CreateSigningKey() =>
Key.Create(
SignatureAlgorithm.Ed25519,
new KeyCreationParameters { ExportPolicy = KeyExportPolicies.AllowPlaintextExport });
private static byte[] PublicKeyBytes(Key key) => key.PublicKey.Export(KeyBlobFormat.RawPublicKey);
private static byte[] Canonical(Key signingKey) =>
KeyStatementCodec.Encode(new KeyStatementFields(
Version: 1,
Issuer: "https://idp.example/realms/dodossh",
Subject: "alice-subject",
Email: "alice@example.com",
EncryptionPublicKey: TestKeys.Encryption,
SigningPublicKey: PublicKeyBytes(signingKey),
KeyGeneration: 1,
CreatedAt: DateTimeOffset.FromUnixTimeMilliseconds(1_750_000_000_123),
DeviceName: "alice-laptop"));
}