0
# Low-level X25519 Operations
1

2
Low-level X25519 cryptographic primitives providing direct access to Curve25519 scalar multiplication, key generation, and shared key computation.
3

4
## Capabilities
5

6
### Key Generation
7

8
Generate X25519 key pairs for cryptographic operations.
9

10
```typescript { .api }
11
/**
12
 * Generate a random X25519 key pair using secure random number generation
13
 * @param prng - Optional random source, uses system random if not provided
14
 * @returns KeyPair containing public and secret keys
15
 */
16
function generateKeyPair(prng?: RandomSource): KeyPair;
17

18
/**
19
 * Generate deterministic X25519 key pair from a 32-byte seed
20
 * @param seed - 32-byte seed for deterministic key generation
21
 * @returns KeyPair containing public and secret keys
22
 * @throws Error if seed length is not 32 bytes
23
 */
24
function generateKeyPairFromSeed(seed: Uint8Array): KeyPair;
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import { generateKeyPair, generateKeyPairFromSeed } from "@stablelib/x25519";
31

32
// Generate random key pair
33
const keyPair = generateKeyPair();
34
console.log("Public key length:", keyPair.publicKey.length); // 32
35
console.log("Secret key length:", keyPair.secretKey.length); // 32
36

37
// Generate deterministic key pair from seed
38
const seed = new Uint8Array(32); // Fill with your seed data
39
const deterministicKeyPair = generateKeyPairFromSeed(seed);
40
```
41

42
### Shared Key Computation
43

44
Compute shared secret between your secret key and peer's public key.
45

46
```typescript { .api }
47
/**
48
 * Compute shared secret using X25519 key agreement
49
 * @param mySecretKey - Your 32-byte secret key
50
 * @param theirPublicKey - Peer's 32-byte public key
51
 * @param rejectZero - If true, throws error when shared key is all-zero
52
 * @returns 32-byte shared secret (MUST be processed through KDF before use)
53
 * @throws Error if key lengths are incorrect or shared key is zero (when rejectZero=true)
54
 * 
55
 * IMPORTANT: The returned key is raw scalar multiplication output and MUST be
56
 * processed through a key derivation function before use as encryption keys.
57
 */
58
function sharedKey(
59
  mySecretKey: Uint8Array, 
60
  theirPublicKey: Uint8Array, 
61
  rejectZero?: boolean
62
): Uint8Array;
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
import { generateKeyPair, sharedKey } from "@stablelib/x25519";
69

70
// Both parties generate key pairs
71
const alice = generateKeyPair();
72
const bob = generateKeyPair();
73

74
// Compute shared secrets (both will be identical)
75
const aliceShared = sharedKey(alice.secretKey, bob.publicKey);
76
const bobShared = sharedKey(bob.secretKey, alice.publicKey);
77

78
// Shared secrets are equal
79
console.log("Secrets match:", 
80
  aliceShared.every((byte, i) => byte === bobShared[i])); // true
81

82
// Reject all-zero shared keys (recommended for protocols)
83
try {
84
  const safeShared = sharedKey(alice.secretKey, bob.publicKey, true);
85
} catch (error) {
86
  console.log("Invalid shared key detected");
87
}
88
```
89

90
### Scalar Multiplication
91

92
Low-level scalar multiplication operations on Curve25519.
93

94
```typescript { .api }
95
/**
96
 * Perform scalar multiplication on Curve25519
97
 * @param n - 32-byte scalar value
98
 * @param p - 32-byte point on the curve
99
 * @returns 32-byte result of scalar multiplication
100
 */
101
function scalarMult(n: Uint8Array, p: Uint8Array): Uint8Array;
102

103
/**
104
 * Scalar multiplication by the base point (generator)
105
 * @param n - 32-byte scalar value
106
 * @returns 32-byte public key corresponding to the scalar
107
 */
108
function scalarMultBase(n: Uint8Array): Uint8Array;
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import { scalarMult, scalarMultBase } from "@stablelib/x25519";
115

116
// Generate public key from private key
117
const privateKey = new Uint8Array(32); // Your private key
118
const publicKey = scalarMultBase(privateKey);
119

120
// Generic scalar multiplication
121
const scalar = new Uint8Array(32); // Your scalar
122
const point = new Uint8Array(32);  // Point on the curve
123
const result = scalarMult(scalar, point);
124
```
125

126
## Constants
127

128
```typescript { .api }
129
/** Length of X25519 public keys in bytes */
130
const PUBLIC_KEY_LENGTH: 32;
131

132
/** Length of X25519 secret keys in bytes */
133
const SECRET_KEY_LENGTH: 32;
134

135
/** Length of X25519 shared keys in bytes */
136
const SHARED_KEY_LENGTH: 32;
137
```
138

139
## Types
140

141
```typescript { .api }
142
/** X25519 key pair containing public and secret keys */
143
interface KeyPair {
144
  /** 32-byte public key */
145
  publicKey: Uint8Array;
146
  /** 32-byte secret key */
147
  secretKey: Uint8Array;
148
}
149

150
/** Interface for secure random number generation */
151
interface RandomSource {
152
  /** Generate random bytes of specified length */
153
  randomBytes(length: number): Uint8Array;
154
  /** Indicates if the random source is available */
155
  isAvailable: boolean;
156
}
157
```