Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions api/helpers/agent/sign-csr.js
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@
* Exits (a caller maps them; the enroll brief maps notConfigured to 503):
* badHostId hostId is not 1 to 10 digits
* badCsr not a CSR, does not parse, or its self-signature fails
* notConfigured a CA file is missing from custom.pkiDir
* notConfigured a CA file is missing from custom.pkiDir, or root.pem is not
* the root that the Setting ROOT_SETTING records
* signFailed the signing failed, or a result does not verify
*
* The CA key is read from custom.pkiDir on each call.
Expand All @@ -37,7 +38,7 @@ module.exports = {
success: {outputType: 'ref', description: '{leafPem, chainPem}'},
badHostId: {description: 'hostId is not 1 to 10 digits.'},
badCsr: {description: 'The CSR is not valid, or its signature does not verify.'},
notConfigured: {description: 'The agent CA files are missing.'},
notConfigured: {description: 'The agent CA files are missing, or the root is not the recorded one.'},
signFailed: {description: 'The signing or its self-check failed.'}
},
fn: async function ({csrPem, hostId}) {
Expand Down Expand Up @@ -66,6 +67,19 @@ module.exports = {
const caPem = read('agent-ca.pem');
const caKeyPem = read('agent-ca.key');

// The root that enrolled agents pin is recorded by setup. Do not sign under
// another root. Unset (an install before the guard): sign as before.
const recorded = await sails.models.setting.findOne({name: pki.ROOT_SETTING});
if (recorded && recorded.value) {
let onDisk;
try {
onDisk = pki.fingerprintOf(rootPem);
} catch (unused) {
throw 'notConfigured';
}
if (onDisk !== recorded.value) throw 'notConfigured';
}

// Do not sign under an agent CA that the root did not issue.
if (!pki.verifies(caPem, rootPem)) throw 'signFailed';

Expand Down
9 changes: 8 additions & 1 deletion api/lib/agent-pki.js
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,11 @@ const verifies = (certPem, issuerPem, leaf) => {
}
};

module.exports = {DAY_MS, CLIENT_AUTH, RSA, isCsrPem, randomSerial, subjectOf, importPair, verifies};
// The Setting that records the root CA that enrolled fog-agents pin.
const ROOT_SETTING = 'FOG_AGENT_ROOT_FINGERPRINT';
const ROOT_SETTING_DESCRIPTION = 'The SHA-256 fingerprint of the root CA that enrolled fog-agents pin. Setup refuses another root while this is set.';

// The fingerprint of a certificate, as Node prints it (colon hex, upper case).
const fingerprintOf = (pem) => new crypto.X509Certificate(pem).fingerprint256;

module.exports = {DAY_MS, CLIENT_AUTH, RSA, ROOT_SETTING, ROOT_SETTING_DESCRIPTION, fingerprintOf, isCsrPem, randomSerial, subjectOf, importPair, verifies};
23 changes: 23 additions & 0 deletions docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,29 @@ encryption key in `config/models.js`, because a new key makes encrypted data
unreadable. It also keeps the existing Administrator account. A re-run does not
change that account's email or password, and the installer says so.

### Agent certificate authority

Setup makes the certificate authority (CA) files for fog-agent in the `pki/`
folder of the application folder. A `custom.pkiDir` in `config/local.js` moves
the folder, and a re-run keeps it. Every enrolled fog-agent pins the root
certificate `pki/root.pem`. Back up the `pki/` folder together with the
database. The `pki/` folder holds the CA keys, so only the user that runs
fog-node may read it.

Setup records the SHA-256 fingerprint of the root in the database, in the
setting `FOG_AGENT_ROOT_FINGERPRINT`. While that setting is set, setup stops if
`pki/root.pem` is missing or is a different root. The error shows the recorded
fingerprint. A reinstall that wipes the application folder causes this. Restore
the `pki/` folder from your backup, then run setup again. Until you do, fog-node
does not sign agent certificates.

To start over with a new root on purpose, run
`npm run setup -- --new-agent-root` (`npm run setup:dev -- --new-agent-root`
for development). Setup renames the four CA files that exist in `pki/`. Each
new name has a timestamp suffix. Setup then makes new CAs. Setup records the new
fingerprint. You must then re-enroll every fog-agent by hand with the new
`ca.cert.pem`.

### Install without prompts

To script an install, put the answers in a JSON file and run
Expand Down
158 changes: 155 additions & 3 deletions test/helpers/agent-pki.test.js
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
const assert = require('assert');
const crypto = require('crypto');
const fs = require('fs');
const os = require('os');
const path = require('path');
const x509 = require('@peculiar/x509');
const {ensurePki} = require('../../tools/setup/pki');
const {DAY_MS} = require('../../api/lib/agent-pki');
const {ensurePki, setupPki} = require('../../tools/setup/pki');
const {DAY_MS, ROOT_SETTING} = require('../../api/lib/agent-pki');
const support = require('../support/pki');

// The fog-agent PKI (the CAs, CSR signing and the key fingerprint), against the
Expand Down Expand Up @@ -249,7 +250,158 @@ N6M/cmtQjgdJ8gIhAOBb4zKxR50Hh3m3NWDCPQK/OG3cmj8QTzCFV8oY7LuI
it('throws signFailed when the agent CA does not verify against the root', () => withCopy(async (dir) => {
const other = await support.foreign();
fs.copyFileSync(path.join(other, 'root.pem'), path.join(dir, 'root.pem'));
assert.strictEqual(await exitOf(sign(CSR_PEM)), 'signFailed');
// The Setting records the foreign root, so the guard passes and the CA check fails.
await support.setRoot(support.rootOf(other));
try {
assert.strictEqual(await exitOf(sign(CSR_PEM)), 'signFailed');
} finally {
await support.setRoot(support.rootOf(fixtureDir()));
}
}));

it('throws notConfigured when root.pem differs from the recorded root', () => withCopy(async (dir) => {
const other = await support.foreign();
fs.copyFileSync(path.join(other, 'root.pem'), path.join(dir, 'root.pem'));
assert.strictEqual(await exitOf(sign(CSR_PEM)), 'notConfigured');
}));

it('signs when the Setting is unset', () => withCopy(async () => {
await support.setRoot(undefined);
try {
const {leafPem} = await sign(CSR_PEM);
assert.ok(new crypto.X509Certificate(leafPem));
} finally {
await support.setRoot(support.rootOf(fixtureDir()));
}
}));
});

describe('root guard::', () => {
const snapshot = (dir) => fs.readdirSync(dir).sort().map((n) => {
const p = path.join(dir, n);
return [n, fs.statSync(p).mtimeMs, fs.readFileSync(p, 'utf8')];
});
const recorded = async () => (await Setting.findOne({name: ROOT_SETTING})).value;
const setup = (pkiDir, extra = {}) => setupPki(Object.assign({
pkiDir, newRoot: false, settings: sails.models.setting, log: () => {}, command: 'setup'
}, extra));
// Run fn with an empty temp folder, then remove it.
const withEmpty = async (fn) => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fog-pki-empty-'));
try {
return await fn(dir);
} finally {
fs.rmSync(dir, {recursive: true, force: true});
}
};
// setupPki writes the Setting, so put the fixture value back after each test.
afterEach(() => support.setRoot(support.rootOf(fixtureDir())));

it('ensurePki with the matching fingerprint changes no file and returns it', () => withCopy(async (dir) => {
const before = snapshot(dir);
const expectedRoot = support.rootOf(dir);
assert.deepStrictEqual(await ensurePki(dir, {expectedRoot}), {rootFingerprint: expectedRoot});
assert.deepStrictEqual(snapshot(dir), before);
}));

it('ensurePki throws E_AGENT_ROOT_MISSING and changes no file when root.pem is gone', () => withCopy(async (dir) => {
const expectedRoot = support.rootOf(dir);
fs.unlinkSync(path.join(dir, 'root.pem'));
const before = snapshot(dir);
await assert.rejects(() => ensurePki(dir, {expectedRoot}), {code: 'E_AGENT_ROOT_MISSING'});
assert.deepStrictEqual(snapshot(dir), before);
}));

it('ensurePki throws E_AGENT_ROOT_MISMATCH and changes no file for another root', () => withCopy(async (dir) => {
const expectedRoot = support.rootOf(dir);
fs.copyFileSync(path.join(await support.foreign(), 'root.pem'), path.join(dir, 'root.pem'));
const before = snapshot(dir);
await assert.rejects(() => ensurePki(dir, {expectedRoot}), {code: 'E_AGENT_ROOT_MISMATCH'});
assert.deepStrictEqual(snapshot(dir), before);
}));

it('ensurePki with no expectedRoot makes the missing root as before', () => withEmpty(async (dir) => {
const {rootFingerprint} = await ensurePki(dir);
assert.strictEqual(rootFingerprint, support.rootOf(dir));
}));

it('setupPki refuses an empty folder while the Setting is set, with the restore message', () => withEmpty(async (dir) => {
const expected = support.rootOf(fixtureDir());
await assert.rejects(() => setup(dir), (err) => {
assert.strictEqual(err.code, 'E_AGENT_ROOT_MISSING');
assert.ok(err.message.includes(expected));
assert.ok(err.message.includes(`Restore the pki folder from your backup to ${dir}, then run setup again.`));
assert.ok(err.message.includes('run: npm run setup -- --new-agent-root'));
assert.ok(err.message.indexOf('Restore the pki') < err.message.indexOf('start over'));
return true;
});
assert.deepStrictEqual(fs.readdirSync(dir), []);
assert.strictEqual(await recorded(), expected);
}));

it('setupPki names setup:dev in its message for command setup:dev', () => withEmpty(async (dir) => {
await assert.rejects(() => setup(dir, {command: 'setup:dev'}), /npm run setup:dev -- --new-agent-root/);
}));

it('setupPki names both fingerprints for a mismatch', () => withCopy(async (dir) => {
fs.copyFileSync(path.join(await support.foreign(), 'root.pem'), path.join(dir, 'root.pem'));
await assert.rejects(() => setup(dir), (err) => {
assert.strictEqual(err.code, 'E_AGENT_ROOT_MISMATCH');
assert.ok(err.message.includes(support.rootOf(fixtureDir())));
assert.ok(err.message.includes(support.rootOf(dir)));
return true;
});
}));

it('setupPki with newRoot on an empty folder makes a root, renames nothing and updates the Setting', () => withEmpty(async (dir) => {
const lines = [];
const {rootFingerprint} = await setup(dir, {newRoot: true, log: (l) => lines.push(l)});
assert.deepStrictEqual(fs.readdirSync(dir).sort(),
['agent-ca-bundle.pem', 'agent-ca.key', 'agent-ca.pem', 'root.key', 'root.pem']);
assert.strictEqual(rootFingerprint, support.rootOf(dir));
assert.notStrictEqual(rootFingerprint, support.rootOf(fixtureDir()));
assert.strictEqual(await recorded(), rootFingerprint);
assert.strictEqual(lines.length, 1);
assert.ok(lines[0].startsWith('A new agent root was made.'));
}));

it('setupPki with newRoot on a full folder renames the four files and makes new CAs', () => withCopy(async (dir) => {
const old = {};
for (const n of ['root.pem', 'root.key', 'agent-ca.pem', 'agent-ca.key']) old[n] = fs.readFileSync(path.join(dir, n), 'utf8');
const {rootFingerprint} = await setup(dir, {newRoot: true});
const names = fs.readdirSync(dir);
for (const n of Object.keys(old)) {
const kept = names.filter((x) => new RegExp(`^${n.replace('.', '\\.')}\\.\\d{14}$`).test(x));
assert.strictEqual(kept.length, 1, n);
assert.strictEqual(fs.readFileSync(path.join(dir, kept[0]), 'utf8'), old[n]);
assert.notStrictEqual(fs.readFileSync(path.join(dir, n), 'utf8'), old[n]);
}
assert.notStrictEqual(rootFingerprint, support.rootOf(fixtureDir()));
assert.strictEqual(await recorded(), rootFingerprint);
assert.ok(cert(path.join(dir, 'agent-ca.pem')).checkIssued(cert(path.join(dir, 'root.pem'))));
}));

it('setupPki with newRoot and no Setting is a plain run: it renames nothing', () => withCopy(async (dir) => {
await support.setRoot(undefined);
const before = snapshot(dir);
await setup(dir, {newRoot: true});
assert.deepStrictEqual(snapshot(dir), before);
assert.strictEqual(await recorded(), support.rootOf(dir));
}));

it('setupPki with no Setting records the root of an existing folder and changes no file', () => withCopy(async (dir) => {
await support.setRoot(undefined);
const before = snapshot(dir);
const {rootFingerprint} = await setup(dir);
assert.deepStrictEqual(snapshot(dir), before);
assert.strictEqual(rootFingerprint, support.rootOf(dir));
assert.strictEqual(await recorded(), rootFingerprint);
}));

it('setupPki on a second run with the Setting set succeeds and changes no file', () => withCopy(async (dir) => {
const before = snapshot(dir);
await setup(dir);
assert.deepStrictEqual(snapshot(dir), before);
}));
});

Expand Down
27 changes: 24 additions & 3 deletions test/support/pki.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ const fs = require('fs');
const os = require('os');
const path = require('path');
const {ensurePki} = require('../../tools/setup/pki');
const {ROOT_SETTING, ROOT_SETTING_DESCRIPTION, fingerprintOf} = require('../../api/lib/agent-pki');

// One PKI for the whole mocha run. RSA-4096 generation is slow, so the tests
// share it. The folder is read-only for the tests: one that deletes, replaces
Expand All @@ -28,17 +29,37 @@ const foreign = () => {
return foreignPki;
};

// The fingerprint of the root in a PKI folder.
const rootOf = (dir) => fingerprintOf(fs.readFileSync(path.join(dir, 'root.pem')));

// Set the root fingerprint Setting to a value, or remove it with undefined.
// An existing record keeps its description; a new one gets the setup text.
const setRoot = async (value) => {
if (value === undefined) return Setting.destroy({name: ROOT_SETTING});
const updated = await Setting.updateOne({name: ROOT_SETTING}).set({value});
if (!updated) await Setting.create({name: ROOT_SETTING, description: ROOT_SETTING_DESCRIPTION, value});
};

// Point sails.config.custom.pkiDir at the shared fixture for one describe
// block, and restore it after. Returns a getter for the fixture path.
// block, and restore it after. The Setting that records the agent root is set
// to the fixture root, and put back as it was (or removed) after. Returns a
// getter for the fixture path.
const useFixture = () => {
let dir;
let saved;
let savedRoot;
before(async () => {
dir = await fixture();
saved = sails.config.custom.pkiDir;
sails.config.custom.pkiDir = dir;
const record = await Setting.findOne({name: ROOT_SETTING});
savedRoot = record ? record.value : undefined;
await setRoot(rootOf(dir));
});
after(async () => {
sails.config.custom.pkiDir = saved;
await setRoot(savedRoot);
});
after(() => { sails.config.custom.pkiDir = saved; });
return () => dir;
};

Expand All @@ -57,4 +78,4 @@ const copy = (dir) => {
return to;
};

module.exports = {fixture, foreign, useFixture, copy};
module.exports = {fixture, foreign, useFixture, copy, rootOf, setRoot};
12 changes: 10 additions & 2 deletions tools/setup/dev.js
Original file line number Diff line number Diff line change
Expand Up @@ -127,9 +127,17 @@ schema.generate(admin.password, admin.email, async (err) => {
process.exit(1);
}
try {
await pki.ensurePki(pkiDir);
// A recorded root that pki/ no longer has stops setup unless --new-agent-root.
await pki.setupPki({
pkiDir,
newRoot: process.argv.includes('--new-agent-root'),
settings: sails.models.setting,
log: console.log,
command: 'setup:dev'
});
} catch (pkiErr) {
console.error(`Failed to make the agent CA files: ${pkiErr.message}`);
// The guard errors carry the full message: print it as is.
console.error(pki.isRootError(pkiErr) ? pkiErr.message : `Failed to make the agent CA files: ${pkiErr.message}`);
process.exit(1);
}
console.log(`Agent CA files are in ${pkiDir}`);
Expand Down
16 changes: 14 additions & 2 deletions tools/setup/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -252,13 +252,25 @@ async.waterfall([
// for a pkiDir override. Files that already exist are left as they are.
(next) => {
header.printSection('Agent certificate authority');
pki.ensurePki(payload.pkiDir).then(
// Sails is loaded by the schema step, so the Setting model is ready. A
// recorded root that pki/ no longer has stops setup unless --new-agent-root.
pki.setupPki({
pkiDir: payload.pkiDir,
newRoot: process.argv.includes('--new-agent-root'),
settings: sails.models.setting,
log: console.log,
command: 'setup'
}).then(
() => {
console.log(`Agent CA files are in ${payload.pkiDir}`);
console.log('The CA keys there must be readable only by the user that runs fog-node.');
next();
},
(err) => next(`Failed to make the agent CA files: ${err && err.message ? err.message : err}`)
(err) => {
// The guard errors carry the full message: show it as is.
if (pki.isRootError(err)) return next(err.message);
next(`Failed to make the agent CA files: ${err && err.message ? err.message : err}`);
}
);
},
// Optional sample/test data -- opt-in (default no), so production installs
Expand Down
Loading
Loading