acme-challenge-test.js/README.md

acme-http-01-test | a Root project

An ACME https-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 three functions to implement:

• set() - set a TXT record in a zone (i.e. _acme-challenge.foo in example.com)
• get() - confirm that the record was set
• remove() - clean up after the ACME challenge passes

The http-01 tests account for single-domain certificates (example.com). If you need multiple domain certs (SAN / AltName), wildcards (*.example.com), or valid private / localhost certificates, you'll need acme-dns-01-test.js instead.

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-http-01-test@3.x

Usage

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

//var challenger = require('acme-http-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 record = 'foo.example.com';

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

Note: If the service you are testing only handles multiple records within a single zone, you should use testZone instead:

var zone = 'example.co.uk';

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

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.

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

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.

Example

See example.js (it works).

Starter Template

Here's what you could start with.

var tester = require('acme-http-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 record = 'example.com';

tester
  .testRecord('http-01', record, {
    // Should make the token url return the key authorization
    // i.e. GET http://example.com/.well-known/acme-challenge/xxxx => xxxx.yyyy
    set: function(opts) {
      console.log('set opts:', opts);
      throw new Error('set not implemented');
    },

    // Should remove the previously set token file (just the one)
    remove: function(opts) {
      console.log('remove opts:', opts);
      throw new Error('remove not implemented');
    },

    // Should get the token file via the hosting service API
    get: function(opts) {
      console.log('get opts:', opts);
      throw new Error('get not implemented');
    }
  })
  .then(function() {
    console.info('PASS');
  });

http-01 vs dns-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

See acme-dns-01-test.js.

Detailed Overview

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

tester
  .testRecord('http-01', 'foo.example.com', {
    set: function(opts) {
      var ch = opts.challenge;
      // { type: 'http-01'
      // , identifier: { type: 'dns', value: 'foo.example.com' }
      // , token: 'xxxx'
      // , keyAuthorization: 'xxxx.yyyy' }

      return YourApi('POST', 'https://examplehost.com/api/sites/', {
        site: ch.identifier.value,
        filename: new URL(ch.url).pathname,
        contents: ch.keyAuthorization
      });
    },

    get: function(query) {
      var ch = query.challenge;
      // { type: 'http-01'
      // , identifier: { type: 'dns', value: 'foo.example.com' }
      // , token: 'xxxx'
      // , url: '...' }
      // Note: query.identifier.value is different for http-01 than for dns-01

      return YourApi(
        'GET',
        'https://examplehost.com/api/sites/' +
          ch.indentifier.value +
          '/' +
          new URL(ch.url).pathname
      ).then(function(secret) {
        // http-01
        return { keyAuthorization: secret };
      });
    },

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

      return YourApi(
        'DELETE',
        'https://examplehost.com/api/sites/' +
          ch.indentifier.value +
          '/' +
          new URL(ch.url).pathname
      );
    }
  })
  .then(function() {
    console.info('PASS');
  });

Where YourApi might look something like this:

var YourApi = function createApi(config) {
  var request = require('@root/request');
  request = require('util').promisify(request);

  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;
    });
  };
};

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 or add the appropriate data to the database that handles such things.

Note 2:

You can't do wildcards with http-01 challenges.