Node Forge Cryptography and TLS Library

Common errors

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

  cause 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

  cause 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

  cause 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.

Warnings

• breaking Node 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.
• gotcha As 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.
• gotcha Node 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');`.
• gotcha When 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.

Install

• npm install node-forge npm
• yarn add node-forge yarn
• pnpm add node-forge pnpm

Imports

• forge
  wrong:

  import { forge } from 'node-forge';

  correct:

  import forge from 'node-forge';
  // or for CommonJS:
  const forge = require('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
  wrong:

  import { pki } from 'node-forge';

  correct:

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

  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
  wrong:

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

  correct:

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

  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.

Quickstart

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);