Documentation of new options

3 files changed, 68 insertions, 31 deletions

diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md
index 8eb22656db..c7959a27ca 100644
--- a/docs/MSC1711_certificates_FAQ.md
+++ b/docs/MSC1711_certificates_FAQ.md
@@ -177,6 +177,41 @@ You can do this with a `.well-known` file as follows:
        on `customer.example.net:8000` it correctly handles HTTP requests with
        Host header set to `customer.example.net:8000`.
 
+## Turning off certificate validation
+
+It is possible to turn off certificate validation for remote servers, but
+note that this must be explicitly enabled and is thus only suitable for
+private federations. This will only disable TLS certificate validation on
+federation endpoints; other requests made to recaptcha, identity services
+etc. will be unaffected.
+
+```
+tls.federation_verify_certificates = false
+```
+
+You can also only disable certificate validation for a specific set of
+homeservers:
+
+```
+tls.federation_certificate_verification_whitelist:
+  - subdomain.my-server.org
+  - example.org
+  - 1.2.3.4
+```
+
+## Specifying your own Certificate Authorities
+
+If you would like to specify your own list of trusted Certificate
+Authorities, you can do so with the following option. **Note that this list
+will replace any certificates provided by your operating environment:**
+
+```
+tls.federation_custom_ca_list:
+  - myCA1.pem
+  - myCA2.pem
+```
+
+Certificate files must be provided in PEM format.
 
 ## FAQ
 
diff --git a/synapse/config/server.py b/synapse/config/server.py
index affba6d920..08e4e45482 100644
--- a/synapse/config/server.py
+++ b/synapse/config/server.py
@@ -110,22 +110,6 @@ class ServerConfig(Config):
         # due to resource constraints
         self.admin_contact = config.get("admin_contact", None)
 
-        self.federation_verify_certificates = config.get(
-            "federation_verify_certificates", False,
-        )
-
-        # Whitelist of domains to not verify certificates for
-        self.federation_certificate_verification_whitelist = None
-        federation_certificate_verification_whitelist = config.get(
-            "federation_certificate_verification_whitelist", None
-        )
-
-        # Store whitelisted domains in a hash for fast lookup
-        if federation_certificate_verification_whitelist is not None:
-            self.federation_certificate_verification_whitelist = {}
-            for domain in federation_certificate_verification_whitelist:
-                self.federation_certificate_verification_whitelist[domain] = True
-
         # FIXME: federation_domain_whitelist needs sytests
         self.federation_domain_whitelist = None
         federation_domain_whitelist = config.get(
@@ -355,18 +339,6 @@ class ServerConfig(Config):
         #
         #enable_search: false
 
-        # Whether to verify TLS certificates when sending federation traffic.
-        #
-        #federation_verify_certificates: true
-
-        # Prevent federation certificate validation on the following whitelist
-        # of domains. Only effective if federation_verify_certicates is true.
-        #
-        #federation_certificate_validation_whitelist:
-        #  - lon.example.com
-        #  - nyc.example.com
-        #  - syd.example.com
-
         # Restrict federation to the following whitelist of domains.
         # N.B. we recommend also firewalling your federation listener to limit
         # inbound federation traffic as early as possible, rather than relying
diff --git a/synapse/config/tls.py b/synapse/config/tls.py
index 5e4ed8289d..e2e4e15c3f 100644
--- a/synapse/config/tls.py
+++ b/synapse/config/tls.py
@@ -72,6 +72,23 @@ class TlsConfig(Config):
 
         self.tls_fingerprints = list(self._original_tls_fingerprints)
 
+        # Whether to verify certificates on outbound federation traffic
+        self.federation_verify_certificates = config.get(
+            "federation_verify_certificates", False,
+        )
+
+        # Whitelist of domains to not verify certificates for
+        self.federation_certificate_verification_whitelist = None
+        federation_certificate_verification_whitelist = config.get(
+            "federation_certificate_verification_whitelist", None
+        )
+
+        # Store whitelisted domains in a hash for fast lookup
+        if federation_certificate_verification_whitelist is not None:
+            self.federation_certificate_verification_whitelist = {}
+            for domain in federation_certificate_verification_whitelist:
+                self.federation_certificate_verification_whitelist[domain] = True
+
         # List of custom certificate authorities for TLS verification
         self.federation_custom_ca_list = config.get(
             "federation_custom_ca_list", [],
@@ -225,15 +242,28 @@ class TlsConfig(Config):
         #
         #tls_private_key_path: "%(tls_private_key_path)s"
 
+        # Whether to verify TLS certificates when sending federation traffic.
+        #
+        #federation_verify_certificates: true
+
+        # Prevent federation certificate validation on the following whitelist
+        # of domains. Only effective if federation_verify_certicates is true.
+        #
+        #federation_certificate_validation_whitelist:
+        #  - lon.example.com
+        #  - nyc.example.com
+        #  - syd.example.com
+
+
         # List of custom certificate authorities for federation traffic.
         #
         # Note that this list will replace those that are provided by your
         # operating environment. Certificates must be in PEM format.
         #
         #federation_custom_ca_list:
-        #  - myca1.pem
-        #  - myca2.pem
-        #  - myca3.pem
+        #  - myCA1.pem
+        #  - myCA2.pem
+        #  - myCA3.pem
 
         # ACME support: This will configure Synapse to request a valid TLS certificate
         # for your configured `server_name` via Let's Encrypt.