diff --git a/changelogs/client_server/newsfragments/2029.clarification b/changelogs/client_server/newsfragments/2029.clarification new file mode 100644 index 00000000..74050082 --- /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 001fe1f5..de4501b3 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 6f242614..059dcae4 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: []