Required dependencies

npm install node-forge

No native modules, no pod install, no Android linking, no npx expo prebuild required. The library is pure JavaScript and runs in Node.js 12+ or any modern browser.

Project setup

1. Copy the source/ directory into your project, e.g. src/forge/.
2. The entry point is source/index.js (CommonJS). For TypeScript projects install the types:

   npm install --save-dev @types/node-forge
   

3. In tsconfig.json, if you reference source directly, add a path alias:

   {
     "compilerOptions": {
       "paths": {
         "forge/*": ["src/forge/*"]
       },
       "esModuleInterop": true,
       "allowSyntheticDefaultImports": true
     }
   }
   

4. Import via the index entry point; do not import individual files unless you need tree-shaking:

   import forge from 'src/forge/index.js'; // direct source
   // or if installed via npm:
   import forge from 'node-forge';
   

5. No environment variables are required. For browser bundles, use the pre-built dist/forge.min.js instead of bundling source directly, as some modules reference process and window.

Public API

forge.util.ByteStringBuffer

class ByteStringBuffer {
  constructor(data?: string | ArrayBuffer | Uint8Array);
  putBytes(bytes: string): ByteStringBuffer;
  getBytes(count?: number): string;
  bytes(count?: number): string;
  length(): number;
  toHex(): string;
}

Core buffer type used throughout forge. Use it to accumulate binary data before passing to ciphers or digest functions. Returned by most low-level encrypt/decrypt operations.

forge.pki

namespace pki {
  function generateKeyPair(options: { bits: number; workers?: number }, callback: (err: Error | null, keypair: { privateKey: any; publicKey: any }) => void): void;
  function privateKeyToPem(key: any): string;
  function publicKeyToPem(key: any): string;
  function privateKeyFromPem(pem: string): any;
  function publicKeyFromPem(pem: string): any;
  function createCertificate(): any;
  function certificateToPem(cert: any): string;
  function certificateFromPem(pem: string): any;
}

High-level PKI interface. Use pki to generate RSA key pairs, parse/export PEM-encoded keys and certificates, and build self-signed or CA-signed X.509 certificates.

forge.md.sha256

namespace md {
  namespace sha256 {
    function create(): MessageDigest;
  }
  namespace sha512 {
    function create(): MessageDigest;
  }
  namespace sha1 {
    function create(): MessageDigest;
  }
  namespace md5 {
    function create(): MessageDigest;
  }
}
interface MessageDigest {
  update(msg: string): MessageDigest;
  digest(): { toHex(): string; bytes(): string };
}

Create and use message digest instances. Call update() one or more times with string data, then digest() to get the final hash. Use sha256 or sha512 for security-sensitive hashing; md5 only for legacy compatibility.

Working examples

Scenario - AES-GCM encryption and decryption

Encrypt a plaintext string with AES-256-GCM, then decrypt it and verify the result. This is the recommended symmetric cipher for new code.

import forge from 'node-forge'; // or: require('./source/index.js')

const key = forge.random.getBytesSync(32); // 256-bit key
const iv  = forge.random.getBytesSync(12); // 96-bit IV for GCM

// Encrypt
const cipher = forge.cipher.createCipher('AES-GCM', key);
cipher.start({ iv });
cipher.update(forge.util.createBuffer('Hello, secure world!', 'utf8'));
cipher.finish();

const encrypted = cipher.output.bytes();
const tag       = cipher.mode.tag.bytes(); // authentication tag

// Decrypt
const decipher = forge.cipher.createDecipher('AES-GCM', key);
decipher.start({ iv, tag: forge.util.createBuffer(tag) });
decipher.update(forge.util.createBuffer(encrypted));
const pass = decipher.finish(); // false if tag mismatch

console.log(pass); // true
console.log(decipher.output.toString()); // "Hello, secure world!"

Scenario - RSA key pair generation and PEM export

Generate a 2048-bit RSA key pair and export both keys to PEM strings for storage or transmission.

import forge from 'node-forge';

forge.pki.generateKeyPair({ bits: 2048, workers: -1 }, (err, keypair) => {
  if (err) throw err;

  const privateKeyPem = forge.pki.privateKeyToPem(keypair.privateKey);
  const publicKeyPem  = forge.pki.publicKeyToPem(keypair.publicKey);

  console.log(privateKeyPem); // -----BEGIN RSA PRIVATE KEY-----...
  console.log(publicKeyPem);  // -----BEGIN PUBLIC KEY-----...

  // Round-trip: parse back from PEM
  const parsedPrivate = forge.pki.privateKeyFromPem(privateKeyPem);
  const parsedPublic  = forge.pki.publicKeyFromPem(publicKeyPem);

  // Sign and verify with PKCS#1 v1.5 SHA-256
  const md = forge.md.sha256.create();
  md.update('data to sign', 'utf8');

  const signature = parsedPrivate.sign(md);
  const verified  = parsedPublic.verify(md.digest().bytes(), signature);
  console.log(verified); // true
});

Scenario - PBKDF2 key derivation and HMAC

Derive a key from a password using PBKDF2, then compute an HMAC-SHA256 over a message. Suitable for password-based MAC generation or symmetric key derivation.

import forge from 'node-forge';

const password   = 'correct horse battery staple';
const salt       = forge.random.getBytesSync(16);
const iterations = 100_000;
const keyLen     = 32; // 256 bits

// Derive key
const derivedKey = forge.pkcs5.pbkdf2(password, salt, iterations, keyLen);

// Compute HMAC-SHA256
const hmac = forge.hmac.create();
hmac.start('sha256', derivedKey);
hmac.update('message to authenticate');

const macHex = hmac.getMac().toHex();
console.log('HMAC-SHA256:', macHex);

// SHA-256 hash for reference
const hash = forge.md.sha256.create();
hash.update('message to hash', 'utf8');
console.log('SHA-256:', hash.digest().toHex());

File walkthrough

• index.js - Default entry; requires forge root and all core modules. Use this as your single import point.
• forge.js - Defines the global forge namespace object shared across all modules.
• util.js - ByteStringBuffer, base64/hex encoding helpers, nextTick/setImmediate polyfills. Required by every other module.
• aes.js - Registers forge.aes; underlying engine for forge.cipher AES operations.
• cipher.js - Generic createCipher/createDecipher factory; delegates to aes/des/rc2 engines.
• cipherModes.js - ECB, CBC, CFB, OFB, CTR, GCM mode logic consumed by cipher.js.
• des.js - DES and Triple-DES implementations; same API pattern as aes.js.
• rc2.js - RC2 block cipher; legacy use only.
• rsa.js - RSA encrypt/decrypt/sign/verify; big-number arithmetic via jsbn.js.
• jsbn.js - Big-integer library used internally by RSA and prime generation.
• pki.js - High-level PKI entry point; aggregates x509.js, rsa.js, key serialization.
• x509.js - X.509 certificate creation, parsing, extension handling, chain verification.
• asn1.js - DER encoding/decoding primitives used by all PKI and PKCS modules.
• asn1-validator.js - Schema-based ASN.1 structure validation.
• pem.js - PEM armor encode/decode (base64 with header/footer).
• pkcs1.js - PKCS#1 v1.5 and OAEP RSA padding schemes.
• pkcs7.js / pkcs7asn1.js - CMS/PKCS#7 signed and enveloped data structures.
• pkcs12.js - PKCS#12 (.p12/.pfx) file parsing and creation.
• pbe.js - Password-Based Encryption for PKCS#5 and PKCS#12.
• pbkdf2.js - PBKDF2 implementation; exposed as forge.pkcs5.pbkdf2.
• pss.js - RSA-PSS signature padding scheme.
• mgf.js / mgf1.js - MGF1 mask generation for OAEP and PSS.
• hmac.js - HMAC over any forge message digest.
• md.js / md.all.js - Message digest interface and loader for all digest algorithms.
• sha1.js, sha256.js, sha512.js, md5.js - Individual digest implementations.
• ed25519.js - Ed25519 key generation, signing, and verification.
• prime.js / prime.worker.js - Probable prime generation; worker script for browser offload.
• prng.js - Fortuna-based PRNG seeded by platform entropy.
• random.js - forge.random.getBytesSync / getBytes using the PRNG.
• kem.js - RSA-KEM key encapsulation/decapsulation.
• oids.js - OID string-to-name registry used across PKI modules.
• baseN.js - Base-N codec (base64, base58) used by util.js.
• tls.js - Full TLS 1.0/1.1 implementation (handshake + record layer).
• tlssocket.js - TLS socket wrapper combining tls.js with socket.js.
• socket.js - Raw TCP socket abstraction (primarily for browser Flash transport).
• http.js - HTTP client utilities built on forge's socket layer.
• ssh.js - SSH public key format encode/decode (OpenSSH wire format).
• xhr.js - XHR shim for use inside Flash/socket environments.
• log.js - Structured logging with category and level filtering.
• form.js - URL-encoded form data serialization helper.
• aesCipherSuites.js - TLS AES cipher suite definitions used by tls.js.
• index.all.js - Loads every module including networking extras.

Common pitfalls and fixes

• process is not defined in browser bundles: util.js references process.nextTick; use the pre-built dist/forge.min.js or configure your bundler to polyfill process.
• CJS/ESM interop in TypeScript: index.js uses module.exports; set "esModuleInterop": true and "allowSyntheticDefaultImports": true in tsconfig.json or use import forge = require('node-forge').
• forge.pkcs5 is undefined: pbkdf2.js must be explicitly required; index.js already does this, but if you import modules individually you must require('./pbkdf2') before calling forge.pkcs5.pbkdf2.
• Slow RSA key generation on the main thread: Pass workers: -1 to generateKeyPair to use Web Workers in the browser; in Node.js this falls back to synchronous generation automatically.
• GCM authentication failure returns false silently: decipher.finish() returns false on tag mismatch instead of throwing; always check the return value and reject the plaintext if false.
• @types/node-forge version mismatch: Pin @types/node-forge to ^1.0.0 to match this 1.4.x source; older type packages (0.x) have incompatible signatures for pki.generateKeyPair and cipher modes.

Vibe-coding prompt template

I have the node-forge cryptography library source code in `src/forge/` (entry point: `src/forge/index.js`).
I also have a USAGE.md integration guide in `src/forge/USAGE.md`.
The upstream npm package is `user@example.com`.

Please help me integrate this library into my project step by step:

1. Read USAGE.md and the file walkthrough to understand what is available.
2. Install any required dependencies listed in the "Required dependencies" section.
3. Set up the import path so I can use `forge` throughout the project (CommonJS or ESM as appropriate).
4. Implement the following feature using the real exports from `src/forge/index.js`: [DESCRIBE YOUR FEATURE HERE]
5. Use only the APIs documented in USAGE.md - do not invent methods not present in the source excerpts.
6. Show the complete, runnable TypeScript/JavaScript code with correct imports from `src/forge/index.js` or `node-forge`.
7. Point out any pitfalls from the "Common pitfalls and fixes" section that apply to my use case.

License and credit

node-forge is Copyright (c) 2009-2024 Digital Bazaar, Inc. and contributors. It is licensed under the BSD 3-Clause License and/or the GNU General Public License v2 (dual-licensed). See source/LICENSE if present, or refer to the upstream repository for the full license text.

Upstream package: node-forge on npm | GitHub repository

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

CryptoJS JavaScript Cryptographic Standards Library

Automation, Utilities & Developer Tools

Free