Home Download FAQ / Knowledge Base Screenshots Documentation Support Roadmap

Configuring SSL/TLS certificates in Citadel

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.

File locations

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.

Using a self-signed certificate

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.

Configuring Citadel to use the Let's Encrypt free certificate authority

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:

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.

Manual key generation and certificate installation

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.

There are no social media links here. Enjoy a friendly Citadel community instead. Or go outside.