zelo72
/
documentation
mirror of https://github.com/mastodon/documentation
1
0
Fork 0
Code Issues 6 Releases Wiki Activity

Update signature requirements and advice

This commit is contained in:
a 2022-11-26 14:11:48 -06:00
parent 6e9256e786
commit 57d1d7694e
2 changed files with 62 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
content/en/spec/activitypub.md
View File

@ -42,17 +42,17 @@ Undo
The first-class Object types supported by Mastodon are `Note` and `Question`.
* Notes are transformed into regular statuses.
* Questions are transformed into a poll status.
- Notes are transformed into regular statuses.
- Questions are transformed into a poll status.
Some other Object types are converted as best as possible:
* Article
* Page
* Image
* Audio
* Video
* Event
- Article
- Page
- Image
- Audio
- Video
- Event
The transformer uses `content` if available, or `name` if not, in order to generate status text. The `url` will be appended. The `summary` property will be used as the CW text. The `icon` will be used as a thumbnail.

72
content/en/spec/security.md
View File

@ -42,37 +42,61 @@ See also: [https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-
### Creating HTTP signatures {#http-sign}
To create an HTTP signature, you will have to define which headers are being hashed and signed. For example, consider the following request being sent out:
To create an HTTP signature, you will have to define which headers are being hashed and signed. For example, consider the following GET request:
```http
GET /users/username/inbox HTTP/1.1
GET /users/username/outbox HTTP/1.1
Host: mastodon.example
Date: 18 Dec 2019 10:08:46 GMT
Accept: application/activity+json
Accept: application/ld+json; profile="http://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 request, to generate a `Signature:` with `headers="(request-target) host date"` we would generate the following string:
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:
```text
(request-target): get /users/username/inbox
(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 SHA256 and signed with the actor's public key. The resulting value is attached as `signature` within the Signature: header. The final request looks like this:
The signature string is then hashed with SHA256 and signed with the actor's public key. The resulting value is attached as `signature` within the `Signature:` header. The final request looks like this:
```http
GET /users/username/inbox HTTP/1.1
Host: mastodon.example
Date: 18 Dec 2019 10:08:46 GMT
Accept: application/activity+json
Accept: application/ld+json; profile="http://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 public key linked at `keyId`, resulting in the provided `signature`.
#### Signing POST requests and the Digest header {#digest}
When making a POST request to Mastodon, you must calculate the SHA256 digest hash of your request's body and include this hash within the `Digest:` header. The `Digest:` header must also be included within the `headers` parameter of the `Signature:` header. For example:
```http
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="http://www.w3.org/ns/activitystreams"
{
"@context": "https://www.w3.org/ns/activitystreams",
"actor": "https://example.com/actor",
"type": "Create",
"object": {
"type": "Note",
"content": "Hello!"
}
"to": "https://mastodon.example/users/username"
}
```
### Verifying HTTP signatures {#http-verify}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/controllers/concerns/signature_verification.rb" caption="app/controllers/concerns/signature_verification.rb" >}}
@ -80,11 +104,23 @@ This request is functionally equivalent to saying that `https://my-example.com/a
Consider the following request:
```http
GET /users/username/inbox HTTP/1.1
POST /users/username/inbox HTTP/1.1
Host: mastodon.example
Date: 18 Dec 2019 10:08:46 GMT
Accept: application/activity+json
Signature: keyId="https://my-example.com/actor#main-key",headers="(request-target) host date",signature="Y2FiYW...IxNGRiZDk4ZA=="
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="http://www.w3.org/ns/activitystreams"
{
"@context": "https://www.w3.org/ns/activitystreams",
"actor": "https://example.com/actor",
"type": "Create",
"object": {
"type": "Note",
"content": "Hello!"
}
"to": "https://mastodon.example/users/username"
}
```
Mastodon verifies the signature using the following algorithm:
@ -93,16 +129,20 @@ Mastodon verifies the signature using the following algorithm:
* Construct the signature string from the value of `headers`.
* Fetch the `keyId` and resolve to an actor's `publicKey`.
* 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.
* Use the `Date:` header to check that the signed request was made within the past 12 hours.
## Linked Data Signatures {#ld}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/activitypub/linked_data_signature.rb" caption="app/lib/activitypub/linked_data_signature.rb" >}}
[Linked Data Signatures 1.0](https://w3c-dvcg.github.io/ld-signatures/) is a 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:
{{< hint style="warning" >}}
Mastodon's current implementation of LD Signatures is outdated due to a change in the JSON-LD `@context` between the drafting stage and finalization stage of the specification. Mastodon expects a `type` of `RsaSignature2017` while later drafts instead define `RsaSignature2018` via the namespace `https://w3id.org/security/v2`. Furthermore, the LD Signatures specification as a whole has been superseded by the [Verifiable Credential Data Integrity 1.0](https://w3c.github.io/vc-data-integrity/) specification, which is largely incompatible with the earlier LD Signature spec. For this reason, it is not advised to implement support for LD Signatures.
{{< /hint >}}
* When running a [self-destruct]({{< relref "admin/tootctl#tootctl-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.
[Linked Data Signatures 1.0](https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/) 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]({{< relref "admin/tootctl#tootctl-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 {#ld-sign}
@ -117,10 +157,6 @@ To create a signature, Mastodon uses the keypair attached to an actor at `https:
}
```
{{< hint style="warning" >}}
Mastodon's current implementation of LD Signatures is somewhat outdated due to a change in the JSON-LD @context between the drafting stage and finalization stage of the specification. Mastodon expects a `type` of `RsaSignature2017` while the current specification instead defines `RsaSignature2018` via the namespace `https://w3id.org/security/v2`.
{{< /hint >}}
### Verifying LD signatures {#ld-verify}
To verify a signature, Mastodon uses the following algorithm: