38. Certificates

For the most part, ShimmerCat is a TLS-only web-server, where plain HTTP requests are always redirected to the secure HTTPS protocol. For HTTPS connections, ShimmerCat uses standard X.509 certificates and private keys, just as other web servers.

ShimmerCat will use certificate and private keys in two locations:

• In a domain-named subdirectory of <scratch-folder>/sni-certs.

• Or just immediately under the scratch folder.

If when ShimmerCat starts there are no usable certificates, ShimmerCat will create or use a starting Certification Authority in the local server, and use it to sign a certificate for all domains defined in the devlove file.

38.1. The start CA

The process of obtaining valid website certificates is designed to ensure that they are available only to somebody having enough control of the domain that the certificate represents. To make website development or when moving websites to ShimmerCat more fluid, ShimmerCat can create and maintain a local Certification Authority (CA) in a completely automatic way.

Files for the certificate authority are created under $HOME/.config/mousebox/ for the user under which ShimmerCat runs. The files include a self-signed CA root certificate that can be manually imported into browsers, and a ca_persistent_registry.bin file with serial counter of signed certificates and the private key of the start CA self-signed certificate. These files are created on-demand, the first time ShimmerCat needs to create a certificate for a domain.

Once you have set ShimmerCat to run a particular domain, it’s possible to fetch the CA root certificate using the special URL path http://<domain-or-ip-where-shimmercat-listens>/.well-known/mousebox/ca-root.pem. Note however:

• The above URL is HTTP

• If you are using a load-balancer to redirect HTTP requests to HTTPS, be sure to open a hole for the URL path /.well-known/mousebox/ca-root.pem.

Whenever ShimmerCat creates a certificate and private key pair with the start CA, those files are written to the top of the scratch folder, together with a matching certificate signing request, which can be submitted to a real Certificate Authority to purchase a real certificate accepted by all browsers, or to LetsEncrypt.

38.2. Certificate and private key format understood by ShimmerCat

When you need to run websites for actual Internet visitors, you need to obtain one or many certificates the normal way. ShimmerCat understands certificates built using a very conventional format:

• The private key should be in PKCS #8 format, and the file should be called privkey.unencrypted-pkcs8.pem and exists either directly on the scratch folder or under sni-certs/<domain-name>/.

• The leaf certificate, together with any intermediate certificates, should be in PEM encoding. If there are intermediate certificates, they should be after the leaf certificate in the PEM file. And there should be an empty line at the end of the file.

38.3. Example workflow for setting up TLS

Imagine you want to start using ShimmerCat for domain www.example.com, then you can follow the following steps to get up and running with TLS:

38.3.1. First few minutes: let ShimmerCat use the Start CA

You just create a devlove.yaml file with the configuration for www.example.com, e.g.:

shimmercat-devlove:
  domains:
    elec www.example.com:
        root-dir: /var/www/www.example.com/

cd into the folder with the devlove file and and start ShimmerCat with

$ shimmercat internet  --listen 0.0.0.0:4043 -t 8080

In the command above we have used port numbers that do not require special privileges to bind, but in practice you may want to use ports 443 or port 80 to connect to, something you can achieve by either putting ShimmerCat behind a TCP load-balancer, running the script prime_shimmercat.sh next to ShimmerCat’s executable with root privileges, or running ShimmerCat with root privileges.

Then, you can fetch the CA root certificate using a browser or the curl command:

$ curl http://<address-of-your-server>:8080/.well-known/mousebox/ca-root.pem

Now you have your own CA root certificate, which you can install in your development browser. After that, you should be able to connect to www.example.com served by ShimmerCat either directly or through ShimmerCat’s built-in SOCKS5 proxy.

38.3.2. Next step: acquire a real certificate

To acquire a real certificate, you can use the .csr file that ShimmerCat creates in the previous step, submit it to any SSL certificate seller, e.g. “NameCheap”, and do the domain validation steps as prescribed by said seller. Then you can prepare the final .pem file as described above.

Note that the .csr contains the public key matching the private key created by the Start CA, so you need to take good care of said private key.

An alternative way to get certificates issued is through LetsEncrypt. We support LetsEncrypt directly via sc_pack, where domain ownership can be validated for an entire ShimmerCat CDN network, or if you already have something setup through certbot, via a special certificate installation command in sc_pack.

38.4. LetsEncrypt validation support

ShimmerCat QS does not implement all of the ACME protocol on its own, because other parts of our infrastructure are better at securely storing the cryptographic keys needed to operate ACME. However, ShimmerCat implements the bits needed to verify domain ownership using the “http-01” challenge and the “tls-alpn-01” challenge. To use it, just place specially named files in the scratch-folder.

38.5. 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/www.domain.com/cert.pem

• Unencrypted 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.