acme-dns-01-test | a Root project

An ACME dns-01 test harness for Let's Encrypt integrations.

This was specificially designed for ACME.js and Greenlock.js, but will be generically useful to any ACME module.

Passing the tests is very easy. There are just five functions to implement:

• init(deps) - (optional) this gives you the request object you should use for HTTP APIs
• zones(opts) - list domain zones (i.e. example.co.uk, example.com)
• set(opts) - set a TXT record in a zone (i.e. _acme-challenge.foo in example.co.jp)
• get(opts) - confirm that the record was set
• remove(opts) - clean up after the ACME challenge completes

The tests account for single-domain certificates (example.com) as well as multiple domain certs (SAN / AltName), wildcards (*.example.com), and valid private / localhost certificates. No worries on your end, just pass the tests. 👌

Node v6 Support: Please build community plugins using node v6 / vanillajs to ensure that all acme.js and greenlock.js users are fully supported.

Install

npm install --save-dev acme-dns-01-test@3.x

Usage

var tester = require('acme-dns-01-test');

//var challenger = require('acme-dns-01-cli').create({});
var challenger = require('./YOUR-CHALLENGE-STRATEGY').create({
	YOUR_TOKEN_OPTION: 'SOME_API_KEY'
});

// The dry-run tests can pass on, literally, 'example.com'
// but the integration tests require that you have control over the domain
var zone = 'example.com';

tester.testZone('dns-01', zone, challenger).then(function() {
	console.info('PASS');
});

Note: If the service you are testing only handles individual records (not multiple records in a zone), you can use testRecord instead:

var record = 'foo.example.com';

tester.testRecord('dns-01', record, challenger).then(function() {
	console.info('PASS');
});

Reference Implementations

• Compatibility
  • Let's Encrypt v2.1 / ACME draft 18
  • Node v6+
  • Chrome, Firefox, Safari, Edge, etc
• Quality
  • Written in VanillaJS
  • No compliers or build scripts
  • Simple, minimal code, in a single file
  • Zero dependencies

These libraries are useful as a model for any plugins that you create.

• dns-01
  • cli
  • digitalocean
  • vultr
• http-01
  • cli
  • fs

You can find other implementations by searching npm for acme-http-01- and acme-dns-01-.

If you are building a plugin, please let us know. We may like to co-author and help maintain and promote your module.

Note: In some cases (such as non-HTTP, or very complex APIs) you will not be able to maintain browser compatibility. Other than than, if you keep your code simple, it will also work in browser implementations of ACME.js.

Example

See example.js (it works).

Starter Template

Here's what you could start with.

var tester = require('acme-dns-01-test');

// The dry-run tests can pass on, literally, 'example.com'
// but the integration tests require that you have control over the domain
var zone = 'example.com';
var request;

tester
	.testZone('dns-01', zone, {
		// Gives you the promisified `request` object for HTTP APIs
		init: function(deps) {
			request = deps.request;
			return null;
		},

		// Should return an array of zone domain name strings
		// (APIs that don't implement zones, such as DuckDNS, should return an empty array)
		zones: function(opts) {
			console.log('dnsHosts:', opts.dnsHosts);
			throw new Error('_zone not implemented');
		},

		// Should set a TXT record for dnsHost with dnsAuthorization and ttl || 300
		set: function(opts) {
			console.log('set opts:', opts);
			throw new Error('set not implemented');
		},

		// Should remove the *one* TXT record for dnsHost with dnsAuthorization
		// Should NOT remove otherrecords for dnsHost (wildcard shares dnsHost with
		// non-wildcard)
		remove: function(opts) {
			console.log('remove opts:', opts);
			throw new Error('remove not implemented');
		},

		// Should get the record via the DNS server's API
		// (Note: gets different options than set or remove)
		get: function(opts) {
			console.log('get opts:', opts);
			throw new Error('get not implemented');
		}
	})
	.then(function() {
		console.info('PASS');
	});

dns-01 vs http-01

For type dns-01:

// `dnsHost` is the domain/subdomain/host
// `dnsAuthorization` is the value of the TXT record
// `dnsPrefix` is the record-only part, if `zones()` is implemented
// `dnsZone` is the zone-only part, if `zones()` is implemented

For type http-01:

// `altname` is the name of the domain
// `token` is the name of the file ( .well-known/acme-challenge/`token` )
// `keyAuthorization` is the contents of the file

See acme-http-01-test.js.

Detailed Overview

Here's a quick pseudo stub-out of what a test-passing plugin object might look like:

var request;

tester
	.testZone('dns-01', 'example.com', {
		init: function(deps) {
			// { request: { get, post, put, delete }
			// }

			request = deps.request;
			return null;
		},

		zones: function(opts) {
			// { dnsHosts: [
			//     '_acme-challenge.foo.example.com',
			//     '_acme-challenge.bar.example.com'
			//  ] }

			return YourApi(
				'GET',
				// Most Domain Zone apis don't have a search or filter option,
				// but `opts` includes list of dnsHosts is provided just in case.
				'https://exampledns.com/api/dns/zones?search=' + opts.dnsHosts.join(',')
			).then(function(result) {
				return result.zones.map(function(zone) {
					return zone.name;
				});
			});
		},

		set: function(opts) {
			var ch = opts.challenge;
			// { type: 'dns-01'
			// , identifier: { type: 'dns', value: 'foo.example.com' }
			// , wildcard: false
			// , dnsHost: '_acme-challenge.foo.example.com'
			// , dnsPrefix: '_acme-challenge.foo'
			// , dnsZone: 'example.com'
			// , dnsAuthorization: 'zzzz' }

			return YourApi(
				'POST',
				'https://exampledns.com/api/dns/txt/' + ch.dnsZone + '/' + ch.dnsPrefix,
				{ value: ch.dnsAuthorization }
			);
		},

		get: function(query) {
			var ch = query.challenge;
			// { type: 'dns-01'
			// , identifier: { type: 'dns', value: 'foo.example.com' }
			// , altname: '...'
			// , dnsHost: '...'
			// , wildcard: false }
			// Note: query.identifier.value is different for http-01 than for dns-01
			//       because of how a DNS query is different from an HTTP request

			return YourApi(
				'GET',
				'https://exampledns.com/api/dns/txt/' + ch.dnsZone + '/' + ch.dnsPrefix
			).then(function(secret) {
				return { dnsAuthorization: secret };
			});
		},

		remove: function(opts) {
			var ch = opts.challenge;
			// same options as in `set()` (which are not the same as `get()`

			return YourApi(
				'DELETE',
				'https://exampledns.com/api/dns/txt/' + ch.dnsZone + '/' + ch.dnsPrefix
			);
		}
	})
	.then(function() {
		console.info('PASS');
	});

Where YourApi might look something like this:

var YourApi = function createApi(config) {
	return function(method, url, body) {
		return request({
			method: method,
			url: url,
			json: body || true,
			headers: {
				Authorization: 'Bearer ' + config.apiToken
			}
		}).then(function(resp) {
			return resp.body;
		});
	};
};

Note: request is actually @root/request, but the API is the same as the standard request.

Avoid using 3rd party API libraries where you can - they tend to bloat your dependencies and add security risk. Instead, just use the API documentation and cURL examples.

Two notes:

Note 1:

The API.get(), API.set(), and API.remove() is where you do your magic up to upload a file to the correct location on an http serever, set DNS records, or add the appropriate data to the database that handles such things.

Note 2:

• When altname is foo.example.com the dnsHost will be _acme-challenge.foo.example.com
• When altname is *.foo.example.com the dnsHost will still be _acme-challenge.foo.example.com!!
• When altname is bar.foo.example.com the dnsHost will be _acme-challenge.bar.foo.example.com