In order to support encryption of connections you need to supply Prosody with a certificate and a key file in the standard PEM format. If you run other encrypted services such as a HTTPS website or mail server then you may have these already and can simply direct Prosody to use them. Otherwise you will need to obtain some.

For the time-being StartCom is providing free XMPP certificates compatible with Prosody.

This assumes you are using the terminal in Linux or similar operating system, with 'openssl' installed.

Run the following command:

 openssl req -new -x509 -days 365 -nodes -out "prosody.cert" -keyout "prosody.key"

You can replace 'prosody' in the filename with e.g. your domain name for identification.

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 Host in the Prosody config file).

Copy the .key and .cert files to somewhere Prosody can find them, make sure that they are readable to Prosody, and that the key is kept private from anyone else. In the global section of the config file, put:

ssl = {
  key = "/path/to/prosody.key";
  certificate = "/path/to/prosody.cert";
 }

A more complete guide on certificates and how to generate them can be found at http://www.madboa.com/geek/openssl/

Most systems have a place to store all the certificates from CAs that they trust. By default Prosody uses /etc/ssl/certs, but you can specify a different path with the capath option:

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

In order to supply an Intermediate Certification Authority (e.g. the XMPP ICA), simply add it to your existing certificate file. Make sure you start with your server-certificate and then append the ICA.

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

Some SSL keys are protected with passphrases. If this is the case for your file then Prosody will prompt you to enter the passphrase at startup. To get around this you can specify a 'password' field in the Prosody ssl config:

    ssl = {
        key = "/path/to/key.key";
        certificate = "/path/to/certificate.cert";
        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!

Openfire has a bug that causes the following errors in Prosody's logs:

  ssl handshake failed
  ssl handshake error: wrong version number

If you need to communicate with Openfire servers the only way currently is to disable server-to-server encryption. In a future Prosody version it will be possible to disable it for selected remote domains only. For now use the `s2s_allow_encryption` option. Simply set it to false as below:

    s2s_allow_encryption = false -- Disable server-to-server encryption