Skip to content

A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.

4.9 KB
Raw Blame
import {
	sealBlob,
	openBlob,
	parseHeader,
	encodeHeader,
	BlobDecryptError,
	ARGON2_DEFAULTS,
	KDF_LIMITS,
	MAGIC,
	FORMAT_VERSION,
} from '../../../src/utils/selfBackup/blobFormat';

// No mocks: this module imports only node:crypto, by design.

const PASSWORD = 'correct horse battery staple';
const PAYLOAD = Buffer.from('a pretend tar payload with some bytes in it');

// argon2id at m=64MB is ~110ms per derivation, and most cases here derive twice.
jest.setTimeout(30000);

describe('blobFormat', () => {
	it('round-trips a payload through seal -> open', () => {
		const blob = sealBlob(PAYLOAD, PASSWORD);
		expect(openBlob(blob, PASSWORD)).toEqual(PAYLOAD);
	});

	it('produces a different blob each time (fresh salt and nonce)', () => {
		expect(sealBlob(PAYLOAD, PASSWORD).equals(sealBlob(PAYLOAD, PASSWORD))).toBe(false);
	});

	it('throws on the wrong key rather than returning garbage', () => {
		const blob = sealBlob(PAYLOAD, PASSWORD);
		expect(() => openBlob(blob, 'wrong-password')).toThrow(BlobDecryptError);
	});

	it('rejects a bad magic', () => {
		const blob = sealBlob(PAYLOAD, PASSWORD);
		blob.write('XXXX', 0, 4, 'ascii');
		expect(() => parseHeader(blob)).toThrow(/Not a Pluton backup blob/);
	});

	it('rejects an unknown format version', () => {
		const blob = sealBlob(PAYLOAD, PASSWORD);
		blob.writeUInt16BE(FORMAT_VERSION + 1, 4);
		expect(() => parseHeader(blob)).toThrow(/Unsupported blob format version/);
	});

	it('rejects a file too small to be a blob', () => {
		expect(() => parseHeader(Buffer.from('PLBK'))).toThrow(/too small/);
	});

	it('throws when a ciphertext byte is flipped', () => {
		const blob = sealBlob(PAYLOAD, PASSWORD);
		const { bodyOffset } = parseHeader(blob);
		blob[bodyOffset] ^= 0xff;
		expect(() => openBlob(blob, PASSWORD)).toThrow(BlobDecryptError);
	});

	it('throws when the auth tag is tampered with', () => {
		const blob = sealBlob(PAYLOAD, PASSWORD);
		blob[blob.length - 1] ^= 0xff;
		expect(() => openBlob(blob, PASSWORD)).toThrow(BlobDecryptError);
	});

	it('carries the kdf params in the header so a future KDF swap stays readable', () => {
		const blob = sealBlob(PAYLOAD, PASSWORD);
		const header = parseHeader(blob);
		expect(header.kdf).toEqual(ARGON2_DEFAULTS);
		expect(header.version).toBe(FORMAT_VERSION);
		expect(blob.toString('ascii', 0, 4)).toBe(MAGIC);
	});

	it('opens a blob using the params recorded in its header, not the current defaults', () => {
		const weakKdf = { memory: 8192, passes: 1, parallelism: 1 };
		const blob = sealBlob(PAYLOAD, PASSWORD, weakKdf);
		expect(parseHeader(blob).kdf).toEqual(weakKdf);
		expect(openBlob(blob, PASSWORD)).toEqual(PAYLOAD);
	});

	describe('kdf params from an untrusted header', () => {
		// The header is plaintext AND unauthenticated: it must be read, and the key derived from
		// it, before there is a key with which to check the GCM tag. So on any blob the user did
		// not write -- and --restore-pluton accepts an arbitrary file -- these are attacker
		// controlled, and act before there is anything to authenticate.
		const withKdfParam = (offset: number, value: number): Buffer => {
			const blob = sealBlob(PAYLOAD, PASSWORD);
			blob.writeUInt32BE(value, offset);
			return blob;
		};
		const MEMORY_OFFSET = 6;
		const PASSES_OFFSET = 10;
		const PARALLELISM_OFFSET = 14;

		it('refuses an absurd memory cost instead of asking argon2 for 4 TiB', () => {
			expect(() => parseHeader(withKdfParam(MEMORY_OFFSET, 0xffffffff))).toThrow(
				/unreasonable KDF memory cost/
			);
		});

		it('refuses an absurd pass count instead of hanging forever', () => {
			expect(() => parseHeader(withKdfParam(PASSES_OFFSET, 0xffffffff))).toThrow(
				/unreasonable KDF pass count/
			);
		});

		it('refuses an absurd parallelism', () => {
			expect(() => parseHeader(withKdfParam(PARALLELISM_OFFSET, 0xffffffff))).toThrow(
				/unreasonable KDF parallelism/
			);
		});

		it('refuses zeroed params', () => {
			expect(() => parseHeader(withKdfParam(MEMORY_OFFSET, 0))).toThrow(BlobDecryptError);
			expect(() => parseHeader(withKdfParam(PASSES_OFFSET, 0))).toThrow(BlobDecryptError);
			expect(() => parseHeader(withKdfParam(PARALLELISM_OFFSET, 0))).toThrow(BlobDecryptError);
		});

		it('leaves the defaults, and the limits themselves, comfortably in range', () => {
			// The ceilings must never reject a blob Pluton actually wrote, now or after a
			// params bump.
			expect(() => parseHeader(sealBlob(PAYLOAD, PASSWORD))).not.toThrow();
			expect(ARGON2_DEFAULTS.memory).toBeLessThan(KDF_LIMITS.maxMemory);
			expect(ARGON2_DEFAULTS.passes).toBeLessThan(KDF_LIMITS.maxPasses);
			expect(ARGON2_DEFAULTS.parallelism).toBeLessThan(KDF_LIMITS.maxParallelism);
		});
	});

	it('rejects a salt or nonce of the wrong length', () => {
		expect(() => encodeHeader(ARGON2_DEFAULTS, Buffer.alloc(8), Buffer.alloc(12))).toThrow(
			/salt must be 16 bytes/
		);
		expect(() => encodeHeader(ARGON2_DEFAULTS, Buffer.alloc(16), Buffer.alloc(8))).toThrow(
			/nonce must be 12 bytes/
		);
	});
});