Let's Encrypt Logo

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:

Let's Encrypt Daily Activity

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:

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:

ACME Challenge

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:

  1. You create a private and public key pair on the server.
  2. 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.
  3. You send the CSR to the certificate authority (in this case Let’s Encrypt).
  4. The certificate authority signs the request, thus producing a public certificate.
  5. You use the public certificate in your webserver.

For more information on configuring a webserver with certificates, check out these links:

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

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

⇾ show output

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 admin@example.com \
    -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 admin@example.com \
    -d www.example.com

acme-tiny

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

⇾ show output

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

⇾ show output

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

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:

  1. Manually create a public and private key.
  2. Manually create a certificate signing request (CSR).
  3. Manually sign a number of requests with the private key.
  4. Manually verify ownership by serving the signed requests (either through an existing webserver or a simple Python webserver).
  5. 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
    • Github Stars Github Forks
    • 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

⇾ show output

Obtaining a certificate

$ ./venv/bin/simp_le \
    -f account_key.json -f key.pem -f cert.pem -f fullchain.pem \
    --email admin@example.com \
    -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

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

⇾ show output

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

⇾ show output

acmetool

  • github.com/hlandau/acme
    • Github Stars Github Forks
    • 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

⇾ show output

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
    • Github Stars Github Forks
    • 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

⇾ show output

Obtaining a certificate

$ sudo ./lego --email="admin@example.com" --domains="www.example.com" run

⇾ show output

letsencrypt.sh

Installation

$ git clone https://github.com/lukas2511/letsencrypt.sh
$ ./letsencrypt.sh --help

⇾ show output

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

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 me@example.com

# 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
    • Github Stars Github Forks
    • 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.