0
# Symmetric Encryption
1

2
Block cipher implementations including AES, DES, and RC2 with support for various modes (CBC, CFB, OFB, CTR, GCM). Node-forge provides a unified cipher interface for all symmetric encryption algorithms with consistent API patterns.
3

4
## Capabilities
5

6
### Cipher Creation
7

8
Create encryption and decryption ciphers for symmetric algorithms.
9

10
```javascript { .api }
11
/**
12
 * Create a cipher for encryption
13
 * @param algorithm - Algorithm name (e.g., 'AES-CBC', 'DES-EDE3-CBC', 'RC2-CBC')
14
 * @param key - Encryption key as binary string or ByteStringBuffer
15
 * @returns BlockCipher instance for encryption
16
 */
17
forge.cipher.createCipher(algorithm: string, key: string | ByteStringBuffer): BlockCipher;
18

19
/**
20
 * Create a decipher for decryption
21
 * @param algorithm - Algorithm name (e.g., 'AES-CBC', 'DES-EDE3-CBC', 'RC2-CBC')
22
 * @param key - Decryption key as binary string or ByteStringBuffer
23
 * @returns BlockCipher instance for decryption
24
 */
25
forge.cipher.createDecipher(algorithm: string, key: string | ByteStringBuffer): BlockCipher;
26

27
interface BlockCipher {
28
  /** Start the cipher operation with optional parameters */
29
  start(options?: CipherOptions): void;
30
  /** Update cipher with input data */
31
  update(input?: ByteStringBuffer): void;
32
  /** Complete the cipher operation */
33
  finish(pad?: (input: ByteStringBuffer) => void): boolean;
34
  /** Output buffer containing processed data */
35
  output: ByteStringBuffer;
36
  /** Block size for the cipher algorithm */
37
  blockSize: number;
38
}
39

40
interface CipherOptions {
41
  /** Initialization vector for modes that require it */
42
  iv?: string | ByteStringBuffer;
43
  /** Additional authenticated data for GCM mode */
44
  additionalData?: string;
45
  /** Authentication tag length for GCM mode (default: 128 bits) */
46
  tagLength?: number;
47
  /** Authentication tag for GCM decryption */
48
  tag?: string | ByteStringBuffer;
49
  /** Output buffer (optional) */
50
  output?: ByteStringBuffer;
51
}
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
const forge = require('node-forge');
58

59
// AES-CBC Encryption
60
const key = forge.random.getBytesSync(32); // 256-bit key
61
const iv = forge.random.getBytesSync(16);  // 128-bit IV
62

63
const cipher = forge.cipher.createCipher('AES-CBC', key);
64
cipher.start({iv: iv});
65
cipher.update(forge.util.createBuffer('secret message'));
66
cipher.finish();
67
const encrypted = cipher.output.getBytes();
68

69
// AES-CBC Decryption
70
const decipher = forge.cipher.createDecipher('AES-CBC', key);
71
decipher.start({iv: iv});
72
decipher.update(forge.util.createBuffer(encrypted));
73
decipher.finish();
74
const decrypted = decipher.output.toString();
75

76
// AES-GCM with authentication
77
const gcmCipher = forge.cipher.createCipher('AES-GCM', key);
78
gcmCipher.start({
79
  iv: iv,
80
  additionalData: 'authenticated but not encrypted data',
81
  tagLength: 128
82
});
83
gcmCipher.update(forge.util.createBuffer('confidential message'));
84
gcmCipher.finish();
85
const encryptedGcm = gcmCipher.output.getBytes();
86
const authTag = gcmCipher.mode.tag.getBytes();
87
```
88

89
### Supported Algorithms
90

91
Node-forge supports multiple symmetric cipher algorithms with various modes.
92

93
```javascript { .api }
94
// AES (Advanced Encryption Standard)
95
'AES-CBC'     // AES with CBC mode
96
'AES-CFB'     // AES with CFB mode  
97
'AES-OFB'     // AES with OFB mode
98
'AES-CTR'     // AES with CTR mode
99
'AES-GCM'     // AES with GCM mode (authenticated encryption)
100

101
// 3DES (Triple DES)
102
'DES-EDE3-CBC' // 3DES with CBC mode
103
'DES-EDE3-CFB' // 3DES with CFB mode
104
'DES-EDE3-OFB' // 3DES with OFB mode
105

106
// DES (Data Encryption Standard)
107
'DES-CBC'     // DES with CBC mode
108
'DES-CFB'     // DES with CFB mode
109
'DES-OFB'     // DES with OFB mode
110

111
// RC2
112
'RC2-CBC'     // RC2 with CBC mode
113
'RC2-CFB'     // RC2 with CFB mode
114
'RC2-OFB'     // RC2 with OFB mode
115
```
116

117
### AES-Specific Functions
118

119
Direct AES cipher creation with legacy API support.
120

121
```javascript { .api }
122
/**
123
 * Create AES encryption cipher (legacy API)
124
 * @param key - AES key (128, 192, or 256 bits)
125
 * @param mode - Cipher mode (default: 'CBC')
126
 * @returns AES encryption cipher
127
 * @deprecated Use forge.cipher.createCipher('AES-<mode>', key) instead
128
 */
129
forge.aes.createEncryptionCipher(key: string | ByteStringBuffer, mode?: string): BlockCipher;
130

131
/**
132
 * Create AES decryption cipher (legacy API)
133
 * @param key - AES key (128, 192, or 256 bits)
134
 * @param mode - Cipher mode (default: 'CBC')
135
 * @returns AES decryption cipher
136
 * @deprecated Use forge.cipher.createDecipher('AES-<mode>', key) instead
137
 */
138
forge.aes.createDecryptionCipher(key: string | ByteStringBuffer, mode?: string): BlockCipher;
139
```
140

141
### Cipher Mode Operations
142

143
Different cipher modes provide various security and performance characteristics.
144

145
**CBC (Cipher Block Chaining):**
146
- Requires IV (Initialization Vector)
147
- Sequential processing
148
- Good for data at rest
149
- Requires padding for partial blocks
150

151
**CFB (Cipher Feedback):**
152
- Requires IV
153
- Stream cipher mode
154
- No padding required
155
- Good for real-time data
156

157
**OFB (Output Feedback):**
158
- Requires IV  
159
- Stream cipher mode
160
- No padding required
161
- Synchronous stream cipher
162

163
**CTR (Counter Mode):**
164
- Requires IV/counter
165
- Stream cipher mode
166
- Parallelizable
167
- No padding required
168

169
**GCM (Galois/Counter Mode):**
170
- Authenticated encryption
171
- Requires IV
172
- Provides authenticity and confidentiality
173
- Additional authenticated data support
174

175
**Usage Examples:**
176

177
```javascript
178
// CBC Mode with padding
179
const cbcCipher = forge.cipher.createCipher('AES-CBC', key);
180
cbcCipher.start({iv: iv});
181
cbcCipher.update(forge.util.createBuffer('data that needs padding'));
182
cbcCipher.finish(); // Automatic PKCS#7 padding
183

184
// CTR Mode (no padding needed)
185
const ctrCipher = forge.cipher.createCipher('AES-CTR', key);
186
ctrCipher.start({iv: iv});
187
ctrCipher.update(forge.util.createBuffer('any length data'));
188
ctrCipher.finish();
189

190
// GCM Mode with authentication
191
const gcmCipher = forge.cipher.createCipher('AES-GCM', key);
192
gcmCipher.start({
193
  iv: forge.random.getBytesSync(12), // 96-bit IV recommended for GCM
194
  additionalData: 'metadata'
195
});
196
gcmCipher.update(forge.util.createBuffer('authenticated and encrypted'));
197
gcmCipher.finish();
198
const tag = gcmCipher.mode.tag.getBytes(); // Store tag for verification
199
```
200

201
### Key Length Requirements
202

203
Different algorithms require specific key lengths.
204

205
```javascript { .api }
206
// AES Key Lengths
207
AES_128_KEY_LENGTH = 16;  // 128-bit key (16 bytes)
208
AES_192_KEY_LENGTH = 24;  // 192-bit key (24 bytes)  
209
AES_256_KEY_LENGTH = 32;  // 256-bit key (32 bytes)
210

211
// DES Key Lengths
212
DES_KEY_LENGTH = 8;       // 64-bit key (8 bytes, 56 effective)
213
DES_EDE3_KEY_LENGTH = 24; // 192-bit key (24 bytes) for 3DES
214

215
// RC2 Key Lengths
216
RC2_KEY_LENGTH_MIN = 1;   // Minimum 8-bit key
217
RC2_KEY_LENGTH_MAX = 128; // Maximum 1024-bit key
218
```
219

220
**Key Generation Examples:**
221

222
```javascript
223
// Generate secure random keys
224
const aes128Key = forge.random.getBytesSync(16);  // 128-bit AES key
225
const aes256Key = forge.random.getBytesSync(32);  // 256-bit AES key
226
const desKey = forge.random.getBytesSync(8);      // DES key
227
const des3Key = forge.random.getBytesSync(24);    // 3DES key
228

229
// Derive key from password using PBKDF2
230
const salt = forge.random.getBytesSync(16);
231
const derivedKey = forge.pkcs5.pbkdf2('password', salt, 100000, 32);
232
```
233

234
### Algorithm Registry
235

236
Register custom cipher algorithms with the cipher framework.
237

238
```javascript { .api }
239
/**
240
 * Register a cipher algorithm
241
 * @param name - Algorithm name
242
 * @param algorithm - Algorithm implementation factory function
243
 */
244
forge.cipher.registerAlgorithm(name: string, algorithm: () => CipherAlgorithm): void;
245

246
/**
247
 * Get registered cipher algorithm
248
 * @param name - Algorithm name
249
 * @returns Algorithm factory function or null
250
 */
251
forge.cipher.getAlgorithm(name: string): (() => CipherAlgorithm) | null;
252

253
/**
254
 * Registry of all cipher algorithms
255
 */
256
forge.cipher.algorithms: {[name: string]: () => CipherAlgorithm};
257

258
interface CipherAlgorithm {
259
  initialize(options: any): void;
260
  encryptBlock(input: number[], output: number[]): void;
261
  decryptBlock(input: number[], output: number[]): void;
262
}
263
```
264

265
### Low-Level Cipher Modes
266

267
Direct access to cipher mode implementations for advanced use cases.
268

269
```javascript { .api }
270
/**
271
 * Electronic Codebook (ECB) mode - DO NOT USE for production (insecure)
272
 * @param options - Configuration options including cipher and blockSize
273
 * @returns ECB mode instance
274
 */
275
forge.cipher.modes.ecb(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;
276

277
/**
278
 * Cipher Block Chaining (CBC) mode
279
 * @param options - Configuration options including cipher and blockSize
280
 * @returns CBC mode instance
281
 */
282
forge.cipher.modes.cbc(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;
283

284
/**
285
 * Cipher Feedback (CFB) mode
286
 * @param options - Configuration options including cipher and blockSize
287
 * @returns CFB mode instance
288
 */
289
forge.cipher.modes.cfb(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;
290

291
/**
292
 * Output Feedback (OFB) mode  
293
 * @param options - Configuration options including cipher and blockSize
294
 * @returns OFB mode instance
295
 */
296
forge.cipher.modes.ofb(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;
297

298
/**
299
 * Counter (CTR) mode
300
 * @param options - Configuration options including cipher and blockSize
301
 * @returns CTR mode instance
302
 */
303
forge.cipher.modes.ctr(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;
304

305
/**
306
 * Galois/Counter Mode (GCM) for authenticated encryption
307
 * @param options - Configuration options including cipher and blockSize
308
 * @returns GCM mode instance
309
 */
310
forge.cipher.modes.gcm(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;
311

312
interface CipherMode {
313
  name: string;
314
  cipher: CipherAlgorithm;
315
  blockSize: number;
316
  
317
  start(options: {iv?: ByteStringBuffer, additionalData?: string, tagLength?: number}): void;
318
  encrypt(input: ByteStringBuffer, output: ByteStringBuffer, finish?: boolean): boolean;
319
  decrypt(input: ByteStringBuffer, output: ByteStringBuffer, finish?: boolean): boolean;
320
  pad?(input: ByteStringBuffer, options: any): boolean;
321
  unpad?(output: ByteStringBuffer, options: any): boolean;
322
}
323
```
324

325
### Error Handling
326

327
Common error conditions when using symmetric ciphers.
328

329
```javascript
330
try {
331
  const cipher = forge.cipher.createCipher('AES-CBC', key);
332
  cipher.start({iv: iv});
333
  cipher.update(forge.util.createBuffer(data));
334
  
335
  if (!cipher.finish()) {
336
    throw new Error('Cipher operation failed - possibly incorrect padding');
337
  }
338
  
339
  const result = cipher.output.getBytes();
340
} catch (error) {
341
  // Handle errors:
342
  // - 'Unsupported algorithm' for unknown cipher names
343
  // - Invalid key length for the chosen algorithm  
344
  // - Missing or invalid IV for modes that require it
345
  // - Padding errors during decryption
346
  // - Authentication failures for GCM mode
347
  console.error('Cipher operation failed:', error.message);
348
}
349
```