refactor encrypted file schema as "Extension to m.message"

event-schemas/examples/m.room.message.encrypted_file

@@ -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"
-}

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

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:

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:

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:

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

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:

event-schemas/schema/m.room.message.encrypted_file

@@ -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

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
+A client should send the data as an encrypted ``m.room.message`` event, using
-``m.file`` as the msgtype, or the appropriate msgtype for the file type. The
+either ``m.file`` as the msgtype, or the appropriate msgtype for the file
-structure is similar to an unencrypted file message, except for two differing
+type. The key is sent using the `JSON Web Key`_ format, with a `W3C
-keys: ``url`` and ``thumbnail_url`` are replaced respectively by ``file`` and
+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}}
+.. 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
 ~~~~~~~~~~~~~~~~~~~~~~