keri-http-auth 0.2.0

KERI HTTP message signatures and request authentication
Documentation

keri-http-auth

KERI HTTP message signatures and request authentication in Rust: the Signature and Signature-Input headers, the exact bytes a signature covers, and the Signify-Timestamp header. Both directions interoperate with the Signify scheme, and fixtures generated by signify-ts and KERIA pin the exact bytes.

Modules

Module Purpose
header Validated header names and values, and a bounded collection that refuses duplicates
fields The Signature header: signages, markers and parameters, formatted and parsed strictly
input The Signature-Input header and the signature base it describes
authentication RequestSigner signs a request; ResponseVerifier checks a response
server RequestVerifier checks a request; ResponseSigner signs a response; Freshness bounds created
timestamp The Signify-Timestamp header value

A client uses authentication, and a server uses server. RequestVerifier does no replay check until it is given a Freshness.

Use

cargo add keri-http-auth
use keri_cesr::crypto::salt::{Salt, SecurityTier};
use keri_cesr::crypto::verifier::KeyTransferability;
use keri_http_auth::authentication::RequestSigner;
use keri_http_auth::header::{HeaderName, HeaderValue, Headers};
use keri_http_auth::input::{RequestTarget, default_components};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let salt = Salt::from_raw(b"0123456789abcdef", SecurityTier::Low)?;
    let signer = RequestSigner::new(salt.derive_signer("", KeyTransferability::Transferable)?);

    let headers = Headers::from_pairs([
        (
            HeaderName::new("signify-resource")?,
            HeaderValue::new("EWJkQCFvKuyxZi582yJPb0wcwuW3VXmFNuvbQuBpgmIs")?,
        ),
        (
            HeaderName::new("signify-timestamp")?,
            HeaderValue::new("2022-09-24T00:05:48.196795+00:00")?,
        ),
    ])?;

    let input = signer.signature_input(default_components()?, 1_609_459_200)?;
    let signed = signer.sign(&input, &RequestTarget::new("POST", "/boot")?, &headers)?;

    let mut request_headers = headers;
    signed.apply(&mut request_headers)?;
    assert!(request_headers.get("signature-input").is_some());
    Ok(())
}

Prerequisites

  • Rust 1.97 or newer (rustup installs the toolchain pinned in rust-toolchain.toml).
  • Nightly Rust and cargo-fuzz, only for fuzzing.
  • Node 22 or newer, only to regenerate the fixtures.

Build and test

cargo fmt --all -- --check
cargo clippy --all-targets
cargo test
cargo deny check

Reference fixtures

fixtures/ holds the expected outputs, and each directory has a README with its provenance. Tests read them and never need Node or the network. tools/reference-vectors regenerates authing and ending:

npm ci --prefix tools/reference-vectors
npm run --prefix tools/reference-vectors check      # regenerate and fail if anything changed
npm run --prefix tools/reference-vectors generate   # regenerate after an intended change

Fuzzing

cargo +nightly fuzz list
cargo +nightly fuzz run authing

License

Either of

at your option. Contributions are dual licensed the same way unless you say otherwise.