Module verification

Expand description

Checking a signed request that arrives in an inbox.

In three steps, kept apart so that each can be inspected and tested alone:

parse reads the signature, draft-cavage or RFC 9421, into plain data: which key signed, when, and what it covers.
check applies the policy a signature has to meet before its key is even fetched: it covers the request target, the host, when it was made and, for a request with a body, the body’s digest; the digest is there and matches the body; it was made recently and has not expired; and it was made for this server.
verify checks the signature against a key the caller found.

What lies between the second and third steps — fetching the key, and checking that the actor who signed is the actor the activity is from — is the caller’s, since it needs the network and the application’s cache. key_owner and published_key_pem are the pure halves of that.

Without the second step a signature over date alone would authorise any body, and a request captured on its way to another server, or an hour ago, could be replayed here. signature::verify_request checks a digest only when one happens to be sent, and never the time or the host.

Structs§

Policy: What a signature has to meet.
Request: A request as it arrived.
Signature: A signature, read but not yet checked.

Enums§

Key: The key a signature is checked against.
PublishedKey: A key an actor publishes, as a signature is checked against it.
Rejection: Why a request is refused.
Scheme: Which signature scheme a request is signed with.

Functions§

check: Apply policy to signature on request, now being seconds since the Unix epoch.
key_owner: The actor a key ID most likely belongs to: the key ID without its fragment, or without GoToSocial’s /main-key path, which is where the key is fetched from and whose owner is then checked.
parse: Read the signature on request.
published_key: key_id if actor publishes it as its own key: as published_key_pem reads a publicKey, or an Ed25519 assertionMethod Multikey (FEP-521a) whose id is key_id and whose controller is the actor.
published_key_pem: The PEM of key_id if actor publishes it as its own key: a publicKey whose id is key_id and whose owner, if it names one, is the actor.
verify: Check signature on request against key.