-
-
Notifications
You must be signed in to change notification settings - Fork 296
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] Tidy up federation docs into 'federating with gotosocial' sect…
…ion (#1392)
- Loading branch information
1 parent
8d18888
commit 1fa574f
Showing
8 changed files
with
93 additions
and
30 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
11 changes: 11 additions & 0 deletions
11
docs/federation/federating_with_gotosocial/access_control.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
# Access Control | ||
|
||
GoToSocial uses access control restrictions to protect users and resources from unwanted interactions with remote accounts and instances. | ||
|
||
As shown in the [http signatures](http_signatures.md) document, GoToSocial requires all incoming `GET` and `POST` requests from remote servers to be signed. Unsigned requests will be denied with http code `401 Unauthorized`. | ||
|
||
Access control restrictions are implemented by checking the `keyId` of the signature (who owns the public/private key pair making the request). | ||
|
||
First, the host value of the `keyId` uri is checked against the GoToSocial instance's list of blocked (defederated) domains. If the host is recognized as a blocked domain, then the http request will immediately be aborted with http code `403 Forbidden`. | ||
|
||
Next, GoToSocial will check for the existence of a block (in either direction) between the owner of the public key making the http request, and the owner of the resource that the request is targeting. If the GoToSocial user blocks the remote account making the request, then the request will be aborted with http code `403 Forbidden`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
69 changes: 69 additions & 0 deletions
69
docs/federation/federating_with_gotosocial/http_signatures.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,69 @@ | ||
# HTTP Signatures | ||
|
||
GoToSocial requires all `GET` and `POST` requests to ActivityPub s2s endpoints to be accompanied by a valid http signature. | ||
|
||
GoToSocial will also sign all outgoing `GET` and `POST` requests that it makes to other servers. | ||
|
||
This behavior is the equivalent of Mastodon's [AUTHORIZED_FETCH / "secure mode"](https://docs.joinmastodon.org/admin/config/#authorized_fetch). | ||
|
||
GoToSocial uses the [go-fed/httpsig](https://github.com/go-fed/httpsig) library for signing outgoing requests, and for parsing and validating the signatures of incoming requests. This library strictly follows the [Cavage http signature RFC](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures), which is the same RFC used by other implementations like Mastodon, Pixelfed, Akkoma/Pleroma, etc. (This RFC has since been superceded by the [httpbis http signature RFC](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures), but this is not yet widely implemented.) | ||
|
||
## Incoming Requests | ||
|
||
GoToSocial request signature validation is implemented in [internal/federation](https://github.com/superseriousbusiness/gotosocial/blob/main/internal/federation/authenticate.go). | ||
|
||
GoToSocial will attempt to parse the signature using the following algorithms (in order), stopping at the first success: | ||
|
||
```text | ||
RSA_SHA256 | ||
RSA_SHA512 | ||
ED25519 | ||
``` | ||
|
||
## Outgoing Requests | ||
|
||
GoToSocial request signing is implemented in [internal/transport](https://github.com/superseriousbusiness/gotosocial/blob/main/internal/transport/signing.go). | ||
|
||
When assembling signatures: | ||
|
||
- outgoing `GET` requests use `(request-target) host date` | ||
- outgoing `POST` requests use `(request-target) host date digest` | ||
|
||
GoToSocial uses the `RSA_SHA256` algorithm for signing requests, which is in line with other ActivityPub implementations. | ||
|
||
## Quirks | ||
|
||
The `keyId` used by GoToSocial in the `Signature` header will look something like the following: | ||
|
||
```text | ||
https://example.org/users/example_user/main-key | ||
``` | ||
|
||
This is different from most other implementations, which usually use a fragment (`#`) in the `keyId` uri. For example, on Mastodon the user's key would instead be found at: | ||
|
||
```text | ||
https://example.org/users/example_user#main-key | ||
``` | ||
|
||
For Mastodon, the public key of a user is served as part of that user's Actor representation. GoToSocial mimics this behavior when serving the public key of a user, but instead of returning the entire Actor at the `main-key` endpoint (which may contain sensitive fields), will return only a partial stub of the actor. This looks like the following: | ||
|
||
```json | ||
{ | ||
"@context": [ | ||
"https://w3id.org/security/v1", | ||
"https://www.w3.org/ns/activitystreams" | ||
], | ||
"id": "https://example.org/users/example_user", | ||
"preferredUsername": "example_user", | ||
"publicKey": { | ||
"id": "https://example.org/users/example_user/main-key", | ||
"owner": "https://example.org/users/example_user", | ||
"publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzGB3yDvMl+8p+ViutVRG\nVDl9FO7ZURYXnwB3TedSfG13jyskoiMDNvsbLoUQM9ajZPB0zxJPZUlB/W3BWHRC\nNFQglE5DkB30GjTClNZoOrx64vLRT5wAEwIOjklKVNk9GJi1hFFxrgj931WtxyML\nBvo+TdEblBcoru6MKAov8IU4JjQj5KUmjnW12Rox8dj/rfGtdaH8uJ14vLgvlrAb\neQbN5Ghaxh9DGTo1337O9a9qOsir8YQqazl8ahzS2gvYleV+ou09RDhS75q9hdF2\nLI+1IvFEQ2ZO2tLk3umUP1ioa+5CWKsWD0GAXbQu9uunAV0VoExP4+/9WYOuP0ei\nKwIDAQAB\n-----END PUBLIC KEY-----\n" | ||
}, | ||
"type": "Person" | ||
} | ||
``` | ||
|
||
Remote servers federating with GoToSocial should extract the public key from the `publicKey` field. Then, they should use the `owner` field of the public key to further dereference the full version of the Actor, using a signed `GET` request. | ||
|
||
This behavior was introduced as a way of avoiding having remote servers make unsigned `GET` requests to the full Actor endpoint. However, this may change in future as it is not compliant and causes issues. Tracked in [this issue](https://github.com/superseriousbusiness/gotosocial/issues/1186). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
7 changes: 7 additions & 0 deletions
7
docs/federation/federating_with_gotosocial/request_throttling.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
# Request Throttling and Rate Limiting | ||
|
||
GoToSocial applies http request throttling and rate limiting to the ActivityPub API endpoints (inboxes, user endpoints, emojis, etc). | ||
|
||
This ensures that remote servers cannot flood a GoToSocial instance with spurious requests. Instead, remote servers making GET or POST requests to the ActivityPub API endpoints should respect 429 and 503 http codes, and take account of the `retry-after` http response header. | ||
|
||
For more details on request throttling and rate limiting behavior, please see the [throttling](../../api/throttling.md) and [rate limiting](../../api/ratelimiting.md) documents. |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters