Describe the signature scheme in docs/FORMAT.md as the code builds it (closes #187) #188

Open
clawbot wants to merge 1 commits from issue-187-signature-scheme-doc into next
Collaborator

Implements #187.

The Signature Scheme section of docs/FORMAT.md now describes what signatureString builds and how fingerprint and verifySignature treat it, following sneak's ruling that the code is the format (#82 (comment)). The UUID part is lower-case hex with no hyphens, the hash part is the lower-case hex of the sha256 multihash and starts 1220, signer is upper-case hex, and a signature lives only in the manifest's signature field. The mf.proto comments on fields 201 to 203 say the same, mf.pb.go is regenerated with make generate, and TestSignatureString pins the documented example, which was copied from that test's output.

Worth knowing:

  • The example sha256 is the SHA-256 of no bytes. It only shows how the string is built.
  • A blank line now sits before the 2xx note in mf.proto; without it protoc attaches the note to innerMessage in mf.pb.go.
  • Judgement call: the document also states three things the code already does that the issue did not list. A verifier compares signer without regard to case, the signature covers innerMessage only through sha256, and the reference implementation signs only with version 4 keys and writes armored output.
  • The term stays "canonical string", the name the document already used.

Model: opus-5-5

Implements https://git.eeqj.de/sneak/mfer/issues/187. The Signature Scheme section of `docs/FORMAT.md` now describes what `signatureString` builds and how `fingerprint` and `verifySignature` treat it, following sneak's ruling that the code is the format (https://git.eeqj.de/sneak/mfer/issues/82#issuecomment-132656). The UUID part is lower-case hex with no hyphens, the hash part is the lower-case hex of the `sha256` multihash and starts `1220`, `signer` is upper-case hex, and a signature lives only in the manifest's `signature` field. The `mf.proto` comments on fields 201 to 203 say the same, `mf.pb.go` is regenerated with `make generate`, and `TestSignatureString` pins the documented example, which was copied from that test's output. Worth knowing: - The example `sha256` is the SHA-256 of no bytes. It only shows how the string is built. - A blank line now sits before the `2xx` note in `mf.proto`; without it protoc attaches the note to `innerMessage` in `mf.pb.go`. - Judgement call: the document also states three things the code already does that the issue did not list. A verifier compares `signer` without regard to case, the signature covers `innerMessage` only through `sha256`, and the reference implementation signs only with version 4 keys and writes armored output. - The term stays "canonical string", the name the document already used. Model: opus-5-5
clawbot added the needs-review label 2026-10-12 11:03:32 +02:00
clawbot self-assigned this 2026-10-12 11:03:32 +02:00
clawbot added 1 commit 2026-10-12 11:03:33 +02:00
The Signature Scheme section now states what signatureString builds: the
magic, the outer uuid as lower-case hex with no hyphens, and the outer
sha256 as the lower-case hex of its multihash, which starts 1220, with an
example string taken from a run of the code. It says signer is the
upper-case hex fingerprint of the signing primary key and that a signature
is stored only in the manifest. The mf.proto comments on fields 201 to 203
say the same, and mf.pb.go is regenerated. A new test pins the example
string. Nothing about what is signed or how changes.

Model: opus-5-5
Some checks are pending
check / check (push) Waiting to run
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin issue-187-signature-scheme-doc:issue-187-signature-scheme-doc
git checkout issue-187-signature-scheme-doc
Sign in to join this conversation.