From 867c96c22bfe708193582e323d48903a258f12cb Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 10 Apr 2026 16:16:16 +0100 Subject: [PATCH] Specify m.key_backup account data (MSC4287) Signed-off-by: Andy Balaam --- .../client_server/newsfragments/2354.feature | 1 + content/client-server-api/_index.md | 2 + .../modules/key_backup_enabled.md | 44 +++++++++++++++++++ .../client-server/definitions/key_backup.yaml | 22 ++++++++++ data/event-schemas/examples/m.key_backup.yaml | 7 +++ data/event-schemas/schema/m.key_backup.yaml | 26 +++++++++++ 6 files changed, 102 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2354.feature create mode 100644 content/client-server-api/modules/key_backup_enabled.md create mode 100644 data/api/client-server/definitions/key_backup.yaml create mode 100644 data/event-schemas/examples/m.key_backup.yaml create mode 100644 data/event-schemas/schema/m.key_backup.yaml diff --git a/changelogs/client_server/newsfragments/2354.feature b/changelogs/client_server/newsfragments/2354.feature new file mode 100644 index 00000000..13a56a7e --- /dev/null +++ b/changelogs/client_server/newsfragments/2354.feature @@ -0,0 +1 @@ +Specify m.key_backup account data (MSC4287). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index d790c924..5d655509 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -4280,6 +4280,7 @@ that profile. | [Policy Servers](#policy-servers) | Optional | Optional | Optional | Optional | Optional | | [OpenID](#openid) | Optional | Optional | Optional | Optional | Optional | | [Recently used emoji](#recently-used-emoji) | Optional | Optional | Optional | Optional | Optional | +| [Key Backup Enabled](#key-backup-enabled) | Optional | Optional | Optional | Optional | Optional | | [Reference Relations](#reference-relations) | Optional | Optional | Optional | Optional | Optional | | [Reporting Content](#reporting-content) | Optional | Optional | Optional | Optional | Optional | | [Rich replies](#rich-replies) | Optional | Optional | Optional | Optional | Optional | @@ -4385,5 +4386,6 @@ systems. {{% cs-module name="Event replacements" filename="event_replacements" %}} {{% cs-module name="Event annotations and reactions" filename="event_annotations" %}} {{% cs-module name="Recently used emoji" filename="recent_emoji" %}} +{{% cs-module name="Key backup enabled" filename="key_backup_enabled" %}} {{% cs-module name="Threading" filename="threading" %}} {{% cs-module name="Reference relations" filename="reference_relations" %}} diff --git a/content/client-server-api/modules/key_backup_enabled.md b/content/client-server-api/modules/key_backup_enabled.md new file mode 100644 index 00000000..f0e188b3 --- /dev/null +++ b/content/client-server-api/modules/key_backup_enabled.md @@ -0,0 +1,44 @@ +### Key backup enabled + +{{% added-in v="1.19" %}} + +This module enables clients to track a user's preference about enabling or +disabling [server-side backups of room keys](#server-side-key-backups). The data +is stored in the [`m.key_backup`](#mkey_backup) global +[account data](#client-config). + +#### Events + +{{% event event="m.key_backup" %}} + +#### Client behaviour on sign-in + +When a user signs in to a client which supports encryption and key backup: + +* If this event type exists in account data and contains the specified property + in the correct format, clients which support key backup MUST take account of + its contents in their behaviour. For example, clients may automatically turn + on/off key backup based on the property, or prompt the user, using the + property value as a default. (Because this property is server-controlled, + clients may wish to confirm the user's intention.) + +* If this event type does not exist in account data, or if it does not contain + the `enabled` property, or if the value of `enabled` is not a boolean value, + clients MUST ignore the existing value and MAY decide whether or not to + perform key backup, possibly based on user input. + +#### Client behaviour on setting change + +If the user turns on key backups, clients MUST set this event type in account +data, to `"enabled": true`. + +If the user turns off key backups, clients MUST set this event type in account +data, to `"enabled": false`. + +#### Not actively monitoring this setting + +Clients are not required to monitor the `m.key_backup` account data actively. +Clients MAY monitor the setting but should be aware that changing this setting +without user interaction based on choices made in a different client (or a +compromised homeserver) may cause unforeseen security problems or simply be +unexpected by users. diff --git a/data/api/client-server/definitions/key_backup.yaml b/data/api/client-server/definitions/key_backup.yaml new file mode 100644 index 00000000..1023b67f --- /dev/null +++ b/data/api/client-server/definitions/key_backup.yaml @@ -0,0 +1,22 @@ +# Copyright 2026 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +title: Key Backup +type: object +properties: + enabled: + type: boolean + description: True if the user chose to enable key backup. False if the user chose to disable key backup. +required: + - enabled diff --git a/data/event-schemas/examples/m.key_backup.yaml b/data/event-schemas/examples/m.key_backup.yaml new file mode 100644 index 00000000..678c0ba9 --- /dev/null +++ b/data/event-schemas/examples/m.key_backup.yaml @@ -0,0 +1,7 @@ +{ + "$ref": "core/event.json", + "type": "m.key_backup", + "content": { + "enabled": false + } +} diff --git a/data/event-schemas/schema/m.key_backup.yaml b/data/event-schemas/schema/m.key_backup.yaml new file mode 100644 index 00000000..e03037ff --- /dev/null +++ b/data/event-schemas/schema/m.key_backup.yaml @@ -0,0 +1,26 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "title": "Key Backup Event", + "description": "Allows clients to track user preferences about key backup.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "type": { + "type": "string", + "enum": ["m.key_backup"] + }, + "content": { + "type": "object", + "properties": { + "enabled": { + "description": "True if the user chose to enable key backup. False if the user chose to disable key backup.", + "type": "boolean", + } + }, + "required": ["enabled"] + } + }, + "required": ["type", "content"] +}