Comparison of 10 ACME / Let's Encrypt Clients
Let’s Encrypt is a new certificate authority backed by Mozilla, Akamai, EFF, Facebook and others, which provides free, automated SSL/TLS certificates. The public beta started on December 3, 2015 and a whole lot of certificates have been issued already:
Several clients to automate issuing, renewing and revoking certificates have been released both by the community and the Let’s Encrypt team. This post is an overview and comparison of 10 popular Let’s Encrypt clients:
- letsencrypt-auto, the official Let’s Encrypt client
- acme-tiny, a tiny semi-automatic Python implementation
- gethttpsforfree.com, a static website to assist the manual process
- simp_le, another Python implementation
- letsencrypt-nosudo, the predecessor of acme-tiny and gethttpsforfree
- acmetool, an ACME client in Go
- lego, an ACME client and library written in Go
- letsencrypt.sh, a Bash ACME client implemenation
- acme, ACME implementation in PHP
- lescript, a PHP library
Background
ACME
The Automated Certificate Management Environment (ACME) protocol defines a way of automatically obtaining trusted certificates without human intervention. First, the control of a domain has to be proven, then the agent can request, renew and revoke certificates:
Certificates issued by Let’s Encrypt are valid for 90 days, and are expected to be renewed automatically. More background information can be found on the Let’s Encrypt - How It Works page.
At the time of writing, these rate limits has been in place:
- 10 Registrations per IP per 3 hours
- 5 Certificates per Domain per 7 days (incl. subdomains)
SSL Certificates & Signing
Obtaining a valid SSL certificate generally includes the following steps:
- You create a private and public key pair on the server.
- You create a Certificate Signing Request (CSR) which includes the domain name, organization name, the public key, and other information. The CSR is signed with your private key.
- You send the CSR to the certificate authority (in this case Let’s Encrypt).
- The certificate authority signs the request, thus producing a public certificate.
- You use the public certificate in your webserver.
For more information on configuring a webserver with certificates, check out these links:
- cipherli.st - Example configuration for Apache, nginx and Lighttpd
- Mozilla SSL Config Generator
- Qualsys SSL Labs SSL Server Test
- SSL Decoder
Client Analysis
These tests are going to obtain a certificate for a domain such as www.example.com
and setting up automatic certificate renewal.
Domain ownership verification requires the ACME server being able to access a specific file
on the domain. To accomplish this, we assume a webserver is running and serves
files from /var/www/htdocs/
(the webroot) and it’s subdirectories. For instance, a file at /var/www/htdocs/.well-known/acme-challenge/8303
should be accessible via www.example.com/.well-known/acme-challenge/8303
.
Official Let’s Encrypt Client
- github.com/letsencrypt/letsencrypt
- 4,355 commits, 131 contributors
- Mode: Automatic / Interactive / Manual
- License: Apache 2.0
- Language: Python
- Lines of code: 8,612 (core), ~16,000 (total)
- Dependencies: many
- Documentation
The official Let’s Encrypt client, letsencrypt-auto
, is
a heavyweight, fully automated Python program with various modes of operation and installers (for instance to automagically update Apache and nginx configurations).
The standard client automatically installs various system dependencies via the standard package manager (see the source code and /bootstrap/), and sets up a virtualenv with a number of Python dependencies. The client is also available as a Docker image, which avoids the necessity to install packages system-wide.
In case of an error (eg. the ACME server is not reachable), the official client gracefully terminates with an info message.
The official Let’s Encrypt client also supports config files, which may be easier to automate with a cronjob (see this post for more infos).
- Official client, active community
- Well documented, and well tested
- Can do a lot of things, including server configs (experimental!)
- Accessible for non-technical users
- Complex program, many moving parts, hard to review
- Runs as root and installs dependencies without asking
Standard Installation
$ git clone https://github.com/letsencrypt/letsencrypt
$ cd letsencrypt
$ ./letsencrypt-auto --help
Obtaining a certificate
To obtain a certificate without stopping a running webserver, we are going to use the webroot method, which only requires write access for the webroot to save the authentication file.
$ sudo ./letsencrypt-auto certonly \
--webroot --webroot-path /var/www/htdocs/ \
--email [email protected] \
-d www.example.com
This command creates the private and public keys, generate a certificate signing request, get the challenge from the ACME server, saves it to the webroot, and downloads the signed certificate in /etc/letsencrypt/live/example.com/
. The process
is fully automated and results in the certificate and private key, ready to be used by your webserver.
⇾ show list of generated files
Alternatively the offial Let’s Encrypt client includes a manual plugin, which
can generate a certificate from another computer than the webserver
(akin to gethttpsforfree.com or letsencrypt-nosudo).
You can run this plugin with the command ./letsencrypt-auto certonly --manual
.
Renewal
To renew certificates automatically, simply add the --renew
parameter to the above command:
$ sudo ./letsencrypt-auto certonly \
--renew \
--webroot --webroot-path /var/www/htdocs/ \
--email [email protected] \
-d www.example.com
acme-tiny
- github.com/diafygi/acme-tiny
- 55 commits, 11 contributors
- Mode: Automatic / Semi-Automatic
- License: MIT
- Language: Python
- Lines of code: ~200
- Dependencies: None
- Show HN
Acme-tiny is a tiny Python script which assists with issuing and renewing certificates. You generate
the private key and create a certificate signing request (CSR) manually, and acme-tiny
handles the rest (submitting the CSR
to the ACME server, receiving the authentication files, putting it in the acme-challenge folder and receiving the final certificate). The output of this script is the signed certificate.
- Documentation (in the README)
- Super simple, no dependencies
- Easy to embed in custom Python application
Installation
# Get a copy of acme-tiny
$ cd /opt
$ git clone https://github.com/diafygi/acme-tiny.git
$ cd acme-tiny
$ python acme_tiny.py --help
Obtaining a certificate
# Create a directory for the keys and cert
mkdir -p /etc/letsencrypt/www.example.com
cd /etc/letsencrypt/www.example.com
# Generate a private key
openssl genrsa 4096 > account.key
# Generate a domain private key (if you haven't already)
openssl genrsa 4096 > domain.key
# Create a CSR for www.example.com
openssl req -new -sha256 -key domain.key -subj "/CN=www.example.com" > domain.csr
# Create the challenge folder in the webroot
mkdir -p /var/www/htdocs/.well-known/acme-challenge/
# Get a signed certificate with acme-tiny
python /opt/acme-tiny/acme_tiny.py --account-key ./account.key --csr ./domain.csr --acme-dir /var/www/htdocs/.well-known/acme-challenge/ > ./signed.crt
# Append the Let's Encrypt intermediate cert to your cert
wget -O - https://letsencrypt.org/certs/lets-encrypt-x1-cross-signed.pem > intermediate.pem
cat signed.crt intermediate.pem > chained.pem
At this point chained.pem
contains the signed certificate chain and, along with domain.key
, can be used to run a http server
(more infos).
Renewal simply requires running this script again with the same parameters.
gethttpsforfree.com
- github.com/diafygi/gethttpsforfree
- 70 commits, 10 contributors
- Mode: Semi-Manual
- License: MIT
- Language: HTML & JavaScript
- Lines of code: 1228 JS, 443 HTML
gethttpsforfree.com is a website which helps users to manually generate all the necessary information to create a certificate signing request (CSR), guiding a user through the whole ACME process:
- Manually create a public and private key.
- Manually create a certificate signing request (CSR).
- Manually sign a number of requests with the private key.
- Manually verify ownership by serving the signed requests (either through an existing webserver or a simple Python webserver).
- The website tells the ACME server to check for the verifications, and in case of success provides you with the signed certificate.
The website provides OpenSSL commands at each step, and waits for the output of the commands to be pasted back into the website to verify the success. The website never asks for any kind of private key. It can be saved and used locally without any server side logic.
- Works as advertised
- Static site allows to save and use later
simp_le
- github.com/kuba/simp_le
- 112 commits, 9 contributors
- Mode: Fully or Semi-Automatic
- License: GPLv3
- Language: Python
- Lines of code: 775 Python, 126 Shell Script, 41 YAML
- Dependencies: Some
simp_le
is an ACME client written in Python. It works similar to acme-tiny
, but can
also generate the private key and CSR automatically. Requires a small number of dependencies to be installed.
Installation
$ cd /opt
$ git clone https://github.com/kuba/simp_le
$ cd simp_le
# Setup dependencies and run
$ ./bootstrap.sh
$ ./venv.sh
$ ./venv/bin/simp_le --help
Obtaining a certificate
$ ./venv/bin/simp_le \
-f account_key.json -f key.pem -f cert.pem -f fullchain.pem \
--email [email protected] \
-d www.example.com:/var/www/htdocs/
On success, this command produces 4 files: account_key.json
, cert.pem
, fullchain.pem
and key.pem
,
which can be used from your webserver’s SSL configuration (see here for an example integration in Apache).
Renewal works by using the same command.
Exit codes:
- 0 if certificate data was created or updated;
- 1 if renewal not necessary;
- 2 in case of errors.
letsencrypt-nosudo
- github.com/diafygi/letsencrypt-nosudo
- 45 commits, 5 contributors
- Mode: Manual (assisted)
- License: AGPL
- Language: Python
- Lines of code: 400
- Dependencies: None
This program is a predecessor of acme-tiny and functionally equivalent to gethttpsforfree.com (made by the same author). The script guides you through the whole process and ask you do run all the necessary commands in the terminal.
You generate a private key and certificate signing request (CSR), then run sign_csr.py
to get the signed certificate. The script goes through the ACME protocol with the Let’s Encrypt certificate authority and outputs the signed certificate to stdout.
Installation
$ cd /opt
$ git clone https://github.com/diafygi/letsencrypt-nosudo
$ cd letsencrypt-nosudo
$ python sign_csr.py -h
Obtaining a certificate
$ openssl genrsa 4096 > user.key
$ openssl rsa -in user.key -pubout > user.pub
$ openssl genrsa 4096 > domain.key
$ openssl req -new -sha256 -key domain.key -subj "/CN=example.com" > domain.csr
$ python sign_csr.py --public-key user.pub domain.csr > signed.crt
acmetool
- github.com/hlandau/acme
- 103 commits, 1 contributors
- Mode: Automatic / Interactive
- License: MIT
- Language: Go
- Lines of code: ~6,000
- Dependencies: None (Binary Release)
acmetool
is an ACME client written in Go, supporting automatic domain verification with webroot and standalone methods as well as an interactive wizard. acmetool stores credentials and certificates at /var/lib/acme/live/HOSTNAME/{cert,chain,fullchain,privkey}
by default and includes support to import certificates from the official client.
acmetool furthermore provides a reconcile
option which makes sure all desired hostnames
have valid certificates which don’t expire soon.
Installation
You can either get a binary release, or build from source as described in the Readme:
$ wget https://github.com/hlandau/acme/releases/download/v0.0.22/acmetool-v0.0.22-linux_amd64.tar.gz
$ tar -xvf acmetool-v0.0.22-linux_amd64.tar.gz
$ cd acmetool-v0.0.22-linux_amd64
$ bin/acmetool --help
Obtaining a certificate
You need to set the webroot to /var/run/acme/acme-challenge
as described
in the docs, or use the proxy method. The command acmetool want
tries all available methods.
$ sudo acmetool want www.example.com
lego
- github.com/xenolf/lego
- 162 commits, 4 contributors
- Mode: Automatic
- License: MIT
- Language: Go
- Lines of code: ~2,000
- Dependencies: None (Binary Release)
- Show HN
Lego is an ACME library and standalone application written in Go. It can be downloaded as a binary release or build by yourself.
Running the standalone version requires the permission to bind to port 80 and 443, which conflicts with a webserver which is already running.
Installation
$ wget https://github.com/xenolf/lego/releases/download/v0.1.0/lego_linux_amd64.tar.gz
$ tar -xvf lego_linux_amd64.tar.gz
lego
LICENSES.txt
README.txt
$ ./lego help
Obtaining a certificate
$ sudo ./lego --email="[email protected]" --domains="www.example.com" run
letsencrypt.sh
- github.com/lukas2511/letsencrypt.sh
- 111 commits, 6 contributors
- Mode: Automatic
- License: Unspecified
- Language: Shell Script (Bash)
- Lines of code: ~600 (Bash)
- Dependencies: None / OpenSSL, curl, sed
- Show HN
Installation
$ git clone https://github.com/lukas2511/letsencrypt.sh
$ ./letsencrypt.sh --help
Obtaining a certificate
Create a file called domains.txt
which contains the domains and subdomains you want to
generate certificates for:
example.com www.example.com
example.net www.example.net wiki.example.net
This requests two certificates, for example.com and example.net. The other domains in the corresponding line are their alternative names.
letsencrypt.sh
writes the challenge files by default into the directory "${SCRIPTDIR}/.acme-challenges"
. To adjust this to your webroot, you need to create a config file (config.sh
) with another $WELLKNOWN
path (see config.sh.example):
WELLKNOWN="${SCRIPTDIR}/.well-known/acme-challenge"
Then simply run letsencrypt.sh
(⇾ show output).
acme-client
- github.com/kelunik/acme-client
- 3 commits, 1 contributors
- Mode: Automatic
- License: MIT
- Language: PHP (7)
- Lines of code: ~400
- Dependencies: Few
acme-client
is an ACME client written in PHP, built on top of the acme PHP library by the same author.
It requires PHP 7 and composer to install it’s dependencies.
Installation
$ git clone https://github.com/kelunik/acme-client
$ cd acme-client
$ composer install
Obtaining a certificate
# Register the Let's Encrypt account
$ sudo bin/acme register \
--server acme-v01.api.letsencrypt.org/directory \
--email [email protected]
# Issue the certificate
$ sudo bin/acme issue \
--server acme-v01.api.letsencrypt.org/directory \
--domains example.com,www.example.com \
--path /var/www/example.com/htdocs
lescript
- github.com/analogic/lescript
- 3 commits, 1 contributors
- Mode: Automatic
- License: BSD
- Language: PHP
- Lines of code: ~450
- Dependencies: PHP 5.4.8+ with OpenSSL and curl extension
- Show HN
lescript
is a very simplistic PHP ACME client library, with an example CLI wrapper.
Installation
$ git clone https://github.com/analogic/lescript.git
$ cd lescript
Obtaining a certificate
Use the library as shown in _example.php.
Summary
Client | User Mode | Deps. | Language | LOC | License | Capabilities | Domain Authentication |
---|---|---|---|---|---|---|---|
Official Let's Encrypt Client (Docs) | Automatic / Interactive / Manual | Many | Python | ~8.600 | Apache 2.0 | Issue, Renew, Revoke, Server Config | Webroot, Standalone, Manual |
acme-tiny | Automatic / Semi-Automatic | None | Python | ~200 | MIT | Issue, Renew | Webroot |
gethttpsforfree .com (Source) | Semi-Manual | None | HTML/JS | ~1200 | MIT | Issue, Renew | Webroot |
simp_le | Automatic / Semi-Automatic | Some | Python | ~800 | GPLv3 | Issue, Renew, Revoke | Webroot |
letsencrypt-nosudo | Manual (assisted) | None | Python | ~400 | AGPL | Issue, Renew, Revoke | Standalone |
acmetool | Automatic / Interactive | None | Go | ~6,000 | MIT | Issue, Renew | Webroot, Standalone |
lego | Automatic | None | Go | ~2,000 | MIT | Issue, Renew, Revoke | Standalone |
letsencrypt.sh | Automatic | None | Bash | ~600 | ? | Issue, Renew, Revoke | Webroot |
acme-client | Semi-Automatic | Some (incl. PHP 7) | PHP | ~400 | MIT | Issue, Renew, Revoke | Webroot |
lescript | Semi-Automatic | None | PHP | ~450 | BSD | Issue, Renew | Webroot |
If you have suggestions or feedback, please let me know via @metachris.