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

Compare commits

base: root:master
Branches Tags
root:master
root:v3.1.3
root:v3.1.2
root:v3.1.1
root:v3.1.0
root:v3.0.5
root:v3.0.4
root:v3.0.3
root:v3.0.2
root:v3.0.1
root:v3.0.0
..
compare: root:v3.0.4
Branches Tags
root:master
root:v3.1.3
root:v3.1.2
root:v3.1.1
root:v3.1.0
root:v3.0.5
root:v3.0.4
root:v3.0.3
root:v3.0.2
root:v3.0.1
root:v3.0.0

No commits in common. "master" and "v3.0.4" have entirely different histories.
master ... v3.0.4

5 changed files with 336 additions and 138 deletions
Show Stats Expand all files Collapse all files

2
.prettierrc
View File

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

143
README.md
View File

@ -1,56 +1,38 @@
# [acme-http-01-test](https://git.rootprojects.org/root/acme-http-01-test.js.git) | a [Root](https://rootprojects.org) project
# [acme-challenge-test](https://git.rootprojects.org/root/acme-challenge-test.js.git) | a [Root](https://rootprojects.org) project
An ACME https-01 test harness for Let's Encrypt integrations.
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).
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.
All implementations MUST pass these tests, which is a very easy thing to do (just `set()`, `get()`, and `remove()`).
Passing the tests is very easy. There are just three functions to implement:
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. 👌
- `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.
**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-http-01-test@3.x
npm install --save-dev acme-challenge-test@3.x
```
## Usage
```js
var tester = require('acme-http-01-test');
var tester = require("acme-challenge-test");
//var challenger = require('acme-http-01-cli').create({});
var challenger = require('./YOUR-CHALLENGE-STRATEGY').create({
//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 record = 'foo.example.com';
var domain = "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:
```js
var zone = 'example.co.uk';
tester.testZone('http-01', zone, challenger).then(function() {
console.info('PASS');
tester.test("http-01", domain, challenger).then(function() {
console.info("PASS");
});
```
@ -59,18 +41,10 @@ tester.testZone('http-01', zone, 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.
- 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)
- [`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)
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.
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-).
## Example
@ -81,28 +55,29 @@ See `example.js` (it works).
Here's what you could start with.
```js
var tester = require('acme-http-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 record = 'example.com';
var domain = '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
.test('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');
},
// Should remove the previously set token file (just the one)
// 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 token file via the hosting service API
// Should get the record via the DNS server's API
get: function(opts) {
console.log('get opts:', opts);
throw new Error('get not implemented');
@ -113,7 +88,7 @@ tester
});
```
## http-01 vs dns-01
## dns-01 vs http-01
For `type` http-01:
@ -126,46 +101,50 @@ 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
.testRecord('http-01', 'foo.example.com', {
.test('dns-01', 'example.com', {
set: function(opts) {
var ch = opts.challenge;
// { type: 'http-01'
// , identifier: { type: 'dns', value: 'foo.example.com' }
// { type: 'dns-01' // or 'http-01'
// , identifier: { type: 'dns', value: 'example.com' }
// , wildcard: false
// , token: 'xxxx'
// , keyAuthorization: 'xxxx.yyyy' }
// , keyAuthorization: 'xxxx.yyyy'
// , dnsHost: '_acme-challenge.example.com'
// , dnsAuthorization: 'zzzz' }
return YourApi('POST', 'https://examplehost.com/api/sites/', {
site: ch.identifier.value,
filename: new URL(ch.url).pathname,
contents: ch.keyAuthorization
return YourApi('POST', 'https://example.com/api/dns/txt', {
host: ch.dnsHost,
record: ch.dnsAuthorization
});
},
get: function(query) {
var ch = query.challenge;
// { type: 'http-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: '...' }
// , 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
return YourApi(
'GET',
'https://examplehost.com/api/sites/' +
ch.indentifier.value +
'/' +
new URL(ch.url).pathname
).then(function(secret) {
return YourApi('GET', 'https://example.com/api/dns/txt', {
host: ch.dnsHost
}).then(function(secret) {
// http-01
return { keyAuthorization: secret };
//return { keyAuthorization: secret };
// dns-01
return { dnsAuthorization: secret };
});
},
@ -173,13 +152,7 @@ tester
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
);
return YourApi('DELETE', 'https://example.com/api/dns/txt/' + ch.dnsHost);
}
})
.then(function() {
@ -194,7 +167,7 @@ var YourApi = function createApi(config) {
var request = require('@root/request');
request = require('util').promisify(request);
return function(method, url, body) {
return function (method, url, body) {
return request({
method: method,
url: url,
@ -205,8 +178,8 @@ var YourApi = function createApi(config) {
}).then(function(resp) {
return resp.body;
});
};
};
}
}
```
### Two notes:
@ -214,8 +187,10 @@ 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 or add the appropriate data to the database that handles such things.
location on an http serever, set DNS records, or add the appropriate data to the database that handles such things.
Note 2:
You can't do wildcards with http-01 challenges.
* 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`

21
example.js
View File

@ -1,24 +1,27 @@
'use strict';
"use strict";
//var tester = require('acme-http-01-test');
var tester = require('./');
//var tester = require('acme-challenge-test');
var tester = require("./");
var type = 'http-01';
var challenger = require('acme-http-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 record = 'example.com';
var domain = "example.com";
//var domain = '*.example.com';
tester
.testRecord(type, record, 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
View File

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

23
package.json
View File

@ -1,30 +1,23 @@
{
"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.",
"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-http-01-test.js",
"files": [
"example.js",
"lib"
],
"dependencies": {
"acme-challenge-test": "^3.1.0"
},
"devDependencies": {
"acme-http-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-http-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",
"module",