Chapter 4. SSL configuration

Table of Contents

4.1. SSL providers
4.2. SSL provider configuration
4.3. Generating certificates with symbiosis-ssl
4.4. Generating certificate signing requests
4.5. Applying a third party certificate
4.6. SSL Configuration layout

Secure Sockets Layer is a technique used to encrypt communication between two machines on a network. It uses a system of public and private keys to encrypt and decrypt the connection — the public key is used by the sender to encrypt, and the private key is used by the receiver to decrypt. This protocol is used not only for transactions involving a web server and browser, but also by the email servers and their clients.

In addition to the public key encryption, there is a system of trust that validates that the certificate presented actually belongs to the server that is presenting it. This system involved having the certificate signed by a trusted authority. Web browsers and email clients tend to come with a selection of certificates from trusted authorities pre-installed, which allows them to verify a previously unseen certificate as valid.

4.1. SSL providers

Until recently, having a certificate signed by a trusted authority involved having varying degrees of identity checks made, and paying a fee. Vendors that are able to sell you a certificate include Rapid SSL and Comodo.

In December 2015, a new, free, automatic SSL certificate service started issuing certificates. This servers is called LetsEncrypt, and it is supported by a number of big names on the internet, including Facebook and Mozilla. This service has now been successfully providing domain-verified certificates for a few months, and is used by Symbiosis to generate trusted certificates for all the domains on a machine.

Symbiosis can also generate self-signed certificates on occasions where it has not been possible to use LetsEncrypt.

4.2. SSL provider configuration

Symbiosis has the idea of "providers" to generate SSL keys, requests, and certificates. By default Symbiosis will use the LetsEncrypt provider, but you can specify another provider, e.g. *SelfSigned" by putting the word "selfsigned" in config/ssl-provider for the domain in question.

If you wish to use LetsEncrypt, put "letsencrypt" in config/ssl-provider.

If you wish to disable automatic certificate provisioning entirely, you can put the word false into config/ssl-provider.

4.3. Generating certificates with symbiosis-ssl

Symbiosis uses a command ‘symbiosis-ssl` to manage domains’ certificates. It is run on a daily basis to check and replace certificates that are due to expire in the next 10 days, or are otherwise missing.

This command can also be used to verify sites' certificates.

$ symbiosis-ssl --verbose
* Examining certificates for app.my-brilliant-site.com
  Current SSL set 0: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X1, expires 2016-05-25 23:00:00 UTC
* Examining certificates for my-brilliant-site.com
  Current SSL set 0: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X1, expires 2016-05-25 10:32:00 UTC
* Examining certificates for example.default.bytemark.uk0.bigv.io
  Current SSL set 4: signed by /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X1, expires 2016-05-29 10:26:00 UTC

This command shows the current set in place for each site. A set is a collection of files, consisting of

  • the private key (ssl.key),
  • certificate request (ssl.csr),
  • signed certificate (ssl.crt),
  • intermediate bundle (if required) (ssl.bundle),
  • a combined private key, and certificate, (and bundle) (ssl.combined).

Each set is kept in its own directory in config/ssl/sets, and the current set is symlinked to config/sets/current.

In the above output the host example.default.bytemark.uk0.bigv.io is currently using set 4. That means its directory layout will look like:

/srv/example.default.bytemark.uk0.bigv.io/config/ssl/current -> /srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/4
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/letsencrypt/account_key
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/0/ssl.combined
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/0/ssl.crt
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/0/ssl.csr
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/0/ssl.key
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/1 # (with a complete set of ssl.key etc)
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/2 #
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/3 #
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/4/ssl.bundle
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/4/ssl.combined
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/4/ssl.crt
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/4/ssl.csr
/srv/example.default.bytemark.uk0.bigv.io/config/ssl/sets/4/ssl.key

4.4. Generating certificate signing requests

If you wish to use a different certificate than the one Symbiosis has generated for your domain, you can use the certificate signing request that was created for the certificate that should already be in place. You can then go to your provider with this request, and ask them to generate a certificate.

The CSR generated will be for the "bare" domain, with all aliases as Subject Alternative Names.

If you wish to inspect the CSR, you can run

openssl req -in ssl.csr -text -noout

4.5. Applying a third party certificate

To add a third party SSL certificate for a website, upload your ssl.crt, ssl.key, and ssl.bundle files from the certificate provider to your server. For a domain example.com, these should be located at:

/srv/domain.com/config/ssl.crt
/srv/domain.com/config/ssl.key
/srv/domain.com/config/ssl.bundle

Ensure ssl-provider is set to false, by running: echo "false" > /srv/domain.com/config/ssl-provider

Remove the SSL current symlink if present, as this will otherwise take precedence: rm /srv/domain.com/config/ssl/current

Reconfigure the Apache vhost to activate the certificate: sudo symbiosis-httpd-configure -v domain.com

4.6. SSL Configuration layout

Here is an example configuration layout for the domain my-brilliant-site.com, all of which is contained under /srv/my-brilliant-site.com/.

config/ssl-provider
The SSL provider to be used for this domain. If this is set to false then no certificates will be generated for the domain.
config/ssl.crt
Legacy SSL certificate.
config/ssl.key
Legacy SSL key.
config/ssl.bundle
Legacy SSL certificate chain or bundle.
config/ssl.combined
Legacy combined SSL certificate, chain, and key.
config/ssl/
This is the SSL configuration directory
config/ssl/letsencrypt/
This is the LetsEncrypt configuration directory.
config/ssl/sets/
This is the directory that contains all the various SSL certificate and key sets.
config/ssl/current
This is a symbolic link to the current SSL certificate and key set

Self-signed SSL provider configuration

These files can go in the domain’s config/ directory, or in /etc/symbiosis/, if you want to set host-wide defaults.

ssl/selfsigned/rsa_key_size
The size of RSA key generated for both the SSL certificates, as well as the account. Defaults to 2048.
ssl/selfsigned/lifetime
The length of time in days the certificate should be valid for. Defaults to 365.

LetsEncrypt SSL provider configuration

These files can go in the domain’s config/ directory, or in /etc/symbiosis/ if you want to set host-wide defaults.

ssl/letsencrypt/rsa_key_size
The size of RSA key generated for both the SSL certificates, as well as the account. Defaults to 2048.
ssl/letsencrypt/email
The email address associated with the account. Defaults to root@example.default.bytemark.uk0.bigv.io, where example.default.bytemark.uk0.bigv.io is the hostname of the machine.
ssl/letsencrypt/endpoint
The LetsEncrypt endpoint to use. Defaults to https://acme-v01.api.letsencrypt.org/directory.
ssl/letsencrypt/docroot
The document root for this domain. Defaults to /srv/domain.com/public/htdocs. This is required for the LetsEncrypt domain verification to take place.
ssl/letsencrypt/account_key
The private RSA key for this LetsEncrypt account. A new one is generated if not present.