Browserify Sign

Common errors

• Cannot find module 'crypto'

  cause Attempting to use `require('crypto')` in a browser environment without `browserify` configured to shim the `crypto` module or if `browserify-sign` is not properly integrated.
  fix Ensure `browserify` is correctly configured to bundle your application and replace Node.js `crypto` with `browserify-sign` (often handled automatically by `crypto-browserify` which depends on `browserify-sign`). Run `browserify main.js -o bundle.js`.

• `new Sign(algorithm)` or `new Verify(algorithm)` throws an error about unsupported algorithm or invalid key format.

  cause Incorrect algorithm string provided (e.g., 'SHA256' instead of 'sha256' or 'RSA-SHA256'), or private/public key material is not in the expected PEM format or is corrupted. Also could be due to old OpenSSL versions not supporting certain schemes.
  fix Verify the algorithm string exactly matches one supported by the underlying crypto implementation (case-sensitive where relevant). Ensure private and public keys are correctly formatted PEM strings. Check the `CHANGELOG.md` or source for supported algorithms if issues persist.

Warnings

• breaking Version 4.0.1 introduced a breaking change by modifying the interface for `require('browserify-sign/algos')`. Projects relying on this direct sub-path access experienced failures.
  Fix: Avoid direct `require` calls to internal sub-paths like `/algos`. Instead, pass the algorithm string directly to the `Sign` or `Verify` constructor, e.g., `new Sign('SHA256')`.
• breaking A critical vulnerability (CVE-2023-46234) involving an upper bound check issue in the `dsaVerify` function allowed attackers to construct DSA signatures that could be successfully verified by any public key, leading to signature forgery. This affects all instances performing DSA verification on user-supplied signatures.
  Fix: Immediately upgrade to `browserify-sign` version 4.2.2 or higher to patch the DSA signature forgery vulnerability. Always keep cryptographic libraries updated.
• gotcha This library is designed for use with Browserify to shim Node.js `crypto` functionality in browser environments. Directly importing or using it in a native Node.js environment or a modern ESM-first browser application without Browserify bundling will likely lead to module resolution errors or unexpected behavior.
  Fix: Ensure your project is set up to use Browserify for bundling browser-side code. If you require Node.js `crypto` in Node.js, use the built-in module. For modern browser-native crypto, consider Web Crypto API or modern bundlers with appropriate shims.

Install

• npm install browserify-sign npm
• yarn add browserify-sign yarn
• pnpm add browserify-sign pnpm

Imports

• Sign
  wrong:

  import { Sign } from 'browserify-sign';

  correct:

  const { Sign } = require('browserify-sign');

  This package is primarily CommonJS for use with Browserify. `Sign` is a constructor for creating signer instances.
• Verify
  wrong:

  import Verify from 'browserify-sign/verify';

  correct:

  const { Verify } = require('browserify-sign');

  `Verify` is a constructor for creating verifier instances, matching Node.js `crypto.createVerify` functionality.
• Specific Algorithms (deprecated)
  wrong:

  require('browserify-sign/algos')

  correct:

  /* Use Sign/Verify constructors with algorithm strings directly */

  Directly requiring sub-paths like `algos` was a breaking change in v4.0.1 and is no longer the standard or supported API. Pass algorithm strings to `Sign` or `Verify` constructors.

Quickstart

Demonstrates how to use `browserify-sign` to sign data with a private key and verify it with a public key, mirroring Node.js crypto API. Key generation is shown using Node's native crypto, but in a browser, keys would be pre-loaded.

const { Sign, Verify } = require('browserify-sign');
const crypto = require('crypto'); // Node.js 'crypto' for key generation (use pre-generated keys in browser)

// In a browser environment, you would typically load pre-existing private and public keys.
// For demonstration purposes, we generate them (requires Node.js crypto module).
// NEVER hardcode keys in production.
const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
  modulusLength: 2048,
  publicKeyEncoding: { type: 'spki', format: 'pem' },
  privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
});

const data = 'This is the message to be signed.';
const algorithm = 'sha256'; // Hashing algorithm, e.g., 'sha256', 'rsa-sha256'

// --- Signing Process ---
const signer = new Sign(algorithm);
signer.update(data);
signer.end(); // Indicate no more data will be written

// The privateKey must be loaded securely.
const signature = signer.sign(privateKey, 'base64');
console.log('Generated Signature:', signature);

// --- Verification Process ---
const verifier = new Verify(algorithm);
verifier.update(data);
verifier.end(); // Indicate no more data will be written

// The publicKey must be loaded securely.
const isVerified = verifier.verify(publicKey, signature, 'base64');
console.log('Signature Verification Result:', isVerified);

if (isVerified) {
  console.log('The signature is valid for the data and public key.');
} else {
  console.error('The signature is NOT valid.');
}