From 28ced3b0a4629b8943aa8e4b0f13e719dc67c70e Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 28 Aug 2018 15:04:40 +0200 Subject: [PATCH] fixup! document encrypted attachments --- .../schema/m.room.message.encrypted_file | 15 ++++++--- .../modules/end_to_end_encryption.rst | 32 ++++++++++--------- 2 files changed, 27 insertions(+), 20 deletions(-) diff --git a/event-schemas/schema/m.room.message.encrypted_file b/event-schemas/schema/m.room.message.encrypted_file index b1f5d1f4..4f9229b7 100644 --- a/event-schemas/schema/m.room.message.encrypted_file +++ b/event-schemas/schema/m.room.message.encrypted_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: diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index c6a8f28f..e5bc0cb0 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -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}}