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 -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 the renew_certs periodically. 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>:

  • --push means 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 use run_prod action, 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.xs']
2019-08-12 10:25:57,439 - sc_pack - INFO - import_certificates: ATTENTION! No valid certificate found for domain
2019-08-12 10:25:57,440 - sc_pack - INFO - import_certificates: found certificate and key for domain
2019-08-12 10:25:57,440 - sc_pack - INFO - import_certificates: found certificate and key for domain
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!


== Indexed domains with only expired certificates

domain                       expired
---------------------------  -------------------                 2019-03-17 05:50:56             2019-03-22 23:16:16         2019-03-22 23:16:16

== Certificates that will expire in two weeks

domain                     will expire            days valid
-------------------------  -------------------  ------------  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.csr

  • Private key: /srv/deployment_A/shimmercat-scratch-folder/privkey.pem

  • Certificate: /srv/deployment_A/shimmercat-scratch-folder/sni-certs/

  • Unencrypted private key: /srv/deployment_A/shimmercat-scratch-folder/sni-certs/

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.