From af6e1157d90dc8976e4f3892a5c1abb9fb0ecdf7 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 16 Jun 2020 14:23:10 -0400 Subject: [PATCH 1/3] version is required when getting keys. Also add some full stops. --- api/client-server/key_backup.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/api/client-server/key_backup.yaml b/api/client-server/key_backup.yaml index 34dce118..a0baccc3 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 @@ -645,7 +645,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 @@ -702,7 +702,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 @@ -846,8 +846,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: From 24427242f7f78f7b633e43f7c5b1818c2fe2ad4f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 16 Jun 2020 17:00:29 -0400 Subject: [PATCH 2/3] fix more mistakes in key backup spec, and factor out room key backups --- .../definitions/room_key_backup.yaml | 38 ++++++++++ api/client-server/key_backup.yaml | 75 +++++++------------ 2 files changed, 65 insertions(+), 48 deletions(-) create mode 100644 api/client-server/definitions/room_key_backup.yaml 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 a0baccc3..31c66a25 100644 --- a/api/client-server/key_backup.yaml +++ b/api/client-server/key_backup.yaml @@ -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 @@ -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. @@ -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 @@ -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" + } } } } From b44ebaa32e2e81b6b875bd66a82233d26e18e063 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 16 Jun 2020 17:06:36 -0400 Subject: [PATCH 3/3] add changelog --- changelogs/client_server/2639.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/2639.clarification 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