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

Clarify what clients are required to do for attachment encryption

Browse source
This commit is contained in:
Tulir Asokan 2026-02-28 15:04:45 +02:00
parent 6b6d351ef8
commit 3e2b8ffc0b
2 changed files with 15 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2324.clarification Normal file
View file

@ -0,0 +1 @@
Clarified attachment encryption to require secure generation of keys and hash verification.

24
content/client-server-api/modules/end_to_end_encryption.md
View file

@ -265,11 +265,14 @@ field, and as a result should remove her from its list of tracked users.
When encryption is enabled in a room, files should be uploaded encrypted When encryption is enabled in a room, files should be uploaded encrypted
on the homeserver. on the homeserver.
In order to achieve this, a client should generate a single-use 256-bit In order to achieve this, the client generates a single-use 256-bit AES
AES key, and encrypt the file using AES-CTR. The counter should be key, and encrypts the file using AES-CTR. The counter is 64 bits long,
64-bit long, starting at 0 and prefixed by a random 64-bit starting at 0 and prefixed by a random 64-bit Initialization Vector (IV),
Initialization Vector (IV), which together form a 128-bit unique counter which together form a 128-bit unique counter block.
block.
Clients MUST generate both the AES key and IV using a secure random
source and MUST NOT use the same key or IV multiple times. The latter
64 bits of the 128-bit counter block MUST start at zero.
{{% boxes/warning %}} {{% boxes/warning %}}
An IV must never be used multiple times with the same key. This implies An IV must never be used multiple times with the same key. This implies
@ -279,13 +282,14 @@ same key and IV.
{{% /boxes/warning %}} {{% /boxes/warning %}}
Then, the encrypted file can be uploaded to the homeserver. The key and Then, the encrypted file can be uploaded to the homeserver. The key and
the IV must be included in the room event along with the resulting the IV are included in the room event along with the resulting `mxc://`
`mxc://` in order to allow recipients to decrypt the file. As the event in order to allow recipients to decrypt the file. As the event
containing those will be Megolm encrypted, the server will never have containing those will be Megolm encrypted, the server will never have
access to the decrypted file. access to the decrypted file.
A hash of the ciphertext must also be included, in order to prevent the A hash of the ciphertext MUST also be included, in order to prevent the
homeserver from changing the file content. homeserver from changing the file content. Clients MUST verify the hash
before using the file contents.
A client should send the data as an encrypted `m.room.message` event, A client should send the data as an encrypted `m.room.message` event,
using either `m.file` as the msgtype, or the appropriate msgtype for the using either `m.file` as the msgtype, or the appropriate msgtype for the
@ -307,7 +311,7 @@ properties.
| url | string | **Required.** The URL to the file. | | url | string | **Required.** The URL to the file. |
| key | JWK | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object. | | key | JWK | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object. |
| iv | string | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64. | | iv | string | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64. |
| hashes | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key `sha256`. | | hashes | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients MUST support the SHA-256 hash, which uses the key `sha256`. |
| v | string | **Required.** Version of the encrypted attachment's protocol. Must be `v2`. | | v | string | **Required.** Version of the encrypted attachment's protocol. Must be `v2`. |
`JWK` `JWK`