diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 5d655509..dd1ca0e5 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -4386,6 +4386,5 @@ 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/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 1c3a82da..e470663e 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1528,6 +1528,51 @@ objects described as follows: {{% definition path="api/client-server/definitions/megolm_export_session_data" %}} +###### 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. + #### Messaging Algorithms ##### Messaging Algorithm Names diff --git a/content/client-server-api/modules/key_backup_enabled.md b/content/client-server-api/modules/key_backup_enabled.md deleted file mode 100644 index f0e188b3..00000000 --- a/content/client-server-api/modules/key_backup_enabled.md +++ /dev/null @@ -1,44 +0,0 @@ -### 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.