0
# Authenticated Encryption with Associated Data (AEAD)
1

2
AEAD functions provide encryption that ensures both confidentiality and authenticity. They encrypt the plaintext and authenticate both the encrypted data and optional associated data in a single operation.
3

4
## Supported Algorithms
5

6
- **XChaCha20-Poly1305**: Extended nonce variant, recommended for most applications
7
- **ChaCha20-Poly1305**: Fast, secure cipher with good cross-platform performance  
8
- **AEGIS-128L/256**: High-performance AEAD ciphers with hardware acceleration
9
- **AES-256-GCM**: Hardware-accelerated cipher on supporting platforms
10

11
## XChaCha20-Poly1305 (Recommended)
12

13
The extended nonce variant of ChaCha20-Poly1305, allowing for random nonce generation without collision concerns.
14

15
### Key Generation
16

17
```javascript { .api }
18
/**
19
 * Generate a random key for XChaCha20-Poly1305 AEAD
20
 * @returns Uint8Array - 32-byte key
21
 */
22
function crypto_aead_xchacha20poly1305_ietf_keygen(): Uint8Array;
23
```
24

25
### Encryption
26

27
```javascript { .api }
28
/**
29
 * Encrypt and authenticate data using XChaCha20-Poly1305
30
 * @param message - The plaintext data to encrypt
31
 * @param additional_data - Additional data to authenticate (not encrypted)
32
 * @param secret_nonce - Secret nonce (usually null)
33
 * @param public_nonce - 24-byte nonce (can be random)
34
 * @param key - 32-byte encryption key
35
 * @returns Uint8Array - Encrypted data with authentication tag
36
 */
37
function crypto_aead_xchacha20poly1305_ietf_encrypt(
38
  message: Uint8Array,
39
  additional_data: Uint8Array | null,
40
  secret_nonce: Uint8Array | null,
41
  public_nonce: Uint8Array,
42
  key: Uint8Array
43
): Uint8Array;
44
```
45

46
### Decryption
47

48
```javascript { .api }
49
/**
50
 * Decrypt and verify data using XChaCha20-Poly1305
51
 * @param secret_nonce - Secret nonce (usually null)
52
 * @param ciphertext - Encrypted data with authentication tag
53
 * @param additional_data - Additional authenticated data
54
 * @param public_nonce - 24-byte nonce used for encryption
55
 * @param key - 32-byte decryption key
56
 * @returns Uint8Array - Decrypted plaintext
57
 * @throws Error if authentication fails
58
 */
59
function crypto_aead_xchacha20poly1305_ietf_decrypt(
60
  secret_nonce: Uint8Array | null,
61
  ciphertext: Uint8Array,
62
  additional_data: Uint8Array | null,
63
  public_nonce: Uint8Array,
64
  key: Uint8Array
65
): Uint8Array;
66
```
67

68
### Detached Operations
69

70
```javascript { .api }
71
/**
72
 * Encrypt data with detached authentication tag
73
 * @param message - Plaintext to encrypt
74
 * @param additional_data - Additional authenticated data
75
 * @param secret_nonce - Secret nonce (usually null)
76
 * @param public_nonce - 24-byte nonce
77
 * @param key - 32-byte encryption key
78
 * @returns Object with ciphertext and mac properties
79
 */
80
function crypto_aead_xchacha20poly1305_ietf_encrypt_detached(
81
  message: Uint8Array,
82
  additional_data: Uint8Array | null,
83
  secret_nonce: Uint8Array | null,
84
  public_nonce: Uint8Array,
85
  key: Uint8Array
86
): { ciphertext: Uint8Array; mac: Uint8Array };
87

88
/**
89
 * Decrypt data with separate authentication tag
90
 * @param secret_nonce - Secret nonce (usually null)
91
 * @param ciphertext - Encrypted data (without tag)
92
 * @param mac - Authentication tag
93
 * @param additional_data - Additional authenticated data
94
 * @param public_nonce - 24-byte nonce
95
 * @param key - 32-byte decryption key
96
 * @returns Uint8Array - Decrypted plaintext
97
 * @throws Error if authentication fails
98
 */
99
function crypto_aead_xchacha20poly1305_ietf_decrypt_detached(
100
  secret_nonce: Uint8Array | null,
101
  ciphertext: Uint8Array,
102
  mac: Uint8Array,
103
  additional_data: Uint8Array | null,
104
  public_nonce: Uint8Array,
105
  key: Uint8Array
106
): Uint8Array;
107
```
108

109
### Constants
110

111
```javascript { .api }
112
const crypto_aead_xchacha20poly1305_ietf_KEYBYTES: number;     // 32
113
const crypto_aead_xchacha20poly1305_ietf_NPUBBYTES: number;    // 24
114
const crypto_aead_xchacha20poly1305_ietf_ABYTES: number;       // 16
115
const crypto_aead_xchacha20poly1305_ietf_NSECBYTES: number;    // 0
116
const crypto_aead_xchacha20poly1305_ietf_MESSAGEBYTES_MAX: number; // Large value
117
```
118

119
## ChaCha20-Poly1305 IETF
120

121
Standard ChaCha20-Poly1305 with IETF-compatible nonce size.
122

123
### Key Generation
124

125
```javascript { .api }
126
function crypto_aead_chacha20poly1305_ietf_keygen(): Uint8Array;
127
```
128

129
### Encryption and Decryption
130

131
```javascript { .api }
132
function crypto_aead_chacha20poly1305_ietf_encrypt(
133
  message: Uint8Array,
134
  additional_data: Uint8Array | null,
135
  secret_nonce: Uint8Array | null,
136
  public_nonce: Uint8Array,  // 12 bytes
137
  key: Uint8Array
138
): Uint8Array;
139

140
function crypto_aead_chacha20poly1305_ietf_decrypt(
141
  secret_nonce: Uint8Array | null,
142
  ciphertext: Uint8Array,
143
  additional_data: Uint8Array | null,
144
  public_nonce: Uint8Array,  // 12 bytes
145
  key: Uint8Array
146
): Uint8Array;
147
```
148

149
### Detached Operations
150

151
```javascript { .api }
152
function crypto_aead_chacha20poly1305_ietf_encrypt_detached(
153
  message: Uint8Array,
154
  additional_data: Uint8Array | null,
155
  secret_nonce: Uint8Array | null,
156
  public_nonce: Uint8Array,
157
  key: Uint8Array
158
): { ciphertext: Uint8Array; mac: Uint8Array };
159

160
function crypto_aead_chacha20poly1305_ietf_decrypt_detached(
161
  secret_nonce: Uint8Array | null,
162
  ciphertext: Uint8Array,
163
  mac: Uint8Array,
164
  additional_data: Uint8Array | null,
165
  public_nonce: Uint8Array,
166
  key: Uint8Array
167
): Uint8Array;
168
```
169

170
### Constants
171

172
```javascript { .api }
173
const crypto_aead_chacha20poly1305_ietf_KEYBYTES: number;      // 32
174
const crypto_aead_chacha20poly1305_ietf_NPUBBYTES: number;     // 12
175
const crypto_aead_chacha20poly1305_ietf_ABYTES: number;        // 16
176
const crypto_aead_chacha20poly1305_ietf_NSECBYTES: number;     // 0
177
```
178

179
## AEGIS-256
180

181
High-performance AEAD cipher with excellent security properties.
182

183
### Key Generation
184

185
```javascript { .api }
186
function crypto_aead_aegis256_keygen(): Uint8Array;
187
```
188

189
### Encryption and Decryption
190

191
```javascript { .api }
192
function crypto_aead_aegis256_encrypt(
193
  message: Uint8Array,
194
  additional_data: Uint8Array | null,
195
  secret_nonce: Uint8Array | null,
196
  public_nonce: Uint8Array,  // 32 bytes
197
  key: Uint8Array
198
): Uint8Array;
199

200
function crypto_aead_aegis256_decrypt(
201
  secret_nonce: Uint8Array | null,
202
  ciphertext: Uint8Array,
203
  additional_data: Uint8Array | null,
204
  public_nonce: Uint8Array,
205
  key: Uint8Array
206
): Uint8Array;
207
```
208

209
### Detached Operations
210

211
```javascript { .api }
212
function crypto_aead_aegis256_encrypt_detached(
213
  message: Uint8Array,
214
  additional_data: Uint8Array | null,
215
  secret_nonce: Uint8Array | null,
216
  public_nonce: Uint8Array,
217
  key: Uint8Array
218
): { ciphertext: Uint8Array; mac: Uint8Array };
219

220
function crypto_aead_aegis256_decrypt_detached(
221
  secret_nonce: Uint8Array | null,
222
  ciphertext: Uint8Array,
223
  mac: Uint8Array,
224
  additional_data: Uint8Array | null,
225
  public_nonce: Uint8Array,
226
  key: Uint8Array
227
): Uint8Array;
228
```
229

230
### Constants
231

232
```javascript { .api }
233
const crypto_aead_aegis256_KEYBYTES: number;      // 32
234
const crypto_aead_aegis256_NPUBBYTES: number;     // 32
235
const crypto_aead_aegis256_ABYTES: number;        // 32
236
const crypto_aead_aegis256_NSECBYTES: number;     // 0
237
```
238

239
## AEGIS-128L
240

241
Faster variant of AEGIS with 128-bit security level.
242

243
### API Functions
244

245
```javascript { .api }
246
function crypto_aead_aegis128l_keygen(): Uint8Array;
247

248
function crypto_aead_aegis128l_encrypt(
249
  message: Uint8Array,
250
  additional_data: Uint8Array | null,
251
  secret_nonce: Uint8Array | null,
252
  public_nonce: Uint8Array,  // 16 bytes
253
  key: Uint8Array
254
): Uint8Array;
255

256
function crypto_aead_aegis128l_decrypt(
257
  secret_nonce: Uint8Array | null,
258
  ciphertext: Uint8Array,
259
  additional_data: Uint8Array | null,
260
  public_nonce: Uint8Array,
261
  key: Uint8Array
262
): Uint8Array;
263

264
function crypto_aead_aegis128l_encrypt_detached(
265
  message: Uint8Array,
266
  additional_data: Uint8Array | null,
267
  secret_nonce: Uint8Array | null,
268
  public_nonce: Uint8Array,
269
  key: Uint8Array
270
): { ciphertext: Uint8Array; mac: Uint8Array };
271

272
function crypto_aead_aegis128l_decrypt_detached(
273
  secret_nonce: Uint8Array | null,
274
  ciphertext: Uint8Array,
275
  mac: Uint8Array,
276
  additional_data: Uint8Array | null,
277
  public_nonce: Uint8Array,
278
  key: Uint8Array
279
): Uint8Array;
280
```
281

282
### Constants
283

284
```javascript { .api }
285
const crypto_aead_aegis128l_KEYBYTES: number;      // 16
286
const crypto_aead_aegis128l_NPUBBYTES: number;     // 16
287
const crypto_aead_aegis128l_ABYTES: number;        // 32
288
const crypto_aead_aegis128l_NSECBYTES: number;     // 0
289
```
290

291
## ChaCha20-Poly1305 (Original)
292

293
Original ChaCha20-Poly1305 with 8-byte nonce.
294

295
### API Functions
296

297
```javascript { .api }
298
function crypto_aead_chacha20poly1305_keygen(): Uint8Array;
299

300
function crypto_aead_chacha20poly1305_encrypt(
301
  message: Uint8Array,
302
  additional_data: Uint8Array | null,
303
  secret_nonce: Uint8Array | null,
304
  public_nonce: Uint8Array,  // 8 bytes
305
  key: Uint8Array
306
): Uint8Array;
307

308
function crypto_aead_chacha20poly1305_decrypt(
309
  secret_nonce: Uint8Array | null,
310
  ciphertext: Uint8Array,
311
  additional_data: Uint8Array | null,
312
  public_nonce: Uint8Array,
313
  key: Uint8Array
314
): Uint8Array;
315

316
function crypto_aead_chacha20poly1305_encrypt_detached(
317
  message: Uint8Array,
318
  additional_data: Uint8Array | null,
319
  secret_nonce: Uint8Array | null,
320
  public_nonce: Uint8Array,
321
  key: Uint8Array
322
): { ciphertext: Uint8Array; mac: Uint8Array };
323

324
function crypto_aead_chacha20poly1305_decrypt_detached(
325
  secret_nonce: Uint8Array | null,
326
  ciphertext: Uint8Array,
327
  mac: Uint8Array,
328
  additional_data: Uint8Array | null,
329
  public_nonce: Uint8Array,
330
  key: Uint8Array
331
): Uint8Array;
332
```
333

334
### Constants
335

336
```javascript { .api }
337
const crypto_aead_chacha20poly1305_KEYBYTES: number;       // 32
338
const crypto_aead_chacha20poly1305_NPUBBYTES: number;      // 8
339
const crypto_aead_chacha20poly1305_ABYTES: number;         // 16
340
const crypto_aead_chacha20poly1305_NSECBYTES: number;      // 0
341
```
342

343
## Usage Examples
344

345
### Basic AEAD Encryption
346

347
```javascript
348
import _sodium from 'libsodium-wrappers-sumo';
349
await _sodium.ready;
350
const sodium = _sodium;
351

352
// Generate key
353
const key = sodium.crypto_aead_xchacha20poly1305_ietf_keygen();
354

355
// Prepare data
356
const message = sodium.from_string('Confidential message');
357
const additionalData = sodium.from_string('public header');
358
const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
359

360
// Encrypt
361
const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(
362
  message, additionalData, null, nonce, key
363
);
364

365
// Decrypt
366
const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(
367
  null, ciphertext, additionalData, nonce, key
368
);
369

370
console.log(sodium.to_string(plaintext)); // "Confidential message"
371
```
372

373
### Detached Authentication
374

375
```javascript
376
// Encrypt with separate MAC
377
const { ciphertext, mac } = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt_detached(
378
  message, additionalData, null, nonce, key
379
);
380

381
// Store ciphertext and MAC separately
382
console.log('Ciphertext:', sodium.to_hex(ciphertext));
383
console.log('MAC:', sodium.to_hex(mac));
384

385
// Decrypt with separate MAC
386
const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt_detached(
387
  null, ciphertext, mac, additionalData, nonce, key
388
);
389
```
390

391
### AEGIS High Performance
392

393
```javascript
394
// For high-throughput applications
395
const key = sodium.crypto_aead_aegis256_keygen();
396
const nonce = sodium.randombytes_buf(sodium.crypto_aead_aegis256_NPUBBYTES);
397

398
const ciphertext = sodium.crypto_aead_aegis256_encrypt(
399
  message, additionalData, null, nonce, key
400
);
401

402
const plaintext = sodium.crypto_aead_aegis256_decrypt(
403
  null, ciphertext, additionalData, nonce, key
404
);
405
```
406

407
## Algorithm Selection Guide
408

409
- **XChaCha20-Poly1305**: Best general choice, safe random nonces
410
- **ChaCha20-Poly1305 IETF**: Standards compliance, be careful with nonce reuse
411
- **AEGIS-256**: Maximum performance for high-throughput applications
412
- **AEGIS-128L**: Good performance with smaller keys and tags
413

414
All algorithms provide strong security when used correctly with unique nonces per key.