Stanford Javascript Crypto Library (SJCL)

Common errors

• TypeError: sjcl.json is not a function

  cause Attempting to use sjcl.json for encryption/decryption without ensuring the 'sjcl.json' component is included in the build or loaded correctly.
  fix Ensure your SJCL build includes the 'json' component. If using a pre-built file, verify it's the full version. If custom building, add 'json' to your components list.

• Error: Key doesn't match the one used to encrypt

  cause The key used for decryption does not match the key (or password from which it was derived) used during encryption, or there was corruption of the ciphertext.
  fix Verify that the encryption key and decryption key are absolutely identical. Check for any inconsistencies in key derivation or storage. Ensure the ciphertext was not altered.

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

  cause The 'sjcl.cipher.aes' module was not loaded or included in the SJCL build, making `sjcl.cipher` undefined, or `aes` property inaccessible.
  fix Confirm that the 'aes' component is part of your SJCL build configuration. If using a custom build, ensure 'aes' is selected. If importing, verify the module structure allows access.

Warnings

• deprecated SJCL is officially deprecated. Do not use it in new projects. Consider more modern, actively maintained alternatives due to security implications of unmaintained crypto libraries.
  Fix: Migrate to a modern, actively maintained cryptographic library (e.g., Web Crypto API, 'libsodium-wrappers', 'tweetnacl-js').
• breaking A critical vulnerability (CVE-2026-XXXX) existed in sjcl.ecc.basicKey.publicKey() prior to version 1.0.9, allowing an attacker to recover ECDH private keys via crafted off-curve public keys and observing ECDH outputs. This affects ECDH key exchanges.
  Fix: Upgrade to SJCL 1.0.9 immediately. For new projects, avoid SJCL entirely.
• gotcha The development version prior to commit ac0b3fe0 (before 12.02.2014) had a paranoia bug in the ECC module. This might affect ECC key generation on platforms without a strong platform random number generator.
  Fix: Ensure you are using a stable release (1.0.9) and that your platform has a robust cryptographically secure random number generator.
• breaking In version 1.0.4, `sjcl.codec.base32` was re-enabled with changes to conform to RFC 4648. This changed padding behavior (now applied by default) and the encoding alphabet. The former extended hex alphabet is now `sjcl.codec.base32hex`.
  Fix: If decoding data encoded with `base32` prior to 1.0.4, use `sjcl.codec.base32hex`. If you don't want padding on `fromBits` output, pass a truthy second parameter. Ensure your base32 encoding/decoding logic aligns with RFC 4648 or the new `base32hex`.

Install

• npm install sjcl npm
• yarn add sjcl yarn
• pnpm add sjcl pnpm

Imports

• sjcl
  wrong:

  import sjcl from 'sjcl';

  correct:

  const sjcl = require('sjcl');

  Primarily designed for CommonJS or global script inclusion. ESM imports are not officially supported or recommended for this deprecated library.
• sjcl.cipher.aes

  const sjcl = require('sjcl');
  const aes = sjcl.cipher.aes;

  Access specific modules as properties of the main 'sjcl' object after requiring the library.
• sjcl.hash.sha256

  const sjcl = require('sjcl');
  const sha256 = sjcl.hash.sha256;

  Hashes like SHA-256 are exposed as properties. Ensure the correct module is loaded/available in your build.

Quickstart

Demonstrates basic encryption and decryption using AES in GCM mode and SHA-256 hashing. It shows how to use the 'sjcl' object for core cryptographic operations.

const sjcl = require('sjcl');

// Generate a random key
const password = 'mySecretPassword';
const key = sjcl.misc.stringToBits(password);

// Data to encrypt
const plaintext = 'Hello, secure world!';

// Encrypt the data
const encrypted = sjcl.json.encrypt(key, plaintext);

console.log('Encrypted data:', encrypted);

// Decrypt the data
try {
  const decrypted = sjcl.json.decrypt(key, encrypted);
  console.log('Decrypted data:', decrypted);
} catch (e) {
  console.error('Decryption failed:', e.message);
}

// Example of hashing
const dataToHash = 'This is a test string for hashing.';
const hashBits = sjcl.hash.sha256.hash(dataToHash);
const hashHex = sjcl.codec.hex.fromBits(hashBits);

console.log('SHA-256 hash:', hashHex);