Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Specify .well-known s2s discovery and X.509 validation #1830

Merged
merged 7 commits into from
Feb 1, 2019
Merged

Specify .well-known s2s discovery and X.509 validation #1830

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0347e87
Specify .well-known s2s discovery and X.509 validation
turt2live Jan 31, 2019
d2f012f
Incorporate MSC1831
turt2live Jan 31, 2019
b971bce
Accurately represent the 3 proposals and provide more detail
turt2live Jan 31, 2019
3c17a0e
Mention caching
turt2live Jan 31, 2019
1c30f5e
Clarify certificate usage and ports
turt2live Feb 1, 2019
39b7141
Update specification/server_server_api.rst
richvdh Feb 1, 2019
6421582
Clarifications and alter the error handling of .well-known
turt2live Feb 1, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 30 additions & 27 deletions specification/server_server_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
turt2live marked this conversation as resolved.
Show resolved Hide resolved
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
turt2live marked this conversation as resolved.
Show resolved Hide resolved
provided by the target server for the hostname.

3. If the hostname is not an IP literal, a ``/.well-known`` request is
turt2live marked this conversation as resolved.
Show resolved Hide resolved
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 ``<delegated_server_name>[:<delegated_port>]``
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.
turt2live marked this conversation as resolved.
Show resolved Hide resolved
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 ``<delegated_server_name>[:<delegated_port>]`` and processed
turt2live marked this conversation as resolved.
Show resolved Hide resolved
as follows:

* If ``<delegated_server_name>`` is an IP literal, then that IP address
should be used together with the ``<delegated_port>`` or 8448 if no
Expand All @@ -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 ``<delegated_server_name>``. The resulting IP address is
used, alongside the ``<delegated_port>``, to make requests with a
turt2live marked this conversation as resolved.
Show resolved Hide resolved
``Host`` header of ``<delegated_server_name>``. A valid TLS certificate
must be provided by the target server for ``<delegated_server_name>``.
``Host`` header of ``<delegated_server_name>:<delegated_port>``. A valid
TLS certificate must be provided by the target server for ``<delegated_server_name>``.

* If ``<delegated_server_name>`` is not an IP literal and no
``<delegated_port>`` is present, an SRV record is looked up for
Expand All @@ -143,36 +151,38 @@ The process overall is as follows:
valid TLS certificate must be provided by the target server for the
``<delegated_server_name>``.

* 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 ``<delegated_server_name>``.
A valid TLS certificate for ``<delegated_server_name>`` 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 ``<delegated_server_name>``.
A valid TLS certificate for ``<delegated_server_name>`` 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.<hostname>``. 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.<hostname>``. 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 ``<hostname>``. A valid TLS
certificate for ``<hostname>`` 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 ``<hostname>``. A valid TLS certificate for
``<hostname>`` 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 <https://www.certificate-transparency.org/>`_ project.
Expand All @@ -192,13 +202,6 @@ Retrieving server keys
specification due to lack of significance. It may be reviewed `from the historical draft
<https://github.com/matrix-org/matrix-doc/blob/51faf8ed2e4a63d4cfd6d23183698ed169956cc0/specification/server_server_api.rst#232version-1>`_.

.. NOTE::
Older drafts of this specification made use of a different style of key verification,
however for reasons discussed in `MSC1711 <https://github.com/matrix-org/matrix-doc/pull/1711>`_,
the approach was removed from the initial version of the specification. The older
draft may be reviewed `thanks to web.archive.org
<https://web.archive.org/web/20181019044236/https://matrix.org/docs/spec/server_server/unstable.html>`_.

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
Expand Down