docs(architecture): correct the fingerprint base64 alphabet wording

The format contract (ADR-004 decision 1) is SHA256: + unpadded
standard base64 — not url-safe. The ssh-key re-export and ssh-keygen
both emit the +/ alphabet (visible in the recorded fingerprints); the
'url-safe' wording in ADR-004/auth.md/plans/implementation.md and the
POC-1 §1 finding was a misnomer. Wording corrected; the parity
contract itself unchanged on both sides.
This commit is contained in:
glm-5.3-flash committed 2026-10-28 06:27:49 +00:00
1 parent 635e82b54b
commit 22b82af517
4 files changed
+15 -8

No files matched your search

+6 -4
View File
@@ -23,10 +23,12 @@ verifies a signature; its auth surface is *dispositional* (ADR-004).
0.65.0 shape — the key is the `.public_key` field, and the client's
signature `.algorithm` is exposed for optional hardening).
2. alkssh computes the fingerprint via the `ssh-key` re-export
(`HashAlg::Sha256`) — `SHA256:` + unpadded url-safe base64. The
string format is a **contract invariant** (ADR-004): parity with
assembly-registered values is proven against independent issuers
(`ssh-keygen -lf` — POC-1 §1).
(`HashAlg::Sha256`) — `SHA256:` + unpadded base64 over the
standard alphabet (`ssh-keygen -lf` byte-format; not the
url-safe alphabet). The string format is a **contract invariant**
(ADR-004): parity with assembly-registered values is proven
against independent issuers (`ssh-keygen -lf` — POC-1 §1, pinned
by the committed vectors in `tests/vectors/`).
3. `resolve_from_fingerprint` → `Some(identity)` → accept; `None` →
reject — fail-closed, and the resolved-identity-`None` path never
creates a "weakly authorized" session.
@@ -37,7 +37,9 @@ twice: which methods exist, and what unauthenticated attempts receive.
1. **`auth_publickey` is implemented — the only method.** Handler:
fingerprint (`ssh-key` re-export, `HashAlg::Sha256`,
`SHA256:` + unpadded url-safe base64) →
`SHA256:` + unpadded base64 over the standard alphabet —
`+/`, not the url-safe alphabet; byte-identical to
`ssh-keygen -lf`) →
`resolve_from_fingerprint` → `Some` → accept with the resolved
identity; `None` → reject. The fingerprint *string format* is a
contract invariant: registration strings from any standard issuer
+1 -1
View File
@@ -101,7 +101,7 @@ test. The alkssh analog of alkgit's seam wave.
pins (hard-decline on mismatch) and case-2 assembly policies are the
implementor's; the crate ships the fail-closed default (reject
unknown) and is otherwise policy-blind — no accept-all built-in.
- **Fingerprint** (ADR-004) — the `SHA256:` + unpadded url-safe base64
- **Fingerprint** (ADR-004) — the `SHA256:` + unpadded base64
computation via the `ssh-key` re-export (`HashAlg::Sha256`); the
string format is a contract invariant, proven against independent
issuers (`ssh-keygen -lf` vectors, the POC-1 §1 checkpoint shape).
+5 -2
View File
@@ -32,8 +32,11 @@ the OQ seeds this POC produced.
### 1. Fingerprint-format parity — confirmed, format is exactly the registered string
`public_key.fingerprint(HashAlg::Sha256).to_string()` (via the
`ssh-key` re-export) yields `SHA256:<url-safe base64, unpadded>` —
byte-identical to `ssh-keygen -lf` on the same public key. The
`ssh-key` re-export) yields `SHA256:<unpadded base64, standard
alphabet>` — byte-identical to `ssh-keygen -lf` on the same public key. (An
earlier phrasing of this section called the encoding "url-safe"; the
observed strings and OpenSSH's own format use the standard alphabet —
unpadded standard base64 is the invariant.) The
`resolve_from_fingerprint` string compare works with values that were
registered from OpenSSH tooling output. Parity was additionally
observed against the vanilla client's own host-key check