greenlock-store-test.js/README.md

114 lines
3.8 KiB
Markdown

# [greenlock-store-test](https://git.coolaj86.com/coolaj86/greenlock-store-test.js.git)
| A [Root](https://rootprojects.org) Project |
The test harness you should use when writing a certificate and keypair storage strategy
for [Greenlock](https://git.coolaj86.com/coolaj86/greenlock-express.js) v2.7+ (and v3).
All implementations MUST pass these tests, which is a very easy thing to do (just 3 getter/setter pairs 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. As someone creating a challenge strategy
that's not something you have to take special consideration for - just pass the tests.
## Install
```bash
npm install --save-dev greenlock-store-test@3.x
```
## Usage
```js
var tester = require('greenlock-store-test');
//var store = require('greenlock-store-memory').create({});
//var store = require('greenlock-store-fs').create({});
var store = require('./YOUR-STORAGE-STRATEGY').create({});
// All of these tests can pass locally, standalone without any ACME integration.
tester.test(store).then(function () {
console.info("PASS");
});
```
## Overview
The most generic implementation, with no special considerations or custom logic, ends up looking like this:
```js
tester.test({
// ACME user account
accounts: {
setKeypair: function (opts) {
// { account: { id: '...' } // you may or may not receive 'id'
// , email: 'jon.doe@example.com'
// , keypair: { privateKeyPem: '...', privateKeyJwk: {...} }
// }
var id = opts.account.id || opts.email;
return DB.Keypairs.save(id, JSON.stringify(opts.keypair));
}
, checkKeypair: function (opts) {
// you receive the same options as setKeypair() above
var id = opts.account.id || opts.email;
return DB.Keypairs.get(id).then(function (k) { return JSON.parse(k); });
}
}
// Site Keys & Certificates
, certificates: {
// Site Keys (privkey.pem a.k.a. example.com.key)
setKeypair: function (opts) {
// { certificate: { kid: '...', id: '...' } // you may or may not receive 'kid' or 'id'
// , subject: 'foo.example.com'
// , keypair: { privateKeyPem: '...', privateKeyJwk: {...} }
// }
var id = opts.certificate.kid || opts.certificate.id || opts.subject;
return DB.Keypairs.save(id, JSON.stringify(opts.keypair));
}
, checkKeypair: function (opts) {
// you receive the same options as setKeypair() above
var id = opts.certificate.kid || opts.certificate.id || opts.subject;
return DB.Keypairs.get(id).then(function (x) { return JSON.parse(x); });
}
// Certificates (fullchain.pem a.k.a. cert.pem a.k.a. example.com.crt)
, set: function (opts) {
// { certificate: { id: '...' } // you may or may not receive 'id'
// , subject: 'foo.example.com'
// , pems: { cert: '...', chain: '...', ... }
// }
var id = opts.certificate.id || opts.subject;
return DB.Certificates.save(id, JSON.stringify(opts.keypair));
}
, set: function (opts) {
// { certificate: { id: '...' } // you may or may not receive 'id'
// , subject: 'foo.example.com'
// , pems: { cert: '...', chain: '...', ... }
// }
var id = opts.certificate.id || opts.subject;
return DB.Certificates.save(id, JSON.stringify(opts.keypair));
}
}
}).then(function () {
console.info("PASS");
});
```
Note: The `DB.x.y()` is where you do your magic up to connect to a database or API or whatever and keep stuff safe.
## Examples
See the reference implementations (they work):
* [`greenlock-store-memory`](https://git.coolaj86.com/coolaj86/greenlock-store-memory)
* [`greenlock-store-fs`](https://git.coolaj86.com/coolaj86/greenlock-store-fs)