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](https://github.com/WebOfTrust/signify-ts) and
[KERIA](https://github.com/WebOfTrust/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

```bash
cargo add keri-http-auth
```

```rust
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

```bash
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`:

```bash
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

```bash
cargo +nightly fuzz list
cargo +nightly fuzz run authing
```

## License

Either of

- Apache License, Version 2.0 ([LICENSE-APACHE]LICENSE-APACHE)
- MIT license ([LICENSE-MIT]LICENSE-MIT)

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