Let's Encrypt + Cloudflare DNS = acme-dns-01-cloudflare

| Built by Root for Hub

An ACME dns-01 Cloudflare plugin for Let's Encrypt integrations.

| ACME HTTP-01 | ACME DNS-01 | Greenlock Express | Greenlock.js | ACME.js

This was specificially designed for ACME.js and Greenlock.js, but will be generically useful to any JavaScript DNS plugin for Let's Encrypt.

npm install --save @therealgilles/acme-dns-01-cloudflare

How Let's Encrypt works with DNS

In order to validate wildcard, localhost, and private domains through Let's Encrypt, you must use set some special TXT records in your domain's DNS.

This is called the ACME DNS-01 Challenge

For example:

dig TXT example.com

;; QUESTION SECTION:
;_acme-challenge.example.com.		IN	TXT

;; ANSWER SECTION:
_acme-challenge.example.com.	300	IN	TXT	"xxxxxxx"
_acme-challenge.example.com.	300	IN	TXT	"xxxxxxx"

ACME DNS-01 Challenge Process

The ACME DNS-01 Challenge process works like this:

1. The ACME client order's an SSL Certificate from Let's Encrypt
2. Let's Encrypt asks for validation of the domains on the certificate
3. The ACME client asks to use DNS record verification
4. Let's Encrypt gives a DNS authorization token
5. The ACME client manipulates the token and sets TXT record with the result
6. Let's Encrypt checks the TXT record from DNS clients in diverse locations
7. The ACME client gets a certificate if the validate passes

Using a Let's Encrypt DNS plugin

Each plugin will define some options, such as an api key, or username and password that are specific to that plugin.

Other than that, they're all used the same.

ACME.js + Let's Encrypt DNS-01

This is how an ACME challenge module is with ACME.js:

acme.certificates.create({
	accountKey,
	csr,
	domains,
	challenges: {
		'dns-01': require('acme-dns-01-cloudflare').create({
			email: 'CLOUDFLARE_EMAIL',
			key: 'CLOUDFLARE_API_KEY',
			// or
			token: 'CLOUDFLARE_API_TOKEN',
		})
	}
});

Greenlock + Let's Encrypt DNS-01

This is how modules are used with Greenlock / Greenlock Express

Global default:

greenlock.manager.defaults({
	challenges: {
		'dns-01': {
			module: 'acme-dns-01-cloudflare',
			email: 'CLOUDFLARE_EMAIL',
			key: 'CLOUDFLARE_API_KEY',
			// or
			token: 'CLOUDFLARE_API_TOKEN',
		}
	}
});

Per-Site config:

greenlock.add({
	subject: 'example.com',
	altnames: ['example.com', '*.example.com', 'foo.bar.example.com'],
	challenges: {
		'dns-01': {
			module: 'acme-dns-01-cloudflare',
			email: 'CLOUDFLARE_EMAIL',
			key: 'CLOUDFLARE_API_KEY',
			// or
			token: 'CLOUDFLARE_API_TOKEN',
		}
	}
});