From 5994ffaed34faecc963842cf02595c7fab938444 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travis@t2bot.io>
Date: Wed, 1 May 2024 13:25:54 -0600
Subject: [PATCH] Add MSC3916 text

---
 content/matrix-media-repo/toc.json            |  1 +
 .../unstable/deployment/body.md               | 26 +++++++++++++
 .../unstable/installation/signing-key/body.md | 38 +++++++++++++++++++
 .../installation/signing-key/index.yml        |  7 ++++
 4 files changed, 72 insertions(+)
 create mode 100644 content/matrix-media-repo/unstable/installation/signing-key/body.md
 create mode 100644 content/matrix-media-repo/unstable/installation/signing-key/index.yml

diff --git a/content/matrix-media-repo/toc.json b/content/matrix-media-repo/toc.json
index e73c289..0dc19b8 100644
--- a/content/matrix-media-repo/toc.json
+++ b/content/matrix-media-repo/toc.json
@@ -4,6 +4,7 @@
   "installation",
   "installation/config",
   "installation/server-names",
+  "installation/signing-key",
   "installation/methods",
   "deployment",
   "deployment/horizontal-scaling",
diff --git a/content/matrix-media-repo/unstable/deployment/body.md b/content/matrix-media-repo/unstable/deployment/body.md
index 517d295..1e2af7e 100644
--- a/content/matrix-media-repo/unstable/deployment/body.md
+++ b/content/matrix-media-repo/unstable/deployment/body.md
@@ -46,5 +46,31 @@ server {
       proxy_set_header X-Forwarded-For $remote_addr;
       proxy_pass http://localhost:8000; # Point this towards media-repo
   }
+
+  # Redirect MSC3916 endpoints to MMR
+  location /_matrix/client/unstable/org.matrix.msc3916 {
+      proxy_read_timeout 60s;
+
+      # Make sure this matches your homeserver in your MMR config
+      # You may have to manually specify it if using delegation or the
+      # incoming `Host` doesn't match.
+      proxy_set_header Host $host;
+
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $remote_addr;
+      proxy_pass http://localhost:8000; # Point this towards media-repo
+  }
+  location /_matrix/federation/unstable/org.matrix.msc3916 {
+      proxy_read_timeout 60s;
+
+      # Make sure this matches your homeserver in your MMR config
+      # You may have to manually specify it if using delegation or the
+      # incoming `Host` doesn't match.
+      proxy_set_header Host $host;
+
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $remote_addr;
+      proxy_pass http://localhost:8000; # Point this towards media-repo
+  }
 }
 ```
diff --git a/content/matrix-media-repo/unstable/installation/signing-key/body.md b/content/matrix-media-repo/unstable/installation/signing-key/body.md
new file mode 100644
index 0000000..30d3a34
--- /dev/null
+++ b/content/matrix-media-repo/unstable/installation/signing-key/body.md
@@ -0,0 +1,38 @@
+---
+layout: docs_page
+docsFor: matrix-media-repo/unstable
+titlePrefix: matrix-media-repo
+---
+
+# Signing Keys
+
+MMR is capable of [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916)-style
+authentication, which requires the use of a "signing key" to authorize outbound federated requests
+for media. MMR can authorize inbound requests without a signing key.
+
+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/t2bot/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.
diff --git a/content/matrix-media-repo/unstable/installation/signing-key/index.yml b/content/matrix-media-repo/unstable/installation/signing-key/index.yml
new file mode 100644
index 0000000..8220127
--- /dev/null
+++ b/content/matrix-media-repo/unstable/installation/signing-key/index.yml
@@ -0,0 +1,7 @@
+title: matrix-media-repo -  Signing Keys
+header:
+  - /_shared/header.md
+main:
+  - body.md
+footer:
+  - /_shared/footer.md