Compare commits
	
		
			No commits in common. "master" and "v3.0.4" have entirely different histories.
		
	
	
		
	
		
							
								
								
									
										399
									
								
								README.md
									
									
									
									
									
								
							
							
						
						
									
										399
									
								
								README.md
									
									
									
									
									
								
							@ -1,264 +1,52 @@
 | 
			
		||||
# Let's Encrypt + DNS = [acme-dns-01-test](https://git.rootprojects.org/root/acme-dns-01-test.js.git)
 | 
			
		||||
# [acme-challenge-test](https://git.rootprojects.org/root/acme-challenge-test.js.git) | a [Root](https://rootprojects.org) project
 | 
			
		||||
 | 
			
		||||
| Built by [Root](https://rootprojects.org) for [Hub](https://rootprojects.org/hub/)
 | 
			
		||||
The test harness you should use when writing an ACME challenge strategy
 | 
			
		||||
for [ACME.js](https://git.coolaj86.com/coolaj86/acme-v2.js) and also [Greenlock](https://git.coolaj86.com/coolaj86/greenlock-express.js) v2.7+ (and v3).
 | 
			
		||||
 | 
			
		||||
An ACME dns-01 test harness for Let's Encrypt integrations.
 | 
			
		||||
All implementations MUST pass these tests, which is a very easy thing to do (just `set()`, `get()`, and `remove()`).
 | 
			
		||||
 | 
			
		||||
| [ACME HTTP-01](https://git.rootprojects.org/root/acme-http-01-test.js)
 | 
			
		||||
| [ACME DNS-01](https://git.rootprojects.org/root/acme-dns-01-test.js)
 | 
			
		||||
| [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js)
 | 
			
		||||
| [Greenlock.js](https://git.rootprojects.org/root/greenlock.js)
 | 
			
		||||
| [ACME.js](https://git.rootprojects.org/root/acme.js)
 | 
			
		||||
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. 👌
 | 
			
		||||
 | 
			
		||||
This was specificially designed for [ACME.js](https://git.coolaj86.com/coolaj86/acme-v2.js)
 | 
			
		||||
and [Greenlock.js](https://git.coolaj86.com/coolaj86/greenlock-express.js),
 | 
			
		||||
but will be generically useful to any JavaScript DNS plugin for Let's Encrypt.
 | 
			
		||||
**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
 | 
			
		||||
 | 
			
		||||
```bash
 | 
			
		||||
npm install --save-dev acme-dns-01-test@3.x
 | 
			
		||||
npm install --save-dev acme-challenge-test@3.x
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
<!--
 | 
			
		||||
 | 
			
		||||
```bash
 | 
			
		||||
npx acme-dns-01-test --module /path/to/module.js --foo-user --bar--token
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
-->
 | 
			
		||||
 | 
			
		||||
# 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:
 | 
			
		||||
 | 
			
		||||
```txt
 | 
			
		||||
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:
 | 
			
		||||
## Usage
 | 
			
		||||
 | 
			
		||||
```js
 | 
			
		||||
acme.certificates.create({
 | 
			
		||||
	accountKey,
 | 
			
		||||
	csr,
 | 
			
		||||
	domains,
 | 
			
		||||
	challenges: {
 | 
			
		||||
		'dns-01': require('acme-dns-01-MODULE_NAME').create({
 | 
			
		||||
			fooUser: 'A_PLUGIN_SPECIFIC_OPTION',
 | 
			
		||||
			barToken: 'A_PLUGIN_SPECIFIC_OPTION'
 | 
			
		||||
		})
 | 
			
		||||
	}
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
var tester = require("acme-challenge-test");
 | 
			
		||||
 | 
			
		||||
## Greenlock + Let's Encrypt DNS-01
 | 
			
		||||
 | 
			
		||||
This is how modules are used with Greenlock / Greenlock Express
 | 
			
		||||
 | 
			
		||||
**Global** default:
 | 
			
		||||
 | 
			
		||||
```js
 | 
			
		||||
greenlock.manager.defaults({
 | 
			
		||||
	challenges: {
 | 
			
		||||
		'dns-01': {
 | 
			
		||||
			module: 'acme-dns-01-_MODULE_NAME',
 | 
			
		||||
			fooUser: 'A_PLUGIN_SPECIFIC_OPTION',
 | 
			
		||||
			barToken: 'A_PLUGIN_SPECIFIC_OPTION'
 | 
			
		||||
		}
 | 
			
		||||
	}
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
**Per-Site** config:
 | 
			
		||||
 | 
			
		||||
```js
 | 
			
		||||
greenlock.add({
 | 
			
		||||
	subject: 'example.com',
 | 
			
		||||
	altnames: ['example.com', '*.example.com', 'foo.bar.example.com'],
 | 
			
		||||
	challenges: {
 | 
			
		||||
		'dns-01': {
 | 
			
		||||
			module: 'acme-dns-01-YOUR_MODULE_NAME',
 | 
			
		||||
			fooUser: 'A_PLUGIN_SPECIFIC_OPTION',
 | 
			
		||||
			barToken: 'A_PLUGIN_SPECIFIC_OPTION'
 | 
			
		||||
		}
 | 
			
		||||
	}
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
# The Easy Way to Build a Plugin
 | 
			
		||||
 | 
			
		||||
This repo includes **unit test suite** which makes it _very_ easy to create a plugin.
 | 
			
		||||
 | 
			
		||||
You can start with a **template file** that will fail all of the tests, and just
 | 
			
		||||
build until you pass all of the tests.
 | 
			
		||||
 | 
			
		||||
After that, you can **test the Greenlock CLI** to see if
 | 
			
		||||
you actually get a valid SSL certificate.
 | 
			
		||||
 | 
			
		||||
## Overview
 | 
			
		||||
 | 
			
		||||
There are only a few methods to implement - just basic CRUD operations.
 | 
			
		||||
 | 
			
		||||
For most serivices these are very simple to implement
 | 
			
		||||
(see the **reference implementations** down below).
 | 
			
		||||
 | 
			
		||||
Some enterprise-y services are more difficult as they may have special
 | 
			
		||||
rules about zones (Google Cloud) or intricate authentication schemes (AWS).
 | 
			
		||||
 | 
			
		||||
```
 | 
			
		||||
init({ request })
 | 
			
		||||
 | 
			
		||||
zones({ dnsHosts })
 | 
			
		||||
 | 
			
		||||
set({ challenge: { dnsZone, dnsPrefix, dnsHost, keyAuthorizationDigest } })
 | 
			
		||||
 | 
			
		||||
get({ challenge: { dnsZone, dnsPrefix, dnsHost, keyAuthorizationDigest } })
 | 
			
		||||
 | 
			
		||||
remove({ challenge: { dnsZone, dnsPrefix, dnsHost, keyAuthorizationDigest } })
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
## Plugin Outline
 | 
			
		||||
 | 
			
		||||
This is an even better starter template below,
 | 
			
		||||
but this outline shows the bare bones of a plugin.
 | 
			
		||||
 | 
			
		||||
```
 | 
			
		||||
'use strict';
 | 
			
		||||
 | 
			
		||||
var MyModule = module.exports;
 | 
			
		||||
 | 
			
		||||
MyModule.create = function (options) {
 | 
			
		||||
 | 
			
		||||
    var m = {};
 | 
			
		||||
 | 
			
		||||
    m.init = async function ({ request }) {
 | 
			
		||||
        // (optional) initialize your module
 | 
			
		||||
    }
 | 
			
		||||
 | 
			
		||||
    m.zones = async function ({ dnsHosts }) {
 | 
			
		||||
        // return a list of "Zones" or "Apex Domains" (i.e. example.com, NOT foo.example.com)
 | 
			
		||||
    }
 | 
			
		||||
 | 
			
		||||
    m.set = async function ({ challenge: { dnsZone, dnsPrefix, dnsHost, keyAuthorizationDigest } }) {
 | 
			
		||||
        // set a TXT record for dnsHost with keyAuthorizationDigest as the value
 | 
			
		||||
    }
 | 
			
		||||
 | 
			
		||||
    m.get = async function ({ challenge: { dnsZone, dnsPrefix, dnsHost, keyAuthorizationDigest } }) {
 | 
			
		||||
        // check that the EXACT a TXT record that was set, exists, and return it
 | 
			
		||||
    }
 | 
			
		||||
 | 
			
		||||
    m.remove = async function ({ challenge: { dnsZone, dnsPrefix, dnsHost, keyAuthorizationDigest } }) {
 | 
			
		||||
        // remove the exact TXT record that was set
 | 
			
		||||
    }
 | 
			
		||||
 | 
			
		||||
    return m;
 | 
			
		||||
}
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
## Using the Test Suite
 | 
			
		||||
 | 
			
		||||
Test setup:
 | 
			
		||||
 | 
			
		||||
```js
 | 
			
		||||
var tester = require('acme-dns-01-test');
 | 
			
		||||
var YOUR_PLUGIN = require('./YOUR-CHALLENGE-STRATEGY');
 | 
			
		||||
 | 
			
		||||
var challenger = YOUR_PLUGIN.create({
 | 
			
		||||
//var challenger = require('acme-http-01-cli').create({});
 | 
			
		||||
//var challenger = require('acme-dns-01-cli').create({});
 | 
			
		||||
var challenger = require("./YOUR-CHALLENGE-STRATEGY").create({
 | 
			
		||||
  YOUR_TOKEN_OPTION: 'SOME_API_KEY'
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
Run the tests:
 | 
			
		||||
// The dry-run tests can pass on, literally, 'example.com'
 | 
			
		||||
// but the integration tests require that you have control over the domain
 | 
			
		||||
var domain = "example.com";
 | 
			
		||||
 | 
			
		||||
```
 | 
			
		||||
var zone = 'example.com';
 | 
			
		||||
 | 
			
		||||
tester.testZone('dns-01', zone, challenger).then(function() {
 | 
			
		||||
	console.info('PASS');
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
**Note**: Special DNS services, like **DuckDNS**, only give you a **single sub-domain**,
 | 
			
		||||
not a full "zone". You can test them too:
 | 
			
		||||
 | 
			
		||||
Some DNS services, such as **DuckDNS**, only give you a **single sub-domain**,
 | 
			
		||||
not not _multiple_ records in a zone. Testing them is slightly different:
 | 
			
		||||
 | 
			
		||||
```js
 | 
			
		||||
var record = 'foo.example.com';
 | 
			
		||||
 | 
			
		||||
tester.testRecord('dns-01', record, challenger).then(function() {
 | 
			
		||||
	console.info('PASS');
 | 
			
		||||
tester.test("http-01", domain, challenger).then(function() {
 | 
			
		||||
	console.info("PASS");
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
## Reference Implementations
 | 
			
		||||
 | 
			
		||||
- Compatibility
 | 
			
		||||
  - [x] Let's Encrypt v2.1 / ACME draft 18
 | 
			
		||||
  - [x] Node v6+
 | 
			
		||||
  - [x] Chrome, Firefox, Safari, Edge, etc
 | 
			
		||||
- Quality
 | 
			
		||||
  - [x] Written in VanillaJS
 | 
			
		||||
  - [x] No compliers or build scripts
 | 
			
		||||
  - [x] Simple, minimal code, in a single file
 | 
			
		||||
  - [x] **Zero dependencies**
 | 
			
		||||
These are plugins that use the v2.7+ (v3) API, and pass this test harness,
 | 
			
		||||
which you should use as a model for any plugins that you create.
 | 
			
		||||
 | 
			
		||||
These libraries are useful as a model for any plugins that you create.
 | 
			
		||||
- [`acme-http-01-cli`](https://git.rootprojects.org/root/acme-http-01-cli.js)
 | 
			
		||||
- [`acme-dns-01-cli`](https://git.rootprojects.org/root/acme-dns-01-cli.js)
 | 
			
		||||
 | 
			
		||||
- dns-01
 | 
			
		||||
  - [`cli`](https://git.rootprojects.org/root/acme-dns-01-cli.js)
 | 
			
		||||
  - [`digitalocean`](https://git.rootprojects.org/root/acme-dns-01-digitalocean.js)
 | 
			
		||||
  - [`vultr`](https://git.rootprojects.org/root/acme-dns-01-vultr.js)
 | 
			
		||||
  - [`gandi`](https://git.rootprojects.org/root/acme-dns-01-gandi.js)
 | 
			
		||||
  - [`duckdns`](https://git.rootprojects.org/root/acme-dns-01-duckdns.js)
 | 
			
		||||
- http-01
 | 
			
		||||
  - [`cli`](https://git.rootprojects.org/root/acme-http-01-cli.js)
 | 
			
		||||
  - [`fs`](https://git.rootprojects.org/root/acme-http-01-fs.js)
 | 
			
		||||
You can find other implementations by searching npm for [acme-http-01-](https://www.npmjs.com/search?q=acme-http-01-) and [acme-dns-01-](https://www.npmjs.com/search?q=acme-dns-01-).
 | 
			
		||||
 | 
			
		||||
You can find other implementations by searching npm for [acme-http-01-](https://www.npmjs.com/search?q=acme-http-01-)
 | 
			
		||||
and [acme-dns-01-](https://www.npmjs.com/search?q=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.
 | 
			
		||||
 | 
			
		||||
<small>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.</small>
 | 
			
		||||
 | 
			
		||||
# Example
 | 
			
		||||
## Example
 | 
			
		||||
 | 
			
		||||
See `example.js` (it works).
 | 
			
		||||
 | 
			
		||||
@ -267,28 +55,14 @@ See `example.js` (it works).
 | 
			
		||||
Here's what you could start with.
 | 
			
		||||
 | 
			
		||||
```js
 | 
			
		||||
var tester = require('acme-dns-01-test');
 | 
			
		||||
var tester = require('acme-challenge-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 deps = {};
 | 
			
		||||
var domain = 'example.com';
 | 
			
		||||
 | 
			
		||||
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');
 | 
			
		||||
		},
 | 
			
		||||
 | 
			
		||||
  .test('http-01', domain, {
 | 
			
		||||
    // Should set a TXT record for dnsHost with dnsAuthorization and ttl || 300
 | 
			
		||||
    set: function(opts) {
 | 
			
		||||
      console.log('set opts:', opts);
 | 
			
		||||
@ -304,7 +78,6 @@ tester
 | 
			
		||||
    },
 | 
			
		||||
 | 
			
		||||
    // 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');
 | 
			
		||||
@ -315,71 +88,62 @@ tester
 | 
			
		||||
  });
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
## Full Detailed Example
 | 
			
		||||
## dns-01 vs http-01
 | 
			
		||||
 | 
			
		||||
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
 | 
			
		||||
 | 
			
		||||
For `type` dns-01:
 | 
			
		||||
 | 
			
		||||
    // `dnsHost` is the domain/subdomain/host
 | 
			
		||||
    // `dnsAuthorization` is the value of the TXT record
 | 
			
		||||
 | 
			
		||||
## Detailed Overview
 | 
			
		||||
 | 
			
		||||
Here's a quick pseudo stub-out of what a test-passing plugin object might look like:
 | 
			
		||||
 | 
			
		||||
```js
 | 
			
		||||
var deps = {};
 | 
			
		||||
 | 
			
		||||
tester
 | 
			
		||||
	.testZone('dns-01', 'example.com', {
 | 
			
		||||
		init: function({ request }) {
 | 
			
		||||
			// { request: { get, post, put, delete } }
 | 
			
		||||
 | 
			
		||||
			deps.request = request;
 | 
			
		||||
			return null;
 | 
			
		||||
		},
 | 
			
		||||
 | 
			
		||||
		zones: function({ dnsHosts }) {
 | 
			
		||||
			// { 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;
 | 
			
		||||
				});
 | 
			
		||||
			});
 | 
			
		||||
		},
 | 
			
		||||
  .test('dns-01', 'example.com', {
 | 
			
		||||
  
 | 
			
		||||
    set: function(opts) {
 | 
			
		||||
      var ch = opts.challenge;
 | 
			
		||||
			// { type: 'dns-01'
 | 
			
		||||
			// , identifier: { type: 'dns', value: 'foo.example.com' }
 | 
			
		||||
      // { type: 'dns-01' // or 'http-01'
 | 
			
		||||
      // , identifier: { type: 'dns', value: 'example.com' }
 | 
			
		||||
      // , wildcard: false
 | 
			
		||||
			// , dnsHost: '_acme-challenge.foo.example.com'
 | 
			
		||||
			// , dnsPrefix: '_acme-challenge.foo'
 | 
			
		||||
			// , dnsZone: 'example.com'
 | 
			
		||||
      // , token: 'xxxx'
 | 
			
		||||
      // , keyAuthorization: 'xxxx.yyyy'
 | 
			
		||||
      // , dnsHost: '_acme-challenge.example.com'
 | 
			
		||||
      // , dnsAuthorization: 'zzzz' }
 | 
			
		||||
 | 
			
		||||
			return YourApi(
 | 
			
		||||
				'POST',
 | 
			
		||||
				'https://exampledns.com/api/dns/txt/' + ch.dnsZone + '/' + ch.dnsPrefix,
 | 
			
		||||
				{ value: ch.dnsAuthorization }
 | 
			
		||||
			);
 | 
			
		||||
      return YourApi('POST', 'https://example.com/api/dns/txt', {
 | 
			
		||||
        host: ch.dnsHost,
 | 
			
		||||
        record: ch.dnsAuthorization
 | 
			
		||||
      });
 | 
			
		||||
    },
 | 
			
		||||
    
 | 
			
		||||
    get: function(query) {
 | 
			
		||||
      var ch = query.challenge;
 | 
			
		||||
			// { type: 'dns-01'
 | 
			
		||||
			// , identifier: { type: 'dns', value: 'foo.example.com' }
 | 
			
		||||
      // { type: 'dns-01' // or 'http-01', 'tls-alpn-01', etc
 | 
			
		||||
      // , identifier: { type: 'dns', value: 'example.com' }
 | 
			
		||||
      //   // http-01 only
 | 
			
		||||
      // , token: 'xxxx'
 | 
			
		||||
      // , url: '...' // for testing and debugging
 | 
			
		||||
      //   // dns-01 only, for testing / dubgging
 | 
			
		||||
      // , 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 YourApi('GET', 'https://example.com/api/dns/txt', {
 | 
			
		||||
        host: ch.dnsHost
 | 
			
		||||
      }).then(function(secret) {
 | 
			
		||||
        // http-01
 | 
			
		||||
        //return { keyAuthorization: secret };
 | 
			
		||||
        // dns-01
 | 
			
		||||
        return { dnsAuthorization: secret };
 | 
			
		||||
      });
 | 
			
		||||
    },
 | 
			
		||||
@ -388,10 +152,7 @@ tester
 | 
			
		||||
      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
 | 
			
		||||
			);
 | 
			
		||||
      return YourApi('DELETE', 'https://example.com/api/dns/txt/' + ch.dnsHost);
 | 
			
		||||
    }
 | 
			
		||||
  })
 | 
			
		||||
  .then(function() {
 | 
			
		||||
@ -403,7 +164,10 @@ Where `YourApi` might look something like this:
 | 
			
		||||
 | 
			
		||||
```js
 | 
			
		||||
var YourApi = function createApi(config) {
 | 
			
		||||
	return function(method, url, body) {
 | 
			
		||||
  var request = require('@root/request');
 | 
			
		||||
  request = require('util').promisify(request);
 | 
			
		||||
    
 | 
			
		||||
  return function (method, url, body) {
 | 
			
		||||
    return request({
 | 
			
		||||
      method: method,
 | 
			
		||||
      url: url,
 | 
			
		||||
@ -414,15 +178,10 @@ var YourApi = function createApi(config) {
 | 
			
		||||
    }).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:
 | 
			
		||||
@ -432,14 +191,6 @@ location on an http serever, set DNS records, or add the appropriate data to the
 | 
			
		||||
 | 
			
		||||
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`
 | 
			
		||||
 | 
			
		||||
# We Build Let's Encrypt Plugins for You
 | 
			
		||||
 | 
			
		||||
Want to get the experts involved? [Contact Root](acme-plugins@therootcompany.com)
 | 
			
		||||
 | 
			
		||||
We can take it on ourselves, work within your team, or guide an outsourced team.
 | 
			
		||||
 | 
			
		||||
Turnaround is typically a few days for simple modules with publicly available APIs.
 | 
			
		||||
* 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`
 | 
			
		||||
 | 
			
		||||
							
								
								
									
										27
									
								
								example.js
									
									
									
									
									
								
							
							
						
						
									
										27
									
								
								example.js
									
									
									
									
									
								
							@ -1,26 +1,27 @@
 | 
			
		||||
'use strict';
 | 
			
		||||
"use strict";
 | 
			
		||||
 | 
			
		||||
//var tester = require('acme-dns-01-test');
 | 
			
		||||
var tester = require('./');
 | 
			
		||||
//var tester = require('acme-challenge-test');
 | 
			
		||||
var tester = require("./");
 | 
			
		||||
 | 
			
		||||
var type = 'dns-01';
 | 
			
		||||
var challenger = require('acme-dns-01-cli').create({});
 | 
			
		||||
var type = "http-01";
 | 
			
		||||
var challenger = require("acme-http-01-cli").create({});
 | 
			
		||||
//var type = 'dns-01';
 | 
			
		||||
//var challenger = require('acme-dns-01-cli').create({});
 | 
			
		||||
//var challenger = require('./YOUR-CHALLENGE-STRATEGY').create({});
 | 
			
		||||
//var type = 'YOUR-TYPE-01';
 | 
			
		||||
 | 
			
		||||
// 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 domain = "example.com";
 | 
			
		||||
//var domain = '*.example.com';
 | 
			
		||||
 | 
			
		||||
tester
 | 
			
		||||
	// Will test these domain records
 | 
			
		||||
	// - example.com
 | 
			
		||||
	// - foo.example.com
 | 
			
		||||
	// - *.foo.example.com
 | 
			
		||||
	.testZone(type, zone, challenger)
 | 
			
		||||
	.test(type, domain, challenger)
 | 
			
		||||
	.then(function() {
 | 
			
		||||
		console.info('ALL PASSED');
 | 
			
		||||
		console.info("PASS");
 | 
			
		||||
	})
 | 
			
		||||
	.catch(function(err) {
 | 
			
		||||
		console.error('FAIL');
 | 
			
		||||
		console.error("FAIL");
 | 
			
		||||
		console.error(err);
 | 
			
		||||
		process.exit(20);
 | 
			
		||||
	});
 | 
			
		||||
 | 
			
		||||
							
								
								
									
										229
									
								
								index.js
									
									
									
									
									
								
							
							
						
						
									
										229
									
								
								index.js
									
									
									
									
									
								
							@ -1,3 +1,230 @@
 | 
			
		||||
'use strict';
 | 
			
		||||
/*global Promise*/
 | 
			
		||||
var crypto = require('crypto');
 | 
			
		||||
 | 
			
		||||
module.exports = require('acme-challenge-test');
 | 
			
		||||
module.exports.create = function() {
 | 
			
		||||
	throw new Error(
 | 
			
		||||
		'acme-challenge-test is a test fixture for acme-challenge-* plugins, not a plugin itself'
 | 
			
		||||
	);
 | 
			
		||||
};
 | 
			
		||||
 | 
			
		||||
// ignore all of this, it's just to normalize Promise vs node-style callback thunk vs synchronous
 | 
			
		||||
function promiseCheckAndCatch(obj, name) {
 | 
			
		||||
	var promisify = require('util').promisify;
 | 
			
		||||
	// don't loose this-ness, just in case that's important
 | 
			
		||||
	var fn = obj[name].bind(obj);
 | 
			
		||||
	var promiser;
 | 
			
		||||
 | 
			
		||||
	// function signature must match, or an error will be thrown
 | 
			
		||||
	if (1 === fn.length) {
 | 
			
		||||
		// wrap so that synchronous errors are caught (alsa handles synchronous results)
 | 
			
		||||
		promiser = function(opts) {
 | 
			
		||||
			return Promise.resolve().then(function() {
 | 
			
		||||
				return fn(opts);
 | 
			
		||||
			});
 | 
			
		||||
		};
 | 
			
		||||
	} else if (2 === fn.length) {
 | 
			
		||||
		// wrap as a promise
 | 
			
		||||
		promiser = promisify(fn);
 | 
			
		||||
	} else {
 | 
			
		||||
		return Promise.reject(
 | 
			
		||||
			new Error(
 | 
			
		||||
				"'challenge." +
 | 
			
		||||
					name +
 | 
			
		||||
					"' should accept either one argument, the options," +
 | 
			
		||||
					' and return a Promise or accept two arguments, the options and a node-style callback thunk'
 | 
			
		||||
			)
 | 
			
		||||
		);
 | 
			
		||||
	}
 | 
			
		||||
 | 
			
		||||
	function shouldntBeNull(result) {
 | 
			
		||||
		if ('undefined' === typeof result) {
 | 
			
		||||
			throw new Error(
 | 
			
		||||
				"'challenge.'" +
 | 
			
		||||
					name +
 | 
			
		||||
					"' should never return `undefined`. Please explicitly return null" +
 | 
			
		||||
					" (or fix the place where a value should have been returned but wasn't)."
 | 
			
		||||
			);
 | 
			
		||||
		}
 | 
			
		||||
		return result;
 | 
			
		||||
	}
 | 
			
		||||
 | 
			
		||||
	return function(opts) {
 | 
			
		||||
		return promiser(opts).then(shouldntBeNull);
 | 
			
		||||
	};
 | 
			
		||||
}
 | 
			
		||||
 | 
			
		||||
// Here's the meat, where the tests are happening:
 | 
			
		||||
function run(challenger, opts) {
 | 
			
		||||
	var ch = opts.challenge;
 | 
			
		||||
	if ('http-01' === ch.type && ch.wildname) {
 | 
			
		||||
		throw new Error('http-01 cannot be used for wildcard domains');
 | 
			
		||||
	}
 | 
			
		||||
 | 
			
		||||
	var set = promiseCheckAndCatch(challenger, 'set');
 | 
			
		||||
	if ('function' !== typeof challenger.get) {
 | 
			
		||||
		throw new Error(
 | 
			
		||||
			"'challenge.get' should be implemented for the sake of testing." +
 | 
			
		||||
				' It should be implemented as the internal method for fetching the challenge' +
 | 
			
		||||
				' (i.e. reading from a database, file system or API, not return internal),' +
 | 
			
		||||
				' not the external check (the http call, dns query, etc), which will already be done as part of this test.'
 | 
			
		||||
		);
 | 
			
		||||
	}
 | 
			
		||||
	var get = promiseCheckAndCatch(challenger, 'get');
 | 
			
		||||
	var remove = promiseCheckAndCatch(challenger, 'remove');
 | 
			
		||||
 | 
			
		||||
	// The first time we just check it against itself
 | 
			
		||||
	// this will cause the prompt to appear
 | 
			
		||||
	return set(opts)
 | 
			
		||||
		.then(function() {
 | 
			
		||||
			// this will cause the final completion message to appear
 | 
			
		||||
			// _test is used by the manual cli reference implementations
 | 
			
		||||
			var query = { type: ch.type, /*debug*/ status: ch.status, _test: true };
 | 
			
		||||
			if ('http-01' === ch.type) {
 | 
			
		||||
				query.identifier = ch.identifier;
 | 
			
		||||
				query.token = ch.token;
 | 
			
		||||
				// For testing only
 | 
			
		||||
				query.url = ch.challengeUrl;
 | 
			
		||||
			} else if ('dns-01' === ch.type) {
 | 
			
		||||
				query.identifier = { type: 'dns', value: ch.dnsHost };
 | 
			
		||||
				// For testing only
 | 
			
		||||
				query.altname = ch.altname;
 | 
			
		||||
				// there should only be two possible TXT records per challenge domain:
 | 
			
		||||
				// one for the bare domain, and the other if and only if there's a wildcard
 | 
			
		||||
				query.wildcard = ch.wildcard;
 | 
			
		||||
				query.dnsAuthorization = ch.dnsAuthorization;
 | 
			
		||||
			} else {
 | 
			
		||||
				query = JSON.parse(JSON.stringify(ch));
 | 
			
		||||
				query.comment = 'unknown challenge type, supplying everything';
 | 
			
		||||
			}
 | 
			
		||||
			return get({ challenge: query })
 | 
			
		||||
				.then(function(secret) {
 | 
			
		||||
					if ('string' === typeof secret) {
 | 
			
		||||
						console.info(
 | 
			
		||||
							'secret was passed as a string, which works historically, but should be an object instead:'
 | 
			
		||||
						);
 | 
			
		||||
						console.info('{ "keyAuthorization": "' + secret + '" }');
 | 
			
		||||
						console.info('or');
 | 
			
		||||
						// TODO this should be "keyAuthorizationDigest"
 | 
			
		||||
						console.info('{ "dnsAuthorization": "' + secret + '" }');
 | 
			
		||||
						console.info(
 | 
			
		||||
							'This is to help keep acme / greenlock (and associated plugins) future-proof for new challenge types'
 | 
			
		||||
						);
 | 
			
		||||
					}
 | 
			
		||||
					// historically 'secret' has been a string, but I'd like it to transition to be an object.
 | 
			
		||||
					// to make it backwards compatible in v2.7 to change it,
 | 
			
		||||
					// so I'm not sure that we really need to.
 | 
			
		||||
					if ('http-01' === ch.type) {
 | 
			
		||||
						secret = secret.keyAuthorization || secret;
 | 
			
		||||
						if (ch.keyAuthorization !== secret) {
 | 
			
		||||
							throw new Error(
 | 
			
		||||
								"http-01 challenge.get() returned '" +
 | 
			
		||||
									secret +
 | 
			
		||||
									"', which does not match the keyAuthorization" +
 | 
			
		||||
									" saved with challenge.set(), which was '" +
 | 
			
		||||
									ch.keyAuthorization +
 | 
			
		||||
									"'"
 | 
			
		||||
							);
 | 
			
		||||
						}
 | 
			
		||||
					} else if ('dns-01' === ch.type) {
 | 
			
		||||
						secret = secret.dnsAuthorization || secret;
 | 
			
		||||
						if (ch.dnsAuthorization !== secret) {
 | 
			
		||||
							throw new Error(
 | 
			
		||||
								"dns-01 challenge.get() returned '" +
 | 
			
		||||
									secret +
 | 
			
		||||
									"', which does not match the dnsAuthorization" +
 | 
			
		||||
									" (keyAuthDigest) saved with challenge.set(), which was '" +
 | 
			
		||||
									ch.dnsAuthorization +
 | 
			
		||||
									"'"
 | 
			
		||||
							);
 | 
			
		||||
						}
 | 
			
		||||
					} else {
 | 
			
		||||
						if ('tls-alpn-01' === ch.type) {
 | 
			
		||||
							console.warn(
 | 
			
		||||
								"'tls-alpn-01' support is in development" +
 | 
			
		||||
									" (or developed and we haven't update this yet). Please contact us."
 | 
			
		||||
							);
 | 
			
		||||
						} else {
 | 
			
		||||
							console.warn(
 | 
			
		||||
								"We don't know how to test '" +
 | 
			
		||||
									ch.type +
 | 
			
		||||
									"'... are you sure that's a thing?"
 | 
			
		||||
							);
 | 
			
		||||
						}
 | 
			
		||||
						secret = secret.keyAuthorization || secret;
 | 
			
		||||
						if (ch.keyAuthorization !== secret) {
 | 
			
		||||
							console.warn(
 | 
			
		||||
								"The returned value doesn't match keyAuthorization",
 | 
			
		||||
								ch.keyAuthorization,
 | 
			
		||||
								secret
 | 
			
		||||
							);
 | 
			
		||||
						}
 | 
			
		||||
					}
 | 
			
		||||
				})
 | 
			
		||||
				.then(function() {
 | 
			
		||||
					return remove(opts).then(function() {
 | 
			
		||||
						return get(opts).then(function(result) {
 | 
			
		||||
							if (result) {
 | 
			
		||||
								throw new Error(
 | 
			
		||||
									'challenge.remove() should have made it not possible for challenge.get() to return a value'
 | 
			
		||||
								);
 | 
			
		||||
							}
 | 
			
		||||
							if (null !== result) {
 | 
			
		||||
								throw new Error(
 | 
			
		||||
									'challenge.get() should return null when the value is not set'
 | 
			
		||||
								);
 | 
			
		||||
							}
 | 
			
		||||
						});
 | 
			
		||||
					});
 | 
			
		||||
				});
 | 
			
		||||
		})
 | 
			
		||||
		.then(function() {
 | 
			
		||||
			console.info('All soft tests: PASS');
 | 
			
		||||
			console.warn(
 | 
			
		||||
				'Hard tests (actually checking http URLs and dns records) is implemented in acme-v2.'
 | 
			
		||||
			);
 | 
			
		||||
			console.warn(
 | 
			
		||||
				"We'll copy them over here as well, but that's a TODO for next week."
 | 
			
		||||
			);
 | 
			
		||||
		});
 | 
			
		||||
}
 | 
			
		||||
 | 
			
		||||
module.exports.test = function(type, altname, challenger) {
 | 
			
		||||
	var expires = new Date(Date.now() + 10 * 60 * 1000).toISOString();
 | 
			
		||||
	var token = crypto.randomBytes(8).toString('hex');
 | 
			
		||||
	var thumb = crypto.randomBytes(16).toString('hex');
 | 
			
		||||
	var keyAuth = token + '.' + crypto.randomBytes(16).toString('hex');
 | 
			
		||||
	var dnsAuth = crypto
 | 
			
		||||
		.createHash('sha256')
 | 
			
		||||
		.update(keyAuth)
 | 
			
		||||
		.digest('base64')
 | 
			
		||||
		.replace(/\+/g, '-')
 | 
			
		||||
		.replace(/\//g, '_')
 | 
			
		||||
		.replace(/=/g, '');
 | 
			
		||||
 | 
			
		||||
	var challenge = {
 | 
			
		||||
		type: type,
 | 
			
		||||
		identifier: { type: 'dns', value: null }, // completed below
 | 
			
		||||
		wildcard: false, // completed below
 | 
			
		||||
		status: 'pending',
 | 
			
		||||
		expires: expires,
 | 
			
		||||
		token: token,
 | 
			
		||||
		thumbprint: thumb,
 | 
			
		||||
		keyAuthorization: keyAuth,
 | 
			
		||||
		url: null, // completed below
 | 
			
		||||
		dnsHost: '_acme-challenge.', // completed below
 | 
			
		||||
		dnsAuthorization: dnsAuth,
 | 
			
		||||
		altname: altname,
 | 
			
		||||
		_test: true // used by CLI referenced implementations
 | 
			
		||||
	};
 | 
			
		||||
	if ('*.' === altname.slice(0, 2)) {
 | 
			
		||||
		challenge.wildcard = true;
 | 
			
		||||
		altname = altname.slice(2);
 | 
			
		||||
	}
 | 
			
		||||
	challenge.identifier.value = altname;
 | 
			
		||||
	challenge.url =
 | 
			
		||||
		'http://' + altname + '/.well-known/acme-challenge/' + challenge.token;
 | 
			
		||||
	challenge.dnsHost += altname;
 | 
			
		||||
 | 
			
		||||
	return run(challenger, { challenge: challenge });
 | 
			
		||||
};
 | 
			
		||||
 | 
			
		||||
							
								
								
									
										25
									
								
								package-lock.json
									
									
									
										generated
									
									
									
								
							
							
						
						
									
										25
									
								
								package-lock.json
									
									
									
										generated
									
									
									
								
							@ -1,25 +0,0 @@
 | 
			
		||||
{
 | 
			
		||||
	"name": "acme-dns-01-test",
 | 
			
		||||
	"version": "3.3.1",
 | 
			
		||||
	"lockfileVersion": 1,
 | 
			
		||||
	"requires": true,
 | 
			
		||||
	"dependencies": {
 | 
			
		||||
		"@root/request": {
 | 
			
		||||
			"version": "1.3.11",
 | 
			
		||||
			"resolved": "https://registry.npmjs.org/@root/request/-/request-1.3.11.tgz",
 | 
			
		||||
			"integrity": "sha512-3a4Eeghcjsfe6zh7EJ+ni1l8OK9Fz2wL1OjP4UCa0YdvtH39kdXB9RGWuzyNv7dZi0+Ffkc83KfH0WbPMiuJFw=="
 | 
			
		||||
		},
 | 
			
		||||
		"acme-challenge-test": {
 | 
			
		||||
			"version": "3.3.1",
 | 
			
		||||
			"resolved": "https://registry.npmjs.org/acme-challenge-test/-/acme-challenge-test-3.3.1.tgz",
 | 
			
		||||
			"integrity": "sha512-y7iCHb70hWuFgPvtAWwQd1sz9I2Atu+6PKhN5sIIfqDhkg/sVmlxAVKXn6/SBx9TSrP50xHtiAnMkmt+umemDw==",
 | 
			
		||||
			"requires": {
 | 
			
		||||
				"@root/request": "^1.3.11"
 | 
			
		||||
			}
 | 
			
		||||
		},
 | 
			
		||||
		"acme-dns-01-cli": {
 | 
			
		||||
			"version": "3.1.0",
 | 
			
		||||
			"dev": true
 | 
			
		||||
		}
 | 
			
		||||
	}
 | 
			
		||||
}
 | 
			
		||||
							
								
								
									
										23
									
								
								package.json
									
									
									
									
									
								
							
							
						
						
									
										23
									
								
								package.json
									
									
									
									
									
								
							@ -1,29 +1,22 @@
 | 
			
		||||
{
 | 
			
		||||
	"name": "acme-dns-01-test",
 | 
			
		||||
	"version": "3.3.2",
 | 
			
		||||
	"description": "ACME dns-01 tests for Let's Encrypt integration. Any `acme-dns-01-` plugin should be able to pass these tests.",
 | 
			
		||||
	"name": "acme-challenge-test",
 | 
			
		||||
	"version": "3.0.4",
 | 
			
		||||
	"description": "The base set of tests for all ACME challenge strategies. Any `acme-http-01-`, `acme-dns-01-`, `acme-challenge-`, or greenlock plugin should be able to pass these tests.",
 | 
			
		||||
	"main": "index.js",
 | 
			
		||||
	"homepage": "https://git.rootprojects.org/root/acme-dns-01-test.js",
 | 
			
		||||
	"files": [
 | 
			
		||||
		"example.js",
 | 
			
		||||
		"lib"
 | 
			
		||||
	],
 | 
			
		||||
	"dependencies": {
 | 
			
		||||
		"acme-challenge-test": "^3.3.1"
 | 
			
		||||
	},
 | 
			
		||||
	"devDependencies": {
 | 
			
		||||
		"acme-dns-01-cli": "^3.1.0"
 | 
			
		||||
	},
 | 
			
		||||
	"homepage": "https://git.rootprojects.org/root/acme-challenge-test.js",
 | 
			
		||||
	"dependencies": {},
 | 
			
		||||
	"devDependencies": {},
 | 
			
		||||
	"scripts": {
 | 
			
		||||
		"test": "node example.js"
 | 
			
		||||
	},
 | 
			
		||||
	"repository": {
 | 
			
		||||
		"type": "git",
 | 
			
		||||
		"url": "https://git.rootprojects.org/root/acme-dns-01-test.js.git"
 | 
			
		||||
		"url": "https://git.rootprojects.org/root/acme-challenge-test.js.git"
 | 
			
		||||
	},
 | 
			
		||||
	"keywords": [
 | 
			
		||||
		"Let's Encrypt",
 | 
			
		||||
		"ACME",
 | 
			
		||||
		"http-01",
 | 
			
		||||
		"dns-01",
 | 
			
		||||
		"challenge",
 | 
			
		||||
		"plugin",
 | 
			
		||||
 | 
			
		||||
		Loading…
	
	
			
			x
			
			
		
	
		Reference in New Issue
	
	Block a user