0
# Secret-Key Encryption
1

2
Fast symmetric encryption for protecting data with a shared secret key. Uses XSalsa20 stream cipher with Poly1305 authentication for both confidentiality and integrity.
3

4
## Capabilities
5

6
### Standard Secret Box
7

8
```javascript { .api }
9
/**
10
 * Generates a random 32-byte key for secret-key encryption
11
 * @returns 32-byte encryption key
12
 */
13
function crypto_secretbox_keygen();
14

15
/**
16
 * Encrypts a message with a secret key
17
 * @param message - The plaintext message to encrypt
18
 * @param nonce - 24-byte nonce (must be unique for each message with the same key)
19
 * @param key - 32-byte secret key
20
 * @returns Encrypted ciphertext with authentication tag
21
 */
22
function crypto_secretbox_easy(message, nonce, key);
23

24
/**
25
 * Decrypts a message with a secret key
26
 * @param ciphertext - The encrypted message to decrypt
27
 * @param nonce - 24-byte nonce used during encryption
28
 * @param key - 32-byte secret key used for encryption
29
 * @returns Decrypted plaintext message
30
 * @throws Error if decryption fails or authentication is invalid
31
 */
32
function crypto_secretbox_open_easy(ciphertext, nonce, key);
33

34
/**
35
 * Encrypts a message with detached authentication tag
36
 * @param message - The plaintext message to encrypt
37
 * @param nonce - 24-byte nonce
38
 * @param key - 32-byte secret key
39
 * @returns Object with cipher and mac properties
40
 */
41
function crypto_secretbox_detached(message, nonce, key);
42

43
/**
44
 * Decrypts a message with detached authentication tag
45
 * @param ciphertext - The encrypted message
46
 * @param mac - The detached authentication tag
47
 * @param nonce - 24-byte nonce used during encryption
48
 * @param key - 32-byte secret key
49
 * @returns Decrypted plaintext message
50
 */
51
function crypto_secretbox_open_detached(ciphertext, mac, nonce, key);
52
```
53

54
**Usage Example:**
55

56
```javascript
57
// Generate key and nonce
58
const key = sodium.crypto_secretbox_keygen();
59
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
60

61
// Encrypt a message
62
const message = sodium.from_string("Secret message");
63
const ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);
64

65
// Decrypt the message
66
const decrypted = sodium.crypto_secretbox_open_easy(ciphertext, nonce, key);
67
console.log(sodium.to_string(decrypted)); // "Secret message"
68
```
69

70
### Secret Streams
71

72
For encrypting large amounts of data or streams, use the secret stream API which provides forward secrecy and associated data support.
73

74
```javascript { .api }
75
/**
76
 * Generates a random 32-byte key for secret streams
77
 * @returns 32-byte stream key
78
 */
79
function crypto_secretstream_xchacha20poly1305_keygen();
80

81
/**
82
 * Initializes encryption state for a secret stream
83
 * @param key - 32-byte stream key
84
 * @returns Object with state and header properties
85
 */
86
function crypto_secretstream_xchacha20poly1305_init_push(key);
87

88
/**
89
 * Encrypts a chunk of data in the stream
90
 * @param state_address - State from init_push
91
 * @param message_chunk - Data chunk to encrypt
92
 * @param ad - Optional additional data to authenticate
93
 * @param tag - Message tag (TAG_MESSAGE, TAG_PUSH, TAG_REKEY, or TAG_FINAL)
94
 * @returns Encrypted chunk with authentication
95
 */
96
function crypto_secretstream_xchacha20poly1305_push(state_address, message_chunk, ad, tag);
97

98
/**
99
 * Initializes decryption state for a secret stream
100
 * @param header - Stream header from init_push
101
 * @param key - 32-byte stream key
102
 * @returns State address for decryption operations
103
 */
104
function crypto_secretstream_xchacha20poly1305_init_pull(header, key);
105

106
/**
107
 * Decrypts a chunk of data from the stream
108
 * @param state_address - State from init_pull
109
 * @param cipher - Encrypted chunk to decrypt
110
 * @param ad - Additional data that was authenticated during encryption
111
 * @returns Object with message and tag properties
112
 */
113
function crypto_secretstream_xchacha20poly1305_pull(state_address, cipher, ad);
114

115
/**
116
 * Rekeys the stream state for forward secrecy
117
 * @param state_address - State to rekey
118
 * @returns true on success
119
 */
120
function crypto_secretstream_xchacha20poly1305_rekey(state_address);
121
```
122

123
**Stream Usage Example:**
124

125
```javascript
126
// Initialize encryption
127
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
128
const {state, header} = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
129

130
// Encrypt chunks
131
const chunk1 = sodium.crypto_secretstream_xchacha20poly1305_push(
132
  state, 
133
  sodium.from_string("First chunk"), 
134
  null, 
135
  sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE
136
);
137

138
const chunk2 = sodium.crypto_secretstream_xchacha20poly1305_push(
139
  state, 
140
  sodium.from_string("Final chunk"), 
141
  null, 
142
  sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL
143
);
144

145
// Initialize decryption
146
const pullState = sodium.crypto_secretstream_xchacha20poly1305_init_pull(header, key);
147

148
// Decrypt chunks
149
const decrypted1 = sodium.crypto_secretstream_xchacha20poly1305_pull(pullState, chunk1, null);
150
const decrypted2 = sodium.crypto_secretstream_xchacha20poly1305_pull(pullState, chunk2, null);
151

152
console.log(sodium.to_string(decrypted1.message)); // "First chunk"
153
console.log(sodium.to_string(decrypted2.message)); // "Final chunk"
154
```
155

156
## Constants
157

158
```javascript { .api }
159
// Secret Box
160
const crypto_secretbox_KEYBYTES = 32;     // Key size
161
const crypto_secretbox_NONCEBYTES = 24;   // Nonce size
162
const crypto_secretbox_MACBYTES = 16;     // Authentication tag size
163

164
// Secret Streams  
165
const crypto_secretstream_xchacha20poly1305_KEYBYTES = 32;     // Key size
166
const crypto_secretstream_xchacha20poly1305_HEADERBYTES = 24;  // Header size
167
const crypto_secretstream_xchacha20poly1305_ABYTES = 17;       // Auth tag size
168

169
// Stream Tags
170
const crypto_secretstream_xchacha20poly1305_TAG_MESSAGE = 0;   // Regular message
171
const crypto_secretstream_xchacha20poly1305_TAG_PUSH = 1;      // End of chunk
172
const crypto_secretstream_xchacha20poly1305_TAG_REKEY = 2;     // Rekey point
173
const crypto_secretstream_xchacha20poly1305_TAG_FINAL = 3;     // End of stream
174
```
175

176
## Security Considerations
177

178
- **Nonce Management**: Never reuse nonces with the same key. Use random nonces or counters.
179
- **Key Security**: Secret keys must be generated securely and kept confidential.
180
- **Stream Forward Secrecy**: Use rekeying in streams to provide forward secrecy.
181
- **Tag Selection**: Use appropriate tags in streams to indicate message boundaries and stream state.
182
- **Memory Security**: Clear sensitive data from memory when no longer needed.