diff --git a/api/client-server/definitions/room_key_backup.yaml b/api/client-server/definitions/room_key_backup.yaml new file mode 100644 index 00000000..5c70850f --- /dev/null +++ b/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 diff --git a/api/client-server/key_backup.yaml b/api/client-server/key_backup.yaml index 34dce118..31c66a25 100644 --- a/api/client-server/key_backup.yaml +++ b/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 - 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" - } - } + $ref: "definitions/room_key_backup.yaml" 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: - 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" - } - } + $ref: "definitions/room_key_backup.yaml" 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 - additionalProperties: - allOf: - - $ref: "definitions/key_backup_data.yaml" + allOf: + - $ref: "definitions/room_key_backup.yaml" example: { "!room:example.org": { "sessions": { "sessionid1": { - "ephemeral": "base64+ephemeral+key", - "ciphertext": "base64+ciphertext+of+JSON+data", - "mac": "base64+mac+of+ciphertext" + "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: + - 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 - retrieved from the current backup. + The backup from which to retrieve the keys. + 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 - additionalProperties: - allOf: - - $ref: "definitions/key_backup_data.yaml" + allOf: + - $ref: "definitions/room_key_backup.yaml" example: { "!room:example.org": { "sessions": { "sessionid1": { - "ephemeral": "base64+ephemeral+key", - "ciphertext": "base64+ciphertext+of+JSON+data", - "mac": "base64+mac+of+ciphertext" + "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" + } } } } diff --git a/changelogs/client_server/2639.clarification b/changelogs/client_server/2639.clarification new file mode 100644 index 00000000..7d7032ba --- /dev/null +++ b/changelogs/client_server/2639.clarification @@ -0,0 +1 @@ +Fixed some errors in the key backup spec. \ No newline at end of file