From 73958ecbffbf1ea996961e92d78e354ceb914200 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 2 Aug 2018 16:41:24 -0600 Subject: [PATCH 1/2] Document /event_auth and /query_auth /event_auth is a fairly easy endpoint to determine the use case of. /query_auth is a little harder to investigate and has a fairly interesting purpose: it appears to be used for the sending server to admit defeat and shop around for the right auth chain, correcting it's own perspective as it goes. /query_auth is based off the following research points in synapse: * https://github.com/matrix-org/synapse/blob/43ecfe0b1028fea5e4dda197f5631aed67182ee6/synapse/handlers/federation.py#L1947-L1990 * https://github.com/matrix-org/synapse/blob/43ecfe0b1028fea5e4dda197f5631aed67182ee6/synapse/handlers/federation.py#L2049-L2187 * https://github.com/matrix-org/synapse/blob/43ecfe0b1028fea5e4dda197f5631aed67182ee6/synapse/handlers/federation.py#L1716-L1761 * https://github.com/matrix-org/synapse/blob/43ecfe0b1028fea5e4dda197f5631aed67182ee6/synapse/federation/federation_server.py#L393-L446 * https://github.com/matrix-org/synapse/blob/master/synapse/federation/transport/server.py#L482-L487 --- api/server-server/event_auth.yaml | 172 ++++++++++++++++++++++++++++ specification/server_server_api.rst | 9 ++ 2 files changed, 181 insertions(+) create mode 100644 api/server-server/event_auth.yaml diff --git a/api/server-server/event_auth.yaml b/api/server-server/event_auth.yaml new file mode 100644 index 000000000..77d6fb1e9 --- /dev/null +++ b/api/server-server/event_auth.yaml @@ -0,0 +1,172 @@ +# Copyright 2018 New Vector Ltd +# +# 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. + +swagger: '2.0' +info: + title: "Matrix Federation Event Authorization API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +produces: + - application/json +paths: + "/event_auth/{roomId}/{eventId}": + get: + summary: Get the auth chain for a given event + description: |- + Retrieves the complete auth chain for a given event. + operationId: getEventAuth + parameters: + - in: path + name: roomId + type: string + description: The room ID to get the auth chain for. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID to get the auth chain of. + required: true + x-example: "$helloworld:domain.com" + responses: + 200: + description: The auth chain for the event. + schema: + type: object + properties: + auth_chain: + type: array + description: |- + The full set of authorization events that make up the state of + the room, and their authorization events, recursively. + items: + $ref: "definitions/pdu.yaml" + example: [{"$ref": "examples/pdu.json"}] + required: ['auth_chain'] + "/query_auth/{roomId}/{eventId}": + post: + summary: Compare auth chains with the receiving server + description: |- + Compares the auth chain provided with what the receiving server has for the + room ID and event ID combination. + + The auth difference can be calculated in two parts, where the "remote auth" + is the auth chain provided by the sending server and the "local auth" is the + auth chain the receiving server has. With those lists, the algorithm works + bottom-up after sorting each chain by depth then by event ID. The differences + are then discovered and returned as the response to this API call. + operationId: compareEventAuth + parameters: + - in: path + name: roomId + type: string + description: The room ID to compare the auth chain in. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID to compare the auth chain of. + required: true + x-example: "$helloworld:domain.com" + - in: body + name: body + schema: + type: object + properties: + auth_chain: + type: array + description: The auth chain (the "remote auth"). + items: + $ref: "definitions/pdu.yaml" + example: [{"$ref": "examples/pdu.json"}] + missing: + type: array + description: |- + A list of event IDs that the sender thinks the receiver is missing. + items: + type: string + example: [] + rejects: + type: object + description: |- + The set of events that the sending server has rejected from the provided + auth chain. + + The ``string`` key is the event ID that was rejected. + additionalProperties: + type: object + title: Rejection Reason + properties: + reason: + type: enum + enum: ['auth_error', 'replaced', 'not_ancestor'] + description: |- + The reason for the event being rejected. + required: ['reason'] + example: { + "$some_event:domain.com": { + "reason": "auth_error" + } + } + required: ['auth_chain'] + responses: + 200: + description: The auth chain differences, as determined by the receiver. + schema: + type: object + properties: + auth_chain: + type: array + description: |- + The auth chain the receiver has, and used to determine the auth + chain differences (the "local auth"). + items: + $ref: "definitions/pdu.yaml" + example: [{"$ref": "examples/pdu.json"}] + missing: + type: array + description: |- + The list of event IDs that the receiver believes it is missing, + after comparing the "remote auth" and "local auth" chains. + items: + type: string + example: ["$a_missing_event:domain.com"] + rejects: + type: object + description: |- + The set of events that the receiving server has rejected from the + auth chain, not including events that the sending server is missing + as determined from the difference algorithm. + + The ``string`` key is the event ID that was rejected. + additionalProperties: + type: object + title: Rejection Reason + properties: + reason: + type: enum + enum: ['auth_error', 'replaced', 'not_ancestor'] + description: |- + The reason for the event being rejected. + required: ['reason'] + example: { + "$some_event:domain.com": { + "reason": "auth_error" + } + } + required: ['auth_chain', 'missing', 'rejects'] diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 01172c6ec..bded4a49e 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -440,6 +440,15 @@ The rules are as follows: I think there is some magic about 3pid invites too. +Retrieving event authorization information +++++++++++++++++++++++++++++++++++++++++++ + +The homeserver may be missing event authorization information, or wish to check +with other servers to ensure it is receiving the correct auth chain. These APIs +give the homeserver an avenue for getting the information it needs. + +{{event_auth_ss_http_api}} + EDUs ---- From 13a2b54bf934c30b84b7caf7c1c3d003dbe9a7b2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 3 Aug 2018 13:57:43 -0600 Subject: [PATCH 2/2] query_auth consumes JSON --- api/server-server/event_auth.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/server-server/event_auth.yaml b/api/server-server/event_auth.yaml index 77d6fb1e9..f55afddc8 100644 --- a/api/server-server/event_auth.yaml +++ b/api/server-server/event_auth.yaml @@ -20,6 +20,8 @@ host: localhost:8448 schemes: - https basePath: /_matrix/federation/v1 +consumes: + - application/json produces: - application/json paths: