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 1b157922..00000000 --- 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 4d2a9964..210c3837 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 f15c71a3..c258b85f 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 76e59e09..81f7ace6 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 1237b8f8..349f78f4 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 e8d55769..2d01db63 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 a0240b54..553678c8 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 4f9229b7..00000000 --- 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 e5bc0cb0..950b3041 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 ~~~~~~~~~~~~~~~~~~~~~~