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.

完整安装指南与集成提示词将在购买后解锁。

Automation, Utilities & Developer Tools

免费