0
# Symmetric Encryption
1

2
Symmetric encryption algorithms using the same key for both encryption and decryption. Supports AES in multiple modes and legacy DES algorithms.
3

4
## Capabilities
5

6
### AES (Advanced Encryption Standard)
7

8
AES encryption support in multiple modes with key sizes of 128, 192, or 256 bits.
9

10
```typescript { .api }
11
/**
12
 * AES key generation parameters
13
 */
14
interface AesKeyGenParams extends Algorithm {
15
  name: "AES-CBC" | "AES-CTR" | "AES-GCM" | "AES-ECB" | "AES-KW" | "AES-CMAC";
16
  length: 128 | 192 | 256;
17
}
18
```
19

20
**Usage Example:**
21

22
```typescript
23
// Generate AES-256 key for GCM mode
24
const key = await crypto.subtle.generateKey(
25
  { name: "AES-GCM", length: 256 },
26
  true,
27
  ["encrypt", "decrypt"]
28
);
29
```
30

31
### AES-CBC (Cipher Block Chaining)
32

33
Block cipher mode with initialization vector for semantic security.
34

35
```typescript { .api }
36
/**
37
 * AES-CBC encryption/decryption parameters
38
 */
39
interface AesCbcParams extends Algorithm {
40
  name: "AES-CBC";
41
  iv: BufferSource; // 16 bytes initialization vector
42
}
43
```
44

45
**Usage Example:**
46

47
```typescript
48
const key = await crypto.subtle.generateKey(
49
  { name: "AES-CBC", length: 256 },
50
  false,
51
  ["encrypt", "decrypt"]
52
);
53

54
const iv = crypto.getRandomValues(new Uint8Array(16));
55
const data = new TextEncoder().encode("Secret message");
56

57
const encrypted = await crypto.subtle.encrypt(
58
  { name: "AES-CBC", iv },
59
  key,
60
  data
61
);
62

63
const decrypted = await crypto.subtle.decrypt(
64
  { name: "AES-CBC", iv },
65
  key,
66
  encrypted
67
);
68
```
69

70
### AES-CTR (Counter Mode)
71

72
Stream cipher mode using counter for encryption without padding.
73

74
```typescript { .api }
75
/**
76
 * AES-CTR encryption/decryption parameters
77
 */
78
interface AesCtrParams extends Algorithm {
79
  name: "AES-CTR";
80
  counter: BufferSource; // 16 bytes counter block
81
  length: number; // Counter length in bits (1-128)
82
}
83
```
84

85
**Usage Example:**
86

87
```typescript
88
const key = await crypto.subtle.generateKey(
89
  { name: "AES-CTR", length: 256 },
90
  false,
91
  ["encrypt", "decrypt"]
92
);
93

94
const counter = crypto.getRandomValues(new Uint8Array(16));
95
const data = new TextEncoder().encode("Stream cipher data");
96

97
const encrypted = await crypto.subtle.encrypt(
98
  { name: "AES-CTR", counter, length: 64 },
99
  key,
100
  data
101
);
102
```
103

104
### AES-GCM (Galois/Counter Mode)
105

106
Authenticated encryption providing both confidentiality and authenticity.
107

108
```typescript { .api }
109
/**
110
 * AES-GCM encryption/decryption parameters
111
 */
112
interface AesGcmParams extends Algorithm {
113
  name: "AES-GCM";
114
  iv: BufferSource; // Initialization vector (12 bytes recommended)
115
  additionalData?: BufferSource; // Additional authenticated data (AAD)
116
  tagLength?: 32 | 64 | 96 | 104 | 112 | 120 | 128; // Authentication tag length in bits
117
}
118
```
119

120
**Usage Example:**
121

122
```typescript
123
const key = await crypto.subtle.generateKey(
124
  { name: "AES-GCM", length: 256 },
125
  false,
126
  ["encrypt", "decrypt"]
127
);
128

129
const iv = crypto.getRandomValues(new Uint8Array(12));
130
const additionalData = new TextEncoder().encode("authenticated-data");
131
const data = new TextEncoder().encode("Authenticated encrypted message");
132

133
const encrypted = await crypto.subtle.encrypt(
134
  { 
135
    name: "AES-GCM", 
136
    iv, 
137
    additionalData,
138
    tagLength: 128
139
  },
140
  key,
141
  data
142
);
143

144
const decrypted = await crypto.subtle.decrypt(
145
  { 
146
    name: "AES-GCM", 
147
    iv, 
148
    additionalData,
149
    tagLength: 128
150
  },
151
  key,
152
  encrypted
153
);
154
```
155

156
### AES-ECB (Electronic Codebook)
157

158
Basic block cipher mode without initialization vector (not recommended for production).
159

160
```typescript { .api }
161
/**
162
 * AES-ECB encryption/decryption parameters
163
 */
164
interface AesEcbParams extends Algorithm {
165
  name: "AES-ECB";
166
}
167
```
168

169
### AES-KW (Key Wrap)
170

171
Key wrapping algorithm for securely encrypting cryptographic keys.
172

173
```typescript { .api }
174
/**
175
 * AES-KW key wrapping parameters
176
 */
177
interface AesKwParams extends Algorithm {
178
  name: "AES-KW";
179
}
180
```
181

182
**Usage Example:**
183

184
```typescript
185
const kek = await crypto.subtle.generateKey(
186
  { name: "AES-KW", length: 256 },
187
  false,
188
  ["wrapKey", "unwrapKey"]
189
);
190

191
const keyToWrap = await crypto.subtle.generateKey(
192
  { name: "AES-GCM", length: 128 },
193
  true,
194
  ["encrypt", "decrypt"]
195
);
196

197
const wrappedKey = await crypto.subtle.wrapKey(
198
  "raw",
199
  keyToWrap,
200
  kek,
201
  { name: "AES-KW" }
202
);
203

204
const unwrappedKey = await crypto.subtle.unwrapKey(
205
  "raw",
206
  wrappedKey,
207
  kek,
208
  { name: "AES-KW" },
209
  { name: "AES-GCM" },
210
  true,
211
  ["encrypt", "decrypt"]
212
);
213
```
214

215
### AES-CMAC (Cipher-based Message Authentication Code)
216

217
Message authentication using AES for integrity verification.
218

219
```typescript { .api }
220
/**
221
 * AES-CMAC signing/verification parameters
222
 */
223
interface AesCmacParams extends Algorithm {
224
  name: "AES-CMAC";
225
}
226
```
227

228
**Usage Example:**
229

230
```typescript
231
const key = await crypto.subtle.generateKey(
232
  { name: "AES-CMAC", length: 256 },
233
  false,
234
  ["sign", "verify"]
235
);
236

237
const data = new TextEncoder().encode("Message to authenticate");
238

239
const signature = await crypto.subtle.sign(
240
  { name: "AES-CMAC" },
241
  key,
242
  data
243
);
244

245
const isValid = await crypto.subtle.verify(
246
  { name: "AES-CMAC" },
247
  key,
248
  signature,
249
  data
250
);
251
```
252

253
### DES (Data Encryption Standard)
254

255
Legacy encryption algorithms for compatibility (use with caution).
256

257
```typescript { .api }
258
/**
259
 * DES-CBC key generation parameters
260
 */
261
interface DesKeyGenParams extends Algorithm {
262
  name: "DES-CBC";
263
  length: 64; // DES key length is always 64 bits
264
}
265

266
/**
267
 * DES-CBC encryption/decryption parameters
268
 */
269
interface DesCbcParams extends Algorithm {
270
  name: "DES-CBC";
271
  iv: BufferSource; // 8 bytes initialization vector
272
}
273

274
/**
275
 * 3DES-EDE-CBC key generation parameters
276
 */
277
interface DesEde3KeyGenParams extends Algorithm {
278
  name: "DES-EDE3-CBC";
279
  length: 192; // Triple DES key length is 192 bits
280
}
281

282
/**
283
 * 3DES-EDE-CBC encryption/decryption parameters
284
 */
285
interface DesEde3CbcParams extends Algorithm {
286
  name: "DES-EDE3-CBC";
287
  iv: BufferSource; // 8 bytes initialization vector
288
}
289
```
290

291
**Usage Example:**
292

293
```typescript
294
// Triple DES example (DES-CBC availability is platform-dependent)
295
const key = await crypto.subtle.generateKey(
296
  { name: "DES-EDE3-CBC", length: 192 },
297
  false,
298
  ["encrypt", "decrypt"]
299
);
300

301
const iv = crypto.getRandomValues(new Uint8Array(8));
302
const data = new TextEncoder().encode("Legacy encrypted data");
303

304
const encrypted = await crypto.subtle.encrypt(
305
  { name: "DES-EDE3-CBC", iv },
306
  key,
307
  data
308
);
309
```
310

311
## Key Classes
312

313
### AesCryptoKey
314

315
AES symmetric key implementation.
316

317
```typescript { .api }
318
/**
319
 * AES symmetric cryptographic key
320
 */
321
class AesCryptoKey extends SymmetricKey {
322
  public algorithm: AesKeyAlgorithm;
323
  public type: "secret";
324
  public usages: KeyUsage[];
325
  public extractable: boolean;
326
}
327

328
interface AesKeyAlgorithm extends KeyAlgorithm {
329
  name: "AES-CBC" | "AES-CTR" | "AES-GCM" | "AES-ECB" | "AES-KW" | "AES-CMAC";
330
  length: 128 | 192 | 256;
331
}
332
```
333

334
### DesCryptoKey
335

336
DES symmetric key implementation.
337

338
```typescript { .api }
339
/**
340
 * DES symmetric cryptographic key
341
 */
342
class DesCryptoKey extends SymmetricKey {
343
  public algorithm: DesKeyAlgorithm;
344
  public type: "secret";
345
  public usages: KeyUsage[];
346
  public extractable: boolean;
347
}
348

349
interface DesKeyAlgorithm extends KeyAlgorithm {
350
  name: "DES-CBC" | "DES-EDE3-CBC";
351
  length: 64 | 192;
352
}
353
```
354

355
## Error Handling
356

357
Common errors when working with symmetric encryption:
358

359
- **OperationError**: Invalid key length, incorrect IV size, or authentication failure
360
- **InvalidAccessError**: Key usage doesn't permit the requested operation
361
- **NotSupportedError**: Algorithm not supported on current platform (e.g., DES-CBC)
362
- **DataError**: Invalid parameter values or malformed encrypted data
363

364
```typescript
365
try {
366
  const encrypted = await crypto.subtle.encrypt(algorithm, key, data);
367
} catch (error) {
368
  if (error.name === "OperationError") {
369
    // Handle encryption/decryption failures
370
  } else if (error.name === "InvalidAccessError") {
371
    // Handle key usage violations
372
  }
373
}
374
```