From e9bac1b011957c87e3791b916b70755fbafa401e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 4 Feb 2019 13:49:29 -0700 Subject: [PATCH 01/12] Remove wrong references to TLS fingerprints Also fix some styling in the server discovery section - this didn't feel like it needed its own commit. --- specification/server_server_api.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 778a5819a..d00ca135c 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -157,14 +157,14 @@ The process overall is as follows: and a port of 8448, using a ``Host`` header of ````. The target server must present a valid certificate for ````. -4. If the `/.well-known` request resulted in an error response, a server +4. If the ``/.well-known`` request resulted in an error response, a server is found by resolving an SRV record for ``_matrix._tcp.``. This may result in a hostname (to be resolved using AAAA or A records) and port. Requests are made to the resolved IP address and port, using 8448 as a default port, with a ``Host`` header of ````. The target server must present a valid certificate for ````. -5. If the `/.well-known` request returned an error response, and the SRV +5. If the ``/.well-known`` request returned an error response, and the SRV record was not found, an IP address is resolved using AAAA and A records. Requests are made to the resolved IP address using port 8448 and a ``Host`` header containing the ````. The target server must present a @@ -220,12 +220,11 @@ server by querying other servers. Publishing Keys +++++++++++++++ -Homeservers publish the allowed TLS fingerprints and signing keys in a JSON +Homeservers publish their signing keys in a JSON object at ``/_matrix/key/v2/server/{key_id}``. The response contains a list of ``verify_keys`` that are valid for signing federation requests made by the homeserver and for signing events. It contains a list of ``old_verify_keys`` which -are only valid for signing events. Finally the response contains a list of TLS -certificate fingerprints to validate any connection made to the homeserver. +are only valid for signing events. {{keys_server_ss_http_api}} From 3dd0601a96be6f285753d72aa9fd212bb9ae3bc7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 4 Feb 2019 13:52:20 -0700 Subject: [PATCH 02/12] Remove more TLS fingerprint talk --- api/server-server/keys_server.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/server-server/keys_server.yaml b/api/server-server/keys_server.yaml index 8734f2edd..69985ab7b 100644 --- a/api/server-server/keys_server.yaml +++ b/api/server-server/keys_server.yaml @@ -27,7 +27,7 @@ paths: get: summary: Get the homeserver's public key(s) description: |- - Gets the homeserver's published TLS fingerprints and signing keys. + Gets the homeserver's published signing keys. The homeserver may have any number of active keys and may have a number of old keys. @@ -49,7 +49,7 @@ paths: 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 + opt to return all keys, not just the requested one. The key ID to look up. required: false x-example: "ed25519:abc123" From 6067a4ad3cfcfde21f812484162704728d144a96 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 4 Feb 2019 13:56:59 -0700 Subject: [PATCH 03/12] Use the real identity server version in the APIs table --- scripts/templating/matrix_templates/units.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 721501ff5..f697dbdf0 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -774,7 +774,7 @@ class MatrixUnits(Units): "Privileged server plugins", ), TypeTableRow( "`Identity Service API `_", - "unstable", + is_ver, "Mapping of third party IDs to Matrix IDs", ), TypeTableRow( "`Push Gateway API `_", From f37a6d2ef554a4534ac6834e9c37fb5c1e008275 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 4 Feb 2019 14:00:34 -0700 Subject: [PATCH 04/12] Changelog --- changelogs/server_server/newsfragments/1844.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/server_server/newsfragments/1844.clarification diff --git a/changelogs/server_server/newsfragments/1844.clarification b/changelogs/server_server/newsfragments/1844.clarification new file mode 100644 index 000000000..f80eef518 --- /dev/null +++ b/changelogs/server_server/newsfragments/1844.clarification @@ -0,0 +1 @@ +Remove legacy references to TLS fingerprints. From 3581368f1f9066bf0d2679f8909a921c83d5486c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 4 Feb 2019 14:48:31 -0700 Subject: [PATCH 05/12] Add the "please use latest.html" warning to the s2s spec Now that we have a release, we should be warning people who try and use the unstable spec as fact. --- specification/server_server_api.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 778a5819a..0993cc144 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -16,6 +16,8 @@ Federation API ============== +{{unstable_warning_block_SERVER_RELEASE_LABEL}} + Matrix homeservers use the Federation APIs (also known as server-server APIs) to communicate with each other. Homeservers use these APIs to push messages to each other in real-time, to retrieve historic messages from each other, and to From c8428b1f8bf38ec88a40f9ee38fbaead3bad052d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 5 Feb 2019 22:39:36 -0700 Subject: [PATCH 06/12] Fix contradiction in wellknown discovery for servers Fixes https://github.com/matrix-org/matrix-doc/issues/1854 --- api/server-server/wellknown.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/api/server-server/wellknown.yaml b/api/server-server/wellknown.yaml index 273da7eb3..756766465 100644 --- a/api/server-server/wellknown.yaml +++ b/api/server-server/wellknown.yaml @@ -35,9 +35,8 @@ paths: The delegated server information. The ``Content-Type`` for this response SHOULD be ``application/json``, however servers parsing the response should assume that the body is JSON regardless of type. Failures parsing the JSON or invalid data - provided in the resulting parsed JSON must result in server discovery failure (no - attempts should be made to continue finding an IP address/port number to connect - to). + provided in the resulting parsed JSON should not result in discovery failure - + consult the server discovery process for information on how to continue. examples: application/json: { "m.server": "delegated.example.com:1234" From 4b68b5c9392b44f72c7022686c766c408240d4dc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 6 Feb 2019 12:20:56 -0700 Subject: [PATCH 07/12] Changelog --- changelogs/server_server/newsfragments/1855.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/server_server/newsfragments/1855.clarification diff --git a/changelogs/server_server/newsfragments/1855.clarification b/changelogs/server_server/newsfragments/1855.clarification new file mode 100644 index 000000000..e61e14c6d --- /dev/null +++ b/changelogs/server_server/newsfragments/1855.clarification @@ -0,0 +1 @@ +Clarify that servers should not fail to contact servers if ``/.well-known`` fails. From 8bd9ca4edd7a6f20da3a1d0e4a13854e70f03fa2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 6 Feb 2019 12:35:04 -0700 Subject: [PATCH 08/12] Prep for r0.1.1 of s2s --- changelogs/server_server.rst | 10 ++++++++++ .../server_server/newsfragments/1844.clarification | 1 - .../server_server/newsfragments/1855.clarification | 1 - specification/identity_service_api.rst | 2 +- specification/rooms/v1.rst | 4 ++-- specification/rooms/v2.rst | 2 +- specification/rooms/v3.rst | 4 ++-- specification/server_server_api.rst | 1 + 8 files changed, 17 insertions(+), 8 deletions(-) delete mode 100644 changelogs/server_server/newsfragments/1844.clarification delete mode 100644 changelogs/server_server/newsfragments/1855.clarification diff --git a/changelogs/server_server.rst b/changelogs/server_server.rst index 5dabc4ac2..a21da177a 100644 --- a/changelogs/server_server.rst +++ b/changelogs/server_server.rst @@ -1,3 +1,13 @@ +r0.1.1 +====== + +Spec Clarifications +------------------- + +- Remove legacy references to TLS fingerprints. (`#1844 `_) +- Clarify that servers should not fail to contact servers if ``/.well-known`` fails. (`#1855 `_) + + r0.1.0 ====== diff --git a/changelogs/server_server/newsfragments/1844.clarification b/changelogs/server_server/newsfragments/1844.clarification deleted file mode 100644 index f80eef518..000000000 --- a/changelogs/server_server/newsfragments/1844.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove legacy references to TLS fingerprints. diff --git a/changelogs/server_server/newsfragments/1855.clarification b/changelogs/server_server/newsfragments/1855.clarification deleted file mode 100644 index e61e14c6d..000000000 --- a/changelogs/server_server/newsfragments/1855.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that servers should not fail to contact servers if ``/.well-known`` fails. diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index ecd2c99fd..e00cee813 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -279,4 +279,4 @@ this isn't possible. .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 .. _`3PID Types`: ../appendices.html#pid-types .. _`Signing JSON`: ../appendices.html#signing-json -.. _`/3pid/onbind`: ../server_server/r0.1.0.html#put-matrix-federation-v1-3pid-onbind +.. _`/3pid/onbind`: ../server_server/r0.1.1.html#put-matrix-federation-v1-3pid-onbind diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index 63bb1d7ac..f50131943 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -290,5 +290,5 @@ Events in version 1 rooms have the following structure: {{definition_ss_pdu}} -.. _`auth events selection`: ../../server_server/r0.1.0.html#auth-events-selection -.. _`Signing Events`: ../../server_server/r0.1.0.html#signing-events +.. _`auth events selection`: ../../server_server/r0.1.1.html#auth-events-selection +.. _`Signing Events`: ../../server_server/r0.1.1.html#signing-events diff --git a/specification/rooms/v2.rst b/specification/rooms/v2.rst index b73662ead..7ad7668c9 100644 --- a/specification/rooms/v2.rst +++ b/specification/rooms/v2.rst @@ -159,7 +159,7 @@ The *resolution* of a set of states is obtained as follows: resolved state. -.. _`authorization rules`: ../server_server/r0.1.0.html#authorization-rules +.. _`authorization rules`: ../server_server/r0.1.1.html#authorization-rules Rejected events +++++++++++++++ diff --git a/specification/rooms/v3.rst b/specification/rooms/v3.rst index 368485197..0915d1962 100644 --- a/specification/rooms/v3.rst +++ b/specification/rooms/v3.rst @@ -117,5 +117,5 @@ The remaining rules are the same as `room version 1 `_: Includes all changes since the latest versioned release. +- `r0.1.1 `_ - `r0.1.0 `_ Server discovery From cf11965a8ee6c9bbe2de6e107b9291ecf666b8aa Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 6 Feb 2019 22:15:13 -0700 Subject: [PATCH 09/12] Change notice about room v2's scope to represent reality Fixes https://github.com/matrix-org/matrix-doc/issues/1851 --- specification/rooms/v2.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/rooms/v2.rst b/specification/rooms/v2.rst index 7ad7668c9..6188966a1 100644 --- a/specification/rooms/v2.rst +++ b/specification/rooms/v2.rst @@ -27,9 +27,8 @@ Server implementation components details contained here, and can safely ignore their presence. -The algorithms defined here should only apply to version 2 rooms. Other algorithms -may be used by other room versions, and as such servers should be aware of which -version room they are dealing with prior to executing a given algorithm. +Room version 2 uses the base compoennts of `room version 1 `_, changing +only the state resolution algorithm. State resolution From 85578f984240b3eda83b074f0ee286175806e5a6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 6 Feb 2019 22:18:56 -0700 Subject: [PATCH 10/12] Fix spelling mistake: endponts -> endpoints Fixes https://github.com/matrix-org/matrix-doc/issues/1677 --- changelogs/client_server/newsfragments/1838.clarification | 1 + changelogs/client_server/newsfragments/1860.clarification | 1 + specification/client_server_api.rst | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1838.clarification create mode 100644 changelogs/client_server/newsfragments/1860.clarification diff --git a/changelogs/client_server/newsfragments/1838.clarification b/changelogs/client_server/newsfragments/1838.clarification new file mode 100644 index 000000000..b0f052035 --- /dev/null +++ b/changelogs/client_server/newsfragments/1838.clarification @@ -0,0 +1 @@ +Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1860.clarification b/changelogs/client_server/newsfragments/1860.clarification new file mode 100644 index 000000000..b0f052035 --- /dev/null +++ b/changelogs/client_server/newsfragments/1860.clarification @@ -0,0 +1 @@ +Fix various spelling mistakes throughout the specification. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index c506af4e4..b41c34607 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -73,7 +73,7 @@ MUST be encoded as UTF-8. Clients are authenticated using opaque ``access_token`` strings (see `Client Authentication`_ for details), passed as a query string parameter on all requests. -The names of the API endponts for the HTTP transport follow a convention of +The names of the API endpoints for the HTTP transport follow a convention of using underscores to separate words (for example ``/delete_devices``). The key names in JSON objects passed over the API also follow this convention. From 772ba8dc2af8c9236aa2947603ae270c78f99c9b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 6 Feb 2019 22:26:41 -0700 Subject: [PATCH 11/12] Add a table of contents to each room version spec Fixes https://github.com/matrix-org/matrix-doc/issues/1852 We get clickable headers for free by doing this. --- specification/rooms/v1.rst | 3 +++ specification/rooms/v2.rst | 3 +++ specification/rooms/v3.rst | 3 +++ 3 files changed, 9 insertions(+) diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index f50131943..1c7a56c4c 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -18,6 +18,9 @@ Room Version 1 This room version is the first ever version for rooms, and contains the building blocks for other room versions. +.. contents:: Table of Contents +.. sectnum:: + Server implementation components -------------------------------- diff --git a/specification/rooms/v2.rst b/specification/rooms/v2.rst index 7ad7668c9..b262f47f0 100644 --- a/specification/rooms/v2.rst +++ b/specification/rooms/v2.rst @@ -18,6 +18,9 @@ Room Version 2 This room version builds off of `version 1 `_ with an improved state resolution algorithm. +.. contents:: Table of Contents +.. sectnum:: + Server implementation components -------------------------------- diff --git a/specification/rooms/v3.rst b/specification/rooms/v3.rst index 0915d1962..863f1c3a3 100644 --- a/specification/rooms/v3.rst +++ b/specification/rooms/v3.rst @@ -24,6 +24,9 @@ This room version builds on `version 2 `_ with an improved event format where the contextual room of the request is using this room version. Rooms using other room versions should not be affected by these sweeping requirements. +.. contents:: Table of Contents +.. sectnum:: + Client considerations --------------------- From 0ed0fee26147af548d2684f25ed8aa06028fdc59 Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Thu, 7 Feb 2019 08:09:35 -0700 Subject: [PATCH 12/12] Update specification/rooms/v2.rst Co-Authored-By: turt2live --- specification/rooms/v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/rooms/v2.rst b/specification/rooms/v2.rst index 6188966a1..1ff2d3fcc 100644 --- a/specification/rooms/v2.rst +++ b/specification/rooms/v2.rst @@ -27,7 +27,7 @@ Server implementation components details contained here, and can safely ignore their presence. -Room version 2 uses the base compoennts of `room version 1 `_, changing +Room version 2 uses the base components of `room version 1 `_, changing only the state resolution algorithm.