-
Notifications
You must be signed in to change notification settings - Fork 80
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add early documentation for what this setup will look like
- Loading branch information
Showing
1 changed file
with
51 additions
and
0 deletions.
There are no files selected for viewing
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,51 @@ | ||
| # MSC3916 Support in MMR | ||
|
|
||
| [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916) is a proposal to add new endpoints to the Matrix | ||
| Client-Server API for authenticated media downloads. The MSC itself does not implement restrictions on who can download | ||
| a given piece of media, but does require that both users and servers identify themselves when downloading media. | ||
|
|
||
| MMR supports the MSC by default, allowing the following additional endpoints to be routed to it: | ||
|
|
||
| * `GET /_matrix/client/unstable/org.matrix.msc3916/media/download/:origin/:mediaId` | ||
| * `GET /_matrix/client/unstable/org.matrix.msc3916/media/download/:origin/:mediaId/:fileName` | ||
| * `GET /_matrix/client/unstable/org.matrix.msc3916/media/thumbnail/:origin/:mediaId` | ||
| * `GET /_matrix/client/unstable/org.matrix.msc3916/media/preview_url` | ||
| * `GET /_matrix/client/unstable/org.matrix.msc3916/media/config` | ||
| * `GET /_matrix/federation/unstable/org.matrix.msc3916/media/download/:origin/:mediaId` | ||
| * `GET /_matrix/federation/unstable/org.matrix.msc3916/media/thumbnail/:origin/:mediaId` | ||
|
|
||
| Note that the new endpoints are *not* in the traditional `/_matrix/media` namespace. Note also that the upload endpoint | ||
| does not appear in this list - the endpoint is modified by [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911) | ||
| instead. | ||
|
|
||
| MMR will allow the new `/_matrix/client` endpoints to be used if it is configured with a signing key for the server the | ||
| request is being made to. If MMR is not configured with a signing key, clients will receive the normal "not implemented" | ||
| error responses. When a signing key is configured for the server, MMR will *always* try to use the new federation endpoints | ||
| to download media, regardless as to how it was approached. This will cause a fallback to the legacy `/_matrix/media` | ||
| endpoints if the remote server does not support the new endpoints. | ||
|
|
||
| **It is strongly recommended that a signing key be configured.** Future versions of MMR may refuse to start up without a | ||
| signing key configured. | ||
|
|
||
| To set up a signing key for MMR: | ||
|
|
||
| 1. Back up your existing homeserver signing key, and store it in a safe place. The signing key effectively grants full | ||
| access to your server and events, and should not be disclosed to anyone. | ||
| 2. Download the `generate_signing_key` and `combine_signing_keys` tools for your version of MMR from the | ||
| [GitHub releases page](https://github.com/turt2live/matrix-media-repo/releases). | ||
| 3. Run `./generate_signing_key -output mmr.signing.key` to create a signing key usable with MMR. | ||
| 4. If you're using Synapse as your homeserver software, run `./combine_signing_keys -format synapse -output ./merged.signing.key ./existing.signing.key ./mmr.signing.key` | ||
| to combine the signing keys, being sure to list Synapse's existing signing key *first* in the arguments. For all other | ||
| homeserver software, please consult the homeserver documentation for how to deploy multiple signing keys. Note that | ||
| not all homeserver software options support multiple signing keys. | ||
| 5. Run `cat ./merged.signing.key` to verify that your existing signing key ID is on the first line. You can get your key | ||
| ID from `GET /_matrix/key/v2/server` against your homeserver in a web browser. If your existing signing key is *not* | ||
| first, re-run the steps above, noting the order of keys supplied to `./combine_signing_keys` is important. | ||
| 6. Deploy `./merged.signing.key` to your Synapse server in place of the existing signing key, restarting it. | ||
| 7. Deploy `./mmr.signing.key` alongside MMR and specified as `signingKeyPath` for that homeserver in your MMR config. | ||
|
|
||
| In the event that you ever need to revoke MMR's signing key from your homeserver, restore your signing key from the most | ||
| recent backup. If your homeserver's signing key changes after running the above steps, re-run the steps above to set up | ||
| your server with the new key. Note that it's considered good practice to list your old signing keys, including MMR's | ||
| revoked keys, under `old_verify_keys` on `GET /_matrix/key/v2/server` - many homeservers offer a config option to | ||
| populate this field. |