0
# SJCL (Stanford JavaScript Crypto Library)
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: sjcl
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install sjcl`
10

11
## Core Imports
12

13
```javascript
14
// CommonJS (primary)
15
const sjcl = require('sjcl');
16

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

20
// Browser script tag
21
<script src="sjcl.js"></script>
22
```
23

24
## Basic Usage
25

26
```javascript
27
const sjcl = require('sjcl');
28

29
// Simple encryption/decryption
30
const password = "mySecretPassword";
31
const plaintext = "Hello, World!";
32

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

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

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

46
// Random number generation
47
const randomBytes = sjcl.random.randomWords(4); // 4 32-bit words
48
const hexRandom = sjcl.codec.hex.fromBits(randomBytes);
49
```
50

51
## Architecture
52

53
SJCL is organized around several key architectural components:
54

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

62
## Capabilities
63

64
### High-Level Encryption
65

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

68
```javascript { .api }
69
function encrypt(password, plaintext, params, rp);
70
function decrypt(password, ciphertext, params, rp);
71
```
72

73
[High-Level Encryption](./high-level-encryption.md)
74

75
### Hash Functions
76

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

79
```javascript { .api }
80
// Static hash functions
81
sjcl.hash.sha256.hash(data);
82
sjcl.hash.sha1.hash(data);
83
sjcl.hash.sha512.hash(data);
84
sjcl.hash.ripemd160.hash(data);
85

86
// Streaming hash constructors
87
new sjcl.hash.sha256(hash);
88
new sjcl.hash.sha1(hash);
89
new sjcl.hash.sha512(hash);
90
new sjcl.hash.ripemd160(hash);
91
```
92

93
[Hash Functions](./hash-functions.md)
94

95
### Symmetric Encryption
96

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

99
```javascript { .api }
100
// AES cipher constructor
101
new sjcl.cipher.aes(key);
102
```
103

104
[Symmetric Encryption](./symmetric-encryption.md)
105

106
### Cipher Modes
107

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

110
```javascript { .api }
111
// Authenticated modes
112
sjcl.mode.ccm.encrypt(prf, plaintext, iv, adata, tlen);
113
sjcl.mode.gcm.encrypt(prf, plaintext, iv, adata, tlen);
114
sjcl.mode.ocb2.encrypt(prp, plaintext, iv, adata, tlen, premac);
115

116
// Traditional modes  
117
sjcl.mode.cbc.encrypt(prp, plaintext, iv, adata);
118
sjcl.mode.ctr.encrypt(prf, plaintext, iv, adata);
119
```
120

121
[Cipher Modes](./cipher-modes.md)
122

123
### Key Derivation
124

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

127
```javascript { .api }
128
sjcl.misc.pbkdf2(password, salt, count, length, Prff);
129
sjcl.misc.scrypt(password, salt, N, r, p, length, Prff);
130
sjcl.misc.hkdf(ikm, keyBitLength, salt, info, Hash);
131
```
132

133
[Key Derivation](./key-derivation.md)
134

135
### Message Authentication
136

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

139
```javascript { .api }
140
// HMAC constructor and methods
141
new sjcl.misc.hmac(key, Hash);
142
```
143

144
[Message Authentication](./message-authentication.md)
145

146
### Data Encoding
147

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

150
```javascript { .api }
151
// Primary codecs
152
sjcl.codec.utf8String.toBits(str);
153
sjcl.codec.utf8String.fromBits(arr);
154
sjcl.codec.hex.toBits(str);
155
sjcl.codec.hex.fromBits(arr);
156
sjcl.codec.base64.toBits(str, _url);
157
sjcl.codec.base64.fromBits(arr, _noEquals, _url);
158
```
159

160
[Data Encoding](./data-encoding.md)
161

162
### Random Number Generation
163

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

166
```javascript { .api }
167
// Global PRNG instance
168
sjcl.random.randomWords(nwords, paranoia);
169
sjcl.random.addEntropy(data, estimatedEntropy, source);
170
sjcl.random.isReady(paranoia);
171

172
// PRNG class for custom instances
173
new sjcl.prng(defaultParanoia);
174
```
175

176
[Random Number Generation](./random-number-generation.md)
177

178
### Elliptic Curve Cryptography
179

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

182
```javascript { .api }
183
// Key generation
184
sjcl.ecc.ecdsa.generateKeys(curve, paranoia);
185
sjcl.ecc.ecdh.generateKeys(curve, paranoia);
186
sjcl.ecc.elGamal.generateKeys(curve, paranoia);
187

188
// Available curves
189
sjcl.ecc.curves.c192;
190
sjcl.ecc.curves.c224;
191
sjcl.ecc.curves.c256;
192
sjcl.ecc.curves.c384;
193
sjcl.ecc.curves.c521;
194
sjcl.ecc.curves.k256; // secp256k1
195
```
196

197
[Elliptic Curve Cryptography](./elliptic-curve-cryptography.md)
198

199
### Key Exchange
200

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

203
```javascript { .api }
204
sjcl.keyexchange.srp.makeVerifier(I, P, s, group);
205
sjcl.keyexchange.srp.makeX(I, P, s);
206
```
207

208
[Key Exchange](./key-exchange.md)
209

210
### Bit Array Utilities
211

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

214
```javascript { .api }
215
sjcl.bitArray.bitSlice(a, bstart, bend);
216
sjcl.bitArray.concat(a1, a2);
217
sjcl.bitArray.bitLength(a);
218
sjcl.bitArray.equal(a, b);
219
```
220

221
[Bit Array Utilities](./bit-array-utilities.md)
222

223
### Big Number Arithmetic
224

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

227
```javascript { .api }
228
new sjcl.bn(it);
229
```
230

231
[Big Number Arithmetic](./big-number-arithmetic.md)
232

233
## Error Handling
234

235
SJCL provides specific exception types for different error conditions:
236

237
```javascript { .api }
238
// Exception constructors
239
new sjcl.exception.corrupt(message);    // Ciphertext corruption
240
new sjcl.exception.invalid(message);    // Invalid parameters
241
new sjcl.exception.bug(message);        // Library bugs
242
new sjcl.exception.notReady(message);   // PRNG not ready
243
```
244

245
## Types
246

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

249
```javascript { .api }
250
// Bit arrays: Arrays of 32-bit integers representing binary data
251
type BitArray = number[];
252

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

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

259
// Cipher instances: Objects with encrypt/decrypt methods
260
interface Cipher {
261
  encrypt(data: BitArray): BitArray;
262
  decrypt(data: BitArray): BitArray;
263
}
264

265
// Hash instances: Objects for streaming hash operations
266
interface Hash {
267
  blockSize: number;
268
  reset(): Hash;
269
  update(data: BitArray | string): Hash;
270
  finalize(): BitArray;
271
}
272
```