diff --git a/content/appendices.md b/content/appendices.md index cdaf2629..7fada949 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -940,6 +940,30 @@ 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. The raw key is prepended by the two bytes `0x8B` and `0x01`. +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 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 6c3bbbea..0abbb5b7 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/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. @@ -1315,23 +1315,8 @@ replace it with the new key based on the key metadata as follows: ###### Recovery key If the recovery key (the private half of the backup encryption key) is -presented to the user to save, it is presented as a string constructed -as follows: - -1. The 256-bit curve25519 private key is prepended by the 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. A space should be added after every 4th character. - -When reading in a recovery key, clients must disregard whitespace, and -perform the reverse of steps 1 through 3. +given 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 diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md index e94f361a..541ca877 100644 --- a/content/client-server-api/modules/secrets.md +++ b/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: - -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. +the key should be presented as a string using the common [cryptographic key +representation](/appendices/#cryptographic-key-representation). ##### Deriving keys from passphrases