acme-challenge-test | A Root Project

The test harness you should use when writing an ACME challenge strategy for Greenlock v2.7+ (and v3).

All implementations MUST pass these tests, which is a very easy thing to do (just set(), get(), and remove()).

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. As someone creating a challenge strategy that's not something you have to take special consideration for - just pass the tests.

Install

1npm install --save-dev acme-challenge-test@3.x

Usage

1var tester = require("acme-challenge-test");
2
3//var challenger = require('acme-http-01-cli').create({});
4//var challenger = require('acme-dns-01-cli').create({});
5var challenger = require("./YOUR-CHALLENGE-STRATEGY").create({});
6
7// The dry-run tests can pass on, literally, 'example.com'
8// but the integration tests require that you have control over the domain
9var domain = "example.com";
10
11tester.test("http-01", domain, challenger).then(function() {
12	console.info("PASS");
13});

Reference Implementations

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.

• acme-http-01-cli
• acme-dns-01-cli

Example

See example.js (it works).

Overview

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

1tester.test('http-01', 'example.com', {
2  set: function (opts) {
3    var ch = opts.challenge;
4    // { type: 'http-01' // or 'dns-01'
5    // , identifier: { type: 'dns', value: 'example.com' }
6    // , wildcard: false
7    // , token: 'xxxx'
8    // , keyAuthorization: 'xxxx.yyyy'
9    // , dnsHost: '_acme-challenge.example.com'
10    // , dnsAuthorization: 'zzzz' }
11
12    return API.set(...);
13  }
14, get: function (query) {
15    var ch = query.challenge;
16    // { type: 'http-01' // or 'dns-01', 'tls-alpn-01', etc
17    // , identifier: { type: 'dns', value: 'example.com' }
18    //   // http-01 only
19    // , token: 'xxxx'
20    // , url: '...' // for testing and debugging
21    //   // dns-01 only, for testing / dubgging
22    // , altname: '...'
23    // , dnsHost: '...'
24    // , wildcard: false }
25    // Note: query.identifier.value is different for http-01 than for dns-01
26
27    return API.get(...).then(function (secret) {
28      // http-01
29      return { keyAuthorization: secret };
30      // dns-01
31      //return { dnsAuthorization: secret };
32    });
33  }
34, remove: function (opts) {
35    var ch = opts.challenge;
36    // same options as in `set()` (which are not the same as `get()`
37
38    return API.remove(...);
39  }
40}).then(function () {
41  console.info("PASS");
42});

Note: 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.