= Handling TLS related configuration
...
== Creating a TLS certificate
...

== Organization of TLS certificate-related files
There are two categories of files that need to be kept.
1. Files not directly relevant to production (`'/root/certstore/'` on a secure admin workstation):
* The certificate signing request (CSR);
* CSR creation config files for e.g. OpenSSL;
* CA and site certificates in various formats ;
* (This same file set for past, expired certificates.).
2. Files directly relevant to production (`'/etc/CLARIN_TLS/'`):
* The private key;
* Certificate bundles;
* Diffie-Hellman parameters.
{{{
/etc/CLARIN_TLS/
├── [dr-xr-xr-x root     root     1.0K]  _.clarin.eu
│   ├── [-r--r--r-- root     root     2.6K]  OCSP_bundle.pem
│   ├── [-r--r--r-- root     root     4.3K]  bundle.pem
│   └── [-r-------- root     root     1.6K]  private_nopass.key
└── [-r--r--r-- root     root      424]  dhparam.pem
}}}
For practical reasons, our services use a passphrase-less (unencrypted) private key.
Before private key files are generated (on a secure admin workstation): 
1. A root shell must be used for it (preferably a limited, secure shell such as `dash`).
2. Unnecessary processes must be closed (e.g. graphical environment, browser).
3. The `umask` must be set so that no file created is ever readable by someone other than the superuser. 
4. File permissions must be double checked after completing the work.

The private key should not be stored outside server hosts that critically need it, except for a minimal number of backups on secure admin workstations, always in encrypted form.

== Bundling TLS certificates
=== Bundle for `nginx`'s `ssl_certificate` (site, intermediate, root)
{{{
#!sh
## as root:
cd '/root/certstore/' &&
printf '\n' > 'newline' &&
## Concatenate certificates in this order for Nginx
cat 'clarin.eu/cert/wildcard-clarin-eu.cer' 'newline' 'clarin.eu/cert/RapidSSLSHA256CA-G3.cer' 'newline' 'clarin.eu/cert/GeoTrustGlobalCA.cer' 'newline' > '/etc/CLARIN_TLS/_clarin.eu/bundle.cer'
dos2unix '/etc/CLARIN_TLS/_clarin.eu/bundle.cer'
chmod a=r '/etc/CLARIN_TLS/_clarin.eu/bundle.cer'
}}}

=== Bundle for `nginx`'s `ssl_trusted_certificate` (root, intermediate)

{{{
#!sh
## as root:
cd '/root/certstore/' &&
printf '\n' > 'newline' &&
## Concatenate certificates in this order for Nginx
cat 'clarin.eu/cert/GeoTrustGlobalCA.cer' 'newline' 'clarin.eu/cert/RapidSSLSHA256CA-G3.cer' 'newline' > '/etc/CLARIN_TLS/_clarin.eu/trusted_bundle.cer'
dos2unix '/etc/CLARIN_TLS/_clarin.eu/trusted_bundle.cer'
chmod a=r '/etc/CLARIN_TLS/_clarin.eu/trusted_bundle.cer'
}}}

== Testing connectivity to an HTTPS web server that uses Server Name Indication
If you have e.g. a Docker container listening on 127.0.0.1, port 443, issue:
{{{
#!sh

curl -v -4 --resolve 'infra.clarin.eu:443:127.0.0.1' --resolve 'infra.clarin.eu:80:127.0.0.1' 'https://infra.clarin.eu/'
}}}