0
# High-Level Encryption
1

2
SJCL provides simple, secure encryption and decryption functions that handle all the cryptographic complexity internally, making it easy to encrypt data with just a password.
3

4
## Capabilities
5

6
### Simple Encryption
7

8
Encrypts plaintext using a password with secure defaults including authenticated encryption.
9

10
```javascript { .api }
11
/**
12
 * Encrypt plaintext with a password using secure defaults
13
 * @param {string} password - Password for encryption
14
 * @param {string} plaintext - Data to encrypt
15
 * @param {Object} [params] - Optional encryption parameters
16
 * @param {Object} [rp] - Optional progress callback parameters
17
 * @returns {string} JSON string containing encrypted data and parameters
18
 */
19
function encrypt(password, plaintext, params, rp);
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
const sjcl = require('sjcl');
26

27
// Basic encryption
28
const encrypted = sjcl.encrypt("myPassword", "Hello, World!");
29
console.log(encrypted);
30
// Returns: '{"iv":"...","v":1,"iter":10000,"ks":128,"ts":64,"mode":"ccm","adata":"","cipher":"aes","salt":"...","ct":"..."}'
31

32
// With custom parameters
33
const customParams = {
34
  mode: "gcm",
35
  ts: 128,        // tag size in bits
36
  ks: 256,        // key size in bits  
37
  iter: 100000    // PBKDF2 iterations
38
};
39
const encrypted2 = sjcl.encrypt("myPassword", "Hello, World!", customParams);
40
```
41

42
### Simple Decryption
43

44
Decrypts ciphertext that was encrypted with the encrypt function.
45

46
```javascript { .api }
47
/**
48
 * Decrypt ciphertext encrypted with sjcl.encrypt
49
 * @param {string} password - Password used for encryption
50
 * @param {string} ciphertext - JSON string from encrypt function
51
 * @param {Object} [params] - Optional decryption parameters
52
 * @param {Object} [rp] - Optional progress callback parameters
53
 * @returns {string} Decrypted plaintext
54
 * @throws {sjcl.exception.corrupt} If ciphertext is invalid or password is wrong
55
 * @throws {sjcl.exception.invalid} If parameters are invalid
56
 */
57
function decrypt(password, ciphertext, params, rp);
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
const sjcl = require('sjcl');
64

65
// Decrypt data
66
try {
67
  const decrypted = sjcl.decrypt("myPassword", encryptedData);
68
  console.log(decrypted); // "Hello, World!"
69
} catch (e) {
70
  if (e instanceof sjcl.exception.corrupt) {
71
    console.error("Invalid ciphertext or wrong password");
72
  } else if (e instanceof sjcl.exception.invalid) {
73
    console.error("Invalid parameters");
74
  }
75
}
76
```
77

78
## JSON Format
79

80
### JSON Encryption
81

82
Encrypts data and returns a structured JSON object instead of a string.
83

84
```javascript { .api }
85
/**
86
 * Encrypt plaintext and return JSON object
87
 * @param {string} password - Password for encryption
88
 * @param {string} plaintext - Data to encrypt
89
 * @param {Object} [params] - Optional encryption parameters
90
 * @param {Object} [rp] - Optional progress callback parameters
91
 * @returns {string} JSON string with encryption data
92
 */
93
sjcl.json.encrypt(password, plaintext, params, rp);
94

95
/**
96
 * Internal encryption returning raw object
97
 * @param {string} password - Password for encryption
98
 * @param {string} plaintext - Data to encrypt
99
 * @param {Object} [params] - Optional encryption parameters
100
 * @param {Object} [rp] - Optional progress callback parameters
101
 * @returns {Object} Raw encryption object (not JSON string)
102
 */
103
sjcl.json._encrypt(password, plaintext, params, rp);
104
```
105

106
### JSON Decryption
107

108
Decrypts JSON-formatted ciphertext.
109

110
```javascript { .api }
111
/**
112
 * Decrypt JSON-formatted ciphertext
113
 * @param {string} password - Password used for encryption
114
 * @param {string} ciphertext - JSON string to decrypt
115
 * @param {Object} [params] - Optional decryption parameters
116
 * @param {Object} [rp] - Optional progress callback parameters
117
 * @returns {string} Decrypted plaintext
118
 */
119
sjcl.json.decrypt(password, ciphertext, params, rp);
120

121
/**
122
 * Internal decryption from raw object
123
 * @param {string} password - Password used for encryption
124
 * @param {Object} ciphertext - Raw ciphertext object
125
 * @param {Object} [params] - Optional decryption parameters
126
 * @param {Object} [rp] - Optional progress callback parameters
127
 * @returns {string} Decrypted plaintext
128
 */
129
sjcl.json._decrypt(password, ciphertext, params, rp);
130
```
131

132
### JSON Utilities
133

134
Encode and decode JSON with proper formatting.
135

136
```javascript { .api }
137
/**
138
 * Encode object to JSON string
139
 * @param {Object} obj - Object to encode
140
 * @returns {string} JSON string
141
 */
142
sjcl.json.encode(obj);
143

144
/**
145
 * Decode JSON string to object
146
 * @param {string} str - JSON string to decode
147
 * @returns {Object} Parsed object
148
 */
149
sjcl.json.decode(str);
150
```
151

152
## Default Parameters
153

154
SJCL uses secure defaults for encryption parameters:
155

156
```javascript { .api }
157
/**
158
 * Default encryption parameters object
159
 */
160
sjcl.json.defaults = {
161
  v: 1,           // version
162
  iter: 10000,    // PBKDF2 iterations
163
  ks: 128,        // key size in bits (128, 192, or 256)
164
  ts: 64,         // tag size in bits
165
  mode: "ccm",    // cipher mode
166
  cipher: "aes",  // cipher algorithm
167
  // Additional parameters set automatically:
168
  // iv: random initialization vector
169
  // salt: random salt for key derivation
170
};
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
const sjcl = require('sjcl');
177

178
// Use default parameters
179
const encrypted1 = sjcl.encrypt("password", "data");
180

181
// Override specific defaults
182
const params = Object.assign({}, sjcl.json.defaults, {
183
  iter: 100000,  // Higher security
184
  ks: 256,       // Larger key size
185
  mode: "gcm"    // Different mode
186
});
187
const encrypted2 = sjcl.encrypt("password", "data", params);
188

189
// Check what defaults are being used
190
console.log(sjcl.json.defaults);
191
```
192

193
## Cached PBKDF2
194

195
Optimized password-based key derivation with automatic salt generation and caching.
196

197
```javascript { .api }
198
/**
199
 * Cached PBKDF2 with automatic salt generation
200
 * @param {string} password - Password for key derivation
201
 * @param {Object} obj - Object containing salt and other parameters
202
 * @returns {BitArray} Derived key as bit array
203
 */
204
sjcl.misc.cachedPbkdf2(password, obj);
205
```
206

207
**Usage Examples:**
208

209
```javascript
210
const sjcl = require('sjcl');
211

212
// The obj parameter should contain salt and iteration count
213
const params = {
214
  salt: sjcl.random.randomWords(4), // 4 words of random salt
215
  iter: 10000
216
};
217

218
const derivedKey = sjcl.misc.cachedPbkdf2("myPassword", params);
219
```
220

221
## Error Handling
222

223
The high-level encryption functions can throw several types of exceptions:
224

225
```javascript
226
const sjcl = require('sjcl');
227

228
try {
229
  const encrypted = sjcl.encrypt("password", "data");
230
  const decrypted = sjcl.decrypt("password", encrypted);
231
} catch (e) {
232
  if (e instanceof sjcl.exception.corrupt) {
233
    // Ciphertext is corrupted or password is wrong
234
    console.error("Decryption failed: " + e.message);
235
  } else if (e instanceof sjcl.exception.invalid) {
236
    // Invalid parameters provided
237
    console.error("Invalid parameters: " + e.message);
238
  } else if (e instanceof sjcl.exception.notReady) {
239
    // Random number generator not ready
240
    console.error("RNG not ready: " + e.message);
241
  }
242
}
243
```