Compare commits

..

2 Commits

Author SHA1 Message Date
AJ ONeal 5490a194eb update docs 2019-11-02 13:26:08 -06:00
AJ ONeal e0a9fff07d make Prettier 2019-11-02 12:38:12 -06:00
10 changed files with 610 additions and 524 deletions

7
.prettierrc Normal file
View File

@ -0,0 +1,7 @@
{
"bracketSpacing": true,
"printWidth": 80,
"tabWidth": 4,
"trailingComma": "none",
"useTabs": false
}

211
README.md
View File

@ -4,34 +4,54 @@ A keypair and certificate storage strategy for Greenlock v2.7+ (and v3).
The (much simpler) successor to le-store-certbot.
Works with all ACME (Let's Encrypt) SSL certificate sytles:
* [x] single domains
* [x] multiple domains (SANs, AltNames)
* [x] wildcards
* [x] private / localhost domains
- [x] single domains
- [x] multiple domains (SANs, AltNames)
- [x] wildcards
- [x] private / localhost domains
# Usage
**Global** config:
```js
var greenlock = require('greenlock');
var gl = greenlock.create({
configDir: '~/.config/acme'
, store: require('greenlock-store-fs')
, approveDomains: approveDomains
, ...
greenlock.manager.defaults({
store: {
module: "greenlock-store-fs",
basePath: "~/.config/greenlock"
}
});
```
**Per-site** config:
```js
greenlock.add({
subject: "example.com",
altnames: ["example.com", "www.example.com"],
store: {
module: "greenlock-store-fs",
basePath: "~/.config/greenlock"
}
});
```
# File System
The default file system layout mirrors that of le-store-certbot in order to make transitioning effortless,
in most situations:
The default file system layout mirrors that of certbot (python Let's Encrypt implementation) and
the prior le-store-certbot in order to make transitioning effortless.
```
acme
The default structure looks like this:
```txt
.config
└── greenlock
├── accounts
│   └── acme-staging-v02.api.letsencrypt.org
│   └── directory
│   └── sites@example.com.json
├── staging
│ └── (same as live)
└── live
├── example.com
│   ├── bundle.pem
@ -47,72 +67,125 @@ acme
└── privkey.pem
```
# Wildcards & AltNames
# Internal Implementation Details
Working with wildcards and multiple altnames requires greenlock >= v2.7 (or v3).
You **DO NOT NEED TO KNOW** these details.
To do so you must return `{ subject: '...', altnames: ['...', ...] }` within the `approveDomains()` callback.
They're provided for the sake of understanding what happens "under the hood"
to help you make better choices "in the seat".
`subject` refers to "the subject of the ssl certificate" as opposed to `domain` which indicates "the domain servername
used in the current request". For single-domain certificates they're always the same, but for multiple-domain
certificates `subject` must be the name no matter what `domain` is receiving a request. `subject` is used as
part of the name of the file storage path where the certificate will be saved (or retrieved).
# Parameters
`altnames` should be the list of SubjectAlternativeNames (SANs) on the certificate.
The subject and the first altname must be an exact match: `subject === altnames[0]`.
| parameters | example | notes |
| ----------------- | -------------------------------------------------------- | ---------------- |
| `env` | `staging` or `live` | - |
| `directoryUrl` | `https://acme-staging-v02.api.letsencrypt.org/directory` | - |
| `keypair` | `{ privateKeyPem, privateKeyJwk }` | |
| `account` | `{ id: "an-arbitrary-id" }` | account only |
| `subscriberEmail` | `webhost@example.com` | account only |
| `certificate` | `{ id: "an-arbitrary-id" }` | certificate only |
| `subject` | `example.com` | certificate only |
| `pems` | `{ privkey, cert, chain, issuedAt, expiresAt }` | certificate only |
## Simple Example
### Account Keypair
```js
function approveDomains(opts) {
// Allow only example.com and *.example.com (such as foo.example.com)
// foo.example.com => *.example.com
var wild = '*.' + opts.domain.split('.').slice(1).join('.');
if ('example.com' !== opts.domain && '*.example.com' !== wild) {
cb(new Error(opts.domain + " is not allowed"));
}
var result = { subject: 'example.com', altnames: [ 'example.com', '*.example.com' ] };
return Promise.resolve(result);
}
```
## Realistic Example
```js
function approveDomains(opts, certs, cb) {
var related = getRelated(opts.domain);
if (!related) { cb(new Error(opts.domain + " is not allowed")); };
opts.subject = related.subject;
opts.domains = related.domains;
cb({ options: opts, certs: certs });
}
accounts.setKeypair = async function({
env,
basePath,
directoryUrl,
email,
account
}) {
var id = account.id || email;
var serverDir = directoryUrl.replace("https://", "");
};
```
```js
function getRelated(domain) {
var related;
var wild = '*.' + domain.split('.').slice(1).join('.');
if (Object.keys(allAllowedDomains).some(function (k) {
return allAllowedDomains[k].some(function (name) {
if (domain === name || wild === name) {
related = { subject: k, altnames: allAllowedDomains[k] };
return true;
}
});
})) {
return related;
}
}
accounts.checkKeypair = async function({
env,
basePath,
directoryUrl,
email,
account
}) {
var id = account.id || email;
var serverDir = directoryUrl.replace("https://", "");
return {
privateKeyPem,
privateKeyJwk
};
};
```
### Certificate Keypair
```js
certificate.setKeypair = async function({
env,
basePath,
directoryUrl,
subject,
certificate
}) {
var id = account.id || email;
env = env || directoryUrl.replace("https://", "");
};
```
```js
var allAllowedDomains = {
'example.com': ['example.com', '*.example.com']
, 'example.net': ['example.net', '*.example.net']
}
certificate.checkKeypair = async function({
env,
basePath,
directoryUrl,
subject,
certificate
}) {
var id = account.id || email;
env = env || directoryUrl.replace("https://", "");
return {
privateKeyPem,
privateKeyJwk
};
};
```
### Certificate PEMs
```js
certificate.set = async function({
env,
basePath,
directoryUrl,
subject,
certificate,
pems
}) {
var id = account.id || email;
env = env || directoryUrl.replace("https://", "");
};
```
```js
certificate.check = async function({
env,
basePath,
directoryUrl,
subject,
certificate
}) {
var id = account.id || email;
env = env || directoryUrl.replace("https://", "");
return {
privkey,
cert,
chain,
issuedAt,
expiresAt
};
};
```

View File

@ -1,15 +1,15 @@
'use strict';
"use strict";
var accounts = module.exports;
var store = accounts;
var U = require('./utils.js');
var U = require("./utils.js");
var fs = require('fs');
var path = require('path');
var PromiseA = require('./promise.js');
var fs = require("fs");
var path = require("path");
var PromiseA = require("./promise.js");
var readFileAsync = PromiseA.promisify(fs.readFile);
var writeFileAsync = PromiseA.promisify(fs.writeFile);
var mkdirpAsync = PromiseA.promisify(require('@root/mkdirp'));
var mkdirpAsync = PromiseA.promisify(require("@root/mkdirp"));
// Implement if you need the ACME account metadata elsewhere in the chain of events
//store.accounts.check = function (opts) {
@ -25,14 +25,14 @@ accounts.checkKeypair = function(opts) {
var id =
(opts.account && opts.account.id) ||
(opts.subscriberEmail || opts.email) ||
'single-user';
"single-user";
//console.log('accounts.checkKeypair for', id);
var pathname = path.join(
accountsDir(store, opts),
sanitizeFilename(id) + '.json'
sanitizeFilename(id) + ".json"
);
return readFileAsync(U._tameWild(pathname, opts.subject), 'utf8')
return readFileAsync(U._tameWild(pathname, opts.subject), "utf8")
.then(function(blob) {
// keypair can treated as an opaque object and just passed along,
// but just to show you what it is...
@ -48,7 +48,7 @@ accounts.checkKeypair = function(opts) {
*/
})
.catch(function(err) {
if ('ENOENT' === err.code) {
if ("ENOENT" === err.code) {
return null;
}
throw err;
@ -61,7 +61,7 @@ accounts.checkKeypair = function(opts) {
// Return null (not undefined) on success, or throw on error
accounts.setKeypair = function(opts) {
//console.log('accounts.setKeypair for', opts.account, opts.email, opts.keypair);
var id = opts.account.id || opts.email || 'single-user';
var id = opts.account.id || opts.email || "single-user";
// you can just treat the keypair as opaque and save and retrieve it as JSON
var keyblob = JSON.stringify(opts.keypair);
@ -79,12 +79,12 @@ accounts.setKeypair = function(opts) {
.then(function() {
var pathname = path.join(
accountsDir(store, opts),
sanitizeFilename(id) + '.json'
sanitizeFilename(id) + ".json"
);
return writeFileAsync(
U._tameWild(pathname, opts.subject),
keyblob,
'utf8'
"utf8"
);
})
.then(function() {
@ -100,7 +100,7 @@ accounts.setKeypair = function(opts) {
//};
function sanitizeFilename(id) {
return id.replace(/(\.\.)|\\|\//g, '_').replace(/[^!-~]/g, '_');
return id.replace(/(\.\.)|\\|\//g, "_").replace(/[^!-~]/g, "_");
}
function accountsDir(store, opts) {
@ -109,5 +109,5 @@ function accountsDir(store, opts) {
opts,
opts.accountsDir || store.options.accountsDir
);
return U._tameWild(dir, opts.subject || '');
return U._tameWild(dir, opts.subject || "");
}

View File

@ -1,23 +1,23 @@
'use strict';
"use strict";
var certificates = module.exports;
var store = certificates;
var U = require('./utils.js');
var U = require("./utils.js");
var fs = require('fs');
var path = require('path');
var PromiseA = require('./promise.js');
var sfs = require('safe-replace');
var fs = require("fs");
var path = require("path");
var PromiseA = require("./promise.js");
var sfs = require("safe-replace");
var readFileAsync = PromiseA.promisify(fs.readFile);
var writeFileAsync = PromiseA.promisify(fs.writeFile);
var mkdirpAsync = PromiseA.promisify(require('@root/mkdirp'));
var mkdirpAsync = PromiseA.promisify(require("@root/mkdirp"));
// Certificates.check
//
// Use certificate.id, or subject, if id hasn't been set, to find a certificate.
// Return an object with string PEMs for cert and chain (or null, not undefined)
certificates.check = function(opts) {
// { certificate.id, subject, ... }
// { directoryUrl, subject, certificate.id, ... }
var id = (opts.certificate && opts.certificate.id) || opts.subject;
//console.log('certificates.check for', opts);
@ -25,7 +25,7 @@ certificates.check = function(opts) {
// This just goes to show that any options set in approveDomains() will be available here
// (the same is true for all of the hooks in this file)
if (opts.exampleThrowError) {
return Promise.reject(new Error('You want an error? You got it!'));
return Promise.reject(new Error("You want an error? You got it!"));
}
if (opts.exampleReturnNull) {
return Promise.resolve(null);
@ -35,9 +35,9 @@ certificates.check = function(opts) {
}
return Promise.all([
readFileAsync(U._tameWild(privkeyPath(store, opts), id), 'ascii'), // 0 // all other PEM types are just
readFileAsync(U._tameWild(certPath(store, opts), id), 'ascii'), // 1 // some arrangement of these 3
readFileAsync(U._tameWild(chainPath(store, opts), id), 'ascii') // 2 // (bundle, combined, fullchain, etc)
readFileAsync(U._tameWild(privkeyPath(store, opts), id), "ascii"), // 0 // all other PEM types are just
readFileAsync(U._tameWild(certPath(store, opts), id), "ascii"), // 1 // some arrangement of these 3
readFileAsync(U._tameWild(chainPath(store, opts), id), "ascii") // 2 // (bundle, combined, fullchain, etc)
])
.then(function(all) {
////////////////////////
@ -60,7 +60,7 @@ certificates.check = function(opts) {
})
.catch(function(err) {
// Treat non-exceptional failures as null returns (not undefined)
if ('ENOENT' === err.code) {
if ("ENOENT" === err.code) {
return null;
}
throw err; // True exceptions should be thrown
@ -76,7 +76,7 @@ certificates.checkKeypair = function(opts) {
return readFileAsync(
U._tameWild(privkeyPath(store, opts), opts.subject),
'ascii'
"ascii"
)
.then(function(key) {
////////////////////////
@ -88,7 +88,7 @@ certificates.checkKeypair = function(opts) {
};
})
.catch(function(err) {
if ('ENOENT' === err.code) {
if ("ENOENT" === err.code) {
return null;
}
throw err;
@ -111,7 +111,7 @@ certificates.setKeypair = function(opts) {
return writeFileAsync(
U._tameWild(privkeyPath(store, opts), opts.subject),
keypair.privateKeyPem,
'ascii'
"ascii"
).then(function() {
return null;
});
@ -148,14 +148,14 @@ certificates.set = function(opts) {
)
).then(function() {
var fullchainPem = [
pems.cert.trim() + '\n',
pems.chain.trim() + '\n'
].join('\n'); // for Apache, Nginx, etc
pems.cert.trim() + "\n",
pems.chain.trim() + "\n"
].join("\n"); // for Apache, Nginx, etc
var bundlePem = [
pems.privkey,
pems.cert,
pems.chain
].join('\n'); // for HAProxy
].join("\n"); // for HAProxy
return PromiseA.all([
sfs.writeFileAsync(
U._tameWild(
@ -163,7 +163,7 @@ certificates.set = function(opts) {
opts.subject
),
pems.cert,
'ascii'
"ascii"
),
sfs.writeFileAsync(
U._tameWild(
@ -171,7 +171,7 @@ certificates.set = function(opts) {
opts.subject
),
pems.chain,
'ascii'
"ascii"
),
// Most web servers need these two
sfs.writeFileAsync(
@ -180,7 +180,7 @@ certificates.set = function(opts) {
opts.subject
),
fullchainPem,
'ascii'
"ascii"
),
// HAProxy needs "bundle.pem" aka "combined.pem"
sfs.writeFileAsync(
@ -189,7 +189,7 @@ certificates.set = function(opts) {
opts.subject
),
bundlePem,
'ascii'
"ascii"
)
]);
});
@ -203,7 +203,7 @@ certificates.set = function(opts) {
};
function liveDir(store, opts) {
return opts.liveDir || path.join(opts.configDir, 'live', opts.subject);
return opts.liveDir || path.join(opts.configDir, "live", opts.subject);
}
function privkeyPath(store, opts) {
@ -216,19 +216,19 @@ function privkeyPath(store, opts) {
store.options.serverKeyPath ||
store.options.privkeyPath ||
store.options.domainKeyPath ||
path.join(liveDir(), 'privkey.pem')
path.join(liveDir(), "privkey.pem")
);
return U._tameWild(dir, opts.subject || '');
return U._tameWild(dir, opts.subject || "");
}
function certPath(store, opts) {
var pathname =
opts.certPath ||
store.options.certPath ||
path.join(liveDir(), 'cert.pem');
path.join(liveDir(), "cert.pem");
var dir = U._tpl(store, opts, pathname);
return U._tameWild(dir, opts.subject || '');
return U._tameWild(dir, opts.subject || "");
}
function fullchainPath(store, opts) {
@ -237,9 +237,9 @@ function fullchainPath(store, opts) {
opts,
opts.fullchainPath ||
store.options.fullchainPath ||
path.join(liveDir(), 'fullchain.pem')
path.join(liveDir(), "fullchain.pem")
);
return U._tameWild(dir, opts.subject || '');
return U._tameWild(dir, opts.subject || "");
}
function chainPath(store, opts) {
@ -248,9 +248,9 @@ function chainPath(store, opts) {
opts,
opts.chainPath ||
store.options.chainPath ||
path.join(liveDir(), 'chain.pem')
path.join(liveDir(), "chain.pem")
);
return U._tameWild(dir, opts.subject || '');
return U._tameWild(dir, opts.subject || "");
}
function bundlePath(store, opts) {
@ -259,7 +259,7 @@ function bundlePath(store, opts) {
opts,
opts.bundlePath ||
store.options.bundlePath ||
path.join(liveDir(), 'bundle.pem')
path.join(liveDir(), "bundle.pem")
);
return U._tameWild(dir, opts.subject || '');
return U._tameWild(dir, opts.subject || "");
}

View File

@ -1,7 +1,7 @@
'use strict';
"use strict";
var os = require('os');
var path = require('path');
var os = require("os");
var path = require("path");
// How Storage Works in Greenlock: High-Level Call Stack
//
@ -56,8 +56,8 @@ module.exports.create = function(config) {
// basic setup
var store = {
accounts: require('./accounts.js'),
certificates: require('./certificates.js')
accounts: require("./accounts.js"),
certificates: require("./certificates.js")
};
// For you store.options should probably start empty and get a minimal set of options copied from `config` above.
@ -72,7 +72,7 @@ module.exports.create = function(config) {
store.certificates.options = store.options;
if (!config.basePath && !config.configDir) {
console.info('Greenlock Store FS Path:', store.options.configDir);
console.info("Greenlock Store FS Path:", store.options.configDir);
}
return store;
@ -84,20 +84,20 @@ module.exports.create = function(config) {
//
// Everything below this line is just implementation specific
var defaults = {
basePath: path.join(os.homedir(), '.config', 'greenlock'),
basePath: path.join(os.homedir(), ".config", "greenlock"),
accountsDir: path.join(':basePath', 'accounts', ':directoryUrl'),
accountsDir: path.join(":basePath", "accounts", ":directoryUrl"),
serverDirGet: function(copy) {
return (copy.directoryUrl || copy.server || '')
.replace('https://', '')
.replace(/(\/)$/, '')
return (copy.directoryUrl || copy.server || "")
.replace("https://", "")
.replace(/(\/)$/, "")
.replace(/\//g, path.sep);
},
privkeyPath: path.join(':basePath', ':env', ':subject', 'privkey.pem'),
fullchainPath: path.join(':basePath', ':env', ':subject', 'fullchain.pem'),
certPath: path.join(':basePath', ':env', ':subject', 'cert.pem'),
chainPath: path.join(':basePath', ':env', ':subject', 'chain.pem'),
bundlePath: path.join(':basePath', ':env', ':subject', 'bundle.pem')
privkeyPath: path.join(":basePath", ":env", ":subject", "privkey.pem"),
fullchainPath: path.join(":basePath", ":env", ":subject", "fullchain.pem"),
certPath: path.join(":basePath", ":env", ":subject", "cert.pem"),
chainPath: path.join(":basePath", ":env", ":subject", "chain.pem"),
bundlePath: path.join(":basePath", ":env", ":subject", "bundle.pem")
};
defaults.configDir = defaults.basePath;

2
package-lock.json generated
View File

@ -1,6 +1,6 @@
{
"name": "greenlock-store-fs",
"version": "3.0.1",
"version": "3.2.0",
"lockfileVersion": 1,
"requires": true,
"dependencies": {

View File

@ -1,6 +1,6 @@
{
"name": "greenlock-store-fs",
"version": "3.2.0",
"version": "3.2.2",
"description": "A file-based certificate store for greenlock that supports wildcards.",
"homepage": "https://git.rootprojects.org/root/greenlock-store-fs.js",
"main": "index.js",

View File

@ -1,17 +1,17 @@
'use strict';
"use strict";
function getPromise() {
var util = require('util');
var util = require("util");
var PromiseA;
if (util.promisify && global.Promise) {
PromiseA = global.Promise;
PromiseA.promisify = util.promisify;
} else {
try {
PromiseA = require('bluebird');
PromiseA = require("bluebird");
} catch (e) {
console.error(
'Your version of node is missing Promise. Please run `npm install --save bluebird` in your project to fix'
"Your version of node is missing Promise. Please run `npm install --save bluebird` in your project to fix"
);
process.exit(10);
}

42
test.js
View File

@ -1,26 +1,32 @@
'use strict';
"use strict";
var tester = require('greenlock-store-test');
var tester = require("greenlock-store-test");
var crypto = require('crypto');
var os = require('os');
var path = require('path');
var basedir = path.join(os.tmpdir(), 'greenlock-store-fs-test-' + crypto.randomBytes(4).toString('hex'));
var domain = '*.example.com';
var store = require('./').create({
configDir: basedir
, accountsDir: path.join(basedir, 'accounts')
, privkeyPath: path.join(basedir, 'live', domain, 'privkey.pem')
, fullchainPath: path.join(basedir, 'live', domain, 'fullchain.pem')
, certPath: path.join(basedir, 'live', domain, 'cert.pem')
, chainPath: path.join(basedir, 'live', domain, 'chain.pem')
, bundlePath: path.join(basedir, 'live', domain, 'bundle.pem')
var crypto = require("crypto");
var os = require("os");
var path = require("path");
var basedir = path.join(
os.tmpdir(),
"greenlock-store-fs-test-" + crypto.randomBytes(4).toString("hex")
);
var domain = "*.example.com";
var store = require("./").create({
configDir: basedir,
accountsDir: path.join(basedir, "accounts"),
privkeyPath: path.join(basedir, "live", domain, "privkey.pem"),
fullchainPath: path.join(basedir, "live", domain, "fullchain.pem"),
certPath: path.join(basedir, "live", domain, "cert.pem"),
chainPath: path.join(basedir, "live", domain, "chain.pem"),
bundlePath: path.join(basedir, "live", domain, "bundle.pem")
});
console.info('Test Dir:', basedir);
console.info("Test Dir:", basedir);
tester.test(store).then(function () {
tester
.test(store)
.then(function() {
console.info("PASS");
}).catch(function (err) {
})
.catch(function(err) {
console.error("FAIL");
console.error(err);
process.exit(20);

View File

@ -1,4 +1,4 @@
'use strict';
"use strict";
var U = module.exports;
@ -7,43 +7,43 @@ U._tameWild = function tameWild(pathname, wild) {
if (!wild) {
return pathname;
}
var tame = wild.replace(/\*/g, '_');
var tame = wild.replace(/\*/g, "_");
return pathname.replace(wild, tame);
};
U._tpl = function tpl(store, opts, str) {
var server = ['directoryUrl', 'serverDir', 'server'];
var env = ['env', 'directoryUrl'];
var server = ["directoryUrl", "serverDir", "server"];
var env = ["env", "directoryUrl"];
[
['basePath', 'configDir'],
["basePath", "configDir"],
server,
['subject', 'hostname', 'domain'],
["subject", "hostname", "domain"],
env
].forEach(function(group) {
group.forEach(function(tmpl) {
group.forEach(function(key) {
var item = opts[key] || store.options[key];
if ('string' !== typeof item) {
if ("string" !== typeof item) {
return;
}
if ('directoryUrl' === key) {
item = item.replace(/^https?:\/\//i, '');
if ("directoryUrl" === key) {
item = item.replace(/^https?:\/\//i, "");
}
if ('env' === tmpl) {
if ("env" === tmpl) {
if (/staging/.test(item)) {
item = 'staging';
item = "staging";
} else if (/acme-v02/.test(item)) {
item = 'live';
item = "live";
} else {
// item = item;
}
}
if (-1 === str.indexOf(':' + tmpl)) {
if (-1 === str.indexOf(":" + tmpl)) {
return;
}
str = str.replace(':' + tmpl, item);
str = str.replace(":" + tmpl, item);
});
});
});