Crate actpub_httpsig

Expand description

Dual-stack HTTP message signatures for ActivityPub.

Provides signing and verification for both:

Cavage draft-12 — the de-facto Fediverse standard (Mastodon, Pleroma, Lemmy, Misskey, …)
RFC 9421 — the finalized IETF HTTP Message Signatures standard (Mastodon 4.5+ accepts both)

Algorithms supported out of the box:

rsa-sha256 (2048–8192-bit modulus) — legacy main-key format, required for interop with current Mastodon; RsaBits exposes the conventional 2048 and 4096 presets for generation, and RsaSigningKey::from_pkcs8_der accepts any byte-aligned width in the full range
ed25519 — FEP-521a Multikey, recommended for new deployments

All cryptographic primitives are backed by aws-lc-rs, a memory-safe, constant-time, FIPS 140-3 validated library maintained by AWS. This crate is therefore not affected by RUSTSEC-2023-0071 (Marvin Attack) that impacts the pure-Rust rsa crate.

The crate is HTTP-framework agnostic: it operates on http::Request values and leaves transport to the caller.

§Example — Cavage signing

let key = SigningKey::generate_ed25519();
let body: Vec<u8> = br#"{"type":"Follow"}"#.to_vec();
let mut req = Request::builder()
    .method(Method::POST)
    .uri("https://example.com/inbox")
    .header("host", "example.com")
    .header("date", "Sun, 05 Jan 2014 21:31:40 GMT")
    .header("digest", sha256_digest_header(&body))
    .header("content-type", "application/activity+json")
    .body(body)
    .unwrap();

let signer = CavageSigner::new(&key, "https://example.com/users/alice#main-key");
signer.sign(&mut req).unwrap();
assert!(req.headers().contains_key("signature"));

Structs§

CavageHeaderParams: Parsed Signature: header parameters.
CavageHeaderSet: Which headers to include in the signature base string, in order.
CavageSigner: A request signer that attaches a Cavage Signature: header to an http::Request.
CavageVerified: Successful verification report.
Ed25519PublicKey: A verifying half of an Ed25519 key pair.
Ed25519SigningKey: An Ed25519 key pair capable of producing signatures.
Multikey: A FEP-521a Multikey, pairing the decoded VerifyingKey with the original base58-btc encoded string.
Rfc9421Signer: A request signer that produces RFC 9421 Signature-Input: and Signature: headers.
Rfc9421Verified: Successful RFC 9421 verification report.
RsaPublicKey: The verifying half of an RSA key pair.
RsaSigningKey: An RSA key pair capable of producing PKCS#1 v1.5 SHA-256 signatures.
SignatureInput: One entry of the Signature-Input: dictionary: the ordered component list plus parameters.
VerifyPolicy: Tunables governing which signed requests are accepted at verification time.

Enums§

Algorithm: Algorithm identifier for a signing / verifying key.
Component: A single component in an RFC 9421 signature base.
DigestAlgorithm: A hash algorithm registered with the IANA Hash Algorithm Names registry and accepted by RFC 9530 Content-Digest.
Error: Enumeration of every failure mode that this crate can surface.
RsaBits: Supported RSA key sizes. Fediverse actors use 2048 by default; Mastodon allows 4096 and other implementations occasionally go higher.
SigningKey: A key capable of producing detached signatures.
Verified: Report summarising a successful verification.
VerifyingKey: A key capable of verifying detached signatures.

Constants§

CAVAGE_REQUIRED_HEADERS: Minimum Cavage header set every compliant verifier should enforce.
CONTENT_DIGEST_HEADER: Name of the Content-Digest: HTTP header.
DEFAULT_HEADER_SET: The default header set signed on outbound POST requests.
REDACTED_HEADERS_DEFAULT: Headers whose values Verified::signature_base_redacted replaces with a placeholder.
RFC9421_DEFAULT_COMPONENTS: Default component sequence emitted by Rfc9421Signer::new.
RFC9421_REQUIRED_COMPONENTS: Minimum RFC 9421 covered-component set every compliant verifier should enforce for POST requests.
SHA256_DIGEST_PREFIX: Prefix emitted in the legacy Digest: header for SHA-256.
SIGNATURE_HEADER: Name of the Signature: HTTP header.
SIGNATURE_INPUT_HEADER: Name of the Signature-Input: HTTP header.

Functions§

cavage_verify: Verifies a Cavage-signed request against a key returned by resolve_key(key_id).
cavage_verify_with_policy: Verifies a Cavage-signed request with replay-protection.
content_digest_header: Computes the conventional Mastodon-compatible single-algorithm Content-Digest: value carrying only a sha-256 entry.
content_digest_header_with: Computes a multi-algorithm Content-Digest: value carrying one dictionary entry per requested algorithm, in the order they are supplied.
parse_signature_dict: Parses the raw Signature: header into an ordered list of (label, signature-bytes) pairs.
parse_signature_input_dict: Parses the raw Signature-Input: header into a sequence of (label, SignatureInput) pairs, preserving insertion order.
rfc9421_verify: Verifies an RFC 9421-signed request against a key returned by resolve_key(key_id).
rfc9421_verify_with_policy: Verifies an RFC 9421-signed request with replay-protection.
serialise_signature_dict: Serialises a list of (label, bytes) pairs into a Signature:-compatible value.
serialise_signature_input_dict: Serialises a (label, SignatureInput) sequence into a single header value suitable for inserting into an http::Request.
sha256_digest_header: Computes the legacy Digest: header value for body.
verify: Verifies a signed HTTP request, autodetecting the signature flavour.
verify_any_content_digest_header: Verifies that the Content-Digest: header carries at least one matching entry across the supplied accepted algorithms.
verify_content_digest_header: Verifies that the Content-Digest: header carries a sha-256 entry matching body.
verify_digest_header: Verifies that the Digest: header value matches the computed digest of body.
verify_with_policy: Verifies a signed HTTP request with replay-protection, picking the correct flavour automatically.

Type Aliases§

Result: Crate Result alias with the default error type set to Error.