diff --git a/api/helpers/agent/sign-csr.js b/api/helpers/agent/sign-csr.js index fe548bb..6e887df 100644 --- a/api/helpers/agent/sign-csr.js +++ b/api/helpers/agent/sign-csr.js @@ -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. @@ -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}) { @@ -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'; diff --git a/api/lib/agent-pki.js b/api/lib/agent-pki.js index 4cdc552..2a2f91e 100644 --- a/api/lib/agent-pki.js +++ b/api/lib/agent-pki.js @@ -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}; diff --git a/docs/install.md b/docs/install.md index 6150024..dbadd4d 100644 --- a/docs/install.md +++ b/docs/install.md @@ -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 diff --git a/test/helpers/agent-pki.test.js b/test/helpers/agent-pki.test.js index eba102c..383f942 100644 --- a/test/helpers/agent-pki.test.js +++ b/test/helpers/agent-pki.test.js @@ -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 @@ -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); })); }); diff --git a/test/support/pki.js b/test/support/pki.js index b7bb8d6..a5f6354 100644 --- a/test/support/pki.js +++ b/test/support/pki.js @@ -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 @@ -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; }; @@ -57,4 +78,4 @@ const copy = (dir) => { return to; }; -module.exports = {fixture, foreign, useFixture, copy}; +module.exports = {fixture, foreign, useFixture, copy, rootOf, setRoot}; diff --git a/tools/setup/dev.js b/tools/setup/dev.js index c52829b..5a455af 100644 --- a/tools/setup/dev.js +++ b/tools/setup/dev.js @@ -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}`); diff --git a/tools/setup/index.js b/tools/setup/index.js index 60e2019..0b8b4fb 100644 --- a/tools/setup/index.js +++ b/tools/setup/index.js @@ -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 diff --git a/tools/setup/pki.js b/tools/setup/pki.js index 658cb42..3f33775 100644 --- a/tools/setup/pki.js +++ b/tools/setup/pki.js @@ -88,6 +88,13 @@ const writeCert = (file, pem) => fs.writeFileSync(file, pem.endsWith('\n') ? pem // UTC YYYYMMDDHHMMSS: the suffix of a file that a new one replaces. const stamp = () => new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14); +const {fingerprintOf, ROOT_SETTING, ROOT_SETTING_DESCRIPTION} = shared; + +// An error that the setup tools recognize by its code. +const rootError = (code, message) => Object.assign(new Error(message), {code}); +// Is it one of the two guard errors? The tools print its message and stop. +const isRootError = (err) => Boolean(err) && (err.code === 'E_AGENT_ROOT_MISSING' || err.code === 'E_AGENT_ROOT_MISMATCH'); + /** * Make the CA files that are missing. As 1.6: a certificate file is what * "exists" means. @@ -99,10 +106,25 @@ const stamp = () => new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14); * suffix first. A re-mint with root.key missing throws. * - agent-ca-bundle.pem is brought up to date on every call. It is written * only when its text differs, so a second call changes no file. + * - opts.expectedRoot (a fingerprint256 string) guards the root. A missing + * root.pem throws E_AGENT_ROOT_MISSING, and a root.pem with another + * fingerprint throws E_AGENT_ROOT_MISMATCH. Both throw before any file is + * written. Without it, the rules above apply unchanged. + * Returns {rootFingerprint}, the fingerprint of root.pem after the call. */ -const ensurePki = async (dir) => { - fs.mkdirSync(dir, {recursive: true, mode: 0o700}); +const ensurePki = async (dir, opts = {}) => { + const {expectedRoot} = opts; const f = (name) => path.join(dir, name); + if (expectedRoot) { + if (!exists(f('root.pem'))) { + throw rootError('E_AGENT_ROOT_MISSING', `The agent root ${f('root.pem')} is missing, but the database records the root ${expectedRoot}.`); + } + const onDisk = fingerprintOf(fs.readFileSync(f('root.pem'), 'utf8')); + if (onDisk !== expectedRoot) { + throw rootError('E_AGENT_ROOT_MISMATCH', `The agent root ${f('root.pem')} has the fingerprint ${onDisk}, but the database records the root ${expectedRoot}.`); + } + } + fs.mkdirSync(dir, {recursive: true, mode: 0o700}); if (!exists(f('root.pem'))) { if (exists(f('root.key'))) fs.renameSync(f('root.key'), f(`root.key.${stamp()}`)); @@ -130,6 +152,51 @@ const ensurePki = async (dir) => { if (!exists(f('agent-ca-bundle.pem')) || fs.readFileSync(f('agent-ca-bundle.pem'), 'utf8') !== bundle) { writeCert(f('agent-ca-bundle.pem'), bundle); } + return {rootFingerprint: fingerprintOf(rootPem)}; +}; + +/** + * The setup step for the agent CAs. It records the root fingerprint in the + * Setting ROOT_SETTING (api/lib/agent-pki.js) and refuses another root while it is set. + * - settings: the Setting model. log: a function for the printed lines. + * - newRoot: true after --new-agent-root. With a recorded root, the four CA + * files that exist get a timestamp suffix, so ensurePki makes new CAs. + * - command: 'setup' or 'setup:dev', the npm script that the messages name. + * Returns {rootFingerprint}. A refusal throws an error that keeps its code + * (E_AGENT_ROOT_MISSING or E_AGENT_ROOT_MISMATCH) and has the full message. + */ +const setupPki = async ({pkiDir, newRoot, settings, log, command}) => { + const record = await settings.findOne({name: ROOT_SETTING}); + const recorded = record ? record.value : undefined; + const replace = Boolean(newRoot && recorded); + + if (replace) { + const suffix = stamp(); + for (const name of ['root.pem', 'root.key', 'agent-ca.pem', 'agent-ca.key']) { + const file = path.join(pkiDir, name); + if (exists(file)) fs.renameSync(file, `${file}.${suffix}`); + } + } + + let result; + try { + result = await ensurePki(pkiDir, {expectedRoot: replace ? undefined : recorded}); + } catch (err) { + if (!isRootError(err)) throw err; + throw rootError(err.code, `${err.message}\n` + + `Restore the pki folder from your backup to ${pkiDir}, then run setup again.\n` + + 'To start over with a new root on purpose (every enrolled agent must then be re-enrolled by hand), ' + + `run: npm run ${command} -- --new-agent-root`); + } + + if (replace) log('A new agent root was made. Every enrolled fog-agent must be re-enrolled with the new ca.cert.pem.'); + + if (record) { + await settings.updateOne({name: ROOT_SETTING}).set({value: result.rootFingerprint}); + } else { + await settings.create({name: ROOT_SETTING, description: ROOT_SETTING_DESCRIPTION, value: result.rootFingerprint}); + } + return result; }; /** @@ -146,4 +213,4 @@ const overrideDir = (appPath) => { // The folder the setup tools use: the local.js override, else /pki as config/custom.js. const pkiDirFor = (appPath) => overrideDir(appPath) || path.join(appPath, 'pki'); -module.exports = {ensurePki, overrideDir, pkiDirFor}; +module.exports = {ensurePki, setupPki, isRootError, overrideDir, pkiDirFor};