@hg-ts/rsa 0.7.27 → 0.8.0

package/src/pq-kem/key-pair.ts

@@ -0,0 +1,76 @@
+import Buffer from '@hg-ts/buffer';
+import forge from 'node-forge';
+import {
+	BaseKeyPair,
+	DecapsulatingPrivateKey,
+	EncapsulatingPublicKey,
+	KeyPairOptions,
+	KeyPairResult,
+	NewKeyPairOptions,
+} from '../base/index.js';
+import {
+	DEFAULT_PQ_KEM_ALGORITHM,
+	getPqKemImplementation,
+	type PqKemAlgorithm,
+} from './algorithm.js';
+import { PqKemPrivateKey } from './private-key.js';
+import {
+	PqKemEncapsulation,
+	PqKemPublicKey,
+} from './public-key.js';
+
+export type PqKemKeyPairOptions = KeyPairOptions<PqKemPrivateKey, PqKemAlgorithm>;
+
+export class PqKemKeyPair extends BaseKeyPair<
+	PqKemPrivateKey,
+	PqKemPublicKey,
+	PqKemKeyPairOptions
+> implements EncapsulatingPublicKey, DecapsulatingPrivateKey {
+	public readonly bits: PqKemAlgorithm;
+
+	public constructor(options: PqKemKeyPairOptions = {}) {
+		super(options, PqKemPrivateKey);
+		this.bits = this.privateKeyInstance.bits;
+	}
+
+	public encapsulate(message?: string | Buffer): PqKemEncapsulation {
+		return this.publicKeyInstance.encapsulate(message);
+	}
+
+	public decapsulate(cipherText: string | Buffer): Buffer {
+		return this.privateKeyInstance.decapsulate(cipherText);
+	}
+
+	protected generateNewKeys(options: NewKeyPairOptions<PqKemAlgorithm>): KeyPairResult<
+		PqKemPrivateKey,
+		PqKemPublicKey
+	> {
+		const bits = options.bits ?? DEFAULT_PQ_KEM_ALGORITHM;
+		const implementation = getPqKemImplementation(bits);
+		const keyPair = options.seed
+			? implementation.keygen(this.prepareSeed(options.seed, bits))
+			: implementation.keygen();
+		const privateKey = new PqKemPrivateKey(Buffer.from(keyPair.secretKey), bits);
+
+		return {
+			privateKey,
+			publicKey: new PqKemPublicKey(Buffer.from(keyPair.publicKey), bits),
+		};
+	}
+
+	private prepareSeed(seed: string, bits: PqKemAlgorithm): Buffer {
+		const seedLength = getPqKemImplementation(bits).lengths.seed;
+		const bytes = Buffer.from(seed, 'utf8');
+
+		if (bytes.length === seedLength) {
+			return bytes;
+		}
+
+		const hash = forge.md.sha512.create();
+		hash.update('PQKEM seed', 'utf8');
+		hash.update(bits.toString(), 'utf8');
+		hash.update(bytes.toString('binary'));
+
+		return Buffer.from(hash.digest().getBytes(), 'binary').subarray(0, seedLength);
+	}
+}

package/src/pq-kem/pq-kem.test.ts

@@ -0,0 +1,144 @@
+import Buffer from '@hg-ts/buffer';
+import {
+	Describe,
+	expect,
+	ExpectException,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+import { z } from '@hg-ts/validation';
+
+import {
+	InvalidPqKemKeyLengthException,
+	InvalidPqKemMessageLengthException,
+	getPqKemImplementation,
+	PqKemKeyPair,
+	PqKemPrivateKey,
+	PqKemPublicKey,
+} from '../index.js';
+
+@Describe()
+export class PqKemTest extends Suite {
+	@Test()
+	public async encapsulateAndDecapsulate(): Promise<void> {
+		const recipient = new PqKemKeyPair();
+
+		const encapsulation = recipient.encapsulate();
+		const sharedSecret = recipient.decapsulate(encapsulation.cipherText);
+
+		expect(sharedSecret).toMatchObject(encapsulation.sharedSecret);
+	}
+
+	@Test()
+	public async restoresKeys(): Promise<void> {
+		const keyPair = new PqKemKeyPair({ bits: 1024 });
+
+		const privateKey = PqKemPrivateKey.fromString(keyPair.privateKey);
+		const publicKey = PqKemPublicKey.fromString(keyPair.publicKey);
+
+		expect(privateKey.toString()).toBe(keyPair.privateKey);
+		expect(publicKey.toString()).toBe(keyPair.publicKey);
+	}
+
+	@Test()
+	public async restoresKeyPairFromPrivateKeyString(): Promise<void> {
+		const keyPair = new PqKemKeyPair({ bits: 512 });
+
+		const restored = new PqKemKeyPair({ privateKey: keyPair.privateKey });
+
+		expect(restored.bits).toBe(512);
+		expect(restored.privateKey).toBe(keyPair.privateKey);
+		expect(restored.publicKey).toBe(keyPair.publicKey);
+	}
+
+	@Test()
+	public async decapsulatesBase64CipherText(): Promise<void> {
+		const recipient = new PqKemKeyPair();
+		const encapsulation = recipient.encapsulate();
+
+		const sharedSecret = recipient.privateKeyInstance.decapsulate(
+			encapsulation.cipherText.toString('base64'),
+		);
+
+		expect(sharedSecret).toMatchObject(encapsulation.sharedSecret);
+	}
+
+	@Test()
+	public async encapsulatesWithMessage(): Promise<void> {
+		const recipient = new PqKemKeyPair();
+		const message = Buffer.alloc(getPqKemImplementation(recipient.bits).lengths.msg, 1);
+
+		const encapsulation = recipient.publicKeyInstance.encapsulate(message);
+
+		expect(recipient.decapsulate(encapsulation.cipherText)).toMatchObject(encapsulation.sharedSecret);
+	}
+
+	@Test()
+	public async encapsulatesWithStringMessage(): Promise<void> {
+		const recipient = new PqKemKeyPair();
+		const message = 'a'.repeat(getPqKemImplementation(recipient.bits).lengths.msg);
+
+		const encapsulation = recipient.publicKeyInstance.encapsulate(message);
+
+		expect(recipient.decapsulate(encapsulation.cipherText)).toMatchObject(encapsulation.sharedSecret);
+	}
+
+	@Test()
+	public async seeded(): Promise<void> {
+		const seed = Math.random().toString();
+		const first = new PqKemKeyPair({ seed });
+		const second = new PqKemKeyPair({ seed });
+
+		expect(first.privateKey).toBe(second.privateKey);
+		expect(first.publicKey).toBe(second.publicKey);
+	}
+
+	@Test()
+	public async seededWithExactSeedLength(): Promise<void> {
+		const seed = 'a'.repeat(getPqKemImplementation(768).lengths.seed);
+		const first = new PqKemKeyPair({ seed });
+		const second = new PqKemKeyPair({ seed });
+
+		expect(first.privateKey).toBe(second.privateKey);
+		expect(first.publicKey).toBe(second.publicKey);
+	}
+
+	@Test()
+	public async nativeKeysAreCopied(): Promise<void> {
+		const keyPair = new PqKemKeyPair();
+
+		expect(keyPair.privateKeyInstance.nativeKey).toMatchObject(keyPair.privateKeyInstance.nativeKey);
+		expect(keyPair.publicKeyInstance.nativeKey).toMatchObject(keyPair.publicKeyInstance.nativeKey);
+	}
+
+	@Test()
+	public async publicKeyValidationValid(): Promise<void> {
+		const keyPair = new PqKemKeyPair();
+
+		PqKemPublicKey.schema.parse(keyPair.publicKey);
+	}
+
+	@Test()
+	@ExpectException(z.ZodError)
+	public async publicKeyValidationFails(): Promise<void> {
+		PqKemPublicKey.schema.parse('{}');
+	}
+
+	@Test()
+	@ExpectException(InvalidPqKemMessageLengthException)
+	public async encapsulateFailsForInvalidMessageLength(): Promise<void> {
+		new PqKemKeyPair().encapsulate(Buffer.alloc(31));
+	}
+
+	@Test()
+	@ExpectException(InvalidPqKemKeyLengthException)
+	public async privateKeyFailsForInvalidKeyLength(): Promise<void> {
+		new PqKemPrivateKey(Buffer.alloc(1), 768).toString();
+	}
+
+	@Test()
+	@ExpectException(InvalidPqKemKeyLengthException)
+	public async publicKeyFailsForInvalidKeyLength(): Promise<void> {
+		new PqKemPublicKey(Buffer.alloc(1), 768).toString();
+	}
+}

package/src/pq-kem/private-key.ts

@@ -0,0 +1,67 @@
+import Buffer from '@hg-ts/buffer';
+import {
+	BasePrivateKey,
+	DecapsulatingPrivateKey,
+} from '../base/index.js';
+import { InvalidPqKemKeyLengthException } from '../exceptions/index.js';
+import {
+	getPqKemImplementation,
+	inferPqKemBitsByKeyLength,
+	type PqKemAlgorithm,
+	type PqKemImplementation,
+} from './algorithm.js';
+import { PqKemPublicKey } from './public-key.js';
+
+export class PqKemPrivateKey
+	extends BasePrivateKey<Buffer, PqKemPublicKey>
+	implements DecapsulatingPrivateKey {
+	public readonly bits: PqKemAlgorithm;
+
+	public constructor(key: Buffer, bits: PqKemAlgorithm) {
+		super(key);
+		this.bits = bits;
+		this.validateKey();
+	}
+
+	public decapsulate(cipherText: string | Buffer): Buffer {
+		const value = typeof cipherText === 'string'
+			? Buffer.from(cipherText, 'base64')
+			: cipherText;
+
+		return Buffer.from(this.implementation.decapsulate(value, this.key));
+	}
+
+	public override toPublicKey(): PqKemPublicKey {
+		return new PqKemPublicKey(
+			Buffer.from(this.implementation.getPublicKey(this.key)),
+			this.bits,
+		);
+	}
+
+	public override toString(): string {
+		return this.key.toString('base64');
+	}
+
+	public override get nativeKey(): Buffer {
+		return Buffer.from(this.key);
+	}
+
+	public static fromString(value: string): PqKemPrivateKey {
+		const key = Buffer.from(value, 'base64');
+		const bits = inferPqKemBitsByKeyLength(key.length, 'secretKey');
+
+		return new PqKemPrivateKey(key, bits);
+	}
+
+	private get implementation(): PqKemImplementation {
+		return getPqKemImplementation(this.bits);
+	}
+
+	private validateKey(): void {
+		const { secretKey } = this.implementation.lengths;
+
+		if (this.key.length !== secretKey) {
+			throw new InvalidPqKemKeyLengthException('secretKey', this.key.length);
+		}
+	}
+}

package/src/pq-kem/public-key.ts

@@ -0,0 +1,99 @@
+import Buffer from '@hg-ts/buffer';
+import { z } from '@hg-ts/validation';
+
+import {
+	BasePublicKey,
+	EncapsulatingPublicKey,
+	type KemEncapsulation,
+} from '../base/index.js';
+import {
+	InvalidPqKemKeyLengthException,
+	InvalidPqKemMessageLengthException,
+} from '../exceptions/index.js';
+import {
+	getPqKemImplementation,
+	inferPqKemBitsByKeyLength,
+	type PqKemAlgorithm,
+	type PqKemImplementation,
+} from './algorithm.js';
+
+export type PqKemEncapsulation = KemEncapsulation;
+
+const schema = z.string().transform((value, ctx) => {
+	try {
+		PqKemPublicKey.fromString(value);
+		return value;
+	} catch (error) {
+		ctx.issues.push({
+			message: error instanceof Error ? error.message : 'Invalid PQKEM public key',
+			fatal: true,
+			code: 'invalid_format',
+			input: value,
+			format: 'PQKEM Public Key',
+		});
+		return value;
+	}
+}).pipe(z.string());
+
+export class PqKemPublicKey extends BasePublicKey<Buffer> implements EncapsulatingPublicKey {
+	public readonly bits: PqKemAlgorithm;
+
+	public static schema = schema;
+
+	public constructor(key: Buffer, bits: PqKemAlgorithm) {
+		super(key);
+		this.bits = bits;
+		this.validateKey();
+	}
+
+	public encapsulate(message?: string | Buffer): PqKemEncapsulation {
+		const { cipherText, sharedSecret } = message
+			? this.implementation.encapsulate(this.key, this.prepareMessage(message))
+			: this.implementation.encapsulate(this.key);
+
+		return {
+			cipherText: Buffer.from(cipherText),
+			sharedSecret: Buffer.from(sharedSecret),
+		};
+	}
+
+	public override toString(): string {
+		return this.key.toString('base64');
+	}
+
+	public override get nativeKey(): Buffer {
+		return Buffer.from(this.key);
+	}
+
+	public static fromString(value: string): PqKemPublicKey {
+		const key = Buffer.from(value, 'base64');
+		const bits = inferPqKemBitsByKeyLength(key.length, 'publicKey');
+
+		return new PqKemPublicKey(key, bits);
+	}
+
+	private prepareMessage(message: string | Buffer): Buffer {
+		const value = typeof message === 'string'
+			? Buffer.from(message, 'utf8')
+			: message;
+		const { msg } = this.implementation.lengths;
+
+		if (value.length !== msg) {
+			throw new InvalidPqKemMessageLengthException(msg, value.length);
+		}
+
+		return value;
+	}
+
+	private get implementation(): PqKemImplementation {
+		return getPqKemImplementation(this.bits);
+	}
+
+	private validateKey(): void {
+		const { publicKey } = this.implementation.lengths;
+
+		if (this.key.length !== publicKey) {
+			throw new InvalidPqKemKeyLengthException('publicKey', this.key.length);
+		}
+	}
+}

package/src/rsa/key-pair.ts

@@ -1,31 +1,37 @@
 import forge from 'node-forge';
 import {
 	BaseKeyPair,
+	DecryptingPrivateKey,
+	EncryptingPublicKey,
 	KeyPairOptions,
 	KeyPairResult,
 	NewKeyPairOptions,
+	SigningPrivateKey,
+	VerifyingPublicKey,
 } from '../base/index.js';
 import { RsaPrivateKey } from './private-key.js';
 import { RsaPublicKey } from './public-key.js';
 
-export class RsaKeyPair extends BaseKeyPair<RsaPrivateKey, RsaPublicKey> {
+export class RsaKeyPair
+	extends BaseKeyPair<RsaPrivateKey, RsaPublicKey>
+	implements EncryptingPublicKey, DecryptingPrivateKey, SigningPrivateKey, VerifyingPublicKey {
 	public constructor(options: KeyPairOptions<RsaPrivateKey> = {}) {
 		super(options, RsaPrivateKey);
 	}
 
-	public override encrypt(value: string | Buffer): Buffer {
+	public encrypt(value: string | Buffer): Buffer {
 		return this.publicKeyInstance.encrypt(value);
 	}
 
-	public override decrypt(value: string | Buffer): string {
+	public decrypt(value: string | Buffer): string {
 		return this.privateKeyInstance.decrypt(value);
 	}
 
-	public override sign(value: string): Buffer {
+	public sign(value: string): Buffer {
 		return this.privateKeyInstance.sign(value);
 	}
 
-	public override verify(signature: string | Buffer, value: string): boolean {
+	public verify(signature: string | Buffer, value: string): boolean {
 		return this.publicKeyInstance.verify(signature, value);
 	}
 

package/src/rsa/private-key.ts

@@ -1,9 +1,16 @@
+import Buffer from '@hg-ts/buffer';
 import forge from 'node-forge';
-import { BasePrivateKey } from '../base/index.js';
+import {
+	BasePrivateKey,
+	DecryptingPrivateKey,
+	SigningPrivateKey,
+} from '../base/index.js';
 import { InvalidDecryptionKeyExpection } from '../exceptions/index.js';
 import { RsaPublicKey } from './public-key.js';
 
-export class RsaPrivateKey extends BasePrivateKey<forge.pki.rsa.PrivateKey, RsaPublicKey> {
+export class RsaPrivateKey
+	extends BasePrivateKey<forge.pki.rsa.PrivateKey, RsaPublicKey>
+	implements DecryptingPrivateKey, SigningPrivateKey {
 	public decrypt(encrypted: string | Buffer): string {
 		const md = this.getMd();
 		const chunks = this.prepareToDecrypt(encrypted);

package/src/rsa/public-key.ts

@@ -1,6 +1,11 @@
+import Buffer from '@hg-ts/buffer';
 import { z } from '@hg-ts/validation';
 import forge from 'node-forge';
-import { BasePublicKey } from '../base/index.js';
+import {
+	BasePublicKey,
+	EncryptingPublicKey,
+	VerifyingPublicKey,
+} from '../base/index.js';
 
 const schema = z.string().transform((value, ctx) => {
 	try {
@@ -19,7 +24,9 @@ const schema = z.string().transform((value, ctx) => {
 	}
 }).pipe(z.string());
 
-export class RsaPublicKey extends BasePublicKey<forge.pki.rsa.PublicKey> {
+export class RsaPublicKey
+	extends BasePublicKey<forge.pki.rsa.PublicKey>
+	implements EncryptingPublicKey, VerifyingPublicKey {
 	public static schema = schema;
 
 	public encrypt(value: string | Buffer): Buffer {

package/src/rsa/rsa.test.ts

@@ -1,3 +1,4 @@
+import Buffer from '@hg-ts/buffer';
 import {
 	Describe,
 	expect,

package/src/utils/hkdf.test.ts

@@ -0,0 +1,77 @@
+import Buffer from '@hg-ts/buffer';
+import {
+	Describe,
+	expect,
+	ExpectException,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+import { HkdfOutputLengthException } from '../exceptions/index.js';
+
+import { Hkdf } from './hkdf.js';
+
+@Describe()
+export class HkdfTest extends Suite {
+	@Test()
+	public async rfc5869Sha256CaseOne(): Promise<void> {
+		const inputKeyMaterial = Buffer.alloc(22, 0x0b);
+		const salt = Buffer.from('000102030405060708090a0b0c', 'hex');
+		const info = Buffer.from('f0f1f2f3f4f5f6f7f8f9', 'hex');
+
+		const hkdfInstance = new Hkdf({
+			info,
+			inputKeyMaterial,
+			length: 42,
+			salt,
+		});
+		const pseudorandomKey = hkdfInstance.extract();
+		const outputKeyMaterial = hkdfInstance.getBuffer();
+
+		expect(pseudorandomKey.toString('hex')).toBe(
+			'077709362c2e32df0ddc3f0dc47bba63'
+			+ '90b6c73bb50f9c3122ec844ad7c2b3e5',
+		);
+		expect(outputKeyMaterial.toString('hex')).toBe(
+			'3cb25f25faacd57a90434f64d0362f2a'
+			+ '2d2d0a90cf1a5a4c5db02d56ecc4c5bf'
+			+ '34007208d5b887185865',
+		);
+	}
+
+	@Test()
+	public async expandMatchesFullHkdf(): Promise<void> {
+		const inputKeyMaterial = Buffer.from('shared-secret', 'utf8');
+		const salt = Buffer.from('root-key', 'utf8');
+		const info = Buffer.from('message-key', 'utf8');
+		const hkdfInstance = new Hkdf({
+			info,
+			inputKeyMaterial,
+			length: 64,
+			salt,
+		});
+		const pseudorandomKey = hkdfInstance.extract();
+
+		const expanded = hkdfInstance.expand({
+			info,
+			length: 64,
+			pseudorandomKey,
+		});
+		const derived = new Hkdf({
+			info,
+			inputKeyMaterial,
+			length: 64,
+			salt,
+		}).getBuffer();
+
+		expect(expanded).toMatchObject(derived);
+	}
+
+	@Test()
+	@ExpectException(HkdfOutputLengthException)
+	public async rejectsTooLargeOutputLength(): Promise<void> {
+		new Hkdf({
+			inputKeyMaterial: Buffer.from('shared-secret', 'utf8'),
+			length: (255 * 32) + 1,
+		}).getBuffer();
+	}
+}

package/src/utils/hkdf.ts

@@ -0,0 +1,89 @@
+import Buffer from '@hg-ts/buffer';
+import { HkdfOutputLengthException } from '../exceptions/index.js';
+import {
+	hmac,
+	HMAC_DIGEST_LENGTH,
+	type HmacAlgorithm,
+} from './hmac.js';
+
+export type HkdfOptions = {
+	algorithm?: HmacAlgorithm;
+	info?: Buffer;
+	inputKeyMaterial: Buffer;
+	length: number;
+	salt?: Buffer;
+};
+
+export type HkdfExpandOptions = {
+	info?: Optional<Buffer>;
+	length: number;
+	pseudorandomKey: Buffer;
+};
+
+export class Hkdf {
+	private readonly algorithm: HmacAlgorithm;
+	private readonly info: Buffer;
+	private readonly inputKeyMaterial: Buffer;
+	private readonly length: number;
+	private readonly salt: Buffer;
+
+	public constructor({
+		algorithm = 'sha256',
+		info,
+		inputKeyMaterial,
+		length,
+		salt,
+	}: HkdfOptions) {
+		this.algorithm = algorithm;
+		this.info = info ?? Buffer.alloc(0);
+		this.inputKeyMaterial = inputKeyMaterial;
+		this.length = length;
+		this.salt = salt ?? Buffer.alloc(HMAC_DIGEST_LENGTH[this.algorithm]);
+	}
+
+	public getBuffer(): Buffer {
+		return this.expand({
+			length: this.length,
+			pseudorandomKey: this.extract(),
+		});
+	}
+
+	public extract(): Buffer {
+		return hmac(
+			this.algorithm,
+			this.salt,
+			this.inputKeyMaterial,
+		);
+	}
+
+	public expand({
+		length,
+		info,
+		pseudorandomKey,
+	}: HkdfExpandOptions): Buffer {
+		const digestLength = HMAC_DIGEST_LENGTH[this.algorithm];
+
+		if (length > 255 * digestLength) {
+			throw new HkdfOutputLengthException(255 * digestLength);
+		}
+
+		const expandInfo = info ?? this.info;
+		const blocks: Buffer[] = [];
+		let previous: Buffer = Buffer.alloc(0);
+		let generatedLength = 0;
+
+		for (let counter = 1; generatedLength < length; counter += 1) {
+			previous = hmac(
+				this.algorithm,
+				pseudorandomKey,
+				previous,
+				expandInfo,
+				Buffer.from([counter]),
+			);
+			blocks.push(previous);
+			generatedLength += previous.length;
+		}
+
+		return Buffer.concat(blocks, generatedLength).subarray(0, length);
+	}
+}

package/src/utils/hmac.test.ts

@@ -0,0 +1,43 @@
+import Buffer from '@hg-ts/buffer';
+import {
+	Describe,
+	expect,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+
+import { hmac } from './hmac.js';
+
+@Describe()
+export class HmacTest extends Suite {
+	@Test()
+	public async sha256(): Promise<void> {
+		const actual = hmac(
+			'sha256',
+			Buffer.alloc(20, 0x0b),
+			Buffer.from('Hi There', 'utf8'),
+		);
+
+		expect(actual.toString('hex')).toBe(
+			'b0344c61d8db38535ca8afceaf0bf12b'
+			+ '881dc200c9833da726e9376c2e32cff7',
+		);
+	}
+
+	@Test()
+	public async acceptsSeveralValues(): Promise<void> {
+		const complete = hmac(
+			'sha256',
+			Buffer.from('Jefe', 'utf8'),
+			Buffer.from('what do ya want ', 'utf8'),
+			Buffer.from('for nothing?', 'utf8'),
+		);
+		const joined = hmac(
+			'sha256',
+			Buffer.from('Jefe', 'utf8'),
+			Buffer.from('what do ya want for nothing?', 'utf8'),
+		);
+
+		expect(complete).toMatchObject(joined);
+	}
+}