Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-26 04:54:10 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Clarify that base64 may or may not be padded

Browse source
This commit is contained in:
Richard van der Hoff 2023-12-11 15:14:40 +00:00
parent 162fa9829a
commit b9c1f95aab
1 changed files with 24 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
content/client-server-api/modules/secrets.md
View file

@ -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` entered the key, keys for use with the `m.secret_storage.v1.aes-hmac-sha2`
algorithm are stored with some additional data. 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 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 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 4. Pass the raw encrypted data through HMAC-SHA-256 using the MAC key
generated above. generated above.
5. Encode the IV from step 2, and the MAC from step 4, using base64, and store 5. Encode the IV from step 2, and the MAC from step 4, using [unpadded
the results in the `iv` and `mac` properties respectively in the base64](/appendices/#unpadded-base64), and store the results in the `iv`
`m.secret_storage.key.[key ID]` account-data. (The ciphertext from step 3 and `mac` properties respectively in the `m.secret_storage.key.[key ID]`
is discarded after passing through the MAC calculation.) 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 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 The structure of a `m.secret_storage.key.[key ID]` account data object for use
with this algorithm is therefore as follows: 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. | | 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`. | | 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. | | 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. | | iv | string | Optional. The 16-byte initialization vector for the validation check, encoded as base64. |
| mac | string | The MAC of the result of encrypting 32 bytes of 0, encoded with base64. | | mac | string | Optional. The MAC of the result of encrypting 32 bytes of 0, encoded as base64. |
For example, it could look like: For example, it could look like:
@ -216,8 +224,14 @@ HMAC-SHA-256. The secret is encrypted as follows:
generated above. generated above.
5. Encode the IV from step 2, the ciphertext from step 3, and MAC from step 4, 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` using [unpadded base64](/appendices/#unpadded-base64), and store them as
properties respectively in the account data object. 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 The structure of the `encrypted` property of an account data object encrypted
with this algorithm is therefore as follows: with this algorithm is therefore as follows: