Skip to main content

Using Self-Signed Certificates with mkcert

Overview

We do not recommend using self-signed certificates with Element Enterprise On-Premise, however, we recognize that there are times when self-signed certificates can be the fastest way forward for demo or PoC purposes. It is in this spirit that these directions are provided.

Steps

The following instructions will enable you to use a tool called mkcert to generate self-signed certificates. Element does not ship this tool and so these directions are provided as one example of how to get self-signed certificates.

Ubuntu:

sudo apt-get install wget libnss3-tools

EL:

sudo yum install wget nss-tools -y

Both EL and Ubuntu:

wget
https://github.com/FiloSottile/mkcert/releases/download/v1.4.3/mkcert-v1.4.3-linux-amd64
sudo mv mkcert-v1.4.3-linux-amd64 /usr/bin/mkcert
sudo chmod +x /usr/bin/mkcert

Once you have mkcert executable, you can run:

mkcert -install
The local CA is now installed in the system trust store! ⚡️

Now, you can verify the CA Root by doing:

mkcert -CAROOT
/home/element-demo/.local/share/mkcert

Your output may not be exactly the same, but it should be similar. Once we’ve done this, we need to generate self-signed certificates for our hostnames. The following is an example of how to do it for element.local. You will need to do this for all of the aforementioned hostnames, including the fqdn.tld.

The run for the element fqdn looks like this:

mkcert element.local element 192.168.122.39 127.0.0.1

Created a new certificate valid for the following names
- "element.local"
- "element"
- "192.168.122.39"
- "127.0.0.1"

The certificate is at "./element.local+3.pem" and the key at
"./element.local+3-key.pem" ✅

It will expire on 1 May 2024

Once you have self-signed certificates, you need to copy them into the certs directory under the config directory. Certificates in the certs directory must take the form of fqdn.crt and fqdn.key.

Using our above example, these are the commands we would need to run from the installer directory: (We ran mkcert in that directory as well.)

mkdir ~/.element-onpremise-config/certs
cp element.local+3.pem  ~/.element-onpremise-config/certs/element.local.crt
cp element.local+3-key.pem  ~/.element-onpremise-config/certs/element.local.key
cp synapse.local+3.pem  ~/.element-onpremise-config/certs/synapse.local.crt
cp synapse.local+3-key.pem  ~/.element-onpremise-config/certs/synapse.local.key
cp dimension.local+3.pem  ~/.element-onpremise-config/certs/dimension.local.crt
cp dimension.local+3-key.pem  ~/.element-onpremise-config/certs/dimension.local.key
cp hookshot.local+3.pem  ~/.element-onpremise-config/certs/hookshot.local.crt
cp hookshot.local+3-key.pem  ~/.element-onpremise-config/certs/hookshot.local.key
cp local+2.pem  ~/.element-onpremise-config/certs/local.crt
cp local+2-key.pem  ~/.element-onpremise-config/certs/local.key