Node.js Web Crypto API vs Legacy Crypto Module

This article explores how Node.js supports the standardized Web Crypto API natively alongside its legacy crypto module. We will examine the key differences between these two interfaces, compare their syntax and design philosophies, and discuss when to use each for secure, cross-platform JavaScript development.

What is the Web Crypto API in Node.js?

Introduced as an experimental feature in Node.js 15 and marked as stable in version 19, the Web Crypto API is an implementation of the W3C Web Cryptography API standard. It is exposed globally as crypto (or via globalThis.crypto), meaning you can write cryptographic code that runs identically in Node.js, modern web browsers, Cloudflare Workers, Deno, and Bun without using external polyfills or transpilers.

Historically, Node.js relied exclusively on its proprietary crypto module, which is deeply integrated with OpenSSL. While powerful, the legacy module is platform-specific and cannot run in a browser environment.

Key Differences

1. Portability and Standardization

• Web Crypto API: Follows the W3C standard. Code written using this API is highly portable across frontend and backend environments.
• Legacy Crypto Module: Proprietary to Node.js. Code relying on this module is locked to the Node.js runtime.

2. Asynchronous Execution and Promises

• Web Crypto API: Designed from the ground up to be asynchronous, utilizing modern JavaScript Promises (and async/await). This prevents intensive cryptographic operations from blocking the single-threaded event loop.
• Legacy Crypto Module: Offers both synchronous and callback-based asynchronous methods. The synchronous methods (such as crypto.pbkdf2Sync) are easy to use but can severely degrade application performance by blocking the event loop.

3. Key Management and Security

• Web Crypto API: Introduces the CryptoKey object to represent cryptographic keys. These keys can be configured to be non-extractable, meaning the private key material cannot be read or leaked by application code once imported or generated.
• Legacy Crypto Module: Uses KeyObject or raw buffers/strings. While secure, it does not enforce the same standardized boundaries for key extractability as Web Crypto.

4. Algorithm Support

• Web Crypto API: Focuses on modern, secure algorithms specified by the W3C (such as AES-GCM, SHA-256, ECDSA, and RSASSA-PKCS1-v1_5). It intentionally excludes obsolete or insecure algorithms.
• Legacy Crypto Module: Supports a massive array of legacy, custom, and complex cipher suites provided by OpenSSL, making it highly flexible but easier to misconfigure securely.

Syntax Comparison: Generating a SHA-256 Hash

To see the difference in design, compare how each API generates a SHA-256 digest.

Using the Legacy Crypto Module:

const crypto = require('node:crypto');

const data = 'Hello, World!';
const hash = crypto.createHash('sha256').update(data).digest('hex');
console.log(hash);

This approach is synchronous and relies on Node.js-specific streaming interfaces.

Using the Web Crypto API:

const data = new TextEncoder().encode('Hello, World!');
const hashBuffer = await crypto.subtle.digest('SHA-256', data);

const hashArray = Array.from(new Uint8Array(hashBuffer));
const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
console.log(hashHex);

This standardized approach is asynchronous, utilizes typed arrays, and runs natively in any modern browser console without modifications.

When to Use Web Crypto vs. Legacy Crypto

Use the Web Crypto API if: * You are building isomorphic (universal) JavaScript libraries that need to run in both browsers and servers. * You are writing modern serverless functions (e.g., Cloudflare Workers, Vercel Edge) where the standard legacy Node.js APIs are unavailable. * You are starting a new greenfield project and want to future-proof your security implementation with standardized Promise-based APIs.

Use the Legacy Crypto Module if: * You are maintaining older Node.js codebases that heavily rely on stream-based encryption. * You require specific cryptographic algorithms or configurations not supported by the W3C Web Crypto standard (such as legacy hash algorithms or custom padding schemes). * Your application relies on third-party npm packages that are built specifically around Node’s legacy KeyObject architecture.