From 35c3ddb33b7ade30947bf020010a996b5f1f0c11 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 12 Dec 2024 15:53:21 +0000 Subject: [PATCH] Specify the order in which one-time keys are returned (MSC4225) (#2029) Signed-off-by: Andy Balaam --- .../newsfragments/2029.clarification | 1 + data/api/client-server/keys.yaml | 17 ++++++++++++++++- data/api/server-server/user_keys.yaml | 17 ++++++++++++++++- 3 files changed, 33 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2029.clarification diff --git a/changelogs/client_server/newsfragments/2029.clarification b/changelogs/client_server/newsfragments/2029.clarification new file mode 100644 index 000000000..74050082e --- /dev/null +++ b/changelogs/client_server/newsfragments/2029.clarification @@ -0,0 +1 @@ +Specify order that one-time keys are issued by `/keys/claim`, as per [MSC4225](https://github.com/matrix-org/matrix-spec-proposals/pull/4225). diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index 001fe1f52..de4501b34 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -288,7 +288,22 @@ paths: /keys/claim: post: summary: Claim one-time encryption keys. - description: Claims one-time keys for use in pre-key messages. + description: |- + Claims one-time keys for use in pre-key messages. + + The request contains the user ID, device ID and algorithm name of the + keys that are required. If a key matching these requirements can be + found, the response contains it. The returned key is a one-time key + if one is available, and otherwise a fallback key. + + One-time keys are given out in the order that they were uploaded via + [/keys/upload](/client-server-api/#post_matrixclientv3keysupload). (All + keys uploaded within a given call to `/keys/upload` are considered + equivalent in this regard; no ordering is specified within them.) + + Servers must ensure that each one-time key is returned at most once, + so when a key has been returned, no other request will ever return + the same key. operationId: claimKeys security: - accessTokenQuery: [] diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index 6f242614a..059dcae41 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -20,7 +20,22 @@ paths: /user/keys/claim: post: summary: Claims one-time encryption keys for a user. - description: Claims one-time keys for use in pre-key messages. + description: |- + Claims one-time keys for use in pre-key messages. + + The request contains the user ID, device ID and algorithm name of the + keys that are required. If a key matching these requirements can be + found, the response contains it. The returned key is a one-time key + if one is available, and otherwise a fallback key. + + One-time keys are given out in the order that they were uploaded via + [/keys/upload](/client-server-api/#post_matrixclientv3keysupload). (All + keys uploaded within a given call to `/keys/upload` are considered + equivalent in this regard; no ordering is specified within them.) + + Servers must ensure that each one-time key is returned at most once, + so when a key has been returned, no other request will ever return + the same key. operationId: claimUserEncryptionKeys security: - signedRequest: []