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
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
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
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
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.pemand exists either directly on the scratch folder or under
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
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
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
certbot, via a special certificate
installation command in
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:
Unencrypted private key:
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.