JavaScript Blowfish Encryption Library

Common errors

• Decrypted string contains extra null characters or appears corrupted after decryption.

  cause The library automatically pads input strings with null bytes to meet the 8-byte block size requirement of Blowfish. These null bytes are retained after decryption if not explicitly removed.
  fix For text data, apply `bf.trimZeroes(decryptedString)` after decryption to remove the padding characters.

• Error: 'IV must be 8 bytes long' or unexpected output when using CBC mode.

  cause CBC (Cipher Block Chaining) mode requires an Initialization Vector (IV) that is exactly 8 bytes in length. Not providing it, or providing one of incorrect length, will cause issues.
  fix Pass an 8-byte string as the second argument to the `Blowfish` constructor if specifying 'cbc' mode, and also to the `encrypt` and `decrypt` methods. E.g., `new Blowfish("key", "cbc"); bf.encrypt("message", "cbcvecto");`

• Encrypted output is unreadable or causes issues when stored/transmitted as text.

  cause The `encrypt` method produces a raw binary string. Many text-based systems (databases, web forms, URLs) cannot correctly handle or preserve binary strings.
  fix Use `bf.base64Encode()` on the result of `bf.encrypt()` to convert the binary string into a safe, ASCII-representable format. Remember to `bf.base64Decode()` it before decryption.

Warnings

• breaking Blowfish, with its 64-bit block size, is susceptible to 'Sweet32' birthday attacks and is not recommended for encrypting data larger than 4GB. This is a fundamental cryptographic weakness of Blowfish, not specific to this library's implementation.
  Fix: For new applications or large data volumes, prefer modern ciphers like AES (e.g., `crypto` module in Node.js) or Twofish, which use larger block sizes (e.g., 128-bit).
• gotcha The `encrypt` method returns a raw binary string. This output is not human-readable or safe for direct transmission in many text-based systems (e.g., JSON, URL query parameters).
  Fix: Always use `bf.base64Encode()` on the encrypted output before storing or transmitting it, and `bf.base64Decode()` before decryption, as shown in the examples. This converts the binary data into a safe text format.
• gotcha The library automatically pads input strings with null characters (`\0`) to meet Blowfish's 8-byte block length requirement. For text data, these padding characters will remain in the decrypted output.
  Fix: After decrypting text data, explicitly call `bf.trimZeroes(decryptedString)` to remove the trailing null characters and restore the original plaintext.
• gotcha When using CBC (Cipher Block Chaining) mode, an 8-byte initialization vector (IV) is mandatory. Failing to provide a correct IV will lead to incorrect encryption/decryption or runtime errors.
  Fix: Ensure you provide an 8-byte string as the second argument to `bf.encrypt(message, 'cbcvecto')` and `bf.decrypt(encrypted, 'cbcvecto')` when operating in CBC mode. The IV should be unique for each encryption operation (though not necessarily secret) and transmitted alongside the ciphertext.
• deprecated The Blowfish algorithm itself, while never fully broken, is considered an older cipher (designed in 1993) and has largely been superseded by more modern and robust algorithms like AES for general-purpose encryption.
  Fix: Consider migrating to Advanced Encryption Standard (AES) implementations (e.g., Node.js's built-in `crypto` module or a well-vetted third-party library) for new projects to ensure better security posture and performance on modern hardware.

Install

• npm install javascript-blowfish npm
• yarn add javascript-blowfish yarn
• pnpm add javascript-blowfish pnpm

Imports

• Blowfish
  wrong:

  const Blowfish = require('javascript-blowfish');

  correct:

  import { Blowfish } from 'javascript-blowfish';

  While the README examples show a CommonJS-like `var bf = new Blowfish()`, the package ships TypeScript types, implying a named export for ESM. The CommonJS `require` pattern is also widely used for older Node.js projects.
• Blowfish constructor
  wrong:

  const bf = Blowfish("secret key");

  correct:

  const bf = new Blowfish("secret key");

  Blowfish is a class, and must be instantiated with the `new` keyword.
• CommonJS Import (Legacy)
  wrong:

  import Blowfish from 'javascript-blowfish'; // for CommonJS environments

  correct:

  const Blowfish = require('javascript-blowfish');

  For older Node.js or CommonJS-only environments, `require` is the standard. If the module has a default export, `import Blowfish from '...'` might work in transpiled environments, but named import is safer for class exports.

Quickstart

This quickstart demonstrates basic Blowfish encryption and decryption using a secret key. It covers handling the binary output of encryption, including trimming zero padding for text data and using base64 encoding for convenient representation.

import { Blowfish } from 'javascript-blowfish';

const encryptionKey = process.env.BLOWFISH_KEY ?? 'my-super-secret-key-1234567890';
const message = 'This is a secret message to be encrypted.';

// Initialize Blowfish in ECB mode (default)
const bf = new Blowfish(encryptionKey);

// Encrypt the message
const encrypted = bf.encrypt(message);
console.log('Encrypted (binary string):', encrypted);

// Decrypt the message
let decrypted = bf.decrypt(encrypted);

// Trim zero padding for string/text information
decrypted = bf.trimZeroes(decrypted);

console.log('Decrypted message:', decrypted);

// Example with Base64 encoding for easier handling of binary output
const bfBase64 = new Blowfish(encryptionKey);
const encryptedBase64 = bfBase64.base64Encode(bfBase64.encrypt(message));
console.log('Encrypted (Base64):', encryptedBase64);

let decryptedBase64 = bfBase64.decrypt(bfBase64.base64Decode(encryptedBase64));
decryptedBase64 = bfBase64.trimZeroes(decryptedBase64);
console.log('Decrypted (from Base64):', decryptedBase64);