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
on the homeserver.
In order to achieve this, a client should generate a single-use 256-bit
AES key, and encrypt the file using AES-CTR. The counter should be
64-bit long, starting at 0 and prefixed by a random 64-bit
Initialization Vector (IV), which together form a 128-bit unique counter
block.
In order to achieve this, the client generates a single-use 256-bit AES
key, and encrypts the file using AES-CTR. The counter is 64 bits long,
starting at 0 and prefixed by a random 64-bit Initialization Vector (IV),
which together form a 128-bit unique counter 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 %}}
An IV must never be used multiple times with the same key. This implies
@ -279,13 +282,14 @@ same key and IV.
{{% /boxes/warning %}}
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
`mxc://` in order to allow recipients to decrypt the file. As the event
the IV are included in the room event along with the resulting `mxc://`
in order to allow recipients to decrypt the file. As the event
containing those will be Megolm encrypted, the server will never have
access to the decrypted file.
A hash of the ciphertext must also be included, in order to prevent the
homeserver from changing the file content.
A hash of the ciphertext MUST also be included, in order to prevent the
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,
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. |
| 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. |
| 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`. |
`JWK`