`policy/modulus`

(no submodules)

Purpose

Modulus-length policy gate enforced at every public-API entry point in @suaveplan/crypto-rsa. Combines a default-2048-bit floor (with optional 1024-bit legacy carve-out) and a default-16384-bit ceiling (with optional oversized opt-in) so consumers cannot accidentally accept dangerously short keys or get DoS'd by attacker-supplied oversized keys.

The 2048-bit default tracks NIST SP 800-131A Rev. 2's transition from 112-bit to 128-bit security strength; 1024 bits delivers 80-bit strength which is broken offline and survives only for legacy WebAuthn TPM endorsement keys (see proposal §Why and CLAUDE.md). The 16384-bit ceiling matches the largest modulus a service is realistically expected to verify; beyond that the per-verify modpow cost (cubic in bit length) becomes a viable DoS vector.

Features

enforceMinBitLength(key, { allowLegacy? }) — strict default 2048-bit floor.
enforceMaxBitLength(key, { allowOversize? }) — strict default 16384-bit ceiling.
Hard sub-1024-bit reject regardless of allowLegacy.
Both throw CryptoRsaError with structured context for telemetry.

Usage: Basic Example

import { enforceMinBitLength } from "@suaveplan/crypto-rsa/policy";

enforceMinBitLength(publicKey); // throws if bitLength < 2048

Usage: Advanced Example

import {
    enforceMaxBitLength,
    enforceMinBitLength,
} from "@suaveplan/crypto-rsa/policy";

// WebAuthn TPM legacy path: 1024 bits permitted.
enforceMinBitLength(tpmEndorsementKey, { allowLegacy: true });

// Offline tooling that processes 32 768-bit keys.
enforceMaxBitLength(researchKey, { allowOversize: true });

API Reference

`enforceMinBitLength(key, options?: { allowLegacy?: boolean }): void`

Throws CryptoRsaError(CRYPTO_RSA.MODULUS_TOO_SHORT) with context: { bitLength, floor } when key.bitLength < floor. floor is 2048 by default, 1024 under allowLegacy: true. Sub-1024-bit keys are always rejected.

`enforceMaxBitLength(key, options?: { allowOversize?: boolean }): void`

Throws CryptoRsaError(CRYPTO_RSA.MODULUS_TOO_LARGE) with context: { bitLength, ceiling } when key.bitLength > 16384. allowOversize: true short-circuits the check.

Implementation Notes

The hard sub-1024-bit floor is enforced even when allowLegacy: true because 512-bit and 768-bit moduli have been factored on commodity hardware and there is no realistic legacy use-case that still relies on them.

The ceiling check returns early when allowOversize: true rather than scaling the comparison; this keeps the hot path branch-predictable and the policy scope obvious to readers.

2.7 KiB Raw Blame History

policy/modulus