Security

Signed HTTP requests

HTTP signature headers are a way to cryptographically sign HTTP messages. Mastodon requires the use of HTTP signatures in order to validate that any activity received was authored by the actor generating it. When secure mode is enabled, all GET requests require HTTP signatures as well.

HTTP Signatures

Historically, Mastodon uses a proposed draft standard called HTTP Signatures. This is a specification for signing HTTP messages by using a Signature: header with your HTTP request.

For any HTTP request incoming to Mastodon, the Signature header should be attached:

Signature: keyId="https://my.example.com/actor#main-key",headers="(request-target) host date",signature="Y2FiYW...IxNGRiZDk4ZA==" 

The three parts of the Signature: header can be broken down like so:

Signature:  keyId="https://my.example.com/actor#main-key",  headers="(request-target) host date",  signature="Y2FiYW...IxNGRiZDk4ZA==" 

The keyId should correspond to the actor and the key being used to generate the signature, whose value is equal to all parameters in headers concatenated together and signed by the key, then Base64-encoded. See ActivityPub > Public key for more information on actor keys. An example key looks like this:

"publicKey": {  "id": "https://my.example.com/actor#main-key",  "owner": "https://my.example.com/actor",  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvXc4vkECU2/CeuSo1wtn\nFoim94Ne1jBMYxTZ9wm2YTdJq1oiZKif06I2fOqDzY/4q/S9uccrE9Bkajv1dnkO\nVm31QjWlhVpSKynVxEWjVBO5Ienue8gND0xvHIuXf87o61poqjEoepvsQFElA5ym\novljWGSA/jpj7ozygUZhCXtaS2W5AD5tnBQUpcO0lhItYPYTjnmzcc4y2NbJV8hz\n2s2G8qKv8fyimE23gY1XrPJg+cRF+g4PqFXujjlJ7MihD9oqtLGxbu7o1cifTn3x\nBfIdPythWu5b4cujNsB3m3awJjVmx+MHQ9SugkSIYXV0Ina77cTNS0M2PYiH1PFR\nTwIDAQAB\n-----END PUBLIC KEY-----\n"  }, 

See also: https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/

Creating HTTP signatures

To create an HTTP signature, you will have to define which headers are being hashed and signed. For example, consider the following GET request:

GET /users/username/outbox HTTP/1.1 Host: mastodon.example Date: 18 Dec 2019 10:08:46 GMT Accept: application/ld+json; profile="https://www.w3.org/ns/activitystreams" 

The signature string is constructed using the values of the HTTP headers defined in headers, joined by newlines. Typically, you will want to include the request target, as well as the host and the date. Mastodon assumes Date: header if none are provided. For the above GET request, to generate a Signature: with headers="(request-target) host date" we would generate the following string:

(request-target): get /users/username/outbox host: mastodon.example date: 18 Dec 2019 10:08:46 GMT 

Note that we don’t care about the Accept: header because we won’t be specifying it in headers.

The signature string is then hashed with RSA-SHA256 (RSASSA-PKCS1-v1_5 with SHA-256) and signed with the actor’s private key. The resulting value is attached as signature within the Signature: header. The final request looks like this:

GET /users/username/inbox HTTP/1.1 Host: mastodon.example Date: 18 Dec 2019 10:08:46 GMT Accept: application/ld+json; profile="https://www.w3.org/ns/activitystreams" Signature: keyId="https://my.example.com/actor#main-key",headers="(request-target) host date",signature="Y2FiYW...IxNGRiZDk4ZA==" 

This request is functionally equivalent to saying that https://my.example.com/actor is requesting https://mastodon.example/users/username/inbox and is proving that they sent this request by signing (request-target), Host:, and Date: with their private key linked at keyId, resulting in the provided signature.

Signing POST requests and the Digest header

When making a POST request to Mastodon, you must calculate the RSA-SHA256 digest hash of your request’s body and include this hash (in base64 encoding) within the Digest: header. The Digest: header must also be included within the headers parameter of the Signature: header. For example:

POST /users/username/inbox HTTP/1.1 HOST: mastodon.example Date: 18 Dec 2019 10:08:46 GMT Digest: sha-256=hcK0GZB1BM4R0eenYrj9clYBuyXs/lemt5iWRYmIX0A= Signature: keyId="https://my.example.com/actor#main-key",headers="(request-target) host date digest",signature="Y2FiYW...IxNGRiZDk4ZA==" Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams"  {  "@context": "https://www.w3.org/ns/activitystreams",  "actor": "https://my.example.com/actor",  "type": "Create",  "object": {  "type": "Note",  "content": "Hello!"  },  "to": "https://mastodon.example/users/username" } 

Verifying HTTP signatures

Consider the following request:

POST /users/username/inbox HTTP/1.1 Host: mastodon.example Date: 18 Dec 2019 10:08:46 GMT Digest: e37e179c75071a291f90a5fd4f848da87b491f1282f7bb8509ef2115b81ee0f4 Signature: keyId="https://my.example.com/actor#main-key",headers="(request-target) host date digest",signature="Y2FiYW...IxNGRiZDk4ZA==" Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams"  {  "@context": "https://www.w3.org/ns/activitystreams",  "actor": "https://my.example.com/actor",  "type": "Create",  "object": {  "type": "Note",  "content": "Hello!"  }  "to": "https://mastodon.example/users/username" } 

Mastodon verifies the signature using the following algorithm:

• Split Signature: into its separate parameters.
• Construct the signature string from the value of headers.
• Fetch the keyId and resolve to an actor’s publicKey.
• RSA-SHA256 hash the signature string and compare to the Base64-decoded signature as decrypted by publicKey[publicKeyPem].
• Use the Date: header to check that the signed request was made within the past 12 hours.

HTTP Message Signatures (RFC9421)

Version history:
4.4.0 - added

Since Mastodon implemented HTTP Signatures this draft specification has been overhauled, released as RFC9421 and renamed to “HTTP Message Signatures”.

From version 4.4.0 Mastodon supports incoming HTTP requests to be signed with RFC9421-compatible signatures.

The biggest difference to the HTTP Signatures standard described above is that HTTP Message Signatures use two separate HTTP headers, Signature and Signature-Input:

Signature-Input: sig1=("@method" "@target-uri" "content-digest");created=1748341414;keyid="https://my.example.com/actor#main-key" Signature: sig1=:Y2FiYW...IxNGRiZDk4ZA==: 

Signature-Input includes parameters, like the keyid and a created timestamp, and the different components that need to be signed. These can be HTTP headers and so-called “derived components” like the HTTP method (@method) or URL (@target-uri) used for the request.

Signature only includes the actual signature(s).

Mastodon has the following requirements for RFC9421-compatible signatures:

• Only a single signature is supported
• The created parameter MUST be present
• The @method and @target-uri “derived components” MUST be signed
• A Content-Digest header (RFC9530) MUST be present and signed
• The only supported algorithm is still RSASSA-PKCS1-v1_5 Using SHA-256

To learn more about HTTP Message Signatures please refer to:

• RFC9421 for all the details
• HTTP Message Signatures Sandbox for an interactive playground and a list of libraries implementing RFC9421

Linked Data Signatures

Linked Data Signatures 1.0 was a draft specification for attaching cryptographic signatures to JSON-LD documents. LD Signatures are not used widely within Mastodon, but they are used in the following situations:

• When running a self-destruct sequence to send Delete activities to all known peers, the payload will use LD Signatures because HTTP Signatures will not be available. Receiving servers will process the signature by validating it against the locally cached actor key, since the HTTP server will no longer be hosting old actor information.
• When accepting activities from a relay. Public activities can optionally be sent to a relay with LD Signatures, and any server subscribing to a relay does not have to manually refetch the activity from the origin. This prevents having potentially infinite servers attempt to load the status from your instance.

Creating LD signatures

To create a signature, Mastodon uses the keypair attached to an actor at https://mastodon.example/users/username#main-key. It then creates an RSA-SHA256 hash of the document, signs it with the keypair, and Base64-strict-encodes the resulting output to derive a signatureValue. The following hash is merged into the JSON-LD document:

"signature": {  "type": "RsaSignature2017",  "creator": "https://mastodon.example/users/username#main-key",  "created": "2019-12-08T03:48:33.901Z",  "signatureValue": "s69F3mfddd99dGjmvjdjjs81e12jn121Gkm1" } 

Verifying LD signatures

To verify a signature, Mastodon uses the following algorithm:

• Make sure that a signature exists and is a hash.
• Make sure that signature[type] is RsaSignature2017.
• Fetch the signature[creator] URI. Make sure the creator exists.
• Strip type, id, and signatureValue from the signature, leaving only signature[creator] and signature[created].
• Base64-decode the signatureValue and verify it against the public key in signature[creator].

Last updated June 25, 2025 · Improve this page