Skip to main content

Crate echovalidum_receipt

Crate echovalidum_receipt 

Source
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:

  1. the signature labelled echovalidum, tagged echovalidum-content, covering the five parts a receipt signs;
  2. the SHA-256 of its bytes against its Content-Digest;
  3. 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;
  4. the ML-DSA signature over the text rebuilt from the parts its Signature-Input names;

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-directory serves it.
DirectoryKey
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-65 or ML-DSA-87) and pub (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.
SignatureBase
The text a signature covers, rebuilt from a response as RFC 9421 says.

Enums§

DirectoryError
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-Input serializes them.
LABEL
The label of a receipt’s signature, in Signature-Input and Signature.
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::check with that key alone, except that when it isn’t the key the signature names, the signature is still tried with it, so Check::verified says 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 echovalidum signature covers: each part its Signature-Input names, 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 alg names.