# 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
| `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.