0
# Advanced Cryptographic Operations
1

2
Low-level cryptographic operations for advanced users implementing custom protocols, zero-knowledge proofs, and elliptic curve cryptography. These functions provide direct access to curve operations and should be used with caution.
3

4
## Capabilities
5

6
### Ed25519 Curve Operations
7

8
Direct elliptic curve operations on the Ed25519 curve for advanced cryptographic protocols.
9

10
```javascript { .api }
11
/**
12
 * Adds two Ed25519 curve points
13
 * @param p - First curve point (32 bytes)
14
 * @param q - Second curve point (32 bytes) 
15
 * @returns Sum of the two points (32 bytes)
16
 */
17
function crypto_core_ed25519_add(p, q);
18

19
/**
20
 * Subtracts two Ed25519 curve points
21
 * @param p - First curve point (32 bytes)
22
 * @param q - Second curve point (32 bytes)
23
 * @returns Difference of the two points (32 bytes)
24
 */
25
function crypto_core_ed25519_sub(p, q);
26

27
/**
28
 * Converts hash to Ed25519 curve point
29
 * @param hash - 64-byte hash input
30
 * @returns Ed25519 curve point (32 bytes)
31
 */
32
function crypto_core_ed25519_from_hash(hash);
33

34
/**
35
 * Converts uniform bytes to Ed25519 curve point
36
 * @param bytes - 32-byte uniform input
37
 * @returns Ed25519 curve point (32 bytes)
38
 */
39
function crypto_core_ed25519_from_uniform(bytes);
40

41
/**
42
 * Validates if bytes represent a valid Ed25519 curve point
43
 * @param point - Potential curve point (32 bytes)
44
 * @returns true if valid, false otherwise
45
 */
46
function crypto_core_ed25519_is_valid_point(point);
47

48
/**
49
 * Generates a random Ed25519 curve point
50
 * @returns Random curve point (32 bytes)
51
 */
52
function crypto_core_ed25519_random();
53
```
54

55
### Ed25519 Scalar Operations
56

57
Scalar arithmetic operations for Ed25519 curve scalars.
58

59
```javascript { .api }
60
/**
61
 * Adds two Ed25519 scalars
62
 * @param x - First scalar (32 bytes)
63
 * @param y - Second scalar (32 bytes)
64
 * @returns Sum of scalars (32 bytes)
65
 */
66
function crypto_core_ed25519_scalar_add(x, y);
67

68
/**
69
 * Subtracts two Ed25519 scalars
70
 * @param x - First scalar (32 bytes)
71
 * @param y - Second scalar (32 bytes)
72
 * @returns Difference of scalars (32 bytes)
73
 */
74
function crypto_core_ed25519_scalar_sub(x, y);
75

76
/**
77
 * Multiplies two Ed25519 scalars
78
 * @param x - First scalar (32 bytes)
79
 * @param y - Second scalar (32 bytes)
80
 * @returns Product of scalars (32 bytes)
81
 */
82
function crypto_core_ed25519_scalar_mul(x, y);
83

84
/**
85
 * Negates an Ed25519 scalar
86
 * @param scalar - Input scalar (32 bytes)
87
 * @returns Negated scalar (32 bytes)
88
 */
89
function crypto_core_ed25519_scalar_negate(scalar);
90

91
/**
92
 * Computes multiplicative inverse of Ed25519 scalar
93
 * @param scalar - Input scalar (32 bytes)
94
 * @returns Inverted scalar (32 bytes)
95
 */
96
function crypto_core_ed25519_scalar_invert(scalar);
97

98
/**
99
 * Computes complement of Ed25519 scalar
100
 * @param scalar - Input scalar (32 bytes)
101
 * @returns Complement scalar (32 bytes)
102
 */
103
function crypto_core_ed25519_scalar_complement(scalar);
104

105
/**
106
 * Generates a random Ed25519 scalar
107
 * @returns Random scalar (32 bytes)
108
 */
109
function crypto_core_ed25519_scalar_random();
110

111
/**
112
 * Reduces bytes modulo Ed25519 curve order
113
 * @param bytes - Input bytes (64 bytes)
114
 * @returns Reduced scalar (32 bytes)
115
 */
116
function crypto_core_ed25519_scalar_reduce(bytes);
117
```
118

119
**Ed25519 Usage Example:**
120

121
```javascript
122
import sodium from 'libsodium-wrappers';
123
await sodium.ready;
124

125
// Generate random curve points and scalars
126
const point1 = sodium.crypto_core_ed25519_random();
127
const point2 = sodium.crypto_core_ed25519_random();
128
const scalar1 = sodium.crypto_core_ed25519_scalar_random();
129
const scalar2 = sodium.crypto_core_ed25519_scalar_random();
130

131
// Point arithmetic
132
const pointSum = sodium.crypto_core_ed25519_add(point1, point2);
133
const pointDiff = sodium.crypto_core_ed25519_sub(point1, point2);
134

135
// Scalar arithmetic
136
const scalarSum = sodium.crypto_core_ed25519_scalar_add(scalar1, scalar2);
137
const scalarProduct = sodium.crypto_core_ed25519_scalar_mul(scalar1, scalar2);
138

139
// Validate points
140
const isValid = sodium.crypto_core_ed25519_is_valid_point(point1);
141
console.log('Point is valid:', isValid);
142
```
143

144
### Ristretto255 Curve Operations
145

146
Ristretto255 is a prime-order group built on top of Curve25519, designed for cryptographic protocols requiring a prime-order group.
147

148
```javascript { .api }
149
/**
150
 * Adds two Ristretto255 group elements
151
 * @param p - First group element (32 bytes)
152
 * @param q - Second group element (32 bytes)
153
 * @returns Sum of the elements (32 bytes)
154
 */
155
function crypto_core_ristretto255_add(p, q);
156

157
/**
158
 * Subtracts two Ristretto255 group elements
159
 * @param p - First group element (32 bytes)
160
 * @param q - Second group element (32 bytes)
161
 * @returns Difference of the elements (32 bytes)
162
 */
163
function crypto_core_ristretto255_sub(p, q);
164

165
/**
166
 * Converts hash to Ristretto255 group element
167
 * @param hash - 64-byte hash input
168
 * @returns Ristretto255 group element (32 bytes)
169
 */
170
function crypto_core_ristretto255_from_hash(hash);
171

172
/**
173
 * Validates if bytes represent a valid Ristretto255 element
174
 * @param element - Potential group element (32 bytes)
175
 * @returns true if valid, false otherwise
176
 */
177
function crypto_core_ristretto255_is_valid_point(element);
178

179
/**
180
 * Generates a random Ristretto255 group element
181
 * @returns Random group element (32 bytes)
182
 */
183
function crypto_core_ristretto255_random();
184
```
185

186
### Ristretto255 Scalar Operations
187

188
Scalar arithmetic for Ristretto255 group scalars.
189

190
```javascript { .api }
191
/**
192
 * Adds two Ristretto255 scalars
193
 * @param x - First scalar (32 bytes)
194
 * @param y - Second scalar (32 bytes)
195
 * @returns Sum of scalars (32 bytes)
196
 */
197
function crypto_core_ristretto255_scalar_add(x, y);
198

199
/**
200
 * Subtracts two Ristretto255 scalars
201
 * @param x - First scalar (32 bytes)
202
 * @param y - Second scalar (32 bytes)
203
 * @returns Difference of scalars (32 bytes)
204
 */
205
function crypto_core_ristretto255_scalar_sub(x, y);
206

207
/**
208
 * Multiplies two Ristretto255 scalars
209
 * @param x - First scalar (32 bytes)
210
 * @param y - Second scalar (32 bytes)
211
 * @returns Product of scalars (32 bytes)
212
 */
213
function crypto_core_ristretto255_scalar_mul(x, y);
214

215
/**
216
 * Negates a Ristretto255 scalar
217
 * @param scalar - Input scalar (32 bytes)
218
 * @returns Negated scalar (32 bytes)
219
 */
220
function crypto_core_ristretto255_scalar_negate(scalar);
221

222
/**
223
 * Computes multiplicative inverse of Ristretto255 scalar
224
 * @param scalar - Input scalar (32 bytes)
225
 * @returns Inverted scalar (32 bytes)
226
 */
227
function crypto_core_ristretto255_scalar_invert(scalar);
228

229
/**
230
 * Computes complement of Ristretto255 scalar
231
 * @param scalar - Input scalar (32 bytes)
232
 * @returns Complement scalar (32 bytes)
233
 */
234
function crypto_core_ristretto255_scalar_complement(scalar);
235

236
/**
237
 * Generates a random Ristretto255 scalar
238
 * @returns Random scalar (32 bytes)
239
 */
240
function crypto_core_ristretto255_scalar_random();
241

242
/**
243
 * Reduces bytes modulo Ristretto255 curve order
244
 * @param bytes - Input bytes (64 bytes)
245
 * @returns Reduced scalar (32 bytes)
246
 */
247
function crypto_core_ristretto255_scalar_reduce(bytes);
248
```
249

250
**Ristretto255 Usage Example:**
251

252
```javascript
253
import sodium from 'libsodium-wrappers';
254
await sodium.ready;
255

256
// Generate random elements and scalars
257
const element1 = sodium.crypto_core_ristretto255_random();
258
const element2 = sodium.crypto_core_ristretto255_random();
259
const scalar = sodium.crypto_core_ristretto255_scalar_random();
260

261
// Group operations
262
const sum = sodium.crypto_core_ristretto255_add(element1, element2);
263
const difference = sodium.crypto_core_ristretto255_sub(element1, element2);
264

265
// Hash to curve for deterministic point generation
266
const hash = sodium.crypto_hash_sha512(sodium.from_string('seed data'));
267
const hashedPoint = sodium.crypto_core_ristretto255_from_hash(hash);
268

269
// Validate elements
270
const isValid = sodium.crypto_core_ristretto255_is_valid_point(element1);
271
```
272

273
### Low-Level Core Functions
274

275
Core primitive functions for advanced cryptographic operations.
276

277
```javascript { .api }
278
/**
279
 * HChaCha20 core function for XChaCha20 construction
280
 * @param input - 16-byte input block
281
 * @param key - 32-byte key
282
 * @param constant - 16-byte constant (can be null for default)
283
 * @returns 32-byte output
284
 */
285
function crypto_core_hchacha20(input, key, constant);
286

287
/**
288
 * HSalsa20 core function for XSalsa20 construction
289
 * @param input - 16-byte input block
290
 * @param key - 32-byte key
291
 * @param constant - 16-byte constant (can be null for default)
292
 * @returns 32-byte output
293
 */
294
function crypto_core_hsalsa20(input, key, constant);
295
```
296

297
**Low-Level Usage Example:**
298

299
```javascript
300
import sodium from 'libsodium-wrappers';
301
await sodium.ready;
302

303
// Use HChaCha20 for key derivation in XChaCha20
304
const key = sodium.randombytes_buf(32);
305
const nonce = sodium.randombytes_buf(16);
306

307
// Derive subkey using HChaCha20
308
const subkey = sodium.crypto_core_hchacha20(nonce, key, null);
309

310
// subkey can now be used with ChaCha20 with remaining nonce bytes
311
console.log('Derived subkey length:', subkey.length); // 32
312
```
313

314
## Constants
315

316
Advanced cryptography constants for buffer sizes and parameters:
317

318
```javascript { .api }
319
// Ed25519 constants
320
const crypto_core_ed25519_BYTES = 32;          // Curve point size
321
const crypto_core_ed25519_UNIFORMBYTES = 32;   // Uniform bytes size
322
const crypto_core_ed25519_HASHBYTES = 64;      // Hash input size
323
const crypto_core_ed25519_SCALARBYTES = 32;    // Scalar size
324
const crypto_core_ed25519_NONREDUCEDSCALARBYTES = 64; // Non-reduced scalar size
325

326
// Ristretto255 constants
327
const crypto_core_ristretto255_BYTES = 32;     // Group element size
328
const crypto_core_ristretto255_HASHBYTES = 64; // Hash input size
329
const crypto_core_ristretto255_SCALARBYTES = 32; // Scalar size
330
const crypto_core_ristretto255_NONREDUCEDSCALARBYTES = 64; // Non-reduced scalar size
331

332
// Core function constants
333
const crypto_core_hchacha20_INPUTBYTES = 16;   // HChaCha20 input size
334
const crypto_core_hchacha20_KEYBYTES = 32;     // HChaCha20 key size
335
const crypto_core_hchacha20_CONSTBYTES = 16;   // HChaCha20 constant size
336
const crypto_core_hchacha20_OUTPUTBYTES = 32;  // HChaCha20 output size
337

338
const crypto_core_hsalsa20_INPUTBYTES = 16;    // HSalsa20 input size
339
const crypto_core_hsalsa20_KEYBYTES = 32;      // HSalsa20 key size
340
const crypto_core_hsalsa20_CONSTBYTES = 16;    // HSalsa20 constant size
341
const crypto_core_hsalsa20_OUTPUTBYTES = 32;   // HSalsa20 output size
342
```
343

344
## Security Considerations
345

346
**⚠️ Advanced Users Only**: These functions are low-level primitives that can easily be misused. Incorrect usage can lead to serious security vulnerabilities.
347

348
### Ed25519 Operations:
349
- **Point Validation**: Always validate curve points before use - invalid points can break protocols
350
- **Scalar Reduction**: Ensure scalars are properly reduced - unreduced scalars can leak information
351
- **Side-Channel Attacks**: These operations may not be constant-time for all inputs
352
- **Protocol Design**: Consult cryptographic literature before designing protocols with these primitives
353

354
### Ristretto255 Operations:
355
- **Prime Order Group**: Ristretto255 provides a prime-order group, avoiding cofactor issues of Ed25519
356
- **Hash-to-Curve**: Use `from_hash` for deterministic point generation from arbitrary data
357
- **Element Validation**: All Ristretto255 elements are valid by construction, but still validate untrusted inputs
358

359
### Low-Level Core Functions:
360
- **Construction Only**: HChaCha20/HSalsa20 are building blocks, not standalone encryption functions
361
- **Key Derivation**: Primarily used for deriving subkeys in extended-nonce constructions
362
- **Constant Handling**: Use null for default constants unless you need custom values
363

364
### General Recommendations:
365
- **Use Higher-Level APIs**: Prefer authenticated encryption and digital signatures over these primitives
366
- **Protocol Review**: Have cryptographic experts review any protocol using these functions
367
- **Testing**: Thoroughly test with known test vectors and edge cases
368
- **Documentation**: Study the libsodium documentation and academic papers before implementation