From 9e4503712960a3cfcbf85531e8e2215b9962d8fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 3 Jan 2023 08:46:03 +0100 Subject: [PATCH] Remove `keyId` from the server keys endpoints (#1350) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Remove keyId from the server keys endpoints It has been deprecated forever. Besides, the OpenAPI 3 spec doesn't allow optional path parameters. Signed-off-by: Kévin Commaille * Add newsfragment Signed-off-by: Kévin Commaille * Fix broken link Signed-off-by: Kévin Commaille * Mention MSC3938 in newfragment Signed-off-by: Kévin Commaille Signed-off-by: Kévin Commaille --- .../server_server/newsfragments/1350.breaking | 1 + .../rooms/fragments/v5-signing-requirements.md | 2 +- content/server-server-api.md | 10 +++++----- data/api/server-server/keys_query.yaml | 13 +------------ data/api/server-server/keys_server.yaml | 15 +-------------- 5 files changed, 9 insertions(+), 32 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1350.breaking diff --git a/changelogs/server_server/newsfragments/1350.breaking b/changelogs/server_server/newsfragments/1350.breaking new file mode 100644 index 00000000..81ce2585 --- /dev/null +++ b/changelogs/server_server/newsfragments/1350.breaking @@ -0,0 +1 @@ +Remove `keyId` from the server `/keys` endpoints, as per [MSC3938](https://github.com/matrix-org/matrix-spec-proposals/pull/3938). diff --git a/content/rooms/fragments/v5-signing-requirements.md b/content/rooms/fragments/v5-signing-requirements.md index 136c1c13..ae1d0675 100644 --- a/content/rooms/fragments/v5-signing-requirements.md +++ b/content/rooms/fragments/v5-signing-requirements.md @@ -3,7 +3,7 @@ When validating event signatures, servers MUST enforce the `valid_until_ts` property from a key request is at least as large as the `origin_server_ts` for the event being validated. Servers missing a copy of the signing key MUST try to obtain one via the [GET -/\_matrix/key/v2/server](/server-server-api#get_matrixkeyv2serverkeyid) +/\_matrix/key/v2/server](/server-server-api#get_matrixkeyv2server) or [POST /\_matrix/key/v2/query](/server-server-api#post_matrixkeyv2query) APIs. When using the `/query` endpoint, servers MUST set the diff --git a/content/server-server-api.md b/content/server-server-api.md index 724e3220..13bd9934 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -208,11 +208,11 @@ draft](https://github.com/matrix-org/matrix-doc/blob/51faf8ed2e4a63d4cfd6d231836 {{% /boxes/note %}} Each homeserver publishes its public keys under -`/_matrix/key/v2/server/{keyId}`. Homeservers query for keys by either -getting `/_matrix/key/v2/server/{keyId}` directly or by querying an +`/_matrix/key/v2/server`. Homeservers query for keys by either +getting `/_matrix/key/v2/server` directly or by querying an intermediate notary server using a -`/_matrix/key/v2/query/{serverName}/{keyId}` API. Intermediate notary -servers query the `/_matrix/key/v2/server/{keyId}` API on behalf of +`/_matrix/key/v2/query/{serverName}` API. Intermediate notary +servers query the `/_matrix/key/v2/server` API on behalf of another server and sign the response with their own key. A server may query multiple notary servers to ensure that they all report the same public keys. @@ -239,7 +239,7 @@ homeserver and for signing events. It contains a list of Servers may query another server's keys through a notary server. The notary server may be another homeserver. The notary server will retrieve keys from the queried servers through use of the -`/_matrix/key/v2/server/{keyId}` API. The notary server will +`/_matrix/key/v2/server` API. The notary server will additionally sign the response from the queried server before returning the results. diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index cad6b882..5857ce31 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -25,7 +25,7 @@ consumes: produces: - application/json paths: - "/query/{serverName}/{keyId}": + "/query/{serverName}": get: summary: Query for another server's keys description: |- @@ -39,17 +39,6 @@ paths: description: The server's DNS name to query required: true x-example: matrix.org - - in: path - name: keyId - type: string - description: |- - **Deprecated**. Servers should not use this parameter and instead - opt to return all keys, not just the requested one. The key ID to - look up. - - When excluded, the trailing slash on this endpoint is optional. - required: false - x-example: "ed25519:abc123" - in: query name: minimum_valid_until_ts type: integer diff --git a/data/api/server-server/keys_server.yaml b/data/api/server-server/keys_server.yaml index 81b98b1e..bee520f3 100644 --- a/data/api/server-server/keys_server.yaml +++ b/data/api/server-server/keys_server.yaml @@ -23,7 +23,7 @@ basePath: /_matrix/key/v2 produces: - application/json paths: - "/server/{keyId}": + "/server": get: summary: Get the homeserver's public key(s) description: |- @@ -43,19 +43,6 @@ paths: from the server so that the signatures of old events can still be checked. operationId: getServerKey - parameters: - - in: path - name: keyId - type: string - description: |- - **Deprecated**. Servers should not use this parameter and instead - opt to return all keys, not just the requested one. The key ID to - look up. - - When excluded, the trailing slash on this endpoint is optional. - required: false - x-example: "ed25519:abc123" - deprecated: true responses: 200: description: The homeserver's keys