[[ch-sslreference]]
== SSL configuration
(((SSL, Configuration)))

glossaryterm:SSL[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.

=== 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
https://www.rapidssl.com[Rapid SSL] and
https://www.comodo.com[Comodo].

In December 2015, a new, free, automatic SSL certificate service
started issuing certificates.  This servers is called
https://letsencrypt.org[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.
(((LetsEncrypt)))

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

=== 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'.

=== 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 [directory]'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
------------------------

=== 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

//
// This layout section should always be last.
//
[[s-ssl-configuration-layout]]
=== SSL Configuration layout
(((SSL, configuration layout)))

Here is an example configuration layout for the domain
+my-brilliant-site.com+, all of which is contained under
[directory]'/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-provider)))
'config/ssl.crt':: Legacy SSL certificate.
(((config/,ssl.crt)))
'config/ssl.key':: Legacy SSL key.
(((config/,ssl.key)))
'config/ssl.bundle':: Legacy SSL certificate chain or bundle.
(((config/,ssl.bundle)))
'config/ssl.combined':: Legacy combined SSL certificate, chain, and
key.
(((config/,ssl.combined)))
[directory]'config/ssl/':: This is the SSL configuration directory
(((config/,ssl/)))
[directory]'config/ssl/letsencrypt/':: This is the LetsEncrypt
configuration directory.
(((config/,ssl/,letsencrypt/)))
[directory]'config/ssl/sets/':: This is the directory that contains
all the various SSL certificate and key sets.
(((config/,ssl/,sets/)))
[directory]'config/ssl/current':: This is a symbolic link to the
current SSL certificate and key set
(((config/,ssl/,current)))

==== Self-signed SSL provider configuration

These files can go in the domain's [directory]'config/' directory, or
in [directory]'/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/, rsa_key_size)))
'ssl/selfsigned/lifetime':: The length of time in days the certificate
should be valid for.  Defaults to 365.
(((ssl/, selfsigned/, lifetime)))

==== LetsEncrypt SSL provider configuration

These files can go in the domain's [directory]'config/' directory, or
in [directory]'/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/, rsa_key_size)))
'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/, email)))
'ssl/letsencrypt/endpoint':: The LetsEncrypt endpoint to use. Defaults to
https://acme-v01.api.letsencrypt.org/directory.
(((ssl/, letsencrypt/, endpoint)))
'ssl/letsencrypt/docroot':: The document root for this domain.
Defaults to [directory]'/srv/domain.com/public/htdocs'. This is
required for the LetsEncrypt domain verification to take place.
(((ssl/, letsencrypt/, docroot)))
'ssl/letsencrypt/account_key'::  The private RSA key for this
LetsEncrypt account.  A new one is generated if not present.
(((ssl/, letsencrypt/, account_key)))


