4.3 KiB

Raw Permalink Blame History

greenlock-store-test | A Root Project

The test harness you should use when writing a certificate and keypair storage strategy for Greenlock 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

npm install --save-dev greenlock-store-test@3.x

Usage

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.

Example

See example.js (it works).

Looking for the Easy Button?

Contact Root

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:

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.

4.3 KiB Raw Permalink Blame History