Signatures of draft-cavage-http-signatures as the fediverse uses them: the Signature field that Mastodon and the servers that talk to it send.
The fediverse uses a profile of the draft that no version describes exactly: RSA-SHA256 over a few headers, with a little of the twelfth and last version (from 2019), such as hs2019 and (created). This namespace implements that profile and nothing else of the draft. It uses the key maps, results and errors of the root namespace, and its functions also return values on the JVM and promises in ClojureScript.
Every fediverse server accepts these signatures, but only some accept those of RFC 9421. To sign for both, give httpsig/sender the :signers [sign httpsig/sign].
Signatures of draft-cavage-http-signatures as the fediverse uses them: the Signature field that Mastodon and the servers that talk to it send. The fediverse uses a profile of the draft that no version describes exactly: RSA-SHA256 over a few headers, with a little of the twelfth and last version (from 2019), such as hs2019 and (created). This namespace implements that profile and nothing else of the draft. It uses the key maps, results and errors of the root namespace, and its functions also return values on the JVM and promises in ClojureScript. Every fediverse server accepts these signatures, but only some accept those of RFC 9421. To sign for both, give httpsig/sender the :signers [sign httpsig/sign].
The default of each option of sign and signing-string that has one:
The default of each option of sign and signing-string that has one: - :algorithm, "rsa-sha256": the algorithm that a signature by an RSA key names, as Mastodon, Misskey and WordPress send it (GoToSocial, Lemmy and Forgejo send hs2019) - :query?, true: (request-target) includes the URL's query, as Mastodon signs it
(digest body)The value of an RFC 3230 Digest field for the body (text as UTF-8,
bytes or nil): SHA-256= and the body's SHA-256 in base64.
The value of an RFC 3230 Digest field for the `body` (text as UTF-8, bytes or nil): SHA-256= and the body's SHA-256 in base64.
(sign message key)(sign message key opts)The message signed with the key by the opts below: the message
with a Signature field added (in ClojureScript a promise of it).
It signs (request-target), host and date, and digest when the message has a body, unless :signed-headers says otherwise. It adds a Date and a Digest when it signs them and the message has none. It also rewrites a request's URL as each platform's client sends it. A browser's fetch forbids a Date field, so this works only on the JVM and in Node.
The opts are those of default-options, and these:
It throws ::httpsig/invalid-key for a keyid with a quote, a backslash or a line break, which the draft has no way to write.
The `message` signed with the `key` by the `opts` below: the message with a Signature field added (in ClojureScript a promise of it). It signs (request-target), host and date, and digest when the message has a body, unless :signed-headers says otherwise. It adds a Date and a Digest when it signs them and the message has none. It also rewrites a request's URL as each platform's client sends it. A browser's fetch forbids a Date field, so this works only on the JVM and in Node. The `opts` are those of default-options, and these: - :signed-headers, the headers to sign in order: the message's own, and (request-target), (created) and (expires) - :created and :expires, insts for (created) and (expires), with the time now as the default (created) - :now-fn, a function that returns the time now It throws ::httpsig/invalid-key for a keyid with a quote, a backslash or a line break, which the draft has no way to write.
(signing-string message headers)(signing-string message headers params opts)The text that a signature over the headers of the message signs,
with the :created and :expires of params in seconds and the :query? of
opts.
The headers are names in order, e.g. ["(request-target)" "host" "date"]. A Host that the message lacks comes from its URL, since every client sets that Host itself.
The text that a signature over the `headers` of the `message` signs, with the :created and :expires of `params` in seconds and the :query? of `opts`. The headers are names in order, e.g. ["(request-target)" "host" "date"]. A Host that the message lacks comes from its URL, since every client sets that Host itself.
(verify message key-fn)(verify message key-fn opts)The result of verifying the Signature field of the message with the
key that key-fn returns for it, by the opts below (in ClojureScript
a promise of it).
The key-fn takes the parameters of the signature as a map of its
:keyid and :algorithm (the draft's name, e.g. hs2019, rather than an
:alg of RFC 9421), and returns a key map (or nil, or a future or a
promise of either), as httpsig/verify takes it. The algorithm comes from
the key: hs2019 means RSA-SHA256 for an RSA key (as the fediverse reads
it) and Ed25519 for an Ed25519 key (which GoToSocial also tries).
The result is a map like that of httpsig/verify, with the signed headers as its :components. The errors are the same. A signature can have:
The opts are those of httpsig/default-options, and these:
The signature's time is its (created) when it covers one, and else its Date, which has to be IMF-fixdate.
The result of verifying the Signature field of the `message` with the key that `key-fn` returns for it, by the `opts` below (in ClojureScript a promise of it). The `key-fn` takes the parameters of the signature as a map of its :keyid and :algorithm (the draft's name, e.g. hs2019, rather than an :alg of RFC 9421), and returns a key map (or nil, or a future or a promise of either), as httpsig/verify takes it. The algorithm comes from the key: hs2019 means RSA-SHA256 for an RSA key (as the fediverse reads it) and Ed25519 for an Ed25519 key (which GoToSocial also tries). The result is a map like that of httpsig/verify, with the signed headers as its :components. The errors are the same. A signature can have: - rsa-sha256, hs2019 or no algorithm at all - for a GET or a HEAD, (request-target) with or without the query, since Mobilizon and Pleroma sign the path alone - (created) and (expires), and a Signature prefix, as old Node libraries wrote it - a Digest whose SHA-256 or SHA-512 matches the body, when it's signed The `opts` are those of httpsig/default-options, and these: - :required-headers, the headers that a signature has to cover, in place of the default: date or (created), (request-target) or digest, host for any method but POST, and digest for a message with a body - :now-fn, a function that returns the time now The signature's time is its (created) when it covers one, and else its Date, which has to be IMF-fixdate.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |