Using Let’s Encrypt

We have a page dedicated to using Let’s Encrypt with Prosody.

Using other certificate authorities

Any recognised certificate authority can provide certificates for you, usually for a fee, valid for a certain period of time (usually a year).

*Note:* StartSSL (StartCom) used to be popular within the XMPP community. Their certificates are no longer recommended. For a free alternative, consider using Let's Encrypt instead.

CAs will usually ask you to send them a certificate signing request (CSR). Prosody can generate one for you based on any host in your config. Simply run:

  prosodyctl cert request example.com

After the CA provides you with your new certificate, proceed to installing the certificate.

Creating self-signed certificates

Instead of using a certificate authority, you can create a "self-signed" certificate instead. These are quick and easy to create, but they will show security warnings in clients, and some clients or other servers may refuse to connect to your server entirely.

Prosody makes it easy to produce a self-signed certificate from a host in your config file. Simply run:

  prosodyctl cert generate example.com

Enter the information openssl asks for, it will be encoded in the certificate, and what you enter isn't too important, except ensure that when it asks for the "Common Name (eg, YOUR name)" you must enter the domain of your Prosody server (that is, whatever you defined with VirtualHost in the Prosody config file).

The generated certificate can be used immediately after running prosodyctl reload, if you have not changed the certificate path in the config file.

In earlier versions of Prosody, you will need to copy the generated .key and .crt file to an appropriate place (e.g. /etc/prosody/certs) and set the appropriate permissions.

Manual location

If you need to override the automatic location, you will need to provide the following config under the VirtualHost:

VirtualHost "example.com"
  ssl = {
    certificate = "/etc/prosody/certs/example.com.crt";
    key = "/etc/prosody/certs/example.com.key";
  }

Reload Prosody (e.g. prosodyctl reload) to use the new certificate and key.

Note: If you received your certificate from a certificate authority, many require you to include an 'intermediate' certificate as well as yours. Simply add it into your certificate file, at the end. See certificate chains for more info. If your certificate came from Let's Encrypt, then fullchain.pem already contains this.

Automatic certificate import

prosodyctl has the ability to import and activate certificates in one command:

prosodyctl --root cert import HOSTNAME /path/to/certificates

Certificates and their keys are copied to /etc/prosody/certs (can be changed with the certificates option) and then it signals Prosody to reload itself. --root lets prosodyctl write to paths that may not be writable by the prosody user, as is common with /etc/prosody. Multiple hostnames and paths can be given, as long as the hostnames are given before the paths.

This command can be put in cron or passed as a callback to automated certificate renewal programs such as certbot or other Let's Encrypt clients. For more information on using Prosody with these, see our Let's Encrypt page.

Certificate chains

Many certificate authorities provide you with an intermediate certificate which your server must supply to clients in addition to your own certificate so that they can verify it successfully.

The certbot (formerly "official") Let's Encrypt client includes the certificate and intermediate in the fullchain.pem file, so you should configure Prosody to use this as certificate.

ssl = {
  certificate = "/etc/letsencrypt/live/example.com/fullchain.pem"; -- Note: Only readable by root by default
  key = "/etc/letsencrypt/live/example.com/privkey.pem";
}

Your CA should tell you if you need an intermediate certificate, and either send it to you or tell you where to download it from. Once you have it, you can simply add it to the end of your existing certificate file. The order is important, your own certificate must be at the top.

On the command-line, this is an easy way to append the intermediate (ICA) certificate to yours:

cat /path/to/ica.crt >> /path/to/prosody.crt

If you get them the wrong way round you might see this error when connecting with your client:

  info    Client disconnected: no shared cipher

Note: This error can also happen for other reasons, for example if your key file does not match your certificate, or the format of your certificate/key file is incorrect (they need to be in the standard PEM format).

Specify trusted certificate store

Most systems have a place to store all the certificates from CAs that they trust. By default Prosody uses the operating system's trusted certificate store (generally /etc/ssl/certs on Linux), but you can specify a different path with the capath option:

ssl = {
  -- (other SSL options here) --
 
  capath = "/usr/mycertstore";
 }

Passphrases

Some SSL keys are protected with passphrases. If this is the case for your file then you can specify a 'password' field in the Prosody ssl config. For example:

    ssl = {
        key = "/path/to/key.key";
        certificate = "/path/to/certificate.crt";
        password = "youllneverguess";
    }

However note that including your password in plain text in a config file can compromise your key if you're not careful and the passphrase is the only security measure. Always check that the permissions on both Prosody's config and the key itself are secure against untrusted users.

Should you want to remove the passphrase from a key entirely, you can run:

 cp server.key server.key.orig
 openssl rsa -in server.key.orig -out server.key

Again, be sure to check permissions!

Permissions

Prosody's certificates and keys must be readable by the user that Prosody runs as. For security reasons it is recommended to make sure that no other user (except root) can read the key file.

These examples assume that Prosody is running as the prosody user (the default in most packages).

  sudo chmod 640 /path/to/certificate.key
  sudo chown root:prosody /path/to/certificate.key

Prosody should also be able to read the parent directories of the file.

To test that only Prosody can read the file:

  sudo -u prosody cat /path/to/certificate.key # Should succeed
  sudo -u nobody cat /path/to/certificate.key # Should fail

Automatic location

Prosody will automatically search for a certificate and key for each host, unless a path is manually specified in the config file.

By default the directory that Prosody searches is the 'certs' subdirectory in the same location as the config file. You can override this with the global 'certificates' option:

   -- Global option only (won't work under a VirtualHost or Component):
   certificates = "/etc/prosody/certs"

Within this directory, these are the locations that Prosody will search: