0
# Authenticated Encryption (AEAD)
1

2
Authenticated Encryption with Associated Data (AEAD) provides both confidentiality and authenticity in a single operation. libsodium-wrappers supports multiple AEAD cipher suites optimized for different use cases.
3

4
## Capabilities
5

6
### ChaCha20-Poly1305 IETF (Recommended)
7

8
The recommended AEAD construction using ChaCha20 stream cipher with Poly1305 authenticator, following the IETF specification.
9

10
```javascript { .api }
11
/**
12
 * Encrypts a message using ChaCha20-Poly1305 IETF
13
 * @param message - The plaintext message to encrypt
14
 * @param additional_data - Optional additional data to authenticate (but not encrypt)
15
 * @param secret_nonce - Optional secret nonce (usually null)
16
 * @param public_nonce - 12-byte public nonce
17
 * @param key - 32-byte encryption key
18
 * @returns Encrypted ciphertext with authentication tag
19
 */
20
function crypto_aead_chacha20poly1305_ietf_encrypt(message, additional_data, secret_nonce, public_nonce, key);
21

22
/**
23
 * Decrypts a message using ChaCha20-Poly1305 IETF
24
 * @param secret_nonce - Optional secret nonce (usually null)
25
 * @param ciphertext - The ciphertext to decrypt
26
 * @param additional_data - Additional data that was authenticated during encryption
27
 * @param public_nonce - 12-byte public nonce used during encryption
28
 * @param key - 32-byte encryption key
29
 * @returns Decrypted plaintext message
30
 * @throws Error if authentication fails or ciphertext is invalid
31
 */
32
function crypto_aead_chacha20poly1305_ietf_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
33

34
/**
35
 * Generates a random 32-byte key for ChaCha20-Poly1305 IETF
36
 * @returns 32-byte encryption key
37
 */
38
function crypto_aead_chacha20poly1305_ietf_keygen();
39

40
/**
41
 * Encrypts a message using ChaCha20-Poly1305 IETF with detached authentication tag
42
 * @param message - The plaintext message to encrypt
43
 * @param additional_data - Optional additional data to authenticate
44
 * @param secret_nonce - Optional secret nonce (usually null)
45
 * @param public_nonce - 12-byte public nonce
46
 * @param key - 32-byte encryption key
47
 * @returns Object with separate ciphertext and mac properties
48
 */
49
function crypto_aead_chacha20poly1305_ietf_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);
50

51
/**
52
 * Decrypts a message using ChaCha20-Poly1305 IETF with detached authentication tag
53
 * @param secret_nonce - Optional secret nonce (usually null)
54
 * @param ciphertext - The ciphertext to decrypt
55
 * @param mac - The detached authentication tag
56
 * @param additional_data - Additional data that was authenticated during encryption
57
 * @param public_nonce - 12-byte public nonce used during encryption
58
 * @param key - 32-byte encryption key
59
 * @returns Decrypted plaintext message
60
 */
61
function crypto_aead_chacha20poly1305_ietf_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);
62
```
63

64
**Usage Example:**
65

66
```javascript
67
// Generate key and nonce
68
const key = sodium.crypto_aead_chacha20poly1305_ietf_keygen();
69
const nonce = sodium.randombytes_buf(sodium.crypto_aead_chacha20poly1305_ietf_NPUBBYTES);
70

71
// Encrypt with additional authenticated data
72
const message = sodium.from_string("Secret message");
73
const additionalData = sodium.from_string("public metadata");
74
const ciphertext = sodium.crypto_aead_chacha20poly1305_ietf_encrypt(
75
  message, additionalData, null, nonce, key
76
);
77

78
// Decrypt
79
const decrypted = sodium.crypto_aead_chacha20poly1305_ietf_decrypt(
80
  null, ciphertext, additionalData, nonce, key
81
);
82
console.log(sodium.to_string(decrypted)); // "Secret message"
83
```
84

85
### XChaCha20-Poly1305 IETF
86

87
Extended nonce version of ChaCha20-Poly1305 with 24-byte nonces, providing better resistance to nonce reuse.
88

89
```javascript { .api }
90
/**
91
 * Encrypts a message using XChaCha20-Poly1305 IETF
92
 * @param message - The plaintext message to encrypt
93
 * @param additional_data - Optional additional data to authenticate
94
 * @param secret_nonce - Optional secret nonce (usually null)
95
 * @param public_nonce - 24-byte public nonce
96
 * @param key - 32-byte encryption key
97
 * @returns Encrypted ciphertext with authentication tag
98
 */
99
function crypto_aead_xchacha20poly1305_ietf_encrypt(message, additional_data, secret_nonce, public_nonce, key);
100

101
/**
102
 * Decrypts a message using XChaCha20-Poly1305 IETF
103
 * @param secret_nonce - Optional secret nonce (usually null)
104
 * @param ciphertext - The ciphertext to decrypt
105
 * @param additional_data - Additional data that was authenticated during encryption
106
 * @param public_nonce - 24-byte public nonce used during encryption
107
 * @param key - 32-byte encryption key
108
 * @returns Decrypted plaintext message
109
 */
110
function crypto_aead_xchacha20poly1305_ietf_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
111

112
/**
113
 * Generates a random 32-byte key for XChaCha20-Poly1305 IETF
114
 * @returns 32-byte encryption key
115
 */
116
function crypto_aead_xchacha20poly1305_ietf_keygen();
117

118
function crypto_aead_xchacha20poly1305_ietf_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);
119
function crypto_aead_xchacha20poly1305_ietf_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);
120
```
121

122
### ChaCha20-Poly1305 (Original)
123

124
Original ChaCha20-Poly1305 construction with 8-byte nonces.
125

126
```javascript { .api }
127
function crypto_aead_chacha20poly1305_encrypt(message, additional_data, secret_nonce, public_nonce, key);
128
function crypto_aead_chacha20poly1305_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
129
function crypto_aead_chacha20poly1305_keygen();
130
function crypto_aead_chacha20poly1305_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);
131
function crypto_aead_chacha20poly1305_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);
132
```
133

134
### AEGIS-128L
135

136
High-performance AEAD cipher optimized for modern CPUs with AES acceleration.
137

138
```javascript { .api }
139
function crypto_aead_aegis128l_encrypt(message, additional_data, secret_nonce, public_nonce, key);
140
function crypto_aead_aegis128l_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
141
function crypto_aead_aegis128l_keygen();
142
function crypto_aead_aegis128l_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);
143
function crypto_aead_aegis128l_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);
144
```
145

146
### AEGIS-256
147

148
Higher security version of AEGIS with 256-bit keys.
149

150
```javascript { .api }
151
function crypto_aead_aegis256_encrypt(message, additional_data, secret_nonce, public_nonce, key);
152
function crypto_aead_aegis256_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
153
function crypto_aead_aegis256_keygen();
154
function crypto_aead_aegis256_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);
155
function crypto_aead_aegis256_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);
156
```
157

158
## Constants
159

160
```javascript { .api }
161
// ChaCha20-Poly1305 IETF
162
const crypto_aead_chacha20poly1305_ietf_KEYBYTES = 32;
163
const crypto_aead_chacha20poly1305_ietf_NPUBBYTES = 12;
164
const crypto_aead_chacha20poly1305_ietf_ABYTES = 16;
165

166
// XChaCha20-Poly1305 IETF  
167
const crypto_aead_xchacha20poly1305_ietf_KEYBYTES = 32;
168
const crypto_aead_xchacha20poly1305_ietf_NPUBBYTES = 24;
169
const crypto_aead_xchacha20poly1305_ietf_ABYTES = 16;
170

171
// ChaCha20-Poly1305 (Original)
172
const crypto_aead_chacha20poly1305_KEYBYTES = 32;
173
const crypto_aead_chacha20poly1305_NPUBBYTES = 8;
174
const crypto_aead_chacha20poly1305_ABYTES = 16;
175

176
// AEGIS-128L
177
const crypto_aead_aegis128l_KEYBYTES = 16;
178
const crypto_aead_aegis128l_NPUBBYTES = 16;
179
const crypto_aead_aegis128l_ABYTES = 32;
180

181
// AEGIS-256
182
const crypto_aead_aegis256_KEYBYTES = 32;
183
const crypto_aead_aegis256_NPUBBYTES = 16;
184
const crypto_aead_aegis256_ABYTES = 32;
185
```
186

187
## Security Considerations
188

189
- **Nonce Reuse**: Never reuse the same nonce with the same key. Use random nonces or a counter-based approach.
190
- **Key Management**: Generate keys using the provided keygen functions or a cryptographically secure random source.
191
- **Additional Data**: Additional data is authenticated but not encrypted. Use for metadata that needs integrity but not confidentiality.
192
- **Algorithm Choice**: ChaCha20-Poly1305 IETF is recommended for most applications. Use XChaCha20-Poly1305 IETF when you need larger nonces or better nonce misuse resistance.