From b9c1f95aab952f096cd6acd0b7acc82e3e0e499a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Mon, 11 Dec 2023 15:14:40 +0000 Subject: [PATCH] Clarify that base64 may or may not be padded --- content/client-server-api/modules/secrets.md | 34 ++++++++++++++------ 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md index fda3a9dfa..e222b8147 100644 --- a/content/client-server-api/modules/secrets.md +++ b/content/client-server-api/modules/secrets.md @@ -73,7 +73,7 @@ For the purposes of allowing clients to check whether a user has correctly entered the key, keys for use with the `m.secret_storage.v1.aes-hmac-sha2` algorithm are stored with some additional data. -When storing a key, clients should: +When storing a key, clients SHOULD: 1. Given the secret storage key, generate 64 bytes by performing an HKDF with SHA-256 as the hash, a salt of 32 bytes of 0, and the empty @@ -90,13 +90,21 @@ When storing a key, clients should: 4. Pass the raw encrypted data through HMAC-SHA-256 using the MAC key generated above. -5. Encode the IV from step 2, and the MAC from step 4, using base64, and store - the results in the `iv` and `mac` properties respectively in the - `m.secret_storage.key.[key ID]` account-data. (The ciphertext from step 3 - is discarded after passing through the MAC calculation.) +5. Encode the IV from step 2, and the MAC from step 4, using [unpadded + base64](/appendices/#unpadded-base64), and store the results in the `iv` + and `mac` properties respectively in the `m.secret_storage.key.[key ID]` + account-data. (The ciphertext from step 3 is discarded after passing + through the MAC calculation.) This process can be repeated by a client checking if the key is correct: the -MAC should match if the key is correct. +MAC should match if the key is correct. Note, however, that these properties +are **optional**. If they are not present, clients must assume that the key is +valid. + +Note also, that although clients SHOULD use unpadded base64 as specified above, +some existing implementations use standard [RFC4648-compliant +base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4) with padding, +so clients must accept either encoding. The structure of a `m.secret_storage.key.[key ID]` account data object for use with this algorithm is therefore as follows: @@ -108,8 +116,8 @@ with this algorithm is therefore as follows: | name | string | Optional. The name of the key. | | algorithm | string | **Required.** The encryption algorithm to be used for this key: `m.secret_storage.v1.aes-hmac-sha2`. | | passphrase | object | See [deriving keys from passphrases](#deriving-keys-from-passphrases) section for a description of this property. | -| iv | string | The 16-byte initialization vector, encoded with base64. | -| mac | string | The MAC of the result of encrypting 32 bytes of 0, encoded with base64. | +| iv | string | Optional. The 16-byte initialization vector for the validation check, encoded as base64. | +| mac | string | Optional. The MAC of the result of encrypting 32 bytes of 0, encoded as base64. | For example, it could look like: @@ -216,8 +224,14 @@ HMAC-SHA-256. The secret is encrypted as follows: generated above. 5. Encode the IV from step 2, the ciphertext from step 3, and MAC from step 4, - using base64, and store them as the `iv`, `ciphertext`, and `mac` - properties respectively in the account data object. + using [unpadded base64](/appendices/#unpadded-base64), and store them as + the `iv`, `ciphertext`, and `mac` properties respectively in the account + data object. + + **Note**: some existing implementations encode these properties using + standard [RFC4648-compliant + base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4) with + padding, so clients must accept either encoding. The structure of the `encrypted` property of an account data object encrypted with this algorithm is therefore as follows: