Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-10 05:24:10 +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. description: The original filename of the uploaded file.
type: string type: string
info: info:
description: Information about the file referred to in ``url``. description: Information about the file referred to in ``file``.
properties: properties:
mimetype: mimetype:
description: The mimetype of the file e.g. ``application/msword``. description: The mimetype of the file e.g. ``application/msword``.
@ -46,7 +46,7 @@ properties:
description: The URL to the file. description: The URL to the file.
type: string type: string
key: key:
description: A JSON web key object (as defined in RFC7517 LINK). description: A `JSON web key`_ object.
type: object type: object
title: JWK title: JWK
properties: properties:
@ -66,19 +66,24 @@ properties:
description: The key, encoded as urlsafe unpadded base64. description: The key, encoded as urlsafe unpadded base64.
type: string type: string
ext: ext:
description: Extractable. Must be ``true``.(W3C link) description: Extractable. Must be ``true``. This is a `W3C extension`_.
type: boolean type: boolean
iv: iv:
description: The Initialisation Vector used by AES-CTR. description: |-
The Initialisation Vector used by AES-CTR, encoded as unpadded
base64.
type: string type: string
hashes: 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 type: object
additionalProperties: additionalProperties:
type: string type: string
v: v:
description: Version of the encrypted attachments protocol. description: Version of the encrypted attachments protocol.
type: string type: string
enum: ["v2"]
title: EncryptedFile title: EncryptedFile
type: object type: object
required: 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 When encryption is enabled in a room, files should be uploaded encrypted on
the homeserver. the homeserver.
In order to achieve this, a client should generate a single-use 256 bits AES key. In order to achieve this, a client should generate a single-use 256-bit AES
Then, it should encrypt the file using AES-CTR. The counter should be 64 bits long, key, and encrypt the file using AES-CTR. The counter should be 64-bit long,
starting at 0 and prefixed by a random 64 bits Initialization Vector (IV), which starting at 0 and prefixed by a random 64-bit Initialization Vector (IV), which
together form a 128 bits unique counter block. together form a 128-bit unique counter block.
.. Warning:: .. Warning::
An IV must never be used multiple times with the same key. This implies that if there An IV must never be used multiple times with the same key. This implies that
are multiple files to encrypt in the same message, typically an image and its thumbnail, if there are multiple files to encrypt in the same message, typically an
the key may be reused, but not the IV. 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. 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 The key and the IV must be included in the room event along with the resulting
recipients to decrypt the file. As the event containing those will be Megolm encrypted, ``mxc://`` in order to allow recipients to decrypt the file. As the event
the server will never have access to the decrypted file. 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 A hash of the ciphertext must also be included, in order to prevent the homeserver from
changing the file content. changing the file content.
A client should send those data as a ``m.room.message``. The structure is similar to A client should send the data as a ``m.room.message`` event, using either
a ``m.file`` message or equivalent. The two differing keys are ``url`` and ``m.file`` as the msgtype, or the appropriate msgtype for the file type. The
``thumbnail_url``, which are replaced respectively by ``file`` and ``thumbnail_file``, structure is similar to an unencrypted file message, except for two differing
containing an ``EncryptedFile`` object as specified below. The key is sent using keys: ``url`` and ``thumbnail_url`` are replaced respectively by ``file`` and
the `JSON Web Key`_ format, with a `W3C extension`_. ``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}} {{m_room_message_encrypted_file_event}}