Skip to content

Reject small-order keys and a small-order R: no key anyone can sign for - #31

Merged
pete-builds merged 1 commit into
mainfrom
fix/small-order-keys
Oct 4, 2026
Merged

pete-builds merged 1 commit into
mainfrom
fix/small-order-keys

Conversation

@pete-builds

Copy link
Copy Markdown
Owner

What was wrong

Writ identifies every party by a did:key, which is just an Ed25519 public key. A handful of public keys are "small-order" points, which no real key pair ever produces. For the worst of them, the identity point (did:key:z6MkeXATEjyXENzBXBxgC5EHk2JE5aqd7qMGGtDpLUH1e2Sj), one fixed 64-byte signature (0x01 then 63 zero bytes) verifies over any message. Both implementations accepted it, because the spec said only "Ed25519 (RFC 8032)" and both Ed25519 libraries let it through.

What that meant in practice:

  • A writ issued to that key was a bearer token. Anyone who saw it could sign as the holder, delegate onward, and make calls.
  • A tally signed by that key bound no content. Anyone could forge one, and its "signer" could deny it, which defeats the point of a receipt.
  • The design record was wrong. docs/design/08-builder-review.md:92 said both libraries reject such keys. Nobody had checked.

Reproduced on 85a17fc before the fix, with a control each time:

Probe on 85a17fc Go keys.Verify Python keys.verify
identity key, fixed signature, two different messages accepted both accepted both
control: the same signature under an ordinary key rejected rejected
all 14 small-order encodings parsed as a did:key 14 of 14 accepted 14 of 14 accepted
an honest key's signature made with nonce r = 0 (R = identity) accepted accepted
control: that signature over a different message rejected rejected

What changes

  1. Spec 1.3: a key whose 32 bytes are any of the 14 encodings of the 8 small-order points (8 canonical, 6 non-canonical) is bad_key, wherever a key appears, before any signature is checked. The spec lists them as 7 values with the top bit cleared, the same table libsodium uses. I derived the 14 independently from the curve equation and they match libsodium's list exactly.
  2. Spec 1.4: a signature whose R is one of those encodings is bad_signature. Decision and source are below.
  3. Go and Python both implement it from one 7-entry table.
  4. 19 vectors appended (270 to 288): a writ, a delegated call, and a sub-tally in a receipt tree, each "signed" by the identity key with the fixed signature; each of the 14 encodings as a writ's holder; one in an hld bound; and the r = 0 signature from an honest key. The first 269 regenerate byte for byte.
  5. Docs: a dated spec revision note, the Internet-Draft regenerated from the spec, 08-builder-review.md:92 corrected, two rows in conformance/ADVERSARIAL.md, and every count that changed (README 269 to 288 vectors, 200 to 219 rejections, Python unit tests 140 to 151, implementation-status.md).

Reason code. The builder review called this did_invalid, a name from before the spec existed. Spec section 11 names bad_key for "an identifier is not an Ed25519 did:key", so that is what this uses. No member, object, or reason code changed meaning.

The small-order R decision, and the source

libsodium rejects a small-order R, and also a small-order or non-canonical public key, before it ever runs the verification equation:

  • libsodium 1.0.22-RELEASE (2026-04-09), src/libsodium/crypto_sign/ed25519/ref10/open.c lines 33 to 39: sc25519_is_canonical(sig + 32) == 0 || ge25519_has_small_order(sig) != 0 returns -1, then ge25519_is_canonical(pk) == 0 || ge25519_has_small_order(pk) != 0 returns -1. ge25519_has_small_order (crypto_core/ed25519/ref10/ed25519_ref10.c:1076) is the same 7-value table, sign bit masked. https://github.com/jedisct1/libsodium/blob/1.0.22-RELEASE/src/libsodium/crypto_sign/ed25519/ref10/open.c
  • Unreleased master (75c6d55) rewrote this to decode the points and use a cofactored check, but it still rejects a small-order R and a small-order key.
  • Run, not only read: libsodium bundled in PyNaCl 1.6.2 rejects the identity-key forgery and the honest key's r = 0 signature. Its control, an honest signature, is accepted.

Decision: reject it. Go's crypto/ed25519 and OpenSSL accept the r = 0 signature, so without the rule one signer could make a tally that our verifiers accept and a libsodium-based verifier rejects. No honest signature is affected. It is not needed against outside forgers once small-order keys are gone.

How it was checked

Blast radius

  • Honest users: none. No generated key or honest signature is ever small-order.
  • writ-ts and any outside verifier will fail the 19 new vectors until they add the check. writ-ts checks a did:key's prefix and length only (src/encoding.ts:132) and verifies through Node's crypto, which is OpenSSL. Node 20.19.6 (OpenSSL 3.6.4) accepts the identity-key forgery here, with its control rejecting. So writ-ts has the same hole and is expected to accept all 19. I read its source and tested the primitive; I did not run writ-ts.
  • The live writ-hook binaries in ~/.local/bin were not touched. They run 85a17fc until rebuilt after merge. The gate's own keys are generated, so they are not small-order.
  • Sign through Vault transit: the grantor and gate keys never leave Vault #28 (Vault signer) merges cleanly and inherits the check, since signatures still go through keys.Verify.

Not in this PR (open decisions)

  • Which verification equation to pin, cofactorless (Go, OpenSSL, libsodium 1.0.22) or cofactored (libsodium master, ZIP 215). Until it is pinned, a dishonest key holder can still make a signature that the two kinds of verifier disagree on. This was flagged as your decision in the 2026-09-30 landscape report.
  • Pinning S < L in the text. Every library involved already enforces it.
  • Non-canonical encodings of ordinary points. libsodium rejects them and Go and OpenSSL accept them, but no one can sign under them, so no verdict differs.
  • A GitHub security advisory, if you want to exercise SECURITY.md once.

🤖 Generated with Claude Code

Spec 1.4 said only "Ed25519 (RFC 8032)", which does not say which
signatures to accept. Both implementations accepted a did:key whose key is
the identity point, under which the signature 0x01 followed by 63 zero
bytes verifies for every message, and every other small-order encoding,
canonical or not, at parse. So anyone could sign a writ, a call, or a
tally as such a key, use a writ issued to it, and put a tally in its name
into a receipt tree.

- spec 1.3: all fourteen small-order encodings are bad_key wherever a key
  appears, checked at 6.1 step 5 before any signature.
- spec 1.4: a signature whose R is a small-order encoding is
  bad_signature. Only a signer choosing r = 0 makes one; crypto/ed25519
  and OpenSSL accept it and libsodium 1.0.22 refuses it (open.c,
  ge25519_has_small_order on R and on the key).
- Go keys and Python keys reject both, from one seven-entry table.
- 19 vectors appended (270 to 288); the first 269 regenerate byte for
  byte. Both verifiers at 85a17fc accept all 19.
- Corrects docs/design/08-builder-review.md:92, which said both
  libraries reject such keys.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@pete-builds
pete-builds merged commit 1814582 into main Oct 4, 2026
11 checks passed
@pete-builds
pete-builds deleted the fix/small-order-keys branch October 4, 2026 21:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant