Merge 7c1753b208 into 486a8f8764

changelogs/client_server/newsfragments/2354.feature

@@ -0,0 +1 @@
+Specify `m.key_backup` account data, as per [MSC4287](https://github.com/matrix-org/matrix-spec-proposals/pull/4287).

content/client-server-api/modules/end_to_end_encryption.md

@@ -1479,6 +1479,43 @@ potential new key backup algorithm version that would fix this issue.
 
 {{% http-api spec="client-server" api="key_backup" %}}
 
+###### Key backup enabled preference
+
+{{% added-in v="1.19" %}}
+
+This 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).
+
+{{% event event="m.key_backup" %}}
+
+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.
+
+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`.
+
+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.
+
 ##### Key exports
 
 Keys can be manually exported from one device to an encrypted file,

data/event-schemas/examples/m.key_backup.yaml

@@ -0,0 +1,7 @@
+{
+  "$ref": "core/event.json",
+  "type": "m.key_backup",
+  "content": {
+    "enabled": false
+  }
+}

data/event-schemas/schema/m.key_backup.yaml

@@ -0,0 +1,24 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  Allows clients to track user preferences about key backup.
+properties:
+  content:
+    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
+  type:
+    type: string
+    enum:
+      - m.key_backup
+title: Key Backup Event
+type: object