ACME CA Server

Features

• ACME Server implementation (http-01 challenge)
• Builtin CA to sign/revoke certificates (can be replaced with an external CA), CA rollover is supported
• Notification Mails (account created, certificate will expire soon, certificate is expired) with customizable templates
• Web UI (certificate log) with customizable templates

Tested with Certbot, Traefik, Caddy, uacme, acme.sh.

Setup

1. Generate a CA root certificate (or use an existing cert)

$ openssl genrsa -out ca.key 4096
$ openssl req -new -x509 -nodes -days 3650 -subj "/C=DE/O=Demo" -key ca.key -out ca.pem

2. Deploy the container

Docker Compose snippet:

version: '2.4'
services:

  acme-ca-server:
    image: knrdl/acme-ca-server
    restart: always
    environment:
      EXTERNAL_URL: http://localhost:8080
      DB_DSN: postgresql://postgres:secret@db/postgres
    # ports:
    #   - "8080:8080"
    networks:
      - net
    volumes:
      - ./ca.key:/import/ca.key:ro # needed once to import new ca
      - ./ca.pem:/import/ca.pem:ro # needed once to import new ca
    mem_limit: 250m

  db:
    image: postgres:15-alpine
    restart: always
    environment:
      POSTGRES_PASSWORD: secret
    networks:
      - net
    volumes:
      - ./db:/var/lib/postgresql/data
    mem_limit: 250m

networks:
  net:

3. Reverse proxy

Serve the app behind a TLS terminating reverse proxy, e.g. as https://acme.mydomain.org

The app listens on port 8080 for http traffic.

4. Test with certbot

docker run -it --rm certbot/certbot certonly --server https://acme.mydomain.org/acme/directory --standalone --no-eff-email --email user1@mydomain.org -v --domains test1.mydomain.org

Customizations

Environment Variables

Customize templates

Mail

Templates consist of subject.txt and body.html (see here). Overwrite the following files:

• /app/mail/templates/cert-expired-info/{subject.txt,body.html}
• /app/mail/templates/cert-expires-warning/{subject.txt,body.html}
• /app/mail/templates/new-account-info/{subject.txt,body.html}

Template parameters:

• app_title: str application title from WEB_APP_TITLE
• app_desc: str application description from WEB_APP_DESCRIPTION
• web_url: str web index url from EXTERNAL_URL
• acme_url: str acme directory url
• domains: list[str] list of expiring domains
• expires_at: datetime domain expiration date
• expires_in_days: int days until cert will expire
• serial_number: str expiring certs serial number (hex)

Web UI

Custom files to be served by the http server can be placed in /app/web/www.

Overwrite templates (see here):

• /app/web/templates/cert-log.html (Certificate Listing)
• /app/web/templates/domain-log.html (Domain Listing)
• /app/web/templates/index.html (Startpage)

Template parameters:

• app_title: str application title from WEB_APP_TITLE
• app_desc: str application description from WEB_APP_DESCRIPTION
• web_url: str web index url from EXTERNAL_URL
• acme_url: str acme directory url
• certs: list list of certs for cert-log.html
• domains: list list of domains for domain-log.html

Provide a custom CA implementation

First set env var CA_ENABLED=False. Then overwrite the file /app/ca/service.py (see here) in the docker image. It must provide two functions:

1. sign_csr()

async def sign_csr(csr: x509.CertificateSigningRequest, subject_domain: str, san_domains: list[str]) -> SignedCertInfo:
    ...

• csr: a x509.CertificateSigningRequest object
• subject_domain: the main domain name for the certificate
• san_domains: subject alternative names, all domain names (including subject_domain) for the certificate
• returns: instance of SignedCertInfo()

class SignedCertInfo:
    cert: x509.Certificate
    cert_chain_pem: str

• cert: a x509.Certificate object
• cert_chain_pem: a PEM-encoded text file containing the created cert as well as the root or also intermediate cert. This file will be used by the ACME client

2. revoke_cert()

async def revoke_cert(serial_number: str, revocations: set[tuple[str, datetime]]) -> None:
    ...

• serial_number: certificate serial number to revoke as hex value
• revocations: all revoked certificates including the one specified by serial_number. It's a set of tuples containing (serial_number, revocation_date)
• returns: no error on success, throw exception otherwise

A custom CA backend must also handle the CRL (certificate revocation list) distribution.

Internals

Entities

flowchart LR
    accounts -->|1:0..n| orders
    orders -->|1:1..n| authorizations
    authorizations -->|1:1| challenges
    orders -->|1:0..1| certificates