Step by step guide Mastodon

Step-by-step Guide to Setup & Use the HTTPSignatures Burp Suite Extension with Mastodon

This guide shows detailed the steps to configure and use the HTTPSignatures Burp Suite Extension to test HTTP Signatures with Mastodon and send an ActivityPub message. This tutorial assumes you have a working instance of Mastodon and Burp Suite installed.

Prerequisites

• Have a local Mastodon instance setup (alternatively use a public Mastodon instance)
• Installed Burp Suite (Professional or the free Burp Suite Community Edition)
• Have a web server with a valid TLS certificate to host the actor configuration

Step 1: Install the HTTPSignatures Burp Suite Extension

Download the latest JAR release file and add it in Burp Suite through Extender Tab / Extensions / Add.

Step 2: Create a Private & Public Key

Use the openssl tool to create a private key:

openssl genrsa -out testprivkey.pem 4096

Extract the public key and store it in a file:

openssl rsa -in testprivkey.pem -pubout > testpubkey.pub

We will use both the public and private keys in the next steps.

Step 3: Setup the Public actor JSON-LD Document

We have to create a JSON-LD document so that ActivityPub can authenticate our actor. The JSON-LD file could look like the following:

{
	"@context": [
		"https://www.w3.org/ns/activitystreams",
		"https://w3id.org/security/v1"
	],

	"id": "https://example.com/bob",
	"type": "Person",
	"preferredUsername": "Bob",
	"inbox": "https://example.com/inbox",

	"publicKey": {
		"id": "https://example.com/bob#main-key",
		"owner": "https://example.com/bob",
		"publicKeyPem": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----"
	}
}

This document has to be served over TLS at the location of the id parameter. You have to replace the parameters id (two locations), inbox, owner, and publicKeyPem parameters. The id has to point to the URL where this JSON-LD document is hosted. The publicKeyPem parameter has to contain the content of the public key we created in the previous step (testpubkey.pub).

Step 4: Configure the HTTPSignatures Burp Suite Extension

Start Burp Suite with the HTTPSignatures extension loaded. You should see a new HTTP Signatures menu item in Burp. Click the HTTP Signatures menu item to open the configuration dialog and fill out the following fields:

• Header Name: Signature
• keyId: The URL of the actor containing the JSON-LD above, e.g. https://example.com/actor. You can use curl test if you can retrieve the key: curl https://example.com/actor -H 'Accept: application/activity+json'|jq
• Private key file name and path: The location of the testprivkey.pem private key generated in step 2 above, e.g. /home/user/testprivkey.pem.
• Digest Header Name: digest
• Header Names to Sign: GET: date (request-target) host
• Header Names to Sign: HEAD: date (request-target) host
• Header Names to Sign: DELETE: date (request-target) host
• Header Names to Sign: PUT: date (request-target) host content-length content-type digest
• Header Names to Sign: POST: date (request-target) host content-length content-type digest
• Include query parameters in Signature: true
• Include the port in Signature: true

Don't forget to click Use this profile to set this profile tab active as the Burp Suite extension supports multiple profiles via tabs. Only one profile / tab can be active at the same time.

Step 5: Use Burp Repeater to create a valid ActivityPub Create activity

In Burp Repeater create an HTTP POST request that looks like the following:

POST /inbox HTTP/1.1
Host: my-local-mastodon-instance.example.com
Accept: application/activity+json
Content-Type: application/json
Content-Length: 663
Signature: PLACEHOLDER

{
  "@context":["https://www.w3.org/ns/activitystreams","https://w3id.org/security/v1"],
  "id": "https://example.com/testID1",
  "to": ["https://my-local-mastodon-instance.example.com/users/receivingUser"],
  "type":"Create",
  "actor":"https://example.com/actor",
  "object":{
    "id":"https://example.com/testID1",
    "type":"Note",
    "inReplyTo": "https://my-local-mastodon-instance.example.com/@receivingUser/123456789",
    "published":"2020-11-18T23:29:47+00:00",
    "to":["https://my-local-mastodon-instance.example.com/users/receivingUser"],
    "content":"Hello World"
    }
}

The extension will replace the Signature HTTP header with a new Signature. This means that you can leave the PLACEHOLDER value there. The extension will also add a digest HTTP header for POST and PUT HTTP requests. The JSON-LD document needs to be updated with the correct values for the to, actor, and inReplyTo parameters. The actor should be the same URL as in the keyId parameter configured in HTTPSignatures Burp Suite extension configuration. The to and inReplyTo parameters need to be adjusted to your local Mastodon instance. The to parameter is the receiver of the ActivityPub note. The inReplyTo parameter points to an existing Mastodon toot.

If everything has been setup correctly, the Mastodon instance should reach out to the keyId URL to retrieve the public key of the actor, verify the signature and then respond with a HTTP/1.1 202 Accepted. You can verify if the messaged was successfully accepted by browsing to the inReplyTo toot and check if you see your new message.

Troubleshooting

• Check that you can access the URL configured in the keyId parameter.
• Make sure this JSON-LD document is hosted on a TLS enabled web server with a valid TLS certificate (self-signed certificates are not accepted by Mastodon).
• Make sure the public key (keyId) matches the private key configured in the HTTPSignatures Burp Suite extension configuration.
• Check the Enable Debug Logs checkbox in the HTTPSignatures Burp Suite extension configuration. This will log the full HTTP request and the headers added. Configure where Burp Suite writes these logs at Extender Tab / Extensions / Signing HTTP Messages / Output.
• Make sure the correct tab (profile) is active (click the Use this profile button). The active profile uses red font for the tab name and a red border for the profile.
• Make sure you have the Repeater checkbox enabled under Global Configuration Settings.