first draft of adding .well-known to general docs

3 files changed, 76 insertions, 10 deletions

diff --git a/INSTALL.md b/INSTALL.md
index 2993f3a9e2..e7c3b2b461 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -375,8 +375,12 @@ To configure Synapse to expose an HTTPS port, you will need to edit
   `tls_private_key_path` lines under the `TLS` section. You can either
   point these settings at an existing certificate and key, or you can
   enable Synapse's built-in ACME (Let's Encrypt) support.  Instructions
-  for having Synapse automatically provision and renew federation 
-  certificates through ACME can be found at [ACME.md](docs/ACME.md).
+  for having Synapse automatically provision and renew federation
+  certificates through ACME can be found at [ACME.md](docs/ACME.md). If,
+  alternatively, you wish to delegate a TLS certificate from another domain
+  see the Well Known guide at [well_known.md](docs/well_known.md)
+
+
 
 ## Registering a user
 
diff --git a/README.rst b/README.rst
index 9a7c04b55e..61e9d24ac1 100644
--- a/README.rst
+++ b/README.rst
@@ -93,13 +93,13 @@ Unless you are running a test instance of Synapse on your local machine, in
 general, you will need to enable TLS support before you can successfully
 connect from a client: see `<INSTALL.md#tls-certificates>`_.
 
-An easy way to get started is to login or register via Riot at 
-https://riot.im/app/#/login or https://riot.im/app/#/register respectively. 
+An easy way to get started is to login or register via Riot at
+https://riot.im/app/#/login or https://riot.im/app/#/register respectively.
 You will need to change the server you are logging into from ``matrix.org``
-and instead specify a Homeserver URL of ``https://<server_name>:8448`` 
-(or just ``https://<server_name>`` if you are using a reverse proxy). 
-(Leave the identity server as the default - see `Identity servers`_.) 
-If you prefer to use another client, refer to our 
+and instead specify a Homeserver URL of ``https://<server_name>:8448``
+(or just ``https://<server_name>`` if you are using a reverse proxy).
+(Leave the identity server as the default - see `Identity servers`_.)
+If you prefer to use another client, refer to our
 `client breakdown <https://matrix.org/docs/projects/clients-matrix>`_.
 
 If all goes well you should at least be able to log in, create a room, and
@@ -134,6 +134,11 @@ ACME setup
 For details on having Synapse manage your federation TLS certificates
 automatically, please see `<docs/ACME.md>`_.
 
+Well Known setup
+=================
+
+For details on how to configure your TLS certificate such that one domain may
+delegate to another please see `<docs/well_known>`_.
 
 Security Note
 =============
@@ -242,8 +247,16 @@ should have the format ``_matrix._tcp.<yourdomain.com> <ttl> IN SRV 10 0 <port>
 Note that the server hostname cannot be an alias (CNAME record): it has to point
 directly to the server hosting the synapse instance.
 
-You can then configure your homeserver to use ``<yourdomain.com>`` as the domain in
-its user-ids, by setting ``server_name``::
+If it is not possible to acquire a certificate valid for you matrix domain,
+the correct method is create a Well Known entry. For more details on how to
+configure Well Known `see <https://github.com/matrix-org/synapse/blob/master/docs/well_known.md`_
+
+For those of you upgrading your TLS certificate in readiness for Synapse 1.0,
+please take a look at `our guide <https://github.com/matrix-org/synapse/blob/master/docs/MSC1711_certificates_FAQ.md#configuring-certificates-for-compatibility-with-synapse-100>`_
+
+Having created a valid TLS certificate you can then configure your homeserver
+to use ``<yourdomain.com>`` as the domain in its user-ids, by setting
+``server_name``::
 
     python -m synapse.app.homeserver \
         --server-name <yourdomain.com> \
diff --git a/docs/well-known.md b/docs/well-known.md
new file mode 100644
index 0000000000..7e60029123
--- /dev/null
+++ b/docs/well-known.md
@@ -0,0 +1,49 @@
+# Well-Known
+
+The mapping for a server name to a hostname for federation is done via
+`SRV` records. Synapse v1.0 mandates valid X.509 certificates for the
+federation endpoint where the certificate must match the server name.
+
+This presents difficulties for hosted server offerings: ExampleCorp
+may want to delegate responsibility for running its Matrix homeserver to an
+outside supplier, but it may be difficult for that supplier to obtain a TLS
+certificate for `exmaple.com` (and ExampleCorp may be reluctant to let them have
+one).
+
+`.well-known` solves this problem by augmenting the current `SRV` record
+with a `.well-known` lookup.
+
+## Configuring `.well-known`
+
+ 1. Give synapse a certificate corresponding to the target domain
+    (`customer.example.net`). Currently Synapse's ACME
+    support [does not support
+    this](https://github.com/matrix-org/synapse/issues/4552), so you will have
+    to acquire a certificate yourself and give it to Synapse via
+    `tls_certificate_path` and `tls_private_key_path`.
+
+ 2. Restart Synapse to ensure the new certificate is loaded.
+
+ 3. Arrange for a `.well-known` file at
+    `https://<server_name>/.well-known/matrix/server` with contents:
+
+    ```json
+    {"m.server": "<target server name>"}
+    ```
+
+    where the target server name is resolved as usual (i.e. SRV lookup, falling
+    back to talking to port 8448).
+
+    In the above example, where synapse is listening on port 8000,
+    `https://example.com/.well-known/matrix/server` should have `m.server`
+    set to one of:
+
+    1. `customer.example.net` ─ with a SRV record on
+       `_matrix._tcp.customer.example.com` pointing to port 8000, or:
+
+    2. `customer.example.net` ─ updating synapse to listen on the default port
+       8448, or:
+
+    3. `customer.example.net:8000` ─ ensuring that if there is a reverse proxy
+       on `customer.example.net:8000` it correctly handles HTTP requests with
+       Host header set to `customer.example.net:8000`.