Use OpenAPI definition for EncryptedFile.

... instead of the ad-hoc table we have currently.

content/appendices.md

@@ -12,7 +12,7 @@ Specifically, where RFC 4648 requires that encoded data be padded to a
 multiple of four characters using `=` characters, unpadded Base64 omits
 this padding.
 
-For reference, RFC 4648 uses the following alphabet for Base 64:
+For reference, RFC 4648 uses the following alphabet for Base64:
 
     Value Encoding  Value Encoding  Value Encoding  Value Encoding
         0 A            17 R            34 i            51 z
@@ -47,6 +47,12 @@ When decoding Base64, implementations SHOULD accept input with or
 without padding characters wherever possible, to ensure maximum
 interoperability.
 
+### URL-safe unpadded Base64
+
+URL-safe unpadded Base64 is identical to standard unpadded Base64, except that
+it uses `-` (minus) as the 62nd character in the alphabet, and `_` (underscore)
+as the 63rd.
+
 ## Binary data
 
 In some cases it is necessary to encapsulate binary data, for example,

content/client-server-api/modules/end_to_end_encryption.md

@@ -385,31 +385,11 @@ Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) format, with a
 ###### Extensions to `m.room.message` msgtypes
 
 This module adds `file` and `thumbnail_file` properties, of type
-`EncryptedFile`, to `m.room.message` msgtypes that reference files, such
+[`EncryptedFile`](#definition-encryptedfile), to `m.room.message` msgtypes that
-as [m.file](#mfile) and [m.image](#mimage), replacing the `url` and `thumbnail_url`
+reference files, such as [m.file](#mfile) and [m.image](#mimage), replacing the
-properties.
+`url` and `thumbnail_url` properties.
 
-`EncryptedFile`
+Example `m.room.message` event containing an encrypted image:
-
-| Parameter | Type             | Description                                                                                    |
-|-----------|------------------|------------------------------------------------------------------------------------------------|
-| url       | string           | **Required.** The URL to the file.                                                             |
-| key       | JWK              | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.       |
-| iv        | string           | **Required.** The 128-bit unique counter block 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 MUST support the SHA-256 hash, which uses the key `sha256`. |
-| v         | string           | **Required.** Version of the encrypted attachment's protocol. Must be `v2`.                    |
-
-`JWK`
-
-| Parameter | Type     | Description                                                                                                              |
-| --------- |----------|--------------------------------------------------------------------------------------------------------------------------|
-| kty       | string   | **Required.** Key type. Must be `oct`.                                                                                   |
-| key_ops   | [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](https://w3c.github.io/webcrypto/#iana-section-jwk). |
-
-Example:
 
 ```json
 {
@@ -470,6 +450,8 @@ Example:
 }
 ```
 
+{{% definition path="api/client-server/definitions/encrypted_file" %}}
+
 #### Device verification
 
 Before Alice sends Bob encrypted data, or trusts data received from him,

data/api/client-server/definitions/encrypted_file.yaml

@@ -0,0 +1,84 @@
+# Copyright 2018-2026 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: EncryptedFile
+description: |
+  Information on an encrypted media blob, including its location in the
+  [content repository](/client-server-api/#content-repository), and the keys
+  necessary to decrypt it.
+properties:
+  url:
+    type: string
+    format: mx-mxc-uri
+    description: The URL to the file.
+    example: "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
+  key:
+    type: object
+    title: JWK
+    description: A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.
+    properties:
+      kty:
+        type: string
+        description: Key type. Must be `oct`.
+        example: "oct"
+      key_ops:
+        type: array
+        items:
+          type: string
+        description: Key operations. Must at least contain `encrypt` and `decrypt`.
+        example: ["encrypt", "decrypt"]
+      alg:
+        type: string
+        description: Algorithm. Must be `A256CTR`.
+        example: A256CTR
+      k:
+        type: string
+        description: The key, encoded as [URL-safe unpadded Base64](/appendices/#url-safe-unpadded-base64).
+        example: "aWF6-32KGYaC3A_FEUCk1Bt0JA37zP0wrStgmdCaW-0"
+      ext:
+        type: boolean
+        description: "Extractable. Must be `true`. This is a [W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk)."
+        example: true
+    required:
+      - kty
+      - key_ops
+      - alg
+      - k
+      - ext
+  iv:
+    type: string
+    description: The 128-bit unique counter block used by AES-CTR, encoded as [unpadded Base64](/appendices/#unpadded-base64).
+    example: "w+sE15fzSc0AAAAAAAAAAA"
+  hashes:
+    type: object
+    title: EncryptedFileHashes
+    description:
+      A map from an algorithm name to a hash of the ciphertext. Clients MUST support the SHA-256 hash, which uses the key `sha256`.
+    properties:
+      sha256:
+        type: string
+        description: The hash of the ciphertext. encoded as [unpadded Base64](/appendices/#unpadded-base64).
+        example: "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA"
+    required: ['sha256']
+  v:
+    type: string
+    description: Version of the encrypted attachment’s protocol. Must be `v2`.
+    example: v2
+required:
+  - url
+  - key
+  - iv
+  - hashes
+  - v