or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

big-number-arithmetic.mdbit-array-utilities.mdcipher-modes.mddata-encoding.mdelliptic-curve-cryptography.mdhash-functions.mdhigh-level-encryption.mdindex.mdkey-derivation.mdkey-exchange.mdmessage-authentication.mdrandom-number-generation.mdsymmetric-encryption.md
tile.json

tessl/npm-sjcl

Stanford JavaScript Crypto Library providing comprehensive cryptographic operations including AES encryption, hash functions, key derivation, and elliptic curve cryptography.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/sjcl@1.0.x

To install, run

npx @tessl/cli install tessl/npm-sjcl@1.0.0

index.mddocs/

SJCL (Stanford JavaScript Crypto Library)

SJCL is a comprehensive cryptographic library for JavaScript providing secure, high-performance encryption and cryptographic operations. Developed by the Stanford Computer Security Lab, it offers a wide range of cryptographic primitives including AES encryption, secure hash functions, HMAC authentication, key derivation functions, elliptic curve cryptography, and various cipher modes with multiple encoding formats.

Package Information

  • Package Name: sjcl
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install sjcl

Core Imports

// CommonJS (primary)
const sjcl = require('sjcl');

// ES6 imports (if available)
import sjcl from 'sjcl';

// Browser script tag
<script src="sjcl.js"></script>

Basic Usage

const sjcl = require('sjcl');

// Simple encryption/decryption
const password = "mySecretPassword";
const plaintext = "Hello, World!";

// Encrypt data
const encrypted = sjcl.encrypt(password, plaintext);
console.log(encrypted); // JSON string with encrypted data

// Decrypt data
const decrypted = sjcl.decrypt(password, encrypted);
console.log(decrypted); // "Hello, World!"

// Hash functions
const hash = sjcl.hash.sha256.hash("Hello, World!");
const hexHash = sjcl.codec.hex.fromBits(hash);
console.log(hexHash);

// Random number generation
const randomBytes = sjcl.random.randomWords(4); // 4 32-bit words
const hexRandom = sjcl.codec.hex.fromBits(randomBytes);

Architecture

SJCL is organized around several key architectural components:

  • Namespace Organization: All functionality is organized under the sjcl namespace with clear sub-namespaces (cipher, hash, mode, codec, etc.)
  • Bit Array System: Internal data representation using 32-bit word arrays for efficient cryptographic operations
  • Modular Design: Core cryptographic primitives can be used independently or combined
  • High-Level Convenience: Simple encrypt/decrypt functions for common use cases alongside low-level primitives
  • Security Focus: Paranoia-based entropy collection, constant-time operations, and secure defaults
  • Cross-Platform: Works in browsers, Node.js, and other JavaScript environments

Capabilities

High-Level Encryption

Simple password-based encryption and decryption with secure defaults including authenticated encryption modes.

function encrypt(password, plaintext, params, rp);
function decrypt(password, ciphertext, params, rp);

High-Level Encryption

Hash Functions

Cryptographic hash functions including SHA-1, SHA-256, SHA-512, and RIPEMD-160 with both streaming and one-shot interfaces.

// Static hash functions
sjcl.hash.sha256.hash(data);
sjcl.hash.sha1.hash(data);
sjcl.hash.sha512.hash(data);
sjcl.hash.ripemd160.hash(data);

// Streaming hash constructors
new sjcl.hash.sha256(hash);
new sjcl.hash.sha1(hash);
new sjcl.hash.sha512(hash);
new sjcl.hash.ripemd160(hash);

Hash Functions

Symmetric Encryption

AES encryption with support for 128, 192, and 256-bit keys, providing the foundation for secure symmetric encryption.

// AES cipher constructor
new sjcl.cipher.aes(key);

Symmetric Encryption

Cipher Modes

Authenticated encryption modes including CCM, GCM, and OCB2, plus traditional modes like CBC and CTR for advanced use cases.

// Authenticated modes
sjcl.mode.ccm.encrypt(prf, plaintext, iv, adata, tlen);
sjcl.mode.gcm.encrypt(prf, plaintext, iv, adata, tlen);
sjcl.mode.ocb2.encrypt(prp, plaintext, iv, adata, tlen, premac);

// Traditional modes  
sjcl.mode.cbc.encrypt(prp, plaintext, iv, adata);
sjcl.mode.ctr.encrypt(prf, plaintext, iv, adata);

Cipher Modes

Key Derivation

Password-based key derivation functions including PBKDF2, scrypt, and HKDF for converting passwords to cryptographic keys.

sjcl.misc.pbkdf2(password, salt, count, length, Prff);
sjcl.misc.scrypt(password, salt, N, r, p, length, Prff);
sjcl.misc.hkdf(ikm, keyBitLength, salt, info, Hash);

Key Derivation

Message Authentication

HMAC (Hash-based Message Authentication Code) for message authentication and integrity verification.

// HMAC constructor and methods
new sjcl.misc.hmac(key, Hash);

Message Authentication

Data Encoding

Comprehensive encoding and decoding capabilities for converting between bit arrays and various formats including Base64, hexadecimal, UTF-8, and more.

// Primary codecs
sjcl.codec.utf8String.toBits(str);
sjcl.codec.utf8String.fromBits(arr);
sjcl.codec.hex.toBits(str);
sjcl.codec.hex.fromBits(arr);
sjcl.codec.base64.toBits(str, _url);
sjcl.codec.base64.fromBits(arr, _noEquals, _url);

Data Encoding

Random Number Generation

Cryptographically secure pseudo-random number generator with entropy collection from multiple sources and configurable paranoia levels.

// Global PRNG instance
sjcl.random.randomWords(nwords, paranoia);
sjcl.random.addEntropy(data, estimatedEntropy, source);
sjcl.random.isReady(paranoia);

// PRNG class for custom instances
new sjcl.prng(defaultParanoia);

Random Number Generation

Elliptic Curve Cryptography

Complete elliptic curve cryptography implementation with support for ECDSA signatures, ECDH key agreement, and ElGamal encryption over multiple standard curves.

// Key generation
sjcl.ecc.ecdsa.generateKeys(curve, paranoia);
sjcl.ecc.ecdh.generateKeys(curve, paranoia);
sjcl.ecc.elGamal.generateKeys(curve, paranoia);

// Available curves
sjcl.ecc.curves.c192;
sjcl.ecc.curves.c224;
sjcl.ecc.curves.c256;
sjcl.ecc.curves.c384;
sjcl.ecc.curves.c521;
sjcl.ecc.curves.k256; // secp256k1

Elliptic Curve Cryptography

Key Exchange

Secure Remote Password (SRP) protocol implementation for password-authenticated key agreement without transmitting passwords.

sjcl.keyexchange.srp.makeVerifier(I, P, s, group);
sjcl.keyexchange.srp.makeX(I, P, s);

Key Exchange

Bit Array Utilities

Low-level bit manipulation utilities for working with SJCL's internal bit array format, essential for advanced cryptographic operations.

sjcl.bitArray.bitSlice(a, bstart, bend);
sjcl.bitArray.concat(a1, a2);
sjcl.bitArray.bitLength(a);
sjcl.bitArray.equal(a, b);

Bit Array Utilities

Big Number Arithmetic

Arbitrary precision integer arithmetic for cryptographic operations requiring large number support.

new sjcl.bn(it);

Big Number Arithmetic

Error Handling

SJCL provides specific exception types for different error conditions:

// Exception constructors
new sjcl.exception.corrupt(message);    // Ciphertext corruption
new sjcl.exception.invalid(message);    // Invalid parameters
new sjcl.exception.bug(message);        // Library bugs
new sjcl.exception.notReady(message);   // PRNG not ready

Types

SJCL uses JavaScript's dynamic typing with the following key data structures:

// Bit arrays: Arrays of 32-bit integers representing binary data
type BitArray = number[];

// Word arrays: 32-bit integers used in cryptographic operations  
type Word = number;

// Paranoia levels: 0-10 scale for PRNG entropy requirements
type ParanoiaLevel = number;

// Cipher instances: Objects with encrypt/decrypt methods
interface Cipher {
  encrypt(data: BitArray): BitArray;
  decrypt(data: BitArray): BitArray;
}

// Hash instances: Objects for streaming hash operations
interface Hash {
  blockSize: number;
  reset(): Hash;
  update(data: BitArray | string): Hash;
  finalize(): BitArray;
}