diff --git a/docs/msc3916.md b/docs/msc3916.md new file mode 100644 index 00000000..c1f9755e --- /dev/null +++ b/docs/msc3916.md @@ -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.