SSL Configuration Reference
Secure Sockets Layer (SSL) is a system used to encrypt communication between two machines on a network, which uses public and private key encryption, with certificates signed by trusted parties, and is used by a huge range of services.
Sympl manages your SSL certificates for you, and by default will attempt to retrieve a free Let's Encrypt certificate for each of your configured websites and apply them the website and email for the domain.
While SSL and it's protocols has effectively been replaced by Transport Layer Security (TLS), it is still common to refer to the certificates and systems as 'SSL'.
SSL Providers
Until a few years ago, having a certificate signed by a trusted authority involved a number of manual identity checks and a fee to the certificate signer. These authorities include Comodo, Digicert and GlobalSign, among others.
At the end of 2015 a new free, automated, certificate signing service appeared in the form of Let's Encrypt, which is supported by a large number of tech companies including Mozilla, Google, Facebook and Cisco, and after only a few years is now used on a large range of sites.
Sympl will attempt to retrieve a Let's Encrypt certificate automatically, however it can also generate a 'self-signed' certificate for situations when it's not possible to retrieve one for the relevant domain from Let's Encrypt.
SSL Provider Configuration
Sympl has the concept of 'providers' when generating SSL certificates, keys and requests, and currently directly supports only two providers at present.
The file /srv/example.com/config/ssl-provider controls if :
If .../config/ssl-provider
|
Then |
|---|---|
Contains letsencrypt
|
A Let's Encrypt certificate will be retrieved. |
| Does not exist | |
Contains selfsigned
|
A Self-Signed certificate will be generated. |
Contains false
|
Automatic certificate generation will be disabled for the domain. |
| Is Empty | |
| Contains any other content |
Managing Certificates with sympl-ssl
Sympl uses the tool sympl-ssl to manage domain certificates. It runs daily overnight, and will attempt to retrieve new Let's Encrypt and Self-Signed certificates where missing, and will automatically attempt to renew any which are expiring.
It can also be used to report on certificate status:
sympl@sympl:~$ sudo sympl-ssl --verbose * Examining certificates for example.com Current SSL set 0: self-signed for /CN=example.com, expires 2020-07-09 16:14:09 UTC * Examining certificates for forum.sympl.io Current SSL set 1: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3, expires 2019-10-06 16:43:35 UTC * Examining certificates for mail.forum.sympl.io Current SSL set 1: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3, expires 2019-10-06 16:43:35 UTC * Examining certificates for sympl.io Current SSL set 4: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3, expires 2019-09-09 16:49:41 UTC * Examining certificates for wiki.sympl.io Current SSL set 2: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3, expires 2019-10-10 08:06:09 UTC
The example above shows the current certificate for each domain. These are 'sets', which are made up of a number of files stored in /srv/example.com/config/ssl/sets/<set_number>/, and The currently active set is symlinked as /srv/example.com/config/ssl/sets/current/
| Filename | Contents Description |
|---|---|
ssl.crt
|
The SSL certificate itself. |
ssl.key
|
The private key for the certificate. |
ssl.bundle
|
Intermediate Certification Authority (CA) certificate bundle. |
ssl.combined
|
Combined certificate, bundle (if available) and key, in that order. |
ssl.csr
|
A Certificate Signing Request. |
Let's Encrypt Certificates
This article is a Stub. You can help the Sympl Project by expanding it.
- Let's Encrypt certificates are retrieved automatically overnight, based on what domains are configured.
- Authenticating ownership of the domain requires the server to be serving the website.
- Certificate retrieval can be trigged manually with
sudo sympl-ssl --verbose example.com. - Issued certificates last for 90 days, and are automatically renewed when there are fewer than 30 days until expiry.
- Sympl uses the ACMEv02 endpoint with Let's Encrypt, but does not currently support retrieval of wildcard certificates.
Third Party Certificates
Sympl fully supports third party certificates, however due to the range of providers, certificate types, different processes and methods used, it's not possible to automatically generate the required files needed to support all providers.
Getting a New Third Party Certificate
If you want to swap to a purchased certificate, rather than using Let's Encrypt, you will likely need a Certificate Signing Request (.csr) file along with a new Private Key. The requirements for these can vary from provider to provider.
You can generate a CSR and save the keys to your home directory with:
openssl req -new -newkey rsa:2048 -nodes -keyout ~/example.com.key -out ~/example.com.csr
You will then be prompted for a number of pieces of information:
| Prompt | Information to Enter |
|---|---|
| Country Name | The two-letter ISO format country code for where your organization is registered. Note that for the UK it is 'GB'. |
| State or Province Name | The full name of the county/state/province where your organization is registered. |
| Localitiy Name | The full name of the city where your organization is registered. |
| Organization Name | The full registered name of your business, or or the name of the requestor if an individual. |
| Organization Unit Name | The 'Doing Business As' name, if applicable. |
| Common Name | The fully qualified domain name, such as example.com. If you're requesting a wildcard certificate, use *.example.com.
|
| Email Address | An administrative email address on the domain which can accept mail. Check with the Certificate Authority as to what they will accept before generating the certificate. |
| Challenge Password | Do not specify a password (leave blank). Note that you should still keep the generated .key file in a safe place. |
If you want to request a certificate with multiple domains or subdomains (other than www., which is usually added automatically), please check with the Certificate Authority for instructions on generating the CSR.
You can check the .csr file with the command openssl req -in ~/example.com.csr -text -noout.
Once you have the .csr file, you can provide that to the Certificate Authority, and they will provide you with a signed certificate and usually file containing the intermediate certificates.
Installing a Third Party Certificate
Once you have the certificate, key and intermediate certificate, you should disable automatic certificate provisioning and create a new sets directory in /srv/example.com/config/ssl/sets/. Note that you can use any name for the set, but in this case we are using manual. Also note that Sympl currently only supports RSA private keys and will ignore keys from other algorithms.
echo 'false' > /srv/example.com/config/ssl-provider mkdir -p /srv/example.com/config/ssl/sets/manual
Copy the files into /srv/example.com/config/ssl/sets/manual . You will probably need to rename the files as shown above, and likely combine the cert, bundle and key into the ssl.combined file. You can do that with:
cd /srv/example.com/config/ssl/sets/manual cat ssl.crt ssl.bundle ssl.key > ssl.combined
Once that has been done, you can swap to the new certificate set with:
sudo sympl-ssl example.com --verbose --select manual
SSL Hooks
There are a number of automatic hook scripts which are run once sympl-ssl completes, designed to update the relevant services or configs when SSL certificates have changed.
These are run from /etc/sympl/ssl-hooks.d/, must be executable, and will be passed live-update as the first parameter, with following parameters being the domains which have been changed.
Configuration Reference
| File or Directory | Used For | |
|---|---|---|
.../config/ssl-provider
|
Selects the automatic SSL provider to use, or disables automatic SSL generation. | More... |
.../config/ssl/
|
Directory for the SSL certificates and configuration. Permissions are secured with sympl-filesystem-security.
|
More... |
.../config/ssl/current/
|
A symbolic link which points toward the currently active certificate set directory. | More... |
.../config/ssl/set_id/
|
A directory containing the SSL files for the set set_id.
|
More... |
.../config/ssl/set_id/ssl.crt
|
The SSL certificate in X.509 format. | More... |
.../config/ssl/set_id/ssl.key
|
The SSL key in X.509 format. | More... |
.../config/ssl/set_id/ssl.bundle
|
The SSL intermediate certificate in X.509 format. | More... |
.../config/ssl/set_id/ssl.combined
|
A combination of ssl.crt, ssl.bundle and ssl.key, in that order.
|
More... |
.../config/ssl/set_id/ssl.csr
|
The Certificate Signing Request. file in X.509 format. | More... |
.../config/ssl/letsencrypt/email
|
Email address for Let's Encrypt registration and notices. This defaults to root@your-server-hostname so may need to be changed from the default if your server does not have a publicly visible name.
|
More... |
.../config/ssl/letsencrypt/rsa_key_size
|
The size in bits of the public RSA key generated for the SSL certificate. Defaults to 2048.
|
More... |
.../config/ssl/letsencrypt/endpoint
|
The Let's Encrypt API endpoint to use. Defaults to https://acme-v02.api.letsencrypt.org/directory.
|
More... |
.../config/ssl/letsencrypt/docroot
|
The document root for the domain, used to confirm ownership. Defaults to /srv/example.com/public/htdocs.
|
More... |
.../config/ssl/letsencrypt/account_key
|
The private RSA key for this Let's Encrypt account. Generated automatically if not present. | More... |
.../config/ssl/selfsigned/rsa_key_size
|
The size in bits of the public RSA key generated for the SSL certificate. Defaults to 2048.
|
More... |
.../config/ssl/selfsigned/lifetime
|
The length in days the certificate should be valid for. Defaults to 365.
|
More... |
See also Configuration Reference for other configuration files.