In a previous article here, I described how to setup an ACME server using Step-CA software. While writing that article I got tired fighting with some of the Step-CA nuances and asked myself if there was a better way.

Not finding a better way to issue certificates using the ACME protocol, I created ACME.cgi. This is a CGI script that will utilize an external CA tool to issue/revoke certificates using the ACME protocol (and yes... it's a shell script!).

Overview

The ACME.cgi script will utilize a standard web sever and CGI environment to allow ACME clients to register and issue certificates for domains. The ACME.cgi script does not actually do the work of creating, signing, revoking certificates. Those operations are farmed out to external tools.

This article, and ACME.cgi in general, assume that the external tools is Personal Certificate Authority (PCA). However, this is not required.

Setup

Since servers and requirements vary greatly, the options below give the steps to deploy ACME.cgi into a Docker, non-chroot and chroot web environment. Please note, that I cannot know your specific server setup and you may need to make additional adjustments.

These setups all assume that the ACME.cgi service will utilize the Personal Certificate Authority (PCA) script to manage certificate functions. (If you want more information on what PCA is checkout this article.) If you choose to utilize another tool, update/replace the ACME_helper.* files with whatever makes sense for your setup.

For All Options

The following will need to be done for all deployment options.

1. Download the latest version of ACME.cgi from github.
2. Download the latest version of PCA from github.
   1. Copy the pca script to a location in the PATH. i.e. /usr/local/bin/. If you will setup ACME.cgi in a CHROOT environment, then this path must be callable from that environment.
   2. Since these instruction assume that PCA will be called from the ACME_helper script, set the PCA_ROOT environment variable to the location where the ACME.cgi service is expected to store the certificate environment. i.e. /var/www/etc/pca.
3. Install a FastCGI server. e.g. fcgiwrap, slowcgi. This program is probably already in the package manager of the server.
4. Setup web server to send traffic to CGI file. Below is a quick config for nginx. This configlet assumes the following (adjust for your setup):
   1. The path ACME.cgi will be called from is https://ISSUER_DOMAIN/acme/ (where ISSUER_DOMAIN is the FQDN of the server hosting the application)
   2. The web root is /var/www/html
   3. Web server certificates are kept in /etc/certs
   4. FastCGI program is listening on localhost port 9000

server {
  listen 443 ssl;
  listen [::]:443 ssl;

  ssl_certificate /etc/certs/server.fullchain.pem;
  ssl_certificate_key /etc/certs/server.key;
# use if the server key is encrypted
#  ssl_password_file /etc/certs/server.pass;
  ssl_protocols   TLSv1.2 TLSv1.3;
  ssl_ciphers     HIGH:!aNULL:!MD5;

  index index.html;
  root /var/www/html;

  location /acme/ACME.cgi {
    include /etc/nginx/fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param SCRIPT_NAME nfquery.cgi;
  }
}

Deployment Options

On Docker system

This is the simplest deployment method. There is a Makefile created to assist in creation of the docker container. Three volumes are used, /config, /data and /logs. Config is used to store the configuration files for ACME.cgi and the web server. Data is where PCA certificates are stored as well as the ACME working files. Logs as the name implies, is where the logs are stored.

1. Change to the package/Docker path.
2. Build the docker image by running make build.

make build

3. Copy the env.example file to .env. Configure the .env file as necessary. Note: Set SERVER_NAME, CONTACT_EMAIL and SERVER_SECRET for the site.
4. Start the docker container. Use option A or B
   1. Start docker via make run.
   2. Start docker-container via docker-container up -d

The docker container will create a new CA, create and export a CA directory, create certificate and keys for the container and enable all cron scripts.

On non-chroot systems

This is only slightly more complicated that the docker image. In this option, all configuration steps will need to be performed manually.

1. Copy the ACME.cgi ACME_helper.sh and ACME_cleaner.sh files to the CGI-BIN directory.
2. Copy the ACME.conf example to the /etc directory.
   1. Update the ACME.conf file as necessary. Note that the ISSUER_DOMAIN and ISSUER_EMAIL do not have default values and are required to be filled out.
3. Copy the ACME_helper.conf file to /etc directory.
   1. Set the CA_NAME to be the name to initialize PCA with (or the name that PCA was initialized with, if done in another step.)
   2. Optional: If initializing PCA here run the PCA init command. These commands will:
      1. Initialize the PCA environment using the CA_NAME that was described above.
      2. Create a certificate chain
      3. Create a CRL file (nothing will be in it yet)
      4. Export an html directory with those files in them.
      5. Extract that html export into a web root under a /ca directory.

PCA_ROOT=/etc/pca pca <ca_name> init
PCA_ROOT=/etc/pca pca <ca_name> create chain
PCA_ROOT=/etc/pca pca <ca_name> create crl
PCA_Root=/etc/pca pca <ca_name> export html -file /tmp/ca_html.tgz -overwrite
tar -C /var/www/html -zxf /tmp/ca_hml.tgz

4. Verify that everything is working by connecting to https://ISSUER_DOMAIN/acme/directory. This will return a directory listing of ACME functions and confirm the script is installed.
5. Setup the ACME_cleaner.sh script to run daily.
6. Create a script and set it to run daily that will create a new CRL, HTML export and deploy that export.

#!/bin/sh
export PCA_ROOT=/etc/pca
export CANAME=<ca_name>
pca ${CANAME} create crl
pca ${CANAME} export html -file /tmp/ca_html.tgz -overwrite
tar -C /var/www/html -zxf /tmp/ca_html.tgz

On CHROOT systems

This is perhaps the most complicated setup. If the system is running on OpenBSD, check out the packages/OpenBSD directory. There is a port that can be run to create an OpenBSD port to deploy. In addition read packages/OpenBSD/pkg/README. That file has all command necessary to copy the helper programs into the CHROOT environment.

1. Copy the ACME.cgi, ACME_helper.sh and ACME_cleaner.sh files to the CGI-BIN directory.
2. Copy the required helper programs into the CHROOT directory (Assume the directory /var/www/etc)
   1. The following directories are used and will need to be created in the CHROOT environment: /tmp, /var/run
   2. The following programs are required to be accessible by the CHROOT environment, as well as any libraries that the programs call: cat, sleep, rm, cut, mktemp, host, curl, fold, od, openssl, printf, wc, jq
   3. The following device is required to be available in the CHROOT environment: /dev/null
3. Copy the ACME.conf into a config directory located in the CHROOT path. i.e /var/www/etc
   1. Update the ACME.conf file as necessary. Note that the ISSUER_DOMAIN and ISSUER_EMAIL do not have default values and are required to be filled out.
4. Copy the ACME.conf into a config directory located in the CHROOT path. i.e /var/www/etc
   1. Update the ACME.conf file as necessary. Note that the ISSUER_DOMAIN and ISSUER_EMAIL do not have default values and are required to be filled out.
5. Copy the AMCE_helper.conf into a config directory located in the CHROOT path. i.e. /var/www/etc
   1. Set the CA_NAME to be the name to initialize PCA with (or the name that PCA was initialized with, if done in another step.)
   2. Optional: If initialized PCA here run the PCA init command. Make sure to initialize from the CHROOT path.
      1. Initialize the PCA environment using the CA_NAME that was described above.
      2. Create a certificate chain
      3. Create a CRL file (nothing will be in it yet)
      4. Export an html directory with those files in them.
      5. Extract that html export into a web root under a /ca directory. (see example below)
6. Verify that everything is working by connecting to https://ISSUER_DOMAIN/acme/directory. This will return a directory listing of ACME functions and confirm the script is installed.
7. Setup the ACME_cleaner.sh script to run daily.
8. Create a script and set it to run daily that will create a new CRL, HTML export and deploy that export.

PCA_ROOT=/etc/pca chroot /var/www pca <ca_name> init
PCA_ROOT=/etc/pca chroot /var/www pca <ca_name> create chain
PCA_ROOT=/etc/pca chroot /var/www pca <ca_name> create crl
PCA_Root=/etc/pca chroot /var/www pca <ca_name> export html -file /tmp/ca_html.tgz -overwrite
tar -C /var/www/html -zxf /var/www/tmp/ca_hml.tgz

Clients

Before you begin selecting your favorite ACME client to pull a certificate, you will need to download and install PCA root certificate.

1. Browse to the https://ISSUER_DOMAIN/ca/ site. Accept any certificate errors for "unknown authority".
2. Download the Certificate Chain. It should be in a PEM format.
3. Install that chain into the trusted certificate store on the client. (The process will vary depending on client)

Now use your preferred ACME client to request and download a certificate.

Conclusions

This is the first step in gaining independence from public certificate authorities.