root
/
acme-http-01-test.js
mirror of https://git.coolaj86.com/coolaj86/acme-http-01-test.js.git
2
0
Fork 0
Code Issues Releases Wiki Activity

v3.1.3: move http-01 docs to own package

This commit is contained in:
AJ ONeal 2019-06-13 01:10:41 -06:00
parent dda7ecb497
commit 3dec11ef1b
6 changed files with 170 additions and 444 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.prettierrc
View File

@ -4,5 +4,5 @@
"singleQuote": true,
"tabWidth": 2,
"trailingComma": "none",
"useTabs": true
"useTabs": false
}

231
README.md
View File

@ -1,49 +1,56 @@
# [acme-challenge-test](https://git.rootprojects.org/root/acme-challenge-test.js.git) | a [Root](https://rootprojects.org) project
# [acme-http-01-test](https://git.rootprojects.org/root/acme-http-01-test.js.git) | a [Root](https://rootprojects.org) project
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 https-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()`).
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 ACME module.
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. 👌
Passing the tests is very easy. There are just three functions to implement:
**Node v6 Support**: Please build community plugins using node v6 / vanillajs to ensure that all acme.js and greenlock.js users are fully supported.
- `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](https://git.rootprojects.org/root/acme-http-01-test.js.git) 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
```bash
npm install --save-dev acme-challenge-test@3.x
npm install --save-dev acme-http-01-test@3.x
```
## Usage
```js
var tester = require('acme-challenge-test');
var tester = require('acme-http-01-test');
//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'
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';
var record = 'foo.example.com';
tester.testZone('dns-01', zone, challenger).then(function() {
console.info('PASS');
tester.testRecord('http-01', record, 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:
**Note**: If the service you are testing only handles multiple records
within a single zone, you should use `testZone` instead:
```js
var record = 'foo.example.com';
var zone = 'example.co.uk';
tester.testRecord('dns-01', record, challenger).then(function() {
console.info('PASS');
tester.testZone('http-01', zone, challenger).then(function() {
console.info('PASS');
});
```
@ -52,14 +59,18 @@ tester.testRecord('dns-01', record, challenger).then(function() {
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`](https://git.rootprojects.org/root/acme-http-01-cli.js)
- [`acme-dns-01-cli`](https://git.rootprojects.org/root/acme-dns-01-cli.js)
- http-01
- [`acme-http-01-cli`](https://git.rootprojects.org/root/acme-http-01-cli.js)
- [`acme-http-01-fs`](https://git.rootprojects.org/root/acme-http-01-fs.js)
- dns-01
- [`acme-dns-01-cli`](https://git.rootprojects.org/root/acme-dns-01-cli.js)
- [`acme-dns-01-digitalocean`](https://git.rootprojects.org/root/acme-dns-01-digitalocean.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-).
If you are building a plugin, please let us know.
We would like to co-author and help maintain and promote your module.
We may like to co-author and help maintain and promote your module.
## Example
@ -70,40 +81,39 @@ See `example.js` (it works).
Here's what you could start with.
```js
var tester = require('acme-challenge-test');
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 domain = 'example.com';
var record = 'example.com';
tester
.testRecord('http-01', domain, {
// 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');
},
.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 *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 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 record via the DNS server's API
get: function(opts) {
console.log('get opts:', opts);
throw new Error('get not implemented');
}
})
.then(function() {
console.info('PASS');
});
// 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');
});
```
## dns-01 vs http-01
## http-01 vs dns-01
For `type` http-01:
@ -116,83 +126,86 @@ For `type` dns-01:
// `dnsHost` is the domain/subdomain/host
// `dnsAuthorization` is the value of the TXT record
See [acme-dns-01-test.js](https://git.rootprojects.org/root/acme-http-01-test.js.git).
## Detailed Overview
Here's a quick pseudo stub-out of what a test-passing plugin object might look like:
```js
tester
.testZone('dns-01', 'example.com', {
set: function(opts) {
var ch = opts.challenge;
// { type: 'dns-01' // or 'http-01'
// , identifier: { type: 'dns', value: 'example.com' }
// , wildcard: false
// , token: 'xxxx'
// , keyAuthorization: 'xxxx.yyyy'
// , dnsHost: '_acme-challenge.example.com'
// , dnsAuthorization: 'zzzz' }
.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://example.com/api/dns/txt', {
host: ch.dnsHost,
record: ch.dnsAuthorization
});
},
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: '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
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://example.com/api/dns/txt', {
host: ch.dnsHost
}).then(function(secret) {
// http-01
//return { keyAuthorization: secret };
// dns-01
return { dnsAuthorization: secret };
});
},
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()`
remove: function(opts) {
var ch = opts.challenge;
// same options as in `set()` (which are not the same as `get()`
return YourApi('DELETE', 'https://example.com/api/dns/txt/' + ch.dnsHost);
}
})
.then(function() {
console.info('PASS');
});
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:
```js
var YourApi = function createApi(config) {
var request = require('@root/request');
request = require('util').promisify(request);
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;
});
};
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;
});
};
};
```
@ -201,10 +214,8 @@ var YourApi = function createApi(config) {
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.
location on an http serever 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`
You can't do wildcards with http-01 challenges.

28
example.js
View File

@ -1,26 +1,24 @@
'use strict';
//var tester = require('acme-challenge-test');
//var tester = require('acme-http-01-test');
var tester = require('./');
//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 type = 'http-01';
var challenger = require('acme-http-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 record = 'example.com';
tester
.test(type, zone, challenger)
.then(function() {
console.info('ALL PASSED');
})
.catch(function(err) {
console.error('FAIL');
console.error(err);
process.exit(20);
});
.testRecord(type, record, challenger)
.then(function() {
console.info('ALL PASSED');
})
.catch(function(err) {
console.error('FAIL');
console.error(err);
process.exit(20);
});

283
index.js
View File

@ -1,284 +1,3 @@
'use strict';
/*global Promise*/
var crypto = require('crypto');
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);
};
}
function mapAsync(els, doer) {
els = els.slice(0);
var results = [];
function next() {
var el = els.shift();
if (!el) {
return results;
}
return doer(el).then(function(result) {
results.push(result);
return next();
});
}
return next();
}
// Here's the meat, where the tests are happening:
function testEach(type, domains, challenger) {
var chr = wrapChallenger(challenger);
var all = domains.map(function(d) {
return { domain: d };
});
var rnd = crypto.randomBytes(2).toString('hex');
return mapAsync(all, function(opts) {
console.info("TEST '%s'", opts.domain);
opts.challenge = fakeChallenge(type, opts.domain, rnd);
var ch = opts.challenge;
if ('http-01' === ch.type && ch.wildname) {
throw new Error('http-01 cannot be used for wildcard domains');
}
// The first time we just check it against itself
// this will cause the prompt to appear
return chr.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';
}
opts.query = query;
return opts;
});
})
.then(function(all) {
return mapAsync(all, function(opts) {
var ch = opts.challenge;
return chr.get({ challenge: opts.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 mapAsync(all, function(opts) {
return chr.remove(opts).then(function() {
return chr.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'
);
}
console.info("PASS '%s'", opts.domain);
});
});
});
})
.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."
);
});
}
function testZone(type, zone, challenger) {
var domains = [zone, 'foo.' + zone];
if ('dns-01' === type) {
domains.push('*.foo.' + zone);
}
return testEach(type, domains, challenger);
}
function wrapChallenger(challenger) {
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');
return { set: set, get: get, remove: remove };
}
function fakeChallenge(type, altname, rnd) {
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: '_' + rnd.slice(0, 2) + '-acme-challenge-' + rnd.slice(2) + '.', // 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 challenge;
}
function testRecord(type, altname, challenger) {
return testEach(type, [altname], challenger);
}
module.exports.testRecord = testRecord;
module.exports.testZone = testZone;
module.exports.test = testZone;
module.exports = require('acme-challenge-test');

5
package-lock.json generated
View File

@ -1,5 +0,0 @@
{
"name": "acme-challenge-test",
"version": "3.0.4",
"lockfileVersion": 1
}

65
package.json
View File

@ -1,33 +1,36 @@
{
"name": "acme-challenge-test",
"version": "3.1.2",
"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-challenge-test.js",
"files": [
"example.js",
"lib"
],
"dependencies": {},
"devDependencies": {},
"scripts": {
"test": "node example.js"
},
"repository": {
"type": "git",
"url": "https://git.rootprojects.org/root/acme-challenge-test.js.git"
},
"keywords": [
"Let's Encrypt",
"ACME",
"http-01",
"dns-01",
"challenge",
"plugin",
"module",
"strategy",
"greenlock"
],
"author": "AJ ONeal <solderjs@gmail.com> (https://solderjs.com/)",
"license": "MPL-2.0"
"name": "acme-http-01-test",
"version": "3.1.3",
"description": "ACME http-01 tests for Let's Encrypt integration. Any `acme-http-01-` plugin should be able to pass these tests.",
"main": "index.js",
"homepage": "https://git.rootprojects.org/root/acme-http-01-test.js",
"files": [
"example.js",
"lib"
],
"dependencies": {
"acme-challenge-test": "^3.1.0"
},
"devDependencies": {
"acme-http-01-cli": "^3.1.0"
},
"scripts": {
"test": "node example.js"
},
"repository": {
"type": "git",
"url": "https://git.rootprojects.org/root/acme-http-01-test.js.git"
},
"keywords": [
"Let's Encrypt",
"ACME",
"http-01",
"challenge",
"plugin",
"module",
"strategy",
"greenlock"
],
"author": "AJ ONeal <solderjs@gmail.com> (https://solderjs.com/)",
"license": "MPL-2.0"
}