ECDSA Certificates

ECDSA Certificates

Using ECDSA for certs defined in CERTCACHE_CERTS

CertCache supports generating and caching of ECDSA certificates.

ECDSA algorithms can be requested for each cert defined in CERTCACHE_CERTS separately:

version: '3.7'
services:
  certcache:
    container_name: certcache
      …
      CERTCACHE_CERTS: |
        - certName: cert1
          domains:
            - '<cert-domain-1>'
            - '*.<cert-domain-1>'
          keyType: ecdsa
        - certName: cert2
          domains:
            - '<cert-domain-2>'
            - '*.<cert-domain-2>'

In this example, cert1 will have an ECDSA public key algorithm, while cert2 will use the default algorithm of RSA.

If you want to use ECDSA for all certificates that do not specify a keyType, set the default algorithm using the env var CERTCACHE_KEY_TYPE:

version: '3.7'
services:
  certcache:
    container_name: certcache
      …
      CERTCACHE_CERTS: |
        - certName: cert1
          domains:
            - '<cert-domain-1>'
            - '*.<cert-domain-1>'
        - certName: cert2
          domains:
            - '<cert-domain-2>'
            - '*.<cert-domain-2>'
      CERTCACHE_KEY_TYPE: ecdsa

The default curve is secp256r1. The elliptic curve can be defined separately within each certificate within CERTCACHE_CERTS, or changed for all certs (that don't define an ellipticCurve) using the env var CERTCACHE_ELLIPTIC_CURVE:

version: '3.7'
services:
  certcache:
    container_name: certcache
      …
      CERTCACHE_CERTS: |
        - certName: cert1
          domains:
            - '<cert-domain-1>'
            - '*.<cert-domain-1>'
          keyType: ecdsa
        - certName: cert2
          domains:
            - '<cert-domain-2>'
            - '*.<cert-domain-2>'
          keyType: ecdsa
          ellipticCurve: secp256r1
      CERTCACHE_ELLIPTIC_CURVE: secp384r1

Using ECDSA for certs retrieved from the command line

You can get ECDSA certificates from the command line using the CLI command certcache get -d 'cert-domain-1,cert-domain-2' --key-type ecdsa:

If using docker-compose:

docker-compose run --rm certcache get -d 'cert-domain-1,cert-domain-2' --key-type ecdsa

Curves can optionally be specified using --elliptic-curve.

Minor updates

CATKeys

Keys should now be generated with a .catkey extension and live in a directory named catkeys. Keys with the previous extension in the previous directory (cahkeys) should still continue work.

Running tests in Docker multistage build

Running tests in the Docker build should help catch environmental defects

Supporting latest build dependencies for the Python cryptography library

Cryptography now requires Rust & Cargo as a build dep.

Docker container speedy shutdown has been restored

Container wasn't responding to SIGTERM and was taking 10 seconds before being SIGKILL'd

Fixed bug that broke the creation of cahkeys

Fixed bug that broke creation of cahkeys due to missing dependency in Docker image

Ignore mismatched hostnames

Ignore mismatched hostnames

Access keys (cahkeys) are no longer required to match the hostname being used to access CertCache server.

This simplifies running CertCache server in a containerised environment like Docker Swarm and Kubernetes, where you might use one hostname to access a service from inside the cluster, and another hostname (using public DNS) to access the service over the internet.

For example. If you are using Docker Swarm and have CertCache server running and clients running as follows:

services:
  certcacheserver:
    image: ghcr.io/93million/certcache:0.5.0
    ports:
      - '4433:4433/tcp'
      …
    command: ['serve']

you could access CertCache server from another container using the name certcacheserver. Because the ports have been defined, you could also access it over the internet using a global DNS name (eg. certcache.example.com) that points to the IP address of the Swarm.

Prior to this release it would not have been possible to access CertCache server using 2 different names (certcacheserver internally and certcache.example.com) as only 1 name could be provided when creating the cahkey.

The connection is still securely validated using the cahkeys, however it is of no concern what dns name is used to access the server.

This makes things flexible if you need to change service names or make public your CertCache server instance.

Docker image size

CertCache Docker image size has been reduced from around 480MB to 250MB using Docker's multistage build.

Fixed package vulnerabilities

Merge pull request #10 from 93million/dependabot/npm_and_yarn/bl-4.0.3

Bump bl from 4.0.2 to 4.0.3

Certificate onChange hook

Certificate onChange hook

We created an onChange hook to run commands when certificates are changed (installed or renewed). Use the property onChange in the CERTCACHE_CERTS env var to run a shell command. Commands are executed with the env var CERTCACHE_CHANGED_DIR which points to the directory of the changed certificate.

For example, the following command will concatenate fullchain.pem and privkey.pem for use with HAProxy:

CERTCACHE_CERTS: |
  - certName: <cert-name>
    domains:
      …
    onChange: cat $$CERTCACHE_CHANGED_DIR/fullchain.pem $$CERTCACHE_CHANGED_DIR/privkey.pem | tee $$CERTCACHE_CHANGED_DIR/cert-key-combined.pem

PATH is updated to include /certcache/bin directory. If there was an executable script at the location /certcache/bin/do_stuff then the command in onChange could simply read onChange: do_stuff - without requiring the full path.

Fixed package vulnerabilities

Merge pull request #9 from 93million/0.3.3-beta.0

Fixed package vulnerabilities

Explicitly targeting certbot 1.5.0 after certbot 1.6.0 was released

Merge pull request #7 from 93million/0.3.2-beta.0

Explicitly targeting certbot 1.5.0 after certbot 1.6.0 was released in pypi

Fixed package vulnerabilities

Merge pull request #5 from 93million/0.3.1-beta.0

Fixed package vulnerabilities

Standalone mode

Standalone mode

CertCache doesn't need to be run in a server/client configuration. It can be run in standalone mode which doesn't require a server.

This brings the benefits of being able to use the bunded standalone DNS server (certbot-dns-standalone) for DNS-01 validation and the ability to declaratively define certificates in docker-compose.yml, but loses the benefits of caching functionality. CertCache without the cache.

In this guide, we will run through setting up a simple site protected with a wildcard certificate.

Setting up a simple site using standalone mode

1: Instantiate a server

• Instantiate a server using Google Cloud/AWS/Linode/whatever and create a DNS A record that points your domain to this instance.
• Install Docker and Docker Compose (see https://docs.docker.com/get-docker/ and https://docs.docker.com/compose/install/)

2: Set up DNS

CertCache includes a standalone DNS server (certbot-dns-standalone) which means you do not need to configure and supply DNS API credentials. DNS-01 validation can be performed simply by configuring your domain's DNS records as follows:

• Create an A record for certcache.<your-domain> that points to your server instance
• Create an NS record for acme.certcache.<your-domain> that points to certcache.<your-domain>
• Create a CNAME record for _acme-challenge.<your-domain> that points to <your-domain>.acme.certcache.<your-domain>

Eg. if <your-domain> is example.com then add a CNAME record for the host _acme-challenge.example.com that points to example.com.acme.certcache.example.com

3: Create a docker-compose file

• Create a docker-compose.yml file and place in a directory on your server instance:

version: '3.7'
services:
  nginx:
    container_name: nginx
    restart: unless-stopped
    image: nginx
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - ./certcache/certs:/etc/certcache/certs:ro
      - ./nginx/config:/etc/nginx/conf.d:ro
      - ./www:/var/www:ro
    command: "/bin/sh -c 'while :; do sleep 36000 & wait $${!}; nginx -s reload; done & nginx -g \"daemon off;\"'"
  certcache:
    container_name: certcache
    restart: unless-stopped
    image: 93million/certcache
    ports:
      - '53:53/udp'
      - '53:53/tcp'
    volumes:
      - ./certcache/cache:/certcache/cache:rw
      - ./certcache/cahkeys:/certcache/cahkeys:ro
      - ./certcache/certs:/certcache/certs:rw
    environment:
      CERTCACHE_CERTBOT_EMAIL: <your@certbot-email.address>
      CERTCACHE_CERTS: |
        - certName: web
          domains:
            - '<your-domain>'
            - '*.<your-domain>'

• Change CERTCACHE_CERTBOT_EMAIL to the email address you provide to certbot 'for important account notifications'
• Replace the placeholders <your-domain> in the CERTCACHE_CERTS environment variable with your domain. The domain *.<your-domain> creates a wildcard certificate - it is useful if you want to host your website on the main domain and also multiple subdomains (eg. example.com, www.example.com, anything.example.com)

4: Create an Nginx site

• Create an Nginx config file at ./nginx/config/000-default.conf (relative to docker-compose.yml)

server {
  listen 443 ssl http2 default_server;
  listen [::]:443 ssl http2 default_server;
  ssl_certificate /etc/certcache/certs/web/fullchain.pem;
  ssl_certificate_key /etc/certcache/certs/web/privkey.pem;

  server_name _;

  root /var/www/;
}

server {
  listen 80 default_server;
  listen [::]:80;

  server_name _;

  location / {
    return 301 https://$host$request_uri;
  }
}

5: Create a web site

In this guide we will serve static files. A more practicle application would be to traffic requests to another container.

• Create an HTML file to serve and place it at ./www/index.html (relative to docker-compose.yml):

<!DOCTYPE html>
<html>
    <head>
        <title>CertCache</title>
    </head>
    <body>
        <h1>CertCache HTTPS test</h1>
    </body>
</html>

6: Start the container

• Run docker-compose up -d

The first time you run this, CertCache will use Certbot to generate the SSL certificates. After they are present they will be kept up-to-date. Nginx will start once the certificates are on disk.

Testing

You should now be able to access your site by visiting https://<your-domain> as well as https://www.<your-domain> and also https://whatever.<your-domain>. Visiting the insecure version of these sites should forward you to the secure version.

Example

This is a preconfigured example available in docker-compose/standalone for reference. Remember to change the references to <your-domain> in docker-compose.yml.

Migrating to CertCache server

In the future, if you decide to take advantage of the cache functionality provided by CertCache server (eg. to avoid Let's Encrypt usage limits), you can migrate to CertCache server with relatively little effort:

• Install CertCache Server
• Copy the client.cahkey from the server and place in ./cahkeys
• Change the DNS A record that points to certcache.<your-domain> to point to your CertCache server installation
• Set the env variable CERTCACHE_UPSTREAM in your CertCache container to certcache.<your-domain>