From 0347e873efca4f80460492bdff9271601c7bc341 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 30 Jan 2019 22:11:31 -0700 Subject: [PATCH 1/7] Specify .well-known s2s discovery and X.509 validation Original proposals: * https://github.com/matrix-org/matrix-doc/pull/1708 (note: the JSON requirements were softened by https://github.com/matrix-org/matrix-doc/pull/1824) * https://github.com/matrix-org/matrix-doc/pull/1711 Implementation proofs: * https://github.com/matrix-org/synapse/pull/4489 * No explicit PRs for MSC1711 could be found, however Synapse is known to implement it. There are no intentional changes which differ from the proposals in this commit, however the author has relied upon various historical conversations outside of the proposals to gain the required context. Inaccuracies introduced by the author are purely accidental. --- api/server-server/definitions/keys.yaml | 23 +--- api/server-server/examples/server_key.json | 5 +- api/server-server/wellknown.yaml | 53 +++++++++ specification/server_server_api.rst | 124 ++++++++++++++++----- 4 files changed, 155 insertions(+), 50 deletions(-) create mode 100644 api/server-server/wellknown.yaml diff --git a/api/server-server/definitions/keys.yaml b/api/server-server/definitions/keys.yaml index 738e9e4692d..06619641a17 100644 --- a/api/server-server/definitions/keys.yaml +++ b/api/server-server/definitions/keys.yaml @@ -25,9 +25,9 @@ properties: verify_keys: type: object description: |- - Public keys of the homeserver for verifying digital signatures. - - The object's key is the algorithm and version combined (``ed25519`` being the + Public keys of the homeserver for verifying digital signatures. + + The object's key is the algorithm and version combined (``ed25519`` being the algorithm and ``abc123`` being the version in the example below). Together, this forms the Key ID. The version must have characters matching the regular expression ``[a-zA-Z0-9_]``. @@ -49,9 +49,9 @@ properties: old_verify_keys: type: object description: |- - The public keys that the server used to use and when it stopped using them. - - The object's key is the algorithm and version combined (``ed25519`` being the + The public keys that the server used to use and when it stopped using them. + + The object's key is the algorithm and version combined (``ed25519`` being the algorithm and ``0ldK3y`` being the version in the example below). Together, this forms the Key ID. The version must have characters matching the regular expression ``[a-zA-Z0-9_]``. @@ -90,17 +90,6 @@ properties: additionalProperties: type: string name: Encoded Signature Verification Key - tls_fingerprints: - type: array - description: Hashes of X.509 TLS certificates used by this server. - items: - type: object - title: TLS Fingerprint - properties: - sha256: - type: string - description: The `Unpadded Base64`_ encoded fingerprint. - example: "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw" valid_until_ts: type: integer format: int64 diff --git a/api/server-server/examples/server_key.json b/api/server-server/examples/server_key.json index bebd8445ee3..ffdfcb5a525 100644 --- a/api/server-server/examples/server_key.json +++ b/api/server-server/examples/server_key.json @@ -16,8 +16,5 @@ "ed25519:auto2": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU" } }, - "tls_fingerprints": [{ - "sha256": "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw" - }], "valid_until_ts": 1652262000000 -} \ No newline at end of file +} diff --git a/api/server-server/wellknown.yaml b/api/server-server/wellknown.yaml new file mode 100644 index 00000000000..273da7eb3c9 --- /dev/null +++ b/api/server-server/wellknown.yaml @@ -0,0 +1,53 @@ +# Copyright 2019 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 Server Discovery API" + version: "1.0.0" +host: localhost:443 +schemes: + - https +basePath: /.well-known +produces: + - application/json +paths: + "/matrix/server": + get: + summary: Gets information about the delegated server for server-server communication. + description: |- + Gets information about the delegated server for server-server communication + between Matrix homeservers. Servers should follow 30x redirects, carefully + avoiding redirect loops, and use normal X.509 certificate validation. + responses: + 200: + description: + 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). + examples: + application/json: { + "m.server": "delegated.example.com:1234" + } + schema: + type: object + properties: + "m.server": + type: string + description: |- + The server name to delegate server-server communciations to, with optional + port. The delegated server name uses the same grammar as + `server names in the appendices <../appendices.html#server-name>`_. diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a63bf0a6bfa..c88bd7ae0dd 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -90,35 +90,94 @@ Server discovery Resolving server names ~~~~~~~~~~~~~~~~~~~~~~ -Each matrix homeserver is identified by a server name consisting of a hostname +Each Matrix homeserver is identified by a server name consisting of a hostname and an optional port, as described by the `grammar -<../appendices.html#server-name>`_. Server names should be resolved to an IP -address and port using the following process: - -* If the hostname is an IP literal, then that IP address should be used, - together with the given port number, or 8448 if no port is given. - -* Otherwise, if the port is present, then an IP address is discovered by - looking up an AAAA or A record for the hostname, and the specified port is - used. - -* If the hostname is not an IP literal and no port is given, the server is - discovered by first looking up a ``_matrix._tcp`` SRV record for the - hostname, which may give a hostname (to be looked up using AAAA or A queries) - and port. If the SRV record does not exist, then the server is discovered by - looking up an AAAA or A record on the hostname and taking the default - fallback port number of 8448. - - Homeservers may use SRV records to load balance requests between multiple TLS - endpoints or to failover to another endpoint if an endpoint fails. - -When making requests to servers, use the hostname of the target server in the -``Host`` header, regardless of any hostname given in the SRV record. For -example, if the server name is ``example.org``, and the SRV record resolves to -``matrix.example.org``, the ``Host`` header in the request should be -``example.org``. If an explicit port was given in the server name, it should be -included in the ``Host`` header; otherwise, no port number should be given in -the ``Host`` header. +<../appendices.html#server-name>`_. Where applicable, a delegated server name +uses the same grammar. + +Server names are resolved to an IP address and port to connect to, and have +various conditions affecting which certificates and ``Host`` headers to send. +The process overall is as follows: + +.. Note from the author: The repetitive "use this Host header and this cert" + comments are intentional. The process is overall quite complicated, and + explaining explicitly what requests look like at each step helps ease the + understanding and ensure everyone is on the same page. Implementations + are of course welcome to realize where the process can be optimized, and + do so - just ensure that the result is the same! + +1. If the hostname is an IP literal, then that IP address should be used, + together with the given port number, or 8448 if no port is given. A + valid TLS certificate must be provided by the target server for the + IP address on all requests. Requests must be made with a ``Host`` + header containing the IP address, without port. + +2. If the hostname is not an IP literal, 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 ````. A valid TLS certificate + for ```` must be provided by the target server on all requests. + +3. If the SRV record yielded no results, a ``/.well-known`` request is + made to the hostname (using port 443 exclusively, ignoring the port + provided in the server name). The target must present a valid TLS + certificate for the hostname, and a ``Host`` header containing the + hostname is used to make the request. The schema of the ``/.well-known`` + request is later in this section. Assuming the response is valid, + the ``m.server`` property is parsed as ``[:]`` + and processed as follows: + + * If ```` is an IP literal, then that IP address + should be used together with the ```` or 8448 if no + port is provided. A valid TLS certificate must be provided by the + target server for that IP address. Requests must be made with a + ``Host`` header containing the IP address, without port. + + * If ```` is not an IP literal, and ```` + is present, an IP address is disovered by looking up an AAAA or A + record for ````. The resulting IP address is + used, alongside the ````, to make requests with a + ``Host`` header of ````. A valid TLS certificate + must be provided by the target server for ````. + + * If ```` is not an IP literal and no + ```` is present, an SRV record is looked up for + ``_matrix._tcp.``. This may result in another + hostname (to be resolved using AAAA or A records) and port. Requests + should be made to the resolved IP address and port with a ``Host`` + header containing the ````. Additionally, a + valid TLS certificate must be provided by the target server for the + ````. + + * If no SRV record is found, an IP address is resolved using AAAA + or A records. Requests are then made to the resolve IP address + and a port of 8448, using a ``Host`` header of ````. + A valid TLS certificate for ```` must be + provided by the target server. + +4. If the `/.well-known` request was invalid or 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 ````. A valid TLS + certificate for ```` must be provided by the target server + on all requests. + + +The TLS certificate provided by the target server must be present on all +requests made to the server. The TLS certificate must be signed by a known +Certificate Authority. Servers are ultimately responsible for determining +the trusted Certificate Authorities, however are strongly encouraged to +rely on the operating system's judgement. Servers can offer administrators +a means to override the trusted authorities list. Servers can additionally +skip the certificate validation for a given whitelist of domains or netmasks +for the purposes of testing or in networks where verification is done +elsewhere, such as with ``.onion`` addresses. + +Servers are encouraged to make use of the +`Certificate Transparency `_ project. + +{{wellknown_ss_http_api}} Server implementation ~~~~~~~~~~~~~~~~~~~~~~ @@ -130,9 +189,16 @@ Retrieving server keys .. NOTE:: There was once a "version 1" of the key exchange. It has been removed from the - specification due to lack of significance. It may be reviewed `here + specification due to lack of significance. It may be reviewed `from the historical draft `_. +.. NOTE:: + Older drafts of this specification made use of a different style of key verification, + however for reasons discussed in `MSC1711 `_, + the approach was removed from the initial version of the specification. The older + draft may be reviewed `thanks to web.archive.org + `_. + 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 intermediate notary server using a From d2f012f4ea8f525ace16f75f7abaa5ce3351e3cd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 31 Jan 2019 11:17:56 -0700 Subject: [PATCH 2/7] Incorporate MSC1831 Original proposal: https://github.com/matrix-org/matrix-doc/pull/1831 Implementation proof: pending --- specification/server_server_api.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index c88bd7ae0dd..e680c7924a0 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -112,14 +112,7 @@ The process overall is as follows: IP address on all requests. Requests must be made with a ``Host`` header containing the IP address, without port. -2. If the hostname is not an IP literal, 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 ````. A valid TLS certificate - for ```` must be provided by the target server on all requests. - -3. If the SRV record yielded no results, a ``/.well-known`` request is +2. If the hostname is not an IP literal, a ``/.well-known`` request is made to the hostname (using port 443 exclusively, ignoring the port provided in the server name). The target must present a valid TLS certificate for the hostname, and a ``Host`` header containing the @@ -156,12 +149,19 @@ The process overall is as follows: A valid TLS certificate for ```` must be provided by the target server. -4. If the `/.well-known` request was invalid or 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 ````. A valid TLS - certificate for ```` must be provided by the target server - on all requests. +3. If the `/.well-known` request returned 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 ````. A valid TLS + certificate for ```` must be provided by the target server on + all requests. + +4. 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 ````. A valid TLS certificate for + ```` must be provided by the target server on all requests. The TLS certificate provided by the target server must be present on all From b971bcee7d42e0a497c7476d3272ac80c16e4057 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 31 Jan 2019 16:24:07 -0700 Subject: [PATCH 3/7] Accurately represent the 3 proposals and provide more detail --- specification/server_server_api.rst | 57 +++++++++++++++-------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index e680c7924a0..380fe617457 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -112,14 +112,22 @@ The process overall is as follows: IP address on all requests. Requests must be made with a ``Host`` header containing the IP address, without port. -2. If the hostname is not an IP literal, a ``/.well-known`` request is +2. If the hostname is not an IP literal, and has an explicit port given, + resolve the IP address using AAAA or A records. Requests are made to + the resolved IP address and given port with a ``Host`` header of the + original hostname (without port). A valid TLS certificate must be + provided by the target server for the hostname. + +3. If the hostname is not an IP literal, a ``/.well-known`` request is made to the hostname (using port 443 exclusively, ignoring the port - provided in the server name). The target must present a valid TLS - certificate for the hostname, and a ``Host`` header containing the - hostname is used to make the request. The schema of the ``/.well-known`` - request is later in this section. Assuming the response is valid, - the ``m.server`` property is parsed as ``[:]`` - and processed as follows: + provided in the server name). This is done as a plain HTTPS request + which follows 30x redirects, being careful to avoid redirect loops. + The schema of the ``/.well-known`` request is later in this section. + If the response is invalid (bad JSON, missing properties, etc), + attempts to connect to the target server are aborted - no connections + should be attempted. If the response is valid, the ``m.server`` property + is parsed as ``[:]`` and processed + as follows: * If ```` is an IP literal, then that IP address should be used together with the ```` or 8448 if no @@ -131,8 +139,8 @@ The process overall is as follows: is present, an IP address is disovered by looking up an AAAA or A record for ````. The resulting IP address is used, alongside the ````, to make requests with a - ``Host`` header of ````. A valid TLS certificate - must be provided by the target server for ````. + ``Host`` header of ``:``. A valid + TLS certificate must be provided by the target server for ````. * If ```` is not an IP literal and no ```` is present, an SRV record is looked up for @@ -143,36 +151,38 @@ The process overall is as follows: valid TLS certificate must be provided by the target server for the ````. - * If no SRV record is found, an IP address is resolved using AAAA - or A records. Requests are then made to the resolve IP address - and a port of 8448, using a ``Host`` header of ````. - A valid TLS certificate for ```` must be - provided by the target server. + * If no SRV record is found, an IP address is resolved using AAAA + or A records. Requests are then made to the resolve IP address + and a port of 8448, using a ``Host`` header of ````. + A valid TLS certificate for ```` must be + provided by the target server. -3. If the `/.well-known` request returned an error response, a server is - found by resolving an SRV record for ``_matrix._tcp.``. This +4. If the `/.well-known` request did not result in a 200 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 ````. A valid TLS certificate for ```` must be provided by the target server on all requests. -4. 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 ````. A valid TLS certificate for ```` must be provided by the target server on all requests. -The TLS certificate provided by the target server must be present on all -requests made to the server. The TLS certificate must be signed by a known +The TLS certificate provided by the target server must be signed by a known Certificate Authority. Servers are ultimately responsible for determining the trusted Certificate Authorities, however are strongly encouraged to rely on the operating system's judgement. Servers can offer administrators a means to override the trusted authorities list. Servers can additionally skip the certificate validation for a given whitelist of domains or netmasks for the purposes of testing or in networks where verification is done -elsewhere, such as with ``.onion`` addresses. +elsewhere, such as with ``.onion`` addresses. Servers should respect SNI +when making requests where possible: a SNI should be sent for the certificate +which is expected, unless that certificate is expected to be an IP address in +which case SNI is not supported and should not be sent. Servers are encouraged to make use of the `Certificate Transparency `_ project. @@ -192,13 +202,6 @@ Retrieving server keys specification due to lack of significance. It may be reviewed `from the historical draft `_. -.. NOTE:: - Older drafts of this specification made use of a different style of key verification, - however for reasons discussed in `MSC1711 `_, - the approach was removed from the initial version of the specification. The older - draft may be reviewed `thanks to web.archive.org - `_. - 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 intermediate notary server using a From 3c17a0e53bad28cc38f2df0828e83a71b2f8e1ac Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 31 Jan 2019 16:29:07 -0700 Subject: [PATCH 4/7] Mention caching --- specification/server_server_api.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 380fe617457..a2672e92770 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -122,12 +122,19 @@ The process overall is as follows: made to the hostname (using port 443 exclusively, ignoring the port provided in the server name). This is done as a plain HTTPS request which follows 30x redirects, being careful to avoid redirect loops. - The schema of the ``/.well-known`` request is later in this section. - If the response is invalid (bad JSON, missing properties, etc), - attempts to connect to the target server are aborted - no connections - should be attempted. If the response is valid, the ``m.server`` property - is parsed as ``[:]`` and processed - as follows: + Responses (successful or otherwise) to the ``/.well-known`` endpoint + should be cached by the requesting server. Servers should respect + the cache control headers present on the response, or use a sensible + default when headers are not present. The recommended sensible default + is 24 hours. Servers should additionally impose a maximum cache time + for responses: 48 hours is recommended. Errors are recommended to be + cached for up to an hour, and servers are encouraged to exponentially + back off for repeated failures. The schema of the ``/.well-known`` + request is later in this section. If the response is invalid (bad JSON, + missing properties, etc), attempts to connect to the target server are + aborted - no connections should be attempted. If the response is valid, + the ``m.server`` property is parsed as ``[:]`` + and processed as follows: * If ```` is an IP literal, then that IP address should be used together with the ```` or 8448 if no From 1c30f5eba986335635f1740b1689e9b011beefd1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 31 Jan 2019 21:15:47 -0700 Subject: [PATCH 5/7] Clarify certificate usage and ports --- specification/server_server_api.rst | 75 ++++++++++++++--------------- 1 file changed, 36 insertions(+), 39 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a2672e92770..46a485af33f 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -107,76 +107,73 @@ The process overall is as follows: do so - just ensure that the result is the same! 1. If the hostname is an IP literal, then that IP address should be used, - together with the given port number, or 8448 if no port is given. A - valid TLS certificate must be provided by the target server for the - IP address on all requests. Requests must be made with a ``Host`` - header containing the IP address, without port. + together with the given port number, or 8448 if no port is given. The + target server must present a valid certificate for the IP address. + Requests must be made with a ``Host`` header containing the IP address, + without port. 2. If the hostname is not an IP literal, and has an explicit port given, resolve the IP address using AAAA or A records. Requests are made to the resolved IP address and given port with a ``Host`` header of the - original hostname (without port). A valid TLS certificate must be - provided by the target server for the hostname. - -3. If the hostname is not an IP literal, a ``/.well-known`` request is - made to the hostname (using port 443 exclusively, ignoring the port - provided in the server name). This is done as a plain HTTPS request - which follows 30x redirects, being careful to avoid redirect loops. - Responses (successful or otherwise) to the ``/.well-known`` endpoint - should be cached by the requesting server. Servers should respect - the cache control headers present on the response, or use a sensible - default when headers are not present. The recommended sensible default - is 24 hours. Servers should additionally impose a maximum cache time - for responses: 48 hours is recommended. Errors are recommended to be - cached for up to an hour, and servers are encouraged to exponentially - back off for repeated failures. The schema of the ``/.well-known`` - request is later in this section. If the response is invalid (bad JSON, - missing properties, etc), attempts to connect to the target server are - aborted - no connections should be attempted. If the response is valid, - the ``m.server`` property is parsed as ``[:]`` - and processed as follows: + original hostname (with port). The target server must present a valid + certificate for the hostname. + +3. If the hostname is not an IP literal, a regular HTTPS request is made + to ``https:///.well-known/matrix/server``, expecting the + schema defined later in this section. 30x redirects should be followed, + however redirection loops should be avoided. Responses (successful or + otherwise) to the ``/.well-known`` endpoint should be cached by the + requesting server. Servers should respect the cache control headers + present on the response, or use a sensible default when headers are not + present. The recommended sensible default is 24 hours. Servers should + additionally impose a maximum cache time for responses: 48 hours is + recommended. Errors are recommended to be cached for up to an hour, + and servers are encouraged to exponentially back off for repeated + failures. The schema of the ``/.well-known`` request is later in this + section. If the response is invalid (bad JSON, missing properties, etc), + attempts to connect to the target server are aborted - no connections + should be attempted. If the response is valid, the ``m.server`` property + is parsed as ``[:]`` and processed + as follows: * If ```` is an IP literal, then that IP address should be used together with the ```` or 8448 if no - port is provided. A valid TLS certificate must be provided by the - target server for that IP address. Requests must be made with a - ``Host`` header containing the IP address, without port. + port is provided. The target server must present a valid TLS certificate + for the IP address. Requests must be made with a ``Host`` header containing + the IP address, with port. * If ```` is not an IP literal, and ```` is present, an IP address is disovered by looking up an AAAA or A record for ````. The resulting IP address is used, alongside the ````, to make requests with a - ``Host`` header of ``:``. A valid - TLS certificate must be provided by the target server for ````. + ``Host`` header of ``:``. The + target server must present a valid certificate for ````. * If ```` is not an IP literal and no ```` is present, an SRV record is looked up for ``_matrix._tcp.``. This may result in another hostname (to be resolved using AAAA or A records) and port. Requests should be made to the resolved IP address and port with a ``Host`` - header containing the ````. Additionally, a - valid TLS certificate must be provided by the target server for the - ````. + header containing the ````. The target server + must present a valid certificate for ````. * If no SRV record is found, an IP address is resolved using AAAA or A records. Requests are then made to the resolve IP address and a port of 8448, using a ``Host`` header of ````. - A valid TLS certificate for ```` must be - provided by the target server. + The target server must present a valid certificate for ````. 4. If the `/.well-known` request did not result in a 200 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 ````. A valid TLS - certificate for ```` must be provided by the target server on - all requests. + 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 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 ````. A valid TLS certificate for - ```` must be provided by the target server on all requests. + header containing the ````. The target server must present a + valid certificate for ````. The TLS certificate provided by the target server must be signed by a known From 39b71413be1f20d7071c2d8babe784b22b015537 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Fri, 1 Feb 2019 07:40:39 -0700 Subject: [PATCH 6/7] Update specification/server_server_api.rst Co-Authored-By: turt2live --- specification/server_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 46a485af33f..17f3e646b53 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -112,7 +112,7 @@ The process overall is as follows: Requests must be made with a ``Host`` header containing the IP address, without port. -2. If the hostname is not an IP literal, and has an explicit port given, +2. If the hostname is not an IP literal, and the server name includes an explicit port, resolve the IP address using AAAA or A records. Requests are made to the resolved IP address and given port with a ``Host`` header of the original hostname (with port). The target server must present a valid From 6421582bf2f29f766a151f93264126c3f69f4139 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 1 Feb 2019 08:18:12 -0700 Subject: [PATCH 7/7] Clarifications and alter the error handling of .well-known Note that MSC1831 changes the order, so the changes to MSC1708 might not make sense when combining all the proposals together. However, independently the change should make sense. --- proposals/1708-well-known-for-federation.md | 4 +- specification/server_server_api.rst | 51 ++++++++++----------- 2 files changed, 27 insertions(+), 28 deletions(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index d23c0e2ffd6..c9f90631e30 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -44,8 +44,8 @@ redirect loops). If the request does not return a 200, continue to step 4, otherwise: The response must be valid JSON which follows the structure documented -below. Otherwise, the request is aborted. It is NOT necessary for the response -to have a `Content-Type` of `application/json`. +below. Otherwise, continue to the next step in the discovery process. It is +NOT necessary for the response to have a `Content-Type` of `application/json`. If the response is valid, the `m.server` property is parsed as `[:]`, and processed as follows: diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 17f3e646b53..8de5ecc54fb 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -109,14 +109,14 @@ The process overall is as follows: 1. If the hostname is an IP literal, then that IP address should be used, together with the given port number, or 8448 if no port is given. The target server must present a valid certificate for the IP address. - Requests must be made with a ``Host`` header containing the IP address, - without port. + The ``Host`` header in the request should be set to the server name, + including the port if the server name included one. -2. If the hostname is not an IP literal, and the server name includes an explicit port, - resolve the IP address using AAAA or A records. Requests are made to - the resolved IP address and given port with a ``Host`` header of the - original hostname (with port). The target server must present a valid - certificate for the hostname. +2. If the hostname is not an IP literal, and the server name includes an + explicit port, resolve the IP address using AAAA or A records. Requests + are made to the resolved IP address and given port with a ``Host`` header + of the original server name (with port). The target server must present a + valid certificate for the hostname. 3. If the hostname is not an IP literal, a regular HTTPS request is made to ``https:///.well-known/matrix/server``, expecting the @@ -130,39 +130,38 @@ The process overall is as follows: recommended. Errors are recommended to be cached for up to an hour, and servers are encouraged to exponentially back off for repeated failures. The schema of the ``/.well-known`` request is later in this - section. If the response is invalid (bad JSON, missing properties, etc), - attempts to connect to the target server are aborted - no connections - should be attempted. If the response is valid, the ``m.server`` property - is parsed as ``[:]`` and processed - as follows: + section. If the response is invalid (bad JSON, missing properties, non-200 + response, etc), skip to step 4. If the response is valid, the ``m.server`` + property is parsed as ``[:]`` and + processed as follows: - * If ```` is an IP literal, then that IP address + * If ```` is an IP literal, then that IP address should be used together with the ```` or 8448 if no port is provided. The target server must present a valid TLS certificate for the IP address. Requests must be made with a ``Host`` header containing - the IP address, with port. + the IP address, including the port if one was provided. - * If ```` is not an IP literal, and ```` + * If ```` is not an IP literal, and ```` is present, an IP address is disovered by looking up an AAAA or A - record for ````. The resulting IP address is - used, alongside the ````, to make requests with a - ``Host`` header of ``:``. The - target server must present a valid certificate for ````. + record for ````. The resulting IP address is + used, alongside the ````. Requests must be made with a + ``Host`` header of ``:``. The + target server must present a valid certificate for ````. - * If ```` is not an IP literal and no + * If ```` is not an IP literal and no ```` is present, an SRV record is looked up for - ``_matrix._tcp.``. This may result in another + ``_matrix._tcp.``. This may result in another hostname (to be resolved using AAAA or A records) and port. Requests should be made to the resolved IP address and port with a ``Host`` - header containing the ````. The target server - must present a valid certificate for ````. + header containing the ````. The target server + must present a valid certificate for ````. * If no SRV record is found, an IP address is resolved using AAAA or A records. Requests are then made to the resolve IP address - and a port of 8448, using a ``Host`` header of ````. - The target server must present a valid certificate for ````. + 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 did not result in a 200 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