Table of Contents
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.
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.
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.
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
ssl.key),
ssl.csr),
ssl.crt),
ssl.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
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
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
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
config/ssl.crt
config/ssl.key
config/ssl.bundle
config/ssl.combined
config/ssl/
config/ssl/letsencrypt/
config/ssl/sets/
config/ssl/current
These files can go in the domain’s config/ directory, or
in /etc/symbiosis/, if you want to set host-wide
defaults.
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
ssl/letsencrypt/email
ssl/letsencrypt/endpoint
ssl/letsencrypt/docroot
/srv/domain.com/public/htdocs. This is
required for the LetsEncrypt domain verification to take place.
ssl/letsencrypt/account_key