Matrix Synapse Certificates

· sysadmin openbsd acme matrix synapse

I’ve had a need to set up and run a Matrix homeserver and I wanted to try to set it up for general use as well as just for this project.

The one thing I wanted to do that is a little non-standard is to use the “plain” domain for my user ID while hosting the homeserver on a subdomain. In this case I wanted to use “” as the user ID domain, and “” to host the Synapse homeserver.

If you’ve run an XMPP server before then you’ll know about this sort of arrangement allowing you to seperate identity from the actual infrastructure providing the services. In XMPP this is achieved with DNS SRV records, for example: SRV 5 0 5222 SRV 5 0 5269

There are two records here, one for clients and one for servers. Both of these endpoints should use a TLS certificate with the plain domain “” in the name as this indirection doesn’t change the identity of the service you’re connecting to.

Matrix is considerably more complex unfortunately. There are still two types of discovery required: one for clients and one for servers. The implementation of these however are different. Let’s start with server to server (federation) discovery.

The specification outlines the 5 step process to be used to discover the server that should be connected to. Matrix prefers to use a well known file to be fetched via HTTPS to discover the server to connect to.

In my case, that means connecting to and expecting to receive a JSON object that looks something like:

{"m.server": ""}

If this succeeds then it will connect to the Synapse homeserver and expect that the TLS certificate will have the name I’ve not really got a web server set up there yet though which means that this will fail and move on to the next step.

The next step looks up a DNS SRV record, similar to that used by XMPP, that looks like: SRV 0 0 8448

This allows other Matrix homeservers to now discover my homeserver and federate, but the important thing to watch out for here is that now the name expected on the certificate is the plain domain name,

For clients, there is no DNS SRV option available, only the use of a JSON file at a well known URL. Clients always expect the name on the domain to be the name of the host running Synapse. As I’m the only user on this server I’m quite happy for now to just type into clients that I use rather than automatically discovering the server.

This means there’s a need for both the plain domain name and the server domain name to be present in certificates for federation and for client use. I suspect that the use of the server name is to better support operation from a browser. A browser can lookup the well known URL to get the JSON file, and then create a new HTTPS request to the homeserver. Without the server’s name on the certificate that would fail in the browser. For federation it’s possible to use the plain domain (and so have some better authenticity checks when you consider that the user IDs have the plain domain) because it’s the homeserver that is checking the certificates.

With XMPP, you just have the plain domain because both servers and clients are all XMPP aware and you’re not having to compromise on security checks based on what a browser can do for you.

So now I need to get two certificates into the Matrix homeserver: and I’m using OpenBSD which has acme-client(1) available, but this only implements the http-01 challenge. This means I won’t be able to use acme for the plain domain.

To set up acme-client for the server hostname, I used the hambsd-acme role to configure the client and set up periodic renewals. For the plain domain name, I paid for a certificate to be issued which gives it a longer expiry meaning I’m not having to constantly update it manually.

In the relayd.conf, I added:

tls keypair
tls keypair

This means that when a request comes in, the correct keypair will be chosen based on the SNI TLS option.

In the future, I’ll be aiming to switch from DNS SRV discovery to the well-known URL which will then allow me to use only the certificate for the server hostname and drop the certificate for the plain domain name.

If you would like to contact me with comments, please send me an email.
If you would like to support my free software work, you can support me on Patreon or donate via PayPal.

This post was syndicated on: