fixup! document encrypted attachments

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:

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