Rename "recovery key" to "Backup decryption key"

and other editorial improvements in the area
This commit is contained in:
Richard van der Hoff 2024-05-08 17:29:24 +01:00
parent 2276e9de75
commit 00cbf21357

View file

@ -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 the key from the server and decrypt it. Backups are per-user, and users
may replace backups with new backups. may replace backups with new backups.
In contrast with [Key requests](#key-requests), Server-side key backups In contrast with [key requests](#key-requests), server-side key backups do not
do not require another device to be online from which to request keys. require another device to be online from which to request keys. However, as
However, as the session keys are stored on the server encrypted, it the session keys are stored on the server encrypted, the client requires a
requires users to enter a decryption key to decrypt the session keys. [decryption key](#decryption-key) to decrypt the session keys.
To create a backup, a client will call [POST 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 /\_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 - 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 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 source. Trusted sources for the private key include the user entering the
key, retrieving the key stored in [secret storage](#secret-storage), or key, retrieving the key stored in [secret storage](#secret-storage), or
obtaining the key via [secret sharing](#sharing) from a verified device 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, - and finally, if `is_verified` and `first_message_index` are equal,
then it will keep the key with a lower `forwarded_count`. 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 Normally, the decryption key (i.e. the secret part of the encryption key) is
given to the user, the key should be presented as a string using the common [cryptographic key 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). representation](/appendices/#cryptographic-key-representation).
The recovery key can also be stored on the server or shared with other devices {{% boxes/note %}}
using the [Secrets](#secrets) module. When doing so, it is identified using the The backup decryption key was previously referred to as a "recovery
name `m.megolm_backup.v1`, and the key is base64-encoded before being key". However, this conflicted with common practice in client user
encrypted. 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` ###### Backup algorithm: `m.megolm_backup.v1.curve25519-aes-sha2`