diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index e680c7924..380fe6174 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