128 lines
4.3 KiB
Markdown
128 lines
4.3 KiB
Markdown
# [greenlock-store-test](https://git.rootprojects.org/root/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");
|
|
});
|
|
```
|
|
|
|
## 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.
|
|
|
|
* [`greenlock-store-memory`](https://git.rootprojects.org/root/greenlock-store-memory.js)
|
|
* [`greenlock-store-fs`](https://git.rootprojects.org/root/greenlock-store-fs.js)
|
|
|
|
## Example
|
|
|
|
See `example.js` (it works).
|
|
|
|
## Looking for the Easy Button?
|
|
|
|
[Contact Root](mailto:support@rootprojects.org)
|
|
|
|
If you're looking for fast and inexpensive plugin development,
|
|
we can deliver greater value in less time than most outsouring options.
|
|
We can also work with your in-house team to give a quick, inexpensive 10x
|
|
boost to internal development success.
|
|
|
|
We also offer commercial licenses for LTS (Long-Term Support) versions of Greenlock.
|
|
|
|
## 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.
|