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

fixup! document encrypted attachments

Browse source
This commit is contained in:
Valentin Deniaud 2018-08-28 15:04:40 +02:00
parent d6f5d590f8
commit 28ced3b0a4
2 changed files with 27 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
event-schemas/schema/m.room.message.encrypted_file
View file

@ -17,7 +17,7 @@ properties:
description: The original filename of the uploaded file.
type: string
info:
description: Information about the file referred to in ``url``.
description: Information about the file referred to in ``file``.
properties:
mimetype:
description: The mimetype of the file e.g. ``application/msword``.
@ -46,7 +46,7 @@ properties:
description: The URL to the file.
type: string
key:
description: A JSON web key object (as defined in RFC7517 LINK).
description: A `JSON web key`_ object.
type: object
title: JWK
properties:
@ -66,19 +66,24 @@ properties:
description: The key, encoded as urlsafe unpadded base64.
type: string
ext:
description: Extractable. Must be ``true``.(W3C link)
description: Extractable. Must be ``true``. This is a `W3C extension`_.
type: boolean
iv:
description: The Initialisation Vector used by AES-CTR.
description: |-
The Initialisation Vector used by AES-CTR, encoded as unpadded
base64.
type: string
hashes:
description: A map from an algorithm name to a hash of the ciphertext.
description: |-
A map from an algorithm name to a hash of the ciphertext, encoded
as unpadded base64. Clients should support the SHA-256 hash.
type: object
additionalProperties:
type: string
v:
description: Version of the encrypted attachments protocol.
type: string
enum: ["v2"]
title: EncryptedFile
type: object
required:

32
specification/modules/end_to_end_encryption.rst
View file

@ -231,29 +231,31 @@ Sending encrypted attachments
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 bits AES key.
Then, it should encrypt the file using AES-CTR. The counter should be 64 bits long,
starting at 0 and prefixed by a random 64 bits Initialization Vector (IV), which
together form a 128 bits unique counter block.
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.
.. Warning::
An IV must never be used multiple times with the same key. This implies that if there
are multiple files to encrypt in the same message, typically an image and its thumbnail,
the key may be reused, but not the IV.
An IV must never be used multiple times with the same key. This implies that
if there are multiple files to encrypt in the same message, typically an
image and its thumbnail, the files must not share both the same key and IV.
Then, the encrypted file can be uploaded to the homeserver.
The key and the IV must be shared 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.
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
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 client should send those data as a ``m.room.message``. The structure is similar to
a ``m.file`` message or equivalent. The two differing keys are ``url`` and
``thumbnail_url``, which are replaced respectively by ``file`` and ``thumbnail_file``,
containing an ``EncryptedFile`` object as specified below. The key is sent using
the `JSON Web Key`_ format, with a `W3C extension`_.
A client should send the data as a ``m.room.message`` event, using either
``m.file`` as the msgtype, or the appropriate msgtype for the file type. The
structure is similar to an unencrypted file message, except for two differing
keys: ``url`` and ``thumbnail_url`` are replaced respectively by ``file`` and
``thumbnail_file``, containing an ``EncryptedFile`` object as specified below.
The key is sent using the `JSON Web Key`_ format, with a `W3C extension`_.
{{m_room_message_encrypted_file_event}}