Skip to content
Snippets Groups Projects
Select Git revision
  • tedomum default
  • deploy-exploding-state-groups
  • fix-exploding-state-groups
  • v1.127.1+tedomum.1
  • v1.125.0+tedomum.1
  • v1.123.0+tedomum.1
  • v1.122.0+tedomum.1
  • v1.121.1+tedomum.1
  • v1.119.0+tedomum.1
  • v1.118.0+tedomum.1
  • v1.114.0+tedomum.1
  • v1.109.0+tedomum.1
  • v1.105.1+tedomum.1
  • v1.98.0+tedomum.1
  • v1.97.0+tedomum.1
  • v1.96.1+tedomum.1
  • v1.95.1+tedomum.1
  • v1.88.0+tedomum.1
  • v1.73.0
  • v1.73.0rc2
  • v1.73.0rc1
  • v1.72.0
  • v1.72.0rc1
23 results
Blame Permalink
MSC1711_certificates_FAQ.md 14.91 KiB

MSC1711 Certificates FAQ

Historical Note

This document was originally written to guide server admins through the upgrade path towards Synapse 1.0. Specifically, MSC1711 required that all servers present valid TLS certificates on their federation API. Admins were encouraged to achieve compliance from version 0.99.0 (released in February 2019) ahead of version 1.0 (released June 2019) enforcing the certificate checks.

Much of what follows is now outdated since most admins will have already upgraded, however it may be of use to those with old installs returning to the project.

If you are setting up a server from scratch you almost certainly should look at the installation guide instead.

Introduction

The goal of Synapse 0.99.0 is to act as a stepping stone to Synapse 1.0.0. It supports the r0.1 release of the server to server specification, but is compatible with both the legacy Matrix federation behaviour (pre-r0.1) as well as post-r0.1 behaviour, in order to allow for a smooth upgrade across the federation.

The most important thing to know is that Synapse 1.0.0 will require a valid TLS certificate on federation endpoints. Self signed certificates will not be sufficient.

Synapse 0.99.0 makes it easy to configure TLS certificates and will interoperate with both >= 1.0.0 servers as well as existing servers yet to upgrade.

It is critical that all admins upgrade to 0.99.0 and configure a valid TLS certificate. Admins will have 1 month to do so, after which 1.0.0 will be released and those servers without a valid certificate will not longer be able to federate with >= 1.0.0 servers.

Full details on how to carry out this configuration change is given below. A timeline and some frequently asked questions are also given below.

For more details and context on the release of the r0.1 Server/Server API and imminent Matrix 1.0 release, you can also see our main talk from FOSDEM 2019.

Contents

  • Timeline
  • Configuring certificates for compatibility with Synapse 1.0
  • FAQ
    • Synapse 0.99.0 has just been released, what do I need to do right now?
    • How do I upgrade?
    • What will happen if I do not set up a valid federation certificate immediately?
    • What will happen if I do nothing at all?
    • When do I need a SRV record or .well-known URI?
    • Can I still use an SRV record?
    • I have created a .well-known URI. Do I still need an SRV record?
    • It used to work just fine, why are you breaking everything?
    • Can I manage my own certificates rather than having Synapse renew certificates itself?
    • Do you still recommend against using a reverse proxy on the federation port?
    • Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy?
    • Do I need the same certificate for the client and federation port?
    • How do I tell Synapse to reload my keys/certificates after I replace them?

Timeline

5th Feb 2019 - Synapse 0.99.0 is released.

All server admins are encouraged to upgrade.

0.99.0:

  • provides support for ACME to make setting up Let's Encrypt certs easy, as well as .well-known support.

  • does not enforce that a valid CA cert is present on the federation API, but rather makes it easy to set one up.

  • provides support for .well-known

Admins should upgrade and configure a valid CA cert. Homeservers that require a .well-known entry (see below), should retain their SRV record and use it alongside their .well-known record.