From 00cbf21357f3d33da3ac36c98dd4a1337eb6397c Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 8 May 2024 17:29:24 +0100 Subject: [PATCH] Rename "recovery key" to "Backup decryption key" and other editorial improvements in the area --- .../modules/end_to_end_encryption.md | 32 ++++++++++++------- 1 file changed, 20 insertions(+), 12 deletions(-) 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 0abbb5b7..f18cb9eb 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1271,10 +1271,10 @@ tries to read a message that it does not have keys for, it may request the key from the server and decrypt it. Backups are per-user, and users may replace backups with new backups. -In contrast with [Key requests](#key-requests), Server-side key backups -do not require another device to be online from which to request keys. -However, as the session keys are stored on the server encrypted, it -requires users to enter a decryption key to decrypt the session keys. +In contrast with [key requests](#key-requests), server-side key backups do not +require another device to be online from which to request keys. However, as +the session keys are stored on the server encrypted, the client requires a +[decryption key](#decryption-key) to decrypt the session keys. To create a backup, a client will call [POST /\_matrix/client/v3/room\_keys/version](#post_matrixclientv3room_keysversion) and define how the keys are to @@ -1295,7 +1295,7 @@ Clients must only store keys in backups after they have ensured that the - checking that it is signed by the user's [master cross-signing key](#cross-signing) or by a verified device belonging to the same user, or -- by deriving the public key from a private key that it obtained from a trusted +- deriving the public key from a private key that it obtained from a trusted source. Trusted sources for the private key include the user entering the key, retrieving the key stored in [secret storage](#secret-storage), or obtaining the key via [secret sharing](#sharing) from a verified device @@ -1312,16 +1312,24 @@ replace it with the new key based on the key metadata as follows: - and finally, if `is_verified` and `first_message_index` are equal, then it will keep the key with a lower `forwarded_count`. -###### Recovery key +###### Decryption key -If the recovery key (the private half of the backup encryption key) is -given to the user, the key should be presented as a string using the common [cryptographic key +Normally, the decryption key (i.e. the secret part of the encryption key) is +stored on the server or shared with other devices using the [Secrets](#secrets) +module. When doing so, it is identified using the name `m.megolm_backup.v1`, +and the key is base64-encoded before being encrypted. + +If the backup decryption key is given directly to the user, the key should be +presented as a string using the common [cryptographic key representation](/appendices/#cryptographic-key-representation). -The recovery key can also be stored on the server or shared with other devices -using the [Secrets](#secrets) module. When doing so, it is identified using the -name `m.megolm_backup.v1`, and the key is base64-encoded before being -encrypted. +{{% boxes/note %}} +The backup decryption key was previously referred to as a "recovery +key". However, this conflicted with common practice in client user +interfaces, which often use the term "recovery key" to refer to the [secret +storage](#storage) key. The term "recovery key" is no longer used in this +specification. +{{% /boxes/note %}} ###### Backup algorithm: `m.megolm_backup.v1.curve25519-aes-sha2`