diff --git a/changelogs/server_server/newsfragments/1376.clarification b/changelogs/server_server/newsfragments/1376.clarification new file mode 100644 index 000000000..470783c4f --- /dev/null +++ b/changelogs/server_server/newsfragments/1376.clarification @@ -0,0 +1 @@ +Clarify that CNAMEs are permissible for server names. diff --git a/content/server-server-api.md b/content/server-server-api.md index 6e6258528..144736bab 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -110,11 +110,14 @@ to send. The process overall is as follows: given. The target server must present a valid certificate for the IP address. 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. + +2. If the hostname is not an IP literal, and the server name includes an + explicit port, resolve the hostname to an IP address using CNAME, 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 schema defined later in this section. 30x redirects should be @@ -140,7 +143,7 @@ to send. The process overall is as follows: one was provided. - If `` is not an IP literal, and `` is present, an IP address is discovered by - looking up an AAAA or A record for ``. The + looking up CNAME, AAAA or A records for ``. The resulting IP address is used, alongside the ``. Requests must be made with a `Host` header of `:`. The target server must @@ -153,11 +156,12 @@ to send. The process overall is as follows: a `Host` 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 + - If no SRV record is found, an IP address is resolved using CNAME, 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 ``. + 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 @@ -165,8 +169,9 @@ to send. The process overall is as follows: 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 record was not found, an IP address is resolved using AAAA and A + SRV record was not found, an IP address is resolved using CNAME, 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 valid certificate for ``. @@ -180,6 +185,13 @@ delegation are: and other applications using SRV records such [XMPP](https://datatracker.ietf.org/doc/html/rfc6120#section-13.7.2.1). {{% /boxes/note %}} +{{% boxes/note %}} +Note that the target of a SRV record may *not* be a CNAME, as +mandated by [RFC2782](https://www.rfc-editor.org/rfc/rfc2782.html): + +> the name MUST NOT be an alias (in the sense of RFC 1034 or RFC 2181) +{{% /boxes/note %}} + {{% http-api spec="server-server" api="wellknown" %}} ### Server implementation