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

Merge 3e2b8ffc0b into be21886a73

Browse source
This commit is contained in:
Tulir Asokan 2026-02-28 13:13:49 +00:00 committed by GitHub
parent be21886a73 3e2b8ffc0b
commit 1b6f57b94f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
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

@ -350,11 +350,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
@ -364,13 +367,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
@ -392,7 +396,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`