Note: This process has changed beginning with Citadel version 942. If you are running an earlier version, please upgrade first. The new process is much easier and far more versatile.
All protocols which are capable of encryption, such as IMAP and SMTP and XMPP, and even HTTPS in WebCit, will look for TLS keys and certificates in the following locations:
| /usr/local/citadel/keys/citadel.key | The private key for this server |
| /usr/local/citadel/keys/citadel.csr | A certificate signing request |
| /usr/local/citadel/keys/citadel.cer | The signed certificate (full chain with any intermediate certificates appended) |
All keys and certificates are expected to be in X.509 PEM-encoded format.
When the Citadel Server starts up, it will look for a key an certificate. If they are not found, a new key and a self-signed certificate will be generated. They will be written directly into the file locations listed above.
The self-signed certificate is adequate for small private systems. However, with low or no cost certificates now readily available, you will likely want to install a signed certificate.
Signed TLS certificates are now available at no cost from the nonprofit Let's Encrypt certificate authority. To use these on a Citadel system, you will need the Certbot utility installed.
WebCit is compatible with the HTTP-01 challenge when an HTTP instance is running on port 80. This means there is no need to run an external web server just to obtain a certificate. All you have to do is run a certbot command to obtain a certificate, and then link it in using a script like this one:
HOSTNAME=mycitadel.example.com
certbot certonly --agree-tos --non-interactive --text --rsa-key-size 4096 \
--email admin@${HOSTNAME} \
--webroot --webroot-path /usr/local/webcit \
--domains ${HOSTNAME}
ln -sfv /etc/letsencrypt/live/${HOSTNAME}/privkey.pem /usr/local/citadel/keys/citadel.key
ln -sfv /etc/letsencrypt/live/${HOSTNAME}/fullchain.pem /usr/local/citadel/keys/citadel.cer
Citadel will detect that the key and/or certificate have changed, and will automatically install them.
If you wish to obtain a certificate from some other location and install it manually, you will need to follow whatever procedure is appropriate for your certificate authority. You may use the private key generated by Citadel if you wish.
When you have your certificate, either replace the files in /usr/local/citadel/keys with your key and certificate, or link to them.