From e46295033819032eb3b50eb6e5a8e9adbff59a84 Mon Sep 17 00:00:00 2001 From: V02460 <git@kaialexhiller.de> Date: Mon, 17 Feb 2025 15:25:42 +0100 Subject: [PATCH] Document consequences of replacing secrets (#18138) Document consequences of replacing secrets. The covered config options are `registration_shared_secret`, `macaroon_secret_key`, `form_secret` and `worker_replication_secret`. Even though I looked at the source code to check the added documentation is right, I would appreciate additional verification of the statements made. In an hand-wavy attempt at classifying how bad the consequences of secret replacement are, I added some explanations as warnings and others as regular paragraphs. Closes #17971 ### Pull Request Checklist <!-- Please read https://element-hq.github.io/synapse/latest/development/contributing_guide.html before submitting your pull request --> * [x] Pull request is based on the develop branch * [x] Pull request includes a [changelog file](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#changelog). The entry should: - Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from `EventStore` to `EventWorkerStore`.". - Use markdown where necessary, mostly for `code blocks`. - End with either a period (.) or an exclamation mark (!). - Start with a capital letter. - Feel free to credit yourself, by adding a sentence "Contributed by @github_username." or "Contributed by [Your Name]." to the end of the entry. * [x] [Code style](https://element-hq.github.io/synapse/latest/code_style.html) is correct (run the [linters](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#run-the-linters)) --- changelog.d/18138.doc | 1 + .../configuration/config_documentation.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 changelog.d/18138.doc diff --git a/changelog.d/18138.doc b/changelog.d/18138.doc new file mode 100644 index 0000000000..5f07cd2763 --- /dev/null +++ b/changelog.d/18138.doc @@ -0,0 +1 @@ +Document consequences of replacing secrets. \ No newline at end of file diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index 92ab6438c1..e3c06d5371 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -2592,6 +2592,14 @@ This is primarily intended for use with the `register_new_matrix_user` script (see [Registering a user](../../setup/installation.md#registering-a-user)); however, the interface is [documented](../../admin_api/register_api.html). +Replacing an existing `registration_shared_secret` with a new one requires users +of the [Shared-Secret Registration API](../../admin_api/register_api.html) to +start using the new secret for requesting any further one-time nonces. + +> ⚠️ **Warning** – The additional consequences of replacing +> [`macaroon_secret_key`](#macaroon_secret_key) will apply in case it delegates +> to `registration_shared_secret`. + See also [`registration_shared_secret_path`](#registration_shared_secret_path). Example configuration: @@ -3168,6 +3176,11 @@ A secret which is used to sign If none is specified, the `registration_shared_secret` is used, if one is given; otherwise, a secret key is derived from the signing key. +> ⚠️ **Warning** – Replacing an existing `macaroon_secret_key` with a new one +> will lead to invalidation of access tokens for all guest users. It will also +> break unsubscribe links in emails sent before the change. An unlucky user +> might encounter a broken SSO login flow and would have to start again. + Example configuration: ```yaml macaroon_secret_key: <PRIVATE STRING> @@ -3195,6 +3208,9 @@ A secret which is used to calculate HMACs for form values, to stop falsification of values. Must be specified for the User Consent forms to work. +Replacing an existing `form_secret` with a new one might break the user consent +page for an unlucky user and require them to reopen the page from a new link. + Example configuration: ```yaml form_secret: <PRIVATE STRING> @@ -4443,6 +4459,9 @@ HTTP requests from workers. The default, this value is omitted (equivalently `null`), which means that traffic between the workers and the main process is not authenticated. +Replacing an existing `worker_replication_secret` with a new one will break +communication with all workers that have not yet updated their secret. + Example configuration: ```yaml worker_replication_secret: "secret_secret" -- GitLab