From b7577ea2371bd7b97b7fdf26c1cca9721bbd9621 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 14 Jul 2018 14:22:36 +0200 Subject: [PATCH 1/5] document encrypted attachments Fix #461. --- .../examples/m.room.message.encrypted_file | 55 +++++++++++ .../schema/m.room.message.encrypted_file | 95 +++++++++++++++++++ .../modules/end_to_end_encryption.rst | 35 +++++++ 3 files changed, 185 insertions(+) create mode 100644 event-schemas/examples/m.room.message.encrypted_file create mode 100644 event-schemas/schema/m.room.message.encrypted_file diff --git a/event-schemas/examples/m.room.message.encrypted_file b/event-schemas/examples/m.room.message.encrypted_file new file mode 100644 index 000000000..1b157922d --- /dev/null +++ b/event-schemas/examples/m.room.message.encrypted_file @@ -0,0 +1,55 @@ +{ + "age": 146, + "content": { + "body": "something-important.doc", + "filename": "something-important.doc", + "file": { + "url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe", + "mimetype": "application/msword", + "v": "v2", + "key": { + "alg": "A256CTR", + "ext": true, + "k": "aWF6-32KGYaC3A_FEUCk1Bt0JA37zP0wrStgmdCaW-0", + "key_ops": ["encrypt","decrypt"], + "kty": "oct" + }, + "iv": "w+sE15fzSc0AAAAAAAAAAA", + "hashes": { + "sha256": "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA" + } + }, + "info": { + "mimetype": "application/msword", + "size": 46144, + "thumbnail_file": { + "hashes": { + "sha256": "/NogKqW5bz/m8xHgFiH5haFGjCNVmUIPLzfvOhHdrxY" + }, + "iv": "U+k7PfwLr6UAAAAAAAAAAA", + "key": { + "alg": "A256CTR", + "ext": true, + "k": "RMyd6zhlbifsACM1DXkCbioZ2u0SywGljTH8JmGcylg", + "key_ops": ["encrypt", "decrypt"], + "kty": "oct" + }, + "mimetype": "image/jpeg", + "url": "mxc://localhost/pmVJxyxGlmxHposwVSlOaEOv", + "v": "v2" + }, + "thumbnail_info": { + "h": 768, + "mimetype": "image/jpeg", + "size": 211009, + "w": 432 + } + }, + "msgtype": "m.file" + }, + "event_id": "$143273582443PhrSn:localhost", + "origin_server_ts": 1432735824653, + "room_id": "!jEsUZKDJdhlrceRyVU:localhost", + "type": "m.room.message", + "sender": "@example:localhost" +} diff --git a/event-schemas/schema/m.room.message.encrypted_file b/event-schemas/schema/m.room.message.encrypted_file new file mode 100644 index 000000000..b1f5d1f4e --- /dev/null +++ b/event-schemas/schema/m.room.message.encrypted_file @@ -0,0 +1,95 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: |- + This message represents an encrypted generic file, corresponding to a + plaintext ``m.file`` message. ``m.image``, ``m.video`` and ``m.audio`` can be + sent encrypted using the same structure. +properties: + content: + properties: + body: + description: |- + A human-readable description of the file. This is recommended to be + the filename of the original upload. + type: string + filename: + description: The original filename of the uploaded file. + type: string + info: + description: Information about the file referred to in ``url``. + properties: + mimetype: + description: The mimetype of the file e.g. ``application/msword``. + type: string + size: + description: The size of the file in bytes. + type: integer + thumbnail_file: + description: The URL to the thumbnail of the file. + title: EncryptedFile + type: object + thumbnail_info: + allOf: + - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml + description: Metadata about the image referred to in ``thumbnail_url``. + title: FileInfo + type: object + msgtype: + enum: + - m.file + type: string + file: + description: Information needed to decrypt the file. + properties: + url: + description: The URL to the file. + type: string + key: + description: A JSON web key object (as defined in RFC7517 LINK). + type: object + title: JWK + properties: + kty: + description: Key type. Must be ``oct``. + type: string + key_ops: + description: |- + Key operations. Must at least contain ``encrypt`` and ``decrypt``. + type: array + items: + type: string + alg: + description: Algorithm. Must be ``A256CTR``. + type: string + k: + description: The key, encoded as urlsafe unpadded base64. + type: string + ext: + description: Extractable. Must be ``true``.(W3C link) + type: boolean + iv: + description: The Initialisation Vector used by AES-CTR. + type: string + hashes: + description: A map from an algorithm name to a hash of the ciphertext. + type: object + additionalProperties: + type: string + v: + description: Version of the encrypted attachments protocol. + type: string + title: EncryptedFile + type: object + required: + - msgtype + - body + - file + - filename + type: object + type: + enum: + - m.room.message + type: string +title: EncryptedFileMessage +type: object diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index fa461cc28..c6a8f28fb 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -224,6 +224,39 @@ process: .. |device_lists| replace:: ``device_lists`` .. _`device_lists`: `device_lists_sync`_ + +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. + +.. 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. + +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. + +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`_. + +{{m_room_message_encrypted_file_event}} + Claiming one-time keys ~~~~~~~~~~~~~~~~~~~~~~ @@ -548,6 +581,8 @@ Example response: .. _curve25519: https://cr.yp.to/ecdh.html .. _`Olm specification`: http://matrix.org/docs/spec/olm.html .. _`Megolm specification`: http://matrix.org/docs/spec/megolm.html +.. _`JSON Web Key`: https://tools.ietf.org/html/rfc7517#appendix-A.3 +.. _`W3C extension`: https://w3c.github.io/webcrypto/#iana-section-jwk .. _`Signing JSON`: ../appendices.html#signing-json From d6f5d590f8caaa76ba7c3dc642a2386431189886 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 21 Aug 2018 21:54:37 +0200 Subject: [PATCH 2/5] add encrypted attachments changelog --- changelogs/client_server/newsfragments/1420.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1420.feature diff --git a/changelogs/client_server/newsfragments/1420.feature b/changelogs/client_server/newsfragments/1420.feature new file mode 100644 index 000000000..f7cf687df --- /dev/null +++ b/changelogs/client_server/newsfragments/1420.feature @@ -0,0 +1 @@ +Encrypt file attachments From 28ced3b0a4629b8943aa8e4b0f13e719dc67c70e Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 28 Aug 2018 15:04:40 +0200 Subject: [PATCH 3/5] 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 b1f5d1f4e..4f9229b75 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 c6a8f28fb..e5bc0cb0b 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}} From e3daf10bb965beed3e33a86b616532aa1a303870 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 31 Aug 2018 12:11:27 -0400 Subject: [PATCH 4/5] refactor encrypted file schema as "Extension to m.message" --- .../examples/m.room.message.encrypted_file | 55 -------- .../msgtype_infos/image_info.yaml | 6 + event-schemas/schema/m.room.message#m.audio | 9 +- event-schemas/schema/m.room.message#m.file | 15 ++- event-schemas/schema/m.room.message#m.image | 9 +- .../schema/m.room.message#m.location | 6 + event-schemas/schema/m.room.message#m.video | 15 ++- .../schema/m.room.message.encrypted_file | 100 --------------- .../modules/end_to_end_encryption.rst | 118 ++++++++++++++++-- 9 files changed, 162 insertions(+), 171 deletions(-) delete mode 100644 event-schemas/examples/m.room.message.encrypted_file delete mode 100644 event-schemas/schema/m.room.message.encrypted_file diff --git a/event-schemas/examples/m.room.message.encrypted_file b/event-schemas/examples/m.room.message.encrypted_file deleted file mode 100644 index 1b157922d..000000000 --- a/event-schemas/examples/m.room.message.encrypted_file +++ /dev/null @@ -1,55 +0,0 @@ -{ - "age": 146, - "content": { - "body": "something-important.doc", - "filename": "something-important.doc", - "file": { - "url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe", - "mimetype": "application/msword", - "v": "v2", - "key": { - "alg": "A256CTR", - "ext": true, - "k": "aWF6-32KGYaC3A_FEUCk1Bt0JA37zP0wrStgmdCaW-0", - "key_ops": ["encrypt","decrypt"], - "kty": "oct" - }, - "iv": "w+sE15fzSc0AAAAAAAAAAA", - "hashes": { - "sha256": "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA" - } - }, - "info": { - "mimetype": "application/msword", - "size": 46144, - "thumbnail_file": { - "hashes": { - "sha256": "/NogKqW5bz/m8xHgFiH5haFGjCNVmUIPLzfvOhHdrxY" - }, - "iv": "U+k7PfwLr6UAAAAAAAAAAA", - "key": { - "alg": "A256CTR", - "ext": true, - "k": "RMyd6zhlbifsACM1DXkCbioZ2u0SywGljTH8JmGcylg", - "key_ops": ["encrypt", "decrypt"], - "kty": "oct" - }, - "mimetype": "image/jpeg", - "url": "mxc://localhost/pmVJxyxGlmxHposwVSlOaEOv", - "v": "v2" - }, - "thumbnail_info": { - "h": 768, - "mimetype": "image/jpeg", - "size": 211009, - "w": 432 - } - }, - "msgtype": "m.file" - }, - "event_id": "$143273582443PhrSn:localhost", - "origin_server_ts": 1432735824653, - "room_id": "!jEsUZKDJdhlrceRyVU:localhost", - "type": "m.room.message", - "sender": "@example:localhost" -} diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml index 4d2a99646..210c38378 100644 --- a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml +++ b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml @@ -20,6 +20,12 @@ properties: thumbnail_url: description: The URL to a thumbnail of the image. type: string + thumbnail_file: + description: |- + Information on the encrypted thumbnail file, as specified in + |encrypted_files|_. + title: EncryptedFile + type: object thumbnail_info: allOf: - $ref: thumbnail_info.yaml diff --git a/event-schemas/schema/m.room.message#m.audio b/event-schemas/schema/m.room.message#m.audio index f15c71a3d..c258b85f5 100644 --- a/event-schemas/schema/m.room.message#m.audio +++ b/event-schemas/schema/m.room.message#m.audio @@ -27,12 +27,17 @@ properties: - m.audio type: string url: - description: The URL to the audio clip. + description: Required if the file is not encrypted. The URL to the audio clip. type: string + file: + description: |- + Required if the file is encrypted. Information on the encrypted + file, as specified in |encrypted_files|_. + title: EncryptedFile + type: object required: - msgtype - body - - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message#m.file b/event-schemas/schema/m.room.message#m.file index 76e59e09c..81f7ace6b 100644 --- a/event-schemas/schema/m.room.message#m.file +++ b/event-schemas/schema/m.room.message#m.file @@ -23,6 +23,12 @@ properties: thumbnail_url: description: The URL to the thumbnail of the file. type: string + thumbnail_file: + description: |- + Information on the encrypted thumbnail file, as specified in + |encrypted_files|_. + title: EncryptedFile + type: object thumbnail_info: allOf: - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml @@ -34,12 +40,17 @@ properties: - m.file type: string url: - description: The URL to the file. + description: Required if the file is unencrypted. The URL to the file. type: string + file: + description: |- + Required if the file is encrypted. Information on the encrypted + file, as specified in |encrypted_files|_. + title: EncryptedFile + type: object required: - msgtype - body - - url - filename type: object type: diff --git a/event-schemas/schema/m.room.message#m.image b/event-schemas/schema/m.room.message#m.image index 1237b8f80..349f78f40 100644 --- a/event-schemas/schema/m.room.message#m.image +++ b/event-schemas/schema/m.room.message#m.image @@ -17,12 +17,17 @@ properties: - m.image type: string url: - description: The URL to the image. + description: Required if the file is unencrypted. The URL to the image. type: string + file: + description: |- + Required if the file is encrypted. Information on the encrypted + file, as specified in |encrypted_files|_. + title: EncryptedFile + type: object required: - msgtype - body - - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message#m.location b/event-schemas/schema/m.room.message#m.location index e8d55769f..2d01db637 100644 --- a/event-schemas/schema/m.room.message#m.location +++ b/event-schemas/schema/m.room.message#m.location @@ -21,6 +21,12 @@ properties: thumbnail_url: description: The URL to a thumbnail of the location being represented. type: string + thumbnail_file: + description: |- + Information on the encrypted thumbnail file, as specified in + |encrypted_files|_. + title: EncryptedFile + type: object thumbnail_info: allOf: - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml diff --git a/event-schemas/schema/m.room.message#m.video b/event-schemas/schema/m.room.message#m.video index a0240b548..553678c8d 100644 --- a/event-schemas/schema/m.room.message#m.video +++ b/event-schemas/schema/m.room.message#m.video @@ -29,6 +29,12 @@ properties: thumbnail_url: description: The URL to an image thumbnail of the video clip. type: string + thumbnail_file: + description: |- + Information on the encrypted thumbnail file, as specified in + |encrypted_files|_. + title: EncryptedFile + type: object thumbnail_info: allOf: - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml @@ -40,12 +46,17 @@ properties: - m.video type: string url: - description: The URL to the video clip. + description: Required if the file is unencrypted. The URL to the video clip. type: string + file: + description: |- + Required if the file is encrypted. Information on the encrypted + file, as specified in |encrypted_files|_. + title: EncryptedFile + type: object required: - msgtype - body - - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message.encrypted_file b/event-schemas/schema/m.room.message.encrypted_file deleted file mode 100644 index 4f9229b75..000000000 --- a/event-schemas/schema/m.room.message.encrypted_file +++ /dev/null @@ -1,100 +0,0 @@ ---- -allOf: - - $ref: core-event-schema/room_event.yaml -description: |- - This message represents an encrypted generic file, corresponding to a - plaintext ``m.file`` message. ``m.image``, ``m.video`` and ``m.audio`` can be - sent encrypted using the same structure. -properties: - content: - properties: - body: - description: |- - A human-readable description of the file. This is recommended to be - the filename of the original upload. - type: string - filename: - description: The original filename of the uploaded file. - type: string - info: - description: Information about the file referred to in ``file``. - properties: - mimetype: - description: The mimetype of the file e.g. ``application/msword``. - type: string - size: - description: The size of the file in bytes. - type: integer - thumbnail_file: - description: The URL to the thumbnail of the file. - title: EncryptedFile - type: object - thumbnail_info: - allOf: - - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml - description: Metadata about the image referred to in ``thumbnail_url``. - title: FileInfo - type: object - msgtype: - enum: - - m.file - type: string - file: - description: Information needed to decrypt the file. - properties: - url: - description: The URL to the file. - type: string - key: - description: A `JSON web key`_ object. - type: object - title: JWK - properties: - kty: - description: Key type. Must be ``oct``. - type: string - key_ops: - description: |- - Key operations. Must at least contain ``encrypt`` and ``decrypt``. - type: array - items: - type: string - alg: - description: Algorithm. Must be ``A256CTR``. - type: string - k: - description: The key, encoded as urlsafe unpadded base64. - type: string - ext: - description: Extractable. Must be ``true``. This is a `W3C extension`_. - type: boolean - iv: - 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, 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: - - msgtype - - body - - file - - filename - type: object - type: - enum: - - m.room.message - type: string -title: EncryptedFileMessage -type: object diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index e5bc0cb0b..950b3041e 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -250,14 +250,116 @@ 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 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}} +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 file +type. The key is sent using the `JSON Web Key`_ format, with a `W3C +extension`_. + +.. anchor for link from m.message api spec +.. |encrypted_files| replace:: End-to-end encryption +.. _encrypted_files: + +Extensions to ``m.message`` msgtypes +<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< + +This module adds ``file`` and ``thumbnail_file`` properties to ``m.message`` +msgtypes that reference files, such as ``m.file`` and ``m.image``, replacing +the ``url`` and ``thumbnail_url`` properties. + +.. todo: generate this from a swagger definition? + +``EncryptedFile`` + +========= ================ ===================================================== +Parameter Type Description +========= ================ ===================================================== +url string The URL to the file. +key JWK A `JSON Web Key`_ object. +iv string The Initialisation Vector used by AES-CTR, encoded as + unpadded base64. +hashes {string: string} 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``. +v string Version of the encrypted attachments protocol. Must + be ``v2``. +========= ================ ===================================================== + +``JWK`` + +========= ========= ============================================================ +Parameter Type Description +========= ========= ============================================================ +key string Key type. Must be ``oct``. +key_opts [string] Key operations. Must at least contain ``encrypt`` and + ``decrypt``. +alg string Algorithm. Must be ``A256CTR``. +k string The key, encoded as urlsafe unpadded base64. +ext boolean Extractable. Must be ``true``. This is a `W3C extension`_. +========= ========= ============================================================ + +Example: + +.. code :: json + + { + "content": { + "body": "something-important.jpg", + "file": { + "url": "mxc://domain.com/FHyPlCeYUSFFxlgbQYZmoEoe", + "mimetype": "image/jpeg", + "v": "v2", + "key": { + "alg": "A256CTR", + "ext": true, + "k": "aWF6-32KGYaC3A_FEUCk1Bt0JA37zP0wrStgmdCaW-0", + "key_ops": ["encrypt","decrypt"], + "kty": "oct" + }, + "iv": "w+sE15fzSc0AAAAAAAAAAA", + "hashes": { + "sha256": "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA" + } + }, + "info": { + "mimetype": "image/jpeg", + "h": 1536, + "size": 422018, + "thumbnail_file": { + "hashes": { + "sha256": "/NogKqW5bz/m8xHgFiH5haFGjCNVmUIPLzfvOhHdrxY" + }, + "iv": "U+k7PfwLr6UAAAAAAAAAAA", + "key": { + "alg": "A256CTR", + "ext": true, + "k": "RMyd6zhlbifsACM1DXkCbioZ2u0SywGljTH8JmGcylg", + "key_ops": ["encrypt", "decrypt"], + "kty": "oct" + }, + "mimetype": "image/jpeg", + "url": "mxc://domain.com/pmVJxyxGlmxHposwVSlOaEOv", + "v": "v2" + }, + "thumbnail_info": { + "h": 768, + "mimetype": "image/jpeg", + "size": 211009, + "w": 432 + }, + "w": 864 + }, + "msgtype": "m.image" + }, + "event_id": "$143273582443PhrSn:domain.com", + "origin_server_ts": 1432735824653, + "room_id": "!jEsUZKDJdhlrceRyVU:domain.com", + "sender": "@example:domain.com", + "type": "m.room.message", + "unsigned": { + "age": 1234 + } + } Claiming one-time keys ~~~~~~~~~~~~~~~~~~~~~~ From f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 31 Aug 2018 12:59:57 -0400 Subject: [PATCH 5/5] add more clarifications --- .../msgtype_infos/image_info.yaml | 6 ++-- event-schemas/schema/m.room.message#m.file | 6 ++-- .../schema/m.room.message#m.location | 6 ++-- event-schemas/schema/m.room.message#m.video | 6 ++-- .../modules/end_to_end_encryption.rst | 36 ++++++++++--------- 5 files changed, 35 insertions(+), 25 deletions(-) diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml index 210c38378..8ff27b1e1 100644 --- a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml +++ b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml @@ -18,12 +18,14 @@ properties: description: Size of the image in bytes. type: integer thumbnail_url: - description: The URL to a thumbnail of the image. + description: |- + The URL to a thumbnail of the image. Only present if the + thumbnail is unencrypted. type: string thumbnail_file: description: |- Information on the encrypted thumbnail file, as specified in - |encrypted_files|_. + |encrypted_files|_. Only present if the thumbnail is encrypted. title: EncryptedFile type: object thumbnail_info: diff --git a/event-schemas/schema/m.room.message#m.file b/event-schemas/schema/m.room.message#m.file index 81f7ace6b..2fb4fe500 100644 --- a/event-schemas/schema/m.room.message#m.file +++ b/event-schemas/schema/m.room.message#m.file @@ -21,12 +21,14 @@ properties: description: The size of the file in bytes. type: integer thumbnail_url: - description: The URL to the thumbnail of the file. + description: |- + The URL to the thumbnail of the file. Only present if the + thumbnail is unencrypted. type: string thumbnail_file: description: |- Information on the encrypted thumbnail file, as specified in - |encrypted_files|_. + |encrypted_files|_. Only present if the thumbnail is encrypted. title: EncryptedFile type: object thumbnail_info: diff --git a/event-schemas/schema/m.room.message#m.location b/event-schemas/schema/m.room.message#m.location index 2d01db637..ffc4edcee 100644 --- a/event-schemas/schema/m.room.message#m.location +++ b/event-schemas/schema/m.room.message#m.location @@ -19,12 +19,14 @@ properties: type: object properties: thumbnail_url: - description: The URL to a thumbnail of the location being represented. + description: |- + The URL to the thumbnail of the file. Only present if the + thumbnail is unencrypted. type: string thumbnail_file: description: |- Information on the encrypted thumbnail file, as specified in - |encrypted_files|_. + |encrypted_files|_. Only present if the thumbnail is encrypted. title: EncryptedFile type: object thumbnail_info: diff --git a/event-schemas/schema/m.room.message#m.video b/event-schemas/schema/m.room.message#m.video index 553678c8d..8a66fdeb5 100644 --- a/event-schemas/schema/m.room.message#m.video +++ b/event-schemas/schema/m.room.message#m.video @@ -27,12 +27,14 @@ properties: description: The size of the video in bytes. type: integer thumbnail_url: - description: The URL to an image thumbnail of the video clip. + description: |- + The URL to an image thumbnail of the video clip. Only present if the + thumbnail is unencrypted. type: string thumbnail_file: description: |- Information on the encrypted thumbnail file, as specified in - |encrypted_files|_. + |encrypted_files|_. Only present if the thumbnail is encrypted. title: EncryptedFile type: object thumbnail_info: diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 950b3041e..c5e40a886 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -262,9 +262,10 @@ extension`_. Extensions to ``m.message`` msgtypes <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< -This module adds ``file`` and ``thumbnail_file`` properties to ``m.message`` -msgtypes that reference files, such as ``m.file`` and ``m.image``, replacing -the ``url`` and ``thumbnail_url`` properties. +This module adds ``file`` and ``thumbnail_file`` properties, of type +``EncryptedFile``, to ``m.message`` msgtypes that reference files, such as +`m.file`_ and `m.image`_, replacing the ``url`` and ``thumbnail_url`` +properties. .. todo: generate this from a swagger definition? @@ -273,16 +274,16 @@ the ``url`` and ``thumbnail_url`` properties. ========= ================ ===================================================== Parameter Type Description ========= ================ ===================================================== -url string The URL to the file. -key JWK A `JSON Web Key`_ object. -iv string The Initialisation Vector used by AES-CTR, encoded as - unpadded base64. -hashes {string: string} A map from an algorithm name to a hash of the - ciphertext, encoded as unpadded base64. Clients +url string **Required.** The URL to the file. +key JWK **Required.** A `JSON Web Key`_ object. +iv string **Required.** The Initialisation Vector 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``. -v string Version of the encrypted attachments protocol. Must - be ``v2``. +v string **Required.** Version of the encrypted attachments + protocol. Must be ``v2``. ========= ================ ===================================================== ``JWK`` @@ -290,12 +291,13 @@ v string Version of the encrypted attachments protocol. Must ========= ========= ============================================================ Parameter Type Description ========= ========= ============================================================ -key string Key type. Must be ``oct``. -key_opts [string] Key operations. Must at least contain ``encrypt`` and - ``decrypt``. -alg string Algorithm. Must be ``A256CTR``. -k string The key, encoded as urlsafe unpadded base64. -ext boolean Extractable. Must be ``true``. This is a `W3C extension`_. +key string **Required.** Key type. Must be ``oct``. +key_opts [string] **Required.** Key operations. Must at least contain + ``encrypt`` and ``decrypt``. +alg string **Required.** Algorithm. Must be ``A256CTR``. +k string **Required.** The key, encoded as urlsafe unpadded base64. +ext boolean **Required.** Extractable. Must be ``true``. This is a + `W3C extension`_. ========= ========= ============================================================ Example: