0
# Stream Ciphers
1

2
Stream cipher encryption provides fast encryption/decryption without authentication. Unlike authenticated encryption, stream ciphers only provide confidentiality and are vulnerable to bit-flipping attacks if used without additional authentication. Use authenticated encryption (AEAD) unless you have specific requirements for stream ciphers.
3

4
## Capabilities
5

6
### ChaCha20 Stream Cipher
7

8
High-speed stream cipher providing encryption without authentication. Suitable for applications requiring maximum performance where authentication is handled separately.
9

10
```javascript { .api }
11
/**
12
 * Generate ChaCha20 stream cipher key
13
 * @returns Uint8Array - 32-byte key for ChaCha20
14
 */
15
function crypto_stream_chacha20_keygen();
16

17
/**
18
 * Encrypt/decrypt data using ChaCha20 stream cipher
19
 * @param input_message - Data to encrypt or decrypt
20
 * @param nonce - 8-byte nonce (must be unique for each message with same key)
21
 * @param key - 32-byte ChaCha20 key
22
 * @returns Uint8Array - Encrypted/decrypted data (same length as input)
23
 */
24
function crypto_stream_chacha20_xor(input_message, nonce, key);
25

26
/**
27
 * Encrypt/decrypt data using ChaCha20 with counter
28
 * @param input_message - Data to encrypt or decrypt
29
 * @param nonce - 8-byte nonce
30
 * @param counter - Starting counter value
31
 * @param key - 32-byte ChaCha20 key
32
 * @returns Uint8Array - Encrypted/decrypted data
33
 */
34
function crypto_stream_chacha20_xor_ic(input_message, nonce, counter, key);
35

36
/**
37
 * Generate ChaCha20 keystream
38
 * @param length - Length of keystream to generate
39
 * @param nonce - 8-byte nonce
40
 * @param key - 32-byte ChaCha20 key
41
 * @returns Uint8Array - Generated keystream
42
 */
43
function crypto_stream_chacha20(length, nonce, key);
44
```
45

46
**Usage Example:**
47

48
```javascript
49
import sodium from 'libsodium-wrappers';
50
await sodium.ready;
51

52
// Generate key and nonce
53
const key = sodium.crypto_stream_chacha20_keygen();
54
const nonce = sodium.randombytes_buf(8); // ChaCha20 uses 8-byte nonce
55

56
// Encrypt message
57
const message = sodium.from_string('Hello, World!');
58
const ciphertext = sodium.crypto_stream_chacha20_xor(message, nonce, key);
59

60
// Decrypt message (same operation)
61
const decrypted = sodium.crypto_stream_chacha20_xor(ciphertext, nonce, key);
62
const plaintext = sodium.to_string(decrypted);
63
console.log(plaintext); // "Hello, World!"
64
```
65

66
### ChaCha20 IETF Stream Cipher
67

68
IETF variant of ChaCha20 with 12-byte nonce and 32-bit counter, compatible with RFC 8439.
69

70
```javascript { .api }
71
/**
72
 * Encrypt/decrypt data using ChaCha20-IETF with 12-byte nonce
73
 * @param input_message - Data to encrypt or decrypt
74
 * @param nonce - 12-byte nonce (IETF standard)
75
 * @param key - 32-byte ChaCha20 key
76
 * @returns Uint8Array - Encrypted/decrypted data
77
 */
78
function crypto_stream_chacha20_ietf_xor(input_message, nonce, key);
79

80
/**
81
 * Encrypt/decrypt data using ChaCha20-IETF with counter
82
 * @param input_message - Data to encrypt or decrypt  
83
 * @param nonce - 12-byte nonce
84
 * @param counter - Starting counter value
85
 * @param key - 32-byte ChaCha20 key
86
 * @returns Uint8Array - Encrypted/decrypted data
87
 */
88
function crypto_stream_chacha20_ietf_xor_ic(input_message, nonce, counter, key);
89
```
90

91
### XChaCha20 Stream Cipher
92

93
Extended ChaCha20 with 24-byte nonce, providing better security margins for random nonce generation.
94

95
```javascript { .api }
96
/**
97
 * Generate XChaCha20 stream cipher key
98
 * @returns Uint8Array - 32-byte key for XChaCha20
99
 */
100
function crypto_stream_xchacha20_keygen();
101

102
/**
103
 * Encrypt/decrypt data using XChaCha20 stream cipher
104
 * @param input_message - Data to encrypt or decrypt
105
 * @param nonce - 24-byte nonce (can be randomly generated)
106
 * @param key - 32-byte XChaCha20 key
107
 * @returns Uint8Array - Encrypted/decrypted data
108
 */
109
function crypto_stream_xchacha20_xor(input_message, nonce, key);
110

111
/**
112
 * Encrypt/decrypt data using XChaCha20 with counter
113
 * @param input_message - Data to encrypt or decrypt
114
 * @param nonce - 24-byte nonce
115
 * @param counter - Starting counter value
116
 * @param key - 32-byte XChaCha20 key
117
 * @returns Uint8Array - Encrypted/decrypted data
118
 */
119
function crypto_stream_xchacha20_xor_ic(input_message, nonce, counter, key);
120
```
121

122
**Usage Example:**
123

124
```javascript
125
import sodium from 'libsodium-wrappers';
126
await sodium.ready;
127

128
// XChaCha20 with 24-byte nonce (can be random)
129
const key = sodium.crypto_stream_xchacha20_keygen();
130
const nonce = sodium.randombytes_buf(24); // XChaCha20 uses 24-byte nonce
131

132
const message = sodium.from_string('Secure message');
133
const encrypted = sodium.crypto_stream_xchacha20_xor(message, nonce, key);
134
const decrypted = sodium.crypto_stream_xchacha20_xor(encrypted, nonce, key);
135
```
136

137
### Generic Stream Cipher
138

139
Generic stream cipher interface providing default algorithm selection.
140

141
```javascript { .api }
142
/**
143
 * Generate generic stream cipher key
144
 * @returns Uint8Array - Key for default stream cipher
145
 */
146
function crypto_stream_keygen();
147
```
148

149
## Constants
150

151
Stream cipher constants for buffer sizes and parameters:
152

153
```javascript { .api }
154
// ChaCha20 constants
155
const crypto_stream_chacha20_KEYBYTES; // 32
156
const crypto_stream_chacha20_NONCEBYTES; // 8
157
const crypto_stream_chacha20_ietf_NONCEBYTES; // 12
158

159
// XChaCha20 constants  
160
const crypto_stream_xchacha20_KEYBYTES; // 32
161
const crypto_stream_xchacha20_NONCEBYTES; // 24
162

163
// Generic stream constants
164
const crypto_stream_KEYBYTES; // 32
165
const crypto_stream_NONCEBYTES; // 24
166
```
167

168
## Security Considerations
169

170
**Important Security Notes:**
171

172
1. **No Authentication**: Stream ciphers provide only encryption, not authentication
173
2. **Nonce Reuse**: Never reuse a nonce with the same key - this breaks security completely
174
3. **Bit-Flipping Attacks**: Attackers can flip bits in ciphertext to modify plaintext
175
4. **Use AEAD Instead**: For most applications, use authenticated encryption (ChaCha20-Poly1305) instead
176

177
**When to Use Stream Ciphers:**
178

179
- Performance-critical applications where authentication is handled separately
180
- Protocols that implement authentication at a higher layer
181
- Compatibility with existing systems that require raw stream ciphers
182
- Bulk encryption where separate authentication is more efficient
183

184
**Best Practices:**
185

186
- Generate nonces randomly for XChaCha20 (24-byte nonce provides sufficient collision resistance)
187
- Use counters or sequential nonces for ChaCha20 (8-byte nonce requires careful nonce management)
188
- Always authenticate encrypted data using separate MAC or signature
189
- Consider using authenticated encryption (AEAD) unless you have specific requirements