Rename "recovery key" to "backup decryption key" (#1819)

Also, some other editorial improvements, including factoring out our two definitions of the same key encoding algorithm.

Co-authored-by: Travis Ralston <travisr@matrix.org>

changelogs/appendices/newsfragments/1819.clarification

@@ -0,0 +1 @@
+Define common cryptographic key representation.

changelogs/client_server/newsfragments/1819.clarification

@@ -0,0 +1 @@
+Rename "recovery key" to "backup decryption key".

content/appendices.md

@@ -940,6 +940,31 @@ The acceptable character set matches the unreserved character set in [RFC
 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
 {{% /boxes/note %}}
 
+## Cryptographic key representation
+
+Sometimes it is necessary to present a private cryptographic key in the user
+interface.
+
+When this happens, the key SHOULD be presented as a string formatted as
+follows:
+
+1.  A byte array is created, consisting of two bytes `0x8B` and `0x01`,
+    followed by the raw key.
+2.  All the bytes in the array above, including the two header bytes,
+    are XORed together to form a parity byte. This parity byte is
+    appended to the byte array.
+3.  The byte array is encoded using base58, using the the alphabet
+    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
+4.  A space is added after every 4th character.
+
+When reading in a key, clients should disregard whitespace, and
+perform the reverse of steps 1 through 4.
+
+{{% boxes/note %}}
+The base58 alphabet is the same as that used for [Bitcoin
+addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart).
+{{% /boxes/note %}}
+
 ## 3PID Types
 
 Third-party Identifiers (3PIDs) represent identifiers on other

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

@@ -674,7 +674,7 @@ The process between Alice and Bob verifying each other would be:
     their devices if they match or not.
 15. Assuming they match, Alice and Bob's devices each calculate Message
     Authentication Codes (MACs) for:
-    * Each of the keys that they wish the other user to verify (usually their 
+    * Each of the keys that they wish the other user to verify (usually their
       device ed25519 key and their master cross-signing key).
     * The complete list of key IDs that they wish the other user to verify.
 
@@ -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
+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
 /\_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,31 +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
+Normally, the decryption key (i.e. the secret part of the encryption key) is
-presented to the user to save, it is presented as a string constructed
+stored on the server or shared with other devices using the [Secrets](#secrets)
-as follows:
+module. When doing so, it is identified using the name `m.megolm_backup.v1`,
+and the key is base64-encoded before being encrypted.
 
-1.  The 256-bit curve25519 private key is prepended by the bytes `0x8B`
+If the backup decryption key is given directly to the user, the key should be
-    and `0x01`
+presented as a string using the common [cryptographic key
-2.  All the bytes in the string above, including the two header bytes,
+representation](/appendices/#cryptographic-key-representation).
-    are XORed together to form a parity byte. This parity byte is
-    appended to the byte string.
-3.  The byte string is encoded using base58, using the same [mapping as
-    is used for Bitcoin
-    addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart),
-    that is, using the alphabet
-    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
-4.  A space should be added after every 4th character.
 
-When reading in a recovery key, clients must disregard whitespace, and
+{{% boxes/note %}}
-perform the reverse of steps 1 through 3.
+The backup decryption key was previously referred to as a "recovery
-
+key". However, this conflicted with common practice in client user
-The recovery key can also be stored on the server or shared with other devices
+interfaces, which often use the term "recovery key" to refer to the [secret
-using the [Secrets](#secrets) module. When doing so, it is identified using the
+storage](#storage) key. The term "recovery key" is no longer used in this
-name `m.megolm_backup.v1`, and the key is base64-encoded before being
+specification.
-encrypted.
+{{% /boxes/note %}}
 
 ###### Backup algorithm: `m.megolm_backup.v1.curve25519-aes-sha2`
 

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

@@ -262,22 +262,8 @@ For example, data encrypted using this algorithm could look like this:
 ##### Key representation
 
 When a user is given a raw key for `m.secret_storage.v1.aes-hmac-sha2`,
-it will be presented as a string constructed as follows:
+the key should be presented as a string using the common [cryptographic key
-
+representation](/appendices/#cryptographic-key-representation).
-1.  The key is prepended by the two bytes `0x8b` and `0x01`
-2.  All the bytes in the string above, including the two header bytes,
-    are XORed together to form a parity byte. This parity byte is
-    appended to the byte string.
-3.  The byte string is encoded using base58, using the same [mapping as
-    is used for Bitcoin
-    addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart),
-    that is, using the alphabet
-    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
-4.  The string is formatted into groups of four characters separated by
-    spaces.
-
-When decoding a raw key, the process should be reversed, with the
-exception that whitespace is insignificant in the user's input.
 
 ##### Deriving keys from passphrases