0
# Low-Level API
1

2
Advanced low-level cryptographic primitives exposed for custom protocol implementation and performance optimization. These functions provide direct access to the underlying cryptographic operations without the convenience wrappers of the high-level API.
3

4
⚠️ **Warning**: These functions are intended for advanced users who understand the underlying cryptographic protocols. Most applications should use the high-level API instead.
5

6
## Capabilities
7

8
### Stream Ciphers
9

10
Core stream cipher operations for encryption and key stream generation.
11

12
```javascript { .api }
13
/**
14
 * HSalsa20 core function - fundamental building block for XSalsa20
15
 * @param {Uint8Array} out - Output array (32 bytes)
16
 * @param {Uint8Array} inp - Input array (16 bytes)
17
 * @param {Uint8Array} k - Key (32 bytes)
18
 * @param {Uint8Array} c - Constants (16 bytes)
19
 */
20
nacl.lowlevel.crypto_core_hsalsa20(out, inp, k, c): number
21

22
/**
23
 * XOR data with stream cipher output
24
 * @param {Uint8Array} c - Ciphertext output
25
 * @param {number} cpos - Position in ciphertext array
26
 * @param {Uint8Array} m - Message input  
27
 * @param {number} mpos - Position in message array
28
 * @param {number} d - Number of bytes to process
29
 * @param {Uint8Array} n - Nonce (24 bytes)
30
 * @param {Uint8Array} k - Key (32 bytes)
31
 * @returns {number} 0 on success
32
 */
33
nacl.lowlevel.crypto_stream_xor(c, cpos, m, mpos, d, n, k): number
34

35
/**
36
 * Generate stream cipher output
37
 * @param {Uint8Array} c - Output stream
38
 * @param {number} cpos - Position in output array
39
 * @param {number} d - Number of bytes to generate
40
 * @param {Uint8Array} n - Nonce (24 bytes)
41
 * @param {Uint8Array} k - Key (32 bytes)
42
 * @returns {number} 0 on success
43
 */
44
nacl.lowlevel.crypto_stream(c, cpos, d, n, k): number
45

46
/**
47
 * Salsa20 stream cipher XOR operation
48
 * @param {Uint8Array} c - Ciphertext output
49
 * @param {number} cpos - Position in ciphertext array
50
 * @param {Uint8Array} m - Message input
51
 * @param {number} mpos - Position in message array
52
 * @param {number} b - Number of bytes to process
53
 * @param {Uint8Array} n - Nonce (8 bytes)
54
 * @param {Uint8Array} k - Key (32 bytes)
55
 * @returns {number} 0 on success
56
 */
57
nacl.lowlevel.crypto_stream_salsa20_xor(c, cpos, m, mpos, b, n, k): number
58

59
/**
60
 * Generate Salsa20 stream cipher output
61
 * @param {Uint8Array} c - Output stream
62
 * @param {number} cpos - Position in output array
63
 * @param {number} b - Number of bytes to generate
64
 * @param {Uint8Array} n - Nonce (8 bytes)
65
 * @param {Uint8Array} k - Key (32 bytes)
66
 * @returns {number} 0 on success
67
 */
68
nacl.lowlevel.crypto_stream_salsa20(c, cpos, b, n, k): number
69
```
70

71
### One-Time Authentication
72

73
Poly1305 one-time authentication for message integrity.
74

75
```javascript { .api }
76
/**
77
 * Compute Poly1305 one-time authentication code
78
 * @param {Uint8Array} out - Authentication code output (16 bytes)
79
 * @param {number} outpos - Position in output array
80
 * @param {Uint8Array} m - Message input
81
 * @param {number} mpos - Position in message array
82
 * @param {number} n - Number of bytes to authenticate
83
 * @param {Uint8Array} k - Key (32 bytes)
84
 * @returns {number} 0 on success
85
 */
86
nacl.lowlevel.crypto_onetimeauth(out, outpos, m, mpos, n, k): number
87

88
/**
89
 * Verify Poly1305 one-time authentication code
90
 * @param {Uint8Array} h - Authentication code to verify (16 bytes)
91
 * @param {number} hpos - Position in authentication code array
92
 * @param {Uint8Array} m - Message input
93
 * @param {number} mpos - Position in message array
94
 * @param {number} n - Number of bytes to verify
95
 * @param {Uint8Array} k - Key (32 bytes)
96
 * @returns {number} 0 if verification succeeds, -1 if it fails
97
 */
98
nacl.lowlevel.crypto_onetimeauth_verify(h, hpos, m, mpos, n, k): number
99
```
100

101
### Verification
102

103
Constant-time comparison functions for different lengths.
104

105
```javascript { .api }
106
/**
107
 * Constant-time verification of 16-byte values
108
 * @param {Uint8Array} x - First value
109
 * @param {number} xi - Offset in first array
110
 * @param {Uint8Array} y - Second value
111
 * @param {number} yi - Offset in second array
112
 */
113
nacl.lowlevel.crypto_verify_16(x, xi, y, yi): number
114

115
/**
116
 * Constant-time verification of 32-byte values
117
 * @param {Uint8Array} x - First value
118
 * @param {number} xi - Offset in first array
119
 * @param {Uint8Array} y - Second value
120
 * @param {number} yi - Offset in second array
121
 */
122
nacl.lowlevel.crypto_verify_32(x, xi, y, yi): number
123
```
124

125
### Secret-Key Operations
126

127
Low-level secret-key encryption and decryption.
128

129
```javascript { .api }
130
/**
131
 * Low-level secret-key authenticated encryption
132
 * @param {Uint8Array} c - Ciphertext output
133
 * @param {Uint8Array} m - Message input
134
 * @param {number} mlen - Message length
135
 * @param {Uint8Array} n - Nonce (24 bytes)
136
 * @param {Uint8Array} k - Key (32 bytes)
137
 */
138
nacl.lowlevel.crypto_secretbox(c, m, mlen, n, k): number
139

140
/**
141
 * Low-level secret-key authenticated decryption
142
 * @param {Uint8Array} m - Message output
143
 * @param {Uint8Array} c - Ciphertext input
144
 * @param {number} clen - Ciphertext length
145
 * @param {Uint8Array} n - Nonce (24 bytes)
146
 * @param {Uint8Array} k - Key (32 bytes)
147
 */
148
nacl.lowlevel.crypto_secretbox_open(m, c, clen, n, k): number
149
```
150

151
### Public-Key Operations
152

153
Low-level public-key cryptographic operations.
154

155
```javascript { .api }
156
/**
157
 * Low-level scalar multiplication
158
 * @param {Uint8Array} q - Output point (32 bytes)
159
 * @param {Uint8Array} n - Scalar (32 bytes)
160
 * @param {Uint8Array} p - Input point (32 bytes)
161
 */
162
nacl.lowlevel.crypto_scalarmult(q, n, p): number
163

164
/**
165
 * Low-level scalar multiplication with base point
166
 * @param {Uint8Array} q - Output point (32 bytes)
167
 * @param {Uint8Array} n - Scalar (32 bytes)
168
 */
169
nacl.lowlevel.crypto_scalarmult_base(q, n): number
170

171
/**
172
 * Precompute shared key for box operations
173
 * @param {Uint8Array} k - Shared key output (32 bytes)
174
 * @param {Uint8Array} pk - Public key (32 bytes)
175
 * @param {Uint8Array} sk - Secret key (32 bytes)
176
 */
177
nacl.lowlevel.crypto_box_beforenm(k, pk, sk): number
178

179
/**
180
 * Box operation using precomputed shared key
181
 * @param {Uint8Array} c - Ciphertext output
182
 * @param {Uint8Array} m - Message input
183
 * @param {number} mlen - Message length
184
 * @param {Uint8Array} n - Nonce (24 bytes)
185
 * @param {Uint8Array} k - Precomputed shared key (32 bytes)
186
 */
187
nacl.lowlevel.crypto_box_afternm(c, m, mlen, n, k): number
188

189
/**
190
 * Low-level public-key authenticated encryption
191
 * @param {Uint8Array} c - Ciphertext output
192
 * @param {Uint8Array} m - Message input
193
 * @param {number} mlen - Message length
194
 * @param {Uint8Array} n - Nonce (24 bytes)
195
 * @param {Uint8Array} pk - Public key (32 bytes)
196
 * @param {Uint8Array} sk - Secret key (32 bytes)
197
 */
198
nacl.lowlevel.crypto_box(c, m, mlen, n, pk, sk): number
199

200
/**
201
 * Low-level public-key authenticated decryption
202
 * @param {Uint8Array} m - Message output
203
 * @param {Uint8Array} c - Ciphertext input
204
 * @param {number} clen - Ciphertext length
205
 * @param {Uint8Array} n - Nonce (24 bytes)
206
 * @param {Uint8Array} pk - Public key (32 bytes)
207
 * @param {Uint8Array} sk - Secret key (32 bytes)
208
 */
209
nacl.lowlevel.crypto_box_open(m, c, clen, n, pk, sk): number
210

211
/**
212
 * Generate key pair for box operations
213
 * @param {Uint8Array} pk - Public key output (32 bytes)
214
 * @param {Uint8Array} sk - Secret key output (32 bytes)
215
 */
216
nacl.lowlevel.crypto_box_keypair(pk, sk): number
217
```
218

219
### Digital Signatures
220

221
Low-level digital signature operations.
222

223
```javascript { .api }
224
/**
225
 * Low-level message signing
226
 * @param {Uint8Array} sm - Signed message output
227
 * @param {Uint8Array} smlen_p - Pointer to signed message length
228
 * @param {Uint8Array} m - Message input
229
 * @param {number} mlen - Message length
230
 * @param {Uint8Array} sk - Secret key (64 bytes)
231
 */
232
nacl.lowlevel.crypto_sign(sm, smlen_p, m, mlen, sk): number
233

234
/**
235
 * Generate signing key pair
236
 * @param {Uint8Array} pk - Public key output (32 bytes)
237
 * @param {Uint8Array} sk - Secret key output (64 bytes)
238
 */
239
nacl.lowlevel.crypto_sign_keypair(pk, sk): number
240

241
/**
242
 * Low-level signature verification
243
 * @param {Uint8Array} m - Message output
244
 * @param {Uint8Array} mlen_p - Pointer to message length
245
 * @param {Uint8Array} sm - Signed message input
246
 * @param {number} smlen - Signed message length
247
 * @param {Uint8Array} pk - Public key (32 bytes)
248
 */
249
nacl.lowlevel.crypto_sign_open(m, mlen_p, sm, smlen, pk): number
250
```
251

252
### Hashing
253

254
Low-level hashing operation.
255

256
```javascript { .api }
257
/**
258
 * Low-level SHA-512 hash computation
259
 * @param {Uint8Array} out - Hash output (64 bytes)
260
 * @param {Uint8Array} m - Message input
261
 * @param {number} mlen - Message length
262
 */
263
nacl.lowlevel.crypto_hash(out, m, mlen): number
264
```
265

266
## Constants
267

268
All low-level constants corresponding to the cryptographic parameters:
269

270
```javascript { .api }
271
// Secret box constants
272
nacl.lowlevel.crypto_secretbox_KEYBYTES: number         // 32
273
nacl.lowlevel.crypto_secretbox_NONCEBYTES: number       // 24
274
nacl.lowlevel.crypto_secretbox_ZEROBYTES: number        // 32
275
nacl.lowlevel.crypto_secretbox_BOXZEROBYTES: number     // 16
276

277
// Scalar multiplication constants
278
nacl.lowlevel.crypto_scalarmult_BYTES: number           // 32
279
nacl.lowlevel.crypto_scalarmult_SCALARBYTES: number     // 32
280

281
// Box constants
282
nacl.lowlevel.crypto_box_PUBLICKEYBYTES: number         // 32
283
nacl.lowlevel.crypto_box_SECRETKEYBYTES: number         // 32
284
nacl.lowlevel.crypto_box_BEFORENMBYTES: number          // 32
285
nacl.lowlevel.crypto_box_NONCEBYTES: number             // 24
286
nacl.lowlevel.crypto_box_ZEROBYTES: number              // 32
287
nacl.lowlevel.crypto_box_BOXZEROBYTES: number           // 16
288

289
// Signature constants
290
nacl.lowlevel.crypto_sign_BYTES: number                 // 64
291
nacl.lowlevel.crypto_sign_PUBLICKEYBYTES: number        // 32
292
nacl.lowlevel.crypto_sign_SECRETKEYBYTES: number        // 64
293
nacl.lowlevel.crypto_sign_SEEDBYTES: number             // 32
294

295
// Hash constants
296
nacl.lowlevel.crypto_hash_BYTES: number                 // 64
297
```
298

299
## Usage Considerations
300

301
### Return Values
302

303
Low-level functions typically return `0` on success and non-zero on failure, following NaCl conventions.
304

305
### Memory Management
306

307
These functions work directly with Uint8Array buffers and require careful attention to:
308
- Buffer sizes and length parameters
309
- Offset parameters for array operations
310
- Proper initialization of output buffers
311

312
### Performance
313

314
The low-level API avoids object creation and can be more efficient for performance-critical applications, but requires more careful programming.
315

316
### Security
317

318
When using low-level functions:
319
- Ensure proper buffer sizes to prevent overflows
320
- Use constant-time comparison functions for security-sensitive data
321
- Follow cryptographic protocol specifications exactly
322
- Consider using high-level API unless performance is critical
323

324
Most applications should use the high-level API (`nacl.box`, `nacl.secretbox`, etc.) which provides the same security with better usability.