Merge pull request #2639 from uhoreg/backup_version_required

various key backups fixes

api/client-server/definitions/room_key_backup.yaml

@@ -0,0 +1,38 @@
+# Copyright 2020 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: RoomKeyBackup
+description: "The backed up keys for a room."
+properties:
+  sessions:
+    type: object
+    description: "A map of session IDs to key data."
+    additionalProperties:
+      allOf:
+        - $ref: "key_backup_data.yaml"
+    example: {
+      "sessionid1": {
+        "first_message_index": 1,
+        "forwarded_count": 0,
+        "is_verified": true,
+        "session_data": {
+          "ephemeral": "base64+ephemeral+key",
+          "ciphertext": "base64+ciphertext+of+JSON+data",
+          "mac": "base64+mac+of+ciphertext"
+        }
+      }
+    }
+required:
+  - sessions

api/client-server/key_backup.yaml

@@ -130,7 +130,7 @@ paths:
                 example: "anopaquestring"
               version:
                 type: string
-                description: The backup version
+                description: The backup version.
                 example: "1"
             required:
               - algorithm
@@ -212,7 +212,7 @@ paths:
                 example: "anopaquestring"
               version:
                 type: string
-                description: The backup version
+                description: The backup version.
                 example: "1"
             required:
               - algorithm
@@ -450,7 +450,7 @@ paths:
           type: string
           name: version
           description: |-
-            The backup from which to retrieve the key
+            The backup from which to retrieve the key.
           required: true
           x-example: "1"
         - in: path
@@ -569,22 +569,7 @@ paths:
           description: "The backup data"
           name: backupData
           schema:
-            type: object
+            $ref: "definitions/room_key_backup.yaml"
-            properties:
-              sessions:
-                type: object
-                description: |-
-                  A map of session IDs to key data.
-                additionalProperties:
-                  allOf:
-                    - $ref: "definitions/key_backup_data.yaml"
-                example: {
-                  "sessionid1": {
-                    "ephemeral": "base64+ephemeral+key",
-                    "ciphertext": "base64+ciphertext+of+JSON+data",
-                    "mac": "base64+mac+of+ciphertext"
-                  }
-                }
       responses:
         200:
           description: The update succeeded
@@ -645,7 +630,7 @@ paths:
           type: string
           name: version
           description: |-
-            The backup from which to retrieve the key
+            The backup from which to retrieve the key.
           required: true
           x-example: "1"
         - in: path
@@ -661,21 +646,7 @@ paths:
             ``sessions`` property will be returned (``{"sessions": {}}``).
           schema:
             type: object
-            properties:
+            $ref: "definitions/room_key_backup.yaml"
-              sessions:
-                type: object
-                description: |-
-                  A map of session IDs to key data.
-                additionalProperties:
-                  allOf:
-                    - $ref: "definitions/key_backup_data.yaml"
-                example: {
-                  "sessionid1": {
-                    "ephemeral": "base64+ephemeral+key",
-                    "ciphertext": "base64+ciphertext+of+JSON+data",
-                    "mac": "base64+mac+of+ciphertext"
-                  }
-                }
         404:
           description: |-
             The backup was not found.
@@ -702,7 +673,7 @@ paths:
           type: string
           name: version
           description: |-
-            The backup from which to delete the key
+            The backup from which to delete the key.
           required: true
           x-example: "1"
         - in: path
@@ -761,7 +732,7 @@ paths:
           required: true
           x-example: "1"
         - in: body
-          description: "The backup data"
+          description: "The backup data."
           name: backupData
           schema:
             type: object
@@ -769,23 +740,28 @@ paths:
               rooms:
                 type: object
                 description: |-
-                  A map of room IDs to session IDs to key data.
+                  A map of room IDs to room key backup data.
                 additionalProperties:
-                  type: object
+                  allOf:
-                  additionalProperties:
+                    - $ref: "definitions/room_key_backup.yaml"
-                    allOf:
-                      - $ref: "definitions/key_backup_data.yaml"
                 example: {
                   "!room:example.org": {
                     "sessions": {
                       "sessionid1": {
-                        "ephemeral": "base64+ephemeral+key",
+                        "first_message_index": 1,
-                        "ciphertext": "base64+ciphertext+of+JSON+data",
+                        "forwarded_count": 0,
-                        "mac": "base64+mac+of+ciphertext"
+                        "is_verified": true,
+                        "session_data": {
+                          "ephemeral": "base64+ephemeral+key",
+                          "ciphertext": "base64+ciphertext+of+JSON+data",
+                          "mac": "base64+mac+of+ciphertext"
+                        }
                       }
                     }
                   }
                 }
+            required:
+              - rooms
       responses:
         200:
           description: The update succeeded
@@ -846,8 +822,8 @@ paths:
           type: string
           name: version
           description: |-
-            The backup from which to retrieve the keys. If omitted, the keys are
+            The backup from which to retrieve the keys.
-            retrieved from the current backup.
+          required: true
           x-example: "1"
       responses:
         200:
@@ -860,19 +836,22 @@ paths:
               rooms:
                 type: object
                 description: |-
-                  A map of room IDs to session IDs to key data.
+                  A map of room IDs to room key backup data.
                 additionalProperties:
-                  type: object
+                  allOf:
-                  additionalProperties:
+                    - $ref: "definitions/room_key_backup.yaml"
-                    allOf:
-                      - $ref: "definitions/key_backup_data.yaml"
                 example: {
                   "!room:example.org": {
                     "sessions": {
                       "sessionid1": {
-                        "ephemeral": "base64+ephemeral+key",
+                        "first_message_index": 1,
-                        "ciphertext": "base64+ciphertext+of+JSON+data",
+                        "forwarded_count": 0,
-                        "mac": "base64+mac+of+ciphertext"
+                        "is_verified": true,
+                        "session_data": {
+                          "ephemeral": "base64+ephemeral+key",
+                          "ciphertext": "base64+ciphertext+of+JSON+data",
+                          "mac": "base64+mac+of+ciphertext"
+                        }
                       }
                     }
                   }

changelogs/client_server/2639.clarification

@@ -0,0 +1 @@
+Fixed some errors in the key backup spec.