Expand description
Check an Echovalidum receipt: on your own machine, in your browser as WebAssembly, or anywhere Rust runs.
A receipt is an HTTP response echovalidum.com signed with ML-DSA (FIPS 204), the post-quantum
signature standard, as an HTTP message signature (RFC 9421): a Signature-Input that names the
parts it signs, a Signature, and a Content-Digest of the bytes. A visitor’s card on the site
holds one: a receipt for their visit. Echovalidum Receipts 1.0, for verifiers, says
exactly what a receipt carries and how it is checked; this crate is that check:
- the signature labelled
echovalidum, taggedechovalidum-content, covering the five parts a receipt signs; - the SHA-256 of its bytes against its
Content-Digest; - the key, picked from the site’s key directory by its thumbprint (RFC 7638), which the
signature names as its
keyid, and in use when the receipt was signed; - the ML-DSA signature over the text rebuilt from the parts its
Signature-Inputnames;
and works out the receipt’s number, which the visitor’s card shows: the first 40 bits of the
SHA-256 of its signature, in Crockford’s base 32. When a check fails, Check::problems says
which, each a Problem with a code the conformance vectors use and a reason in plain words.
use echovalidum_receipt::{Directory, Problem, Response};
// A receipt as your card keeps it (here, made up and unsigned), and the site's key directory as
// /.well-known/http-message-signatures-directory publishes it.
let headers = [("content-type", "application/json"), ("content-digest", "sha-256=:AAAA:"),
("signature-input", "echovalidum=(\"@status\");created=1;keyid=\"abc\";tag=\"echovalidum-content\""),
("signature", "echovalidum=:AAAA:")];
let receipt = Response { status: 200, authority: "www.echovalidum.com", path: "/attest", headers: &headers, body: b"{}" };
let directory = Directory::from_json(r#"{"keys": [{"kty": "AKP", "alg": "ML-DSA-65", "pub": "AAAA"}]}"#).unwrap();
let found = directory.check(&receipt);
assert!(!found.ok());
assert_eq!(found.problems, [Problem::Uncovered]); // made up: it signs only its status
for why in found.why() {
println!("{why}");
}check does the same with one key in hand, and Check::lines says what My Card prints.
cite checks a citation, a receipt that proves a quote is on a page of the site (Echovalidum
Citations 1.0). keylog checks the site’s key log (Echovalidum Key Log 1.0), the public,
append-only record of every key it signs with, and carries the log as it stood when this version
was published, so a key the site’s directory lists can be checked against a copy nobody can
rewrite. It
only verifies: nothing here signs, holds a secret or draws a random number, so it builds for
wasm32-unknown-unknown as it is. My Card on echovalidum.com runs it there, and the program it
makes of a visitor’s card runs it natively, and the two must print the same lines.
Modules§
- cite
- Check an Echovalidum citation: proof that a quote is on a page of echovalidum.com, word for word.
- keylog
- Check the key log, Echovalidum Key Log 1.0: the public, append-only record of every key echovalidum.com signs with, chained by SHA-256, and published both by the site and in each version of this crate.
- spec
- Echovalidum Receipts 1.0
Structs§
- Check
- What a check found.
- Directory
- A site’s key directory, as
/.well-known/http-message-signatures-directoryserves it. - Directory
Key - A key in a key directory: an AKP JSON Web Key, and when it may sign, if the directory says.
- Key
- A public key as a key directory publishes it: an AKP JSON Web Key’s
alg(ML-DSA-44,ML-DSA-65orML-DSA-87) andpub(base64url). - Response
- A signed response as it arrived: its status, the host and path it answered, its headers (names in any case, a name more than once as more than one line) and its bytes.
- Signature
Base - The text a signature covers, rebuilt from a response as RFC 9421 says.
Enums§
- Directory
Error - Why a key directory couldn’t be read.
- Problem
- Why a receipt doesn’t check out, in the order Echovalidum Receipts 1.0 checks.
Constants§
- ALGORITHMS
- The ML-DSA levels a receipt’s key may have.
- COMPONENTS
- The parts a receipt’s signature covers, in order, as
Signature-Inputserializes them. - LABEL
- The label of a receipt’s signature, in
Signature-InputandSignature. - TAG
- The tag a receipt’s signature carries: Echovalidum Receipts 1.x.
Functions§
- base64
- Base 64 (url: the URL-safe alphabet, unpadded).
- check
- Check a receipt with one key in hand: as
Directory::checkwith that key alone, except that when it isn’t the key the signature names, the signature is still tried with it, soCheck::verifiedsays whether this key signed it. - number
- A receipt’s number: the first 40 bits of the SHA-256 of its signature, in Crockford’s base 32 (no I, L, O or U to misread), as XXXX-XXXX.
- signature_
base - The text a response’s
echovalidumsignature covers: each part itsSignature-Inputnames, as"name";flags: value, then"@signature-params"(RFC 9421, section 2.5). Empty when there is no signature to read, and a missing header’s value empty. - thumbprint
- A key’s thumbprint (RFC 7638): the base64url SHA-256 of its required members, in order.
- unbase64
- Base 64 back to bytes: either alphabet, padded or not; anything else is skipped.
- verify
- An ML-DSA signature (no context) over a message, with a public key at the level
algnames.