Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-23 19:44:09 +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`
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: