Certificaat
Definition
Certificaat is a general-purpose ACME client, fully compatible with the Let’s Encrypt certificate authority.
Motivation
If certbot does everything for everybody, Certificaat is narrower in scope, focusing on usability and automated renewals.
Certificaat is optimized for a specific workflow: retrieve a certificate for your domain, and subsequently set up a cron job and forget about it.
Installation
Certificaat is available on Clojars.
In your deps.edn
, add an alias for certificaat
.
:aliases {:certificaat {:extra-deps {org.danielsz/certificaat {:mvn/version "2.x.x"}}
:extra-paths ["resources"]
:main-opts ["-m" "certificaat.core"]}}
You can now invoke it like this:
$ clj -A:certificaat
It is recommended to create an executable file in your path for ease of use.
$ echo 'clj -A:certificaat "$@"' > /usr/local/bin/certificaat
$ chmod u+x /usr/local/bin/certificaat
Usage
Overview
To get a certificate for a domain, follow these steps:
a. Run certificaat -m change.me run
certificaat
will display instructions pertaining to the challenge. This is the time to satisfy the requirements (for example, configuring DNS records or preparing your web server).
b. Review your settings in config.edn
.
Make sure you can accept the challenge. With the http01
challenge, you have the option to use the built-in server to respond to the requests, or you can instruct certificaat
to put the authorization tokens in the right folder of your web server.
c. Run certificaat -m change.me run
When you are ready, simply repeat the operation and the challenges will be triggered and, if successfully completed, a certificate downloaded and saved to disk.
From then on, the certificate can be renewed in one pass with certificaat -m change.me run
.
Command line options
certificaat -m change.me run
The -m
option indicates the domain you want to authorize. It will feature in the Subject name of the final X.509 certificate.
certificaat -m change.me -n www.change.me run
The -n
option is for additional domain name you want to
authorize. It will feature in the Subject Alternative Name a(SAN) of
the certificate. Repeat this option for all required names. Caution:
there is a hard limit imposed by the CA.
certificaat -m example.com info
Certificaat will display a summary of the certificate.
Specifying the -v
option will enable verbose logging, useful in debugging operations.
Configuration
Certificaat is driven by its configuration files which are generated with defaults that you can subsequently edit and customize.
Certificaat follows the XDG Base Directory Specification. The
configuration folder is determined by querying the value of
XDG_CONFIG_HOME
in the environment, and if not set, will default to
$HOME/.config/certificaat
.
Configuration files are in edn format and can be edited in any text editor.
The global configuration is stored in the root directory,
$HOME/.config/certificaat/config.edn
and it looks like
this:
{:key-size 2048,
:key-type :rsa,
:keypair-filename "account.key"}
The local configuration file is stored in the per-domain directory,
$HOME/.config/certificaat/change.me/config.edn
, and looks like
this:
{:acme-uri "acme://letsencrypt.org/staging",
:challenges "http-01",
:contact "mailto:admin@change.me",
:domain "change.me",
:organisation "ChangeMe corporation",
:san #{"www.change.me"}
:plugins {:diffie-hellman {:enabled false,
:filename "dhparam.pem",
:group14 true,
:modulus 2048},
:copy-to-path {:enabled true
:path "/tmp"}
:httpd {:enabled true
:port 3010}
:email {:enabled false,
:sendmail false,
:smtp {:host "smtp.changeme.org",
:pass "changeme",
:port 587,
:user "changeme"}},
:webroot {:enabled false, :path "/var/www/"}}}
- the email address used by the CA to send expiry reminders.
- the challenge you want to complete.
- the URI to the ACME CA. By default, Certificaat will talk to Let’s Encrypt’s staging server. The resulting certificates will be fake. This is so you can practice until you are ready to issue a production certificate.
Staging URI | Production URI |
acme://letsencrypt.org/staging | acme://letsencrypt.org |
Plugins
Plugins are provided to perform additional functionality at key moments, namely before the challenges get triggered, or after a certificate has been acquired or renewed. The plugins need to be configured and enabled.
The plugin configuration resides in the per-domain directory, $HOME/.config/certificaat/change.me/config.edn
Copy to path
This will copy the certificate to a folder of your liking. If disabled, the certificate will be found in $HOME/.config/certificaat/change.me/
.
Webroot
This plugin copies the authorization tokens to your web server www directory.
An email will be sent to the contact registered with the certificate after creating or renewing a certificate.
Diffie-Helman parameters
This will save a Diffie-Helman parameters file along with the certificate, for further tuning the SSL setup.
httpd
When enabled, the built-in server will respond to the challenges. Letsencrypt directs its request to port 80 exclusively. The built-in server runs on then non-privileged ports so you will need to tunnel the requests from port 80 to the built-in server’s port. This is easily achieved with:
$ sudo socat tcp-listen:80,reuseaddr,fork tcp:localhost:3010
httpd
and webroot
are the plugins that enable you to acquire the certificate in a single pass. Thus amenable to integrate an automated workflow like a cron job.
5 8 1 * * certificaat -m change.me run && /usr/sbin/service nginx reload
Challenges
Certificaat will honor all challenges defined in the ACME specification.
Challenge | Option identifier | Let’s Encrypt | Certificaat |
HTTP | http-01 | ✓ | ✓ |
DNS | dns-01 | ✓ | ✓ |
ALPN | tls-alpn-01 | ✓ | ✓ |
Wildcard domains
Wildcard domains are supported with the “dns01” challenge only. (as per the protocol)
Implementation
Certificaat is based on the ACME protocol, API version 2.
Contributions
If you plan to submit enhancements beyond bug fixes, please coordinate with me beforehand in order to save everybody’s time and effort.
Credits
I wish to thank Richard Körber who wrote the Java client for the ACME protocol, acme4j, which serves as a foundation for Certificaat. Not only is it well written, it is also exquisitely documented.
License
Licensing terms will be revealed shortly. In the meantime, do what you want with it.
Type certificaat -h
to familiarize yourself with the input it expects.