0
# Key Exchange
1

2
Secure key exchange protocols for establishing shared secrets between parties using X25519 elliptic curve Diffie-Hellman. Supports both basic scalar multiplication and higher-level session key establishment.
3

4
## Capabilities
5

6
### Session Key Exchange
7

8
High-level interface for establishing separate transmission and reception keys between client and server.
9

10
```javascript { .api }
11
/**
12
 * Generates a key pair for key exchange
13
 * @returns Object with publicKey, privateKey, and keyType properties
14
 */
15
function crypto_kx_keypair();
16

17
/**
18
 * Generates deterministic key pair from seed
19
 * @param seed - 32-byte seed for key generation
20
 * @returns Object with publicKey, privateKey, and keyType properties
21
 */
22
function crypto_kx_seed_keypair(seed);
23

24
/**
25
 * Computes client-side session keys
26
 * @param clientPublicKey - Client's 32-byte public key
27
 * @param clientSecretKey - Client's 32-byte secret key
28
 * @param serverPublicKey - Server's 32-byte public key
29
 * @returns Object with sharedRx and sharedTx session keys
30
 */
31
function crypto_kx_client_session_keys(clientPublicKey, clientSecretKey, serverPublicKey);
32

33
/**
34
 * Computes server-side session keys
35
 * @param serverPublicKey - Server's 32-byte public key
36
 * @param serverSecretKey - Server's 32-byte secret key
37
 * @param clientPublicKey - Client's 32-byte public key
38
 * @returns Object with sharedRx and sharedTx session keys
39
 */
40
function crypto_kx_server_session_keys(serverPublicKey, serverSecretKey, clientPublicKey);
41
```
42

43
**Usage Example:**
44

45
```javascript
46
// Generate key pairs
47
const clientKeys = sodium.crypto_kx_keypair();
48
const serverKeys = sodium.crypto_kx_keypair();
49

50
// Client computes session keys
51
const clientSessionKeys = sodium.crypto_kx_client_session_keys(
52
  clientKeys.publicKey,
53
  clientKeys.privateKey,
54
  serverKeys.publicKey
55
);
56

57
// Server computes session keys
58
const serverSessionKeys = sodium.crypto_kx_server_session_keys(
59
  serverKeys.publicKey,
60
  serverKeys.privateKey,
61
  clientKeys.publicKey
62
);
63

64
// Keys are complementary:
65
// clientSessionKeys.sharedTx === serverSessionKeys.sharedRx
66
// clientSessionKeys.sharedRx === serverSessionKeys.sharedTx
67

68
// Use separate keys for each direction
69
const clientToServer = sodium.crypto_secretbox_easy(
70
  sodium.from_string("Hello server"),
71
  nonce1,
72
  clientSessionKeys.sharedTx
73
);
74

75
const serverToClient = sodium.crypto_secretbox_easy(
76
  sodium.from_string("Hello client"),
77
  nonce2,
78
  serverSessionKeys.sharedTx
79
);
80
```
81

82
### Low-Level Scalar Multiplication
83

84
Direct Curve25519 operations for custom key exchange protocols.
85

86
```javascript { .api }
87
/**
88
 * Performs scalar multiplication on Curve25519
89
 * @param privateKey - 32-byte scalar (private key)
90
 * @param publicKey - 32-byte curve point (public key)
91
 * @returns 32-byte shared secret
92
 * @throws Error if public key is weak or invalid
93
 */
94
function crypto_scalarmult(privateKey, publicKey);
95

96
/**
97
 * Computes public key from private key (scalar * base point)
98
 * @param privateKey - 32-byte private key
99
 * @returns 32-byte public key
100
 */
101
function crypto_scalarmult_base(privateKey);
102
```
103

104
**Low-Level Usage Example:**
105

106
```javascript
107
// Generate private keys (random scalars)
108
const alicePrivate = sodium.randombytes_buf(32);
109
const bobPrivate = sodium.randombytes_buf(32);
110

111
// Compute public keys
112
const alicePublic = sodium.crypto_scalarmult_base(alicePrivate);
113
const bobPublic = sodium.crypto_scalarmult_base(bobPrivate);
114

115
// Both parties compute the same shared secret
116
const aliceShared = sodium.crypto_scalarmult(alicePrivate, bobPublic);
117
const bobShared = sodium.crypto_scalarmult(bobPrivate, alicePublic);
118

119
// aliceShared === bobShared
120
```
121

122
### Ed25519 Scalar Operations
123

124
Advanced scalar arithmetic on the Ed25519 curve for cryptographic protocols.
125

126
```javascript { .api }
127
// Scalar multiplication and base point operations
128
function crypto_scalarmult_ed25519(n, p);
129
function crypto_scalarmult_ed25519_base(scalar);
130
function crypto_scalarmult_ed25519_noclamp(n, p);
131
function crypto_scalarmult_ed25519_base_noclamp(scalar);
132

133
// Ristretto255 operations (for advanced protocols)
134
function crypto_scalarmult_ristretto255(scalar, element);
135
function crypto_scalarmult_ristretto255_base(scalar);
136
```
137

138
## Key Pair Structure
139

140
```javascript { .api }
141
interface KeyExchangeKeyPair {
142
  publicKey: Uint8Array;  // 32 bytes - share with other party
143
  privateKey: Uint8Array; // 32 bytes - keep secret
144
  keyType: string;        // "x25519"
145
}
146

147
interface SessionKeys {
148
  sharedRx: Uint8Array;   // 32 bytes - for receiving (decrypting) messages
149
  sharedTx: Uint8Array;   // 32 bytes - for transmitting (encrypting) messages
150
}
151
```
152

153
## Constants
154

155
```javascript { .api }
156
// Key Exchange
157
const crypto_kx_PUBLICKEYBYTES = 32;     // Public key size
158
const crypto_kx_SECRETKEYBYTES = 32;     // Secret key size
159
const crypto_kx_SEEDBYTES = 32;          // Seed size for deterministic keys
160
const crypto_kx_SESSIONKEYBYTES = 32;    // Session key size
161

162
// Scalar Multiplication
163
const crypto_scalarmult_BYTES = 32;      // Shared secret size
164
const crypto_scalarmult_SCALARBYTES = 32; // Private key size
165

166
// Ed25519 Scalars
167
const crypto_scalarmult_ed25519_BYTES = 32;
168
const crypto_scalarmult_ed25519_SCALARBYTES = 32;
169

170
// Ristretto255
171
const crypto_scalarmult_ristretto255_BYTES = 32;
172
const crypto_scalarmult_ristretto255_SCALARBYTES = 32;
173
```
174

175
## Protocol Integration
176

177
**With Secret Box Encryption:**
178

179
```javascript
180
// Establish session keys
181
const sessionKeys = sodium.crypto_kx_client_session_keys(
182
  clientPublic, clientSecret, serverPublic
183
);
184

185
// Encrypt message with transmission key
186
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
187
const encrypted = sodium.crypto_secretbox_easy(
188
  message, 
189
  nonce, 
190
  sessionKeys.sharedTx
191
);
192

193
// Decrypt received message with reception key
194
const decrypted = sodium.crypto_secretbox_open_easy(
195
  receivedCiphertext, 
196
  receivedNonce, 
197
  sessionKeys.sharedRx
198
);
199
```
200

201
## Constants
202

203
```javascript { .api }
204
// Key Exchange
205
const crypto_kx_PUBLICKEYBYTES = 32;    // Public key size
206
const crypto_kx_SECRETKEYBYTES = 32;    // Private key size  
207
const crypto_kx_SEEDBYTES = 32;         // Seed size for deterministic keys
208
const crypto_kx_SESSIONKEYBYTES = 32;   // Session key size
209
```
210

211
## Security Considerations
212

213
- **Key Generation**: Always use `crypto_kx_keypair()` or secure random generation for private keys
214
- **Public Key Validation**: The library automatically validates public keys and rejects weak keys
215
- **Perfect Forward Secrecy**: Generate new key pairs for each session to achieve forward secrecy
216
- **Key Confirmation**: Consider implementing key confirmation to ensure both parties derived the same keys
217
- **Side-Channel Protection**: Private keys should be handled securely to prevent side-channel attacks
218
- **Session Separation**: Use separate keys for transmission and reception to prevent reflection attacks