13. Certificates¶
ShimmerCat gives you more than a way to generate and renew your TLS certificates for your deployments.
You should have a running delpoyment and a registered domain in order to generate a new certificate.
13.1. Generate and Renew certificates network-wide¶
You can manually renew or generate LetsEncrypt certificates for your domains by using one of the following methods:
13.1.1. Using ShimmerCat API¶
You can use ShimmerCat API url to renew or generate TLS certificates or by using a curl post request to the api from your terminal
$ curl -X POST https://accelerator.shimmercat.com/presentation-api/v1/renew-certificates/ -H 'Authorization: Token <your_authentication_token>' -H 'Content-type: application/json' -d '{"env_name": "<staging/production>", "domains": ["<your_domain>"]}'
13.1.2. Using sc_pack¶
$ sc_pack certs <action> -f configuration/file/path/sc_pack.conf.yaml <--push>
you can use these options for <action>:
run_staging: will generate the certificates using the ACME staging CA, this is useful for testing. We encourage you to run it this way first, and once confirmed that the certificates are properly generated for staging, then run it for “prod” (see below).run_prod: will generate the certificates using the ACME production CA. These are the certificates that browsers will recognize as valid.print_crontab_line: will print a crontab line to set up an automatic run of therenew_certsperiodically. The example print runs once a month, the first day of the month at 3:30am.push_local_certificates: will just push the local certificates that the sc_pack instance has to the centralized accelerator platform, and the platform will synchronize the certificates with all the deployment sites.pull_certificates <domain name>: will pull the certificates from the centralized accelerator platform for that specific domain, and deployment site.
and for <--push>:
--pushmeans that the generated certificates will be pushed and synchronized to all the sc_pack instances that have this domain deployed somewhere. It will be available just when you userun_prodaction, though.
If you have issues with either run_prod or run_staging, please double-check that the ports enabled for the celery
are reachable from outside.
13.2. Obtaining the CA root certificate¶
After creating a successfull deployment with the TLS certificates, you can now get the CA root certificate. For more information about how ShimmerCat generate certificates and how to obtain the CA root certificate you can refer to ShimmerCat QS documentation
13.3. Import certificates¶
Bundled in sc_pack is the command import_certificates, which is an alternative mean to install
certificates in deployments for sites which
already employ LetsEncrypt’s certbot, or for sites that use a more conventional
certificate authority, the kind that sends the certificates via e-mail.
Just execute the import_certificates subcommand passing a directory, a .zip file or a .tar.gz file as argument.
For a detailed explanation of how this command work, read after the examples below.
13.3.1. Examples¶
Here are some examples:
sc_pack import_certificates /etc/letsencrypt/live
The line above will try to find and install certificates for the domains in the current deployment
at the folder /etc/letsencrypt/live.
This folder is used by some certbot deployments.
By default, import_certificates will silently ignore any certificates it can’t use, including expired ones.
If you want to know if the command succeeds at finding and installing certificates, you can use
the switch --verbose (which is valid for all sc_pack commands) and even the -d switch to get a few tables
printed with information about the certificates found:
$ sc_pack import_certificates --verbose -d /etc/letsencrypt/live
....
2019-08-12 10:25:57,438 - sc_pack - INFO - import_certificates: installing certificates for ShimmerCat... domains: ['www.supershoes.se', 'supershoes.se', 'www.supershoes.es', 'www.supershoes.xs']
2019-08-12 10:25:57,439 - sc_pack - INFO - import_certificates: ATTENTION! No valid certificate found for domain www.supershoes.se
2019-08-12 10:25:57,440 - sc_pack - INFO - import_certificates: found certificate and key for domain supershoes.se
2019-08-12 10:25:57,440 - sc_pack - INFO - import_certificates: found certificate and key for domain www.supershoes.es
2019-08-12 10:25:57,441 - sc_pack - INFO - import_certificates: ATTENTION! No valid certificate found for domain www.supershoes.xs
2019-08-12 10:25:57,441 - sc_pack - INFO - import_certificates: certificates for ShimmerCat installed!
2019-08-12 10:25:57,441 - sc_pack - INFO - import_certificates: reloading ShimmerCat...
2019-08-12 10:25:57,441 - sc_pack - INFO - import_certificates: ShimmerCat ready!
= SC_PACK CERTIFICATE DIAGNOSTICS DATA
== Indexed domains with only expired certificates
domain expired
--------------------------- -------------------
www.ellpe.se 2019-03-17 05:50:56
securaprotect.se 2019-03-22 23:16:16
www.securaprotect.se 2019-03-22 23:16:16
...
== Certificates that will expire in two weeks
domain will expire days valid
------------------------- ------------------- ------------
www.supershoes.ch 2019-08-13 00:46:29 0
13.3.2. Technical explanation of import_certificates¶
The command works by indexing all the certificates and private keys recursively in the passed argument. This indexing operation includes the common name and subject alternative names present in all certificates, and distinguishes between domain and CA certificates. The indexing operation also takes into account a well-known set of root certificates from CAs, specifically the one present in certifi.
For each of the domains present in the devlove.yaml file, import_certificates uses the index to construct a
certificate chain that goes from the domain certificate to the CA root, excluding the later.
It then matches that certificate with one of the indexed private keys, and writes the chain and the private key
to the correct folder and files where ShimmerCat can find it.
The command has been built from the ground up as a tool for agencies that manage thousands of sites, and requires
little intervention from human operators.
Nevertheless, if you want to known in detail what’s gone wrong in some particular case, you can use the option
--save-db to write the index to disk.
The index includes data for all the certificates and private keys present in the argument folder or achive, not
just the ones in the sc_pack deployment.
The file containing the index is just a
SQLite database, and can be queried with any number of
tools for SQLite.
13.4. Certificates in the origin server¶
ShimmerCat doesn’t require you to have valid certificates in the origin server, but there are several good reasons to still have valid certificates in the origin.
If you want to get the certificates at the edges the simplest option is to just access the servers and get the certificates and their private keys from there (just ask and we will provide you the needed info). The more relevant files you will need are:
CSR:
/srv/deployment_A/shimmercat-scratch-folder/cert.csrPrivate key:
/srv/deployment_A/shimmercat-scratch-folder/privkey.pemCertificate:
/srv/deployment_A/shimmercat-scratch-folder/sni-certs/www.domain.com/cert.pemUnencrypted private key:
/srv/deployment_A/shimmercat-scratch-folder/sni-certs/www.domain.com/privkey.unencrypted-pkcs8.pem
Note that if the edges serve multiple domains, the in /srv/deployment_A/shimmercat-scratch-folder/sni-certs will be the certificates for all your domains.