Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document consequences of replacing secrets #18138

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
+20 −0
Open

Document consequences of replacing secrets #18138

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/18138.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document consequences of replacing secrets.
19 changes: 19 additions & 0 deletions docs/usage/configuration/config_documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2534,6 +2534,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:
Expand Down Expand Up @@ -3110,6 +3118,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>
Expand Down Expand Up @@ -3137,6 +3150,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>
Expand Down Expand Up @@ -4382,6 +4398,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"
Expand Down