node-forge

library1.4.0jsnpmunverified

Node Forge is a comprehensive JavaScript library providing native implementations of cryptographic tools, network transports (like TLS, HTTP, SSH), and PKI components. It supports a wide array of ciphers (AES, DES), message digests (SHA-1, SHA-256, MD5), and PKI standards (X.509, PKCS# series). The current stable version is 1.4.0, which continues to build on its CommonJS module structure for Node.js and UMD bundles for browser environments. Its key differentiators include its entirely JavaScript-native implementation, which avoids native dependencies, and its extensive feature set for both client-side and server-side cryptographic operations, from generating RSA key pairs to parsing X.509 certificates.

auth-security http-networking serialization

npm install node-forge

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-FORGE

node-forge

auth-securityjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

forge

✓ import forge from 'node-forge'; // or for CommonJS: const forge = require('node-forge');

✗ import { forge } from 'node-forge';

Node Forge is primarily a CommonJS module. While `import forge from 'node-forge'` works via default interop in ESM contexts, direct named imports like `import { pki } from 'node-forge'` are not supported. In browser environments, a global `forge` object is exposed when using the UMD bundles.

pki

✓ import forge from 'node-forge'; const pki = forge.pki;

✗ import { pki } from 'node-forge';

Sub-modules like `pki` (Public Key Infrastructure) are properties of the main `forge` object and must be accessed after importing the main library. They are not top-level exports.

md.sha256

✓ import forge from 'node-forge'; const sha256 = forge.md.sha256.create();

✗ import { sha256 } from 'node-forge/lib/sha256';

Message digest algorithms are accessed via the `forge.md` object. Individual algorithm instances are created using `.create()` on the specific algorithm function (e.g., `forge.md.sha256`). Direct imports from internal paths are discouraged and not guaranteed to be stable.

Generates an RSA key pair, exports public and private keys in PEM format, and then creates a self-signed X.509 certificate using these keys.

import forge from 'node-forge'; async function generateAndExportRSAKeypair() { console.log('Generating RSA key pair...'); const keys = await new Promise((resolve) => { forge.pki.rsa.generateKeyPair({ bits: 2048, workers: -1 }, (err, keypair) => { if (err) throw err; resolve(keypair); }); }); const publicKeyPem = forge.pki.publicKeyToPem(keys.publicKey); const privateKeyPem = forge.pki.privateKeyToPem(keys.privateKey); console.log('\n--- Public Key PEM ---'); console.log(publicKeyPem); console.log('\n--- Private Key PEM ---'); console.log(privateKeyPem); // Example of creating a self-signed certificate const cert = forge.pki.createCertificate(); cert.publicKey = keys.publicKey; cert.serialNumber = '01'; cert.validity.notBefore = new Date(); cert.validity.notAfter = new Date(); cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1); const attrs = [ { name: 'commonName', value: 'example.org' }, { name: 'countryName', value: 'US' }, { shortName: 'ST', value: 'Virginia' }, { name: 'organizationName', value: 'Example' } ]; cert.setSubject(attrs); cert.setIssuer(attrs); cert.setExtensions([ { name: 'basicConstraints', cA: true }, { name: 'keyUsage', digitalSignature: true, keyEncipherment: true, dataEncipherment: true }, { name: 'extKeyUsage', serverAuth: true, clientAuth: true, codeSigning: true, emailProtection: true }, { name: 'nsCertType', sslCPS: true, sslBSS: true, emailCA: true }, { name: 'subjectAltName', altNames: [{ type: 6, value: 'http://example.org/' }, { type: 7, ip: '127.0.0.1' }]}, { name: 'subjectKeyIdentifier' } ]); // Sign the certificate with the private key cert.sign(keys.privateKey, forge.md.sha256.create()); const pem = forge.pki.certificateToPem(cert); console.log('\n--- Self-Signed Certificate PEM ---'); console.log(pem); } generateAndExportRSAKeypair().catch(console.error);

Debug

Known issues

breakingNode Forge transitioned from a monolithic 0.6.x branch with standalone files to a CommonJS module structure in 1.x. The 0.6.x branch is no longer regularly updated or maintained, and new projects should use the 1.x series. Code written for 0.6.x will require import and API adjustments.

fix

Upgrade to `node-forge@^1.0.0` and update `require`/`import` statements to access modules via the main `forge` object. Review the 1.x API documentation for specific changes.

affects: <1.0.0

gotchaAs a cryptographic library, it is critical to consult and thoroughly understand the 'Security Considerations' section of the documentation. Misuse of cryptographic primitives can lead to severe security vulnerabilities. Always use recommended best practices and ensure randomness sources are truly secure.

fix

Read the 'Security Considerations' in the official documentation. Use strong, cryptographically secure random number generators (CSPRNGs) provided by the library. Consult security experts for sensitive applications.

affects: >=0.6.0

gotchaNode Forge uses a CommonJS module structure for Node.js. When used in an ESM context (`'type': 'module'` or `.mjs` files), it typically requires `import forge from 'node-forge';` (default import interop). Direct named imports are not available, which can be a common source of confusion for modern JavaScript developers.

fix

Always use `import forge from 'node-forge';` for ESM, and then access sub-modules (e.g., `forge.pki`, `forge.util`) as properties of the `forge` object. For CommonJS, use `const forge = require('node-forge');`.

affects: >=1.0.0

gotchaWhen using Node Forge in web browsers via CDN or bundled files, it synchronously creates a global `forge` object. This can potentially conflict with other scripts or lead to unintended global pollution if not managed carefully.

fix

Be aware of the global `forge` object in browser environments. If integrating into a larger application, consider wrapping the script or using a module loader if possible to isolate the scope, or rename the global variable if the build process allows.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'pki')

Attempting to access a submodule (like `pki`) before the main `forge` object has been correctly imported or initialized.

fix

Ensure `forge` is correctly imported as a default export (`import forge from 'node-forge';`) or required (`const forge = require('node-forge');`). Submodules are then accessed via `forge.pki`.

ReferenceError: require is not defined

Attempting to use `require('node-forge')` in a browser environment without a module bundler like Webpack or Rollup, or in an ESM-only Node.js context without proper configuration.

fix

For browsers, use the UMD bundles via a `<script>` tag (e.g., `<script src="https://cdn.jsdelivr.net/npm/node-forge@1.0.0/dist/forge.min.js"></script>`). For ESM Node.js, use `import forge from 'node-forge';`.

TypeError: forge.md.sha256.create is not a function

Incorrectly calling `create()` on the message digest object, or trying to use a method that doesn't exist on the specific digest.

fix

Ensure you are calling `.create()` on the *algorithm factory* itself, e.g., `forge.md.sha256.create()`. Also verify the algorithm name is correct and supported.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/digitalbazaar/forge ↗

packagehttps://www.npmjs.com/package/node-forge ↗