0
# Key Agreement Protocol
1

2
High-level X25519 key agreement protocol using ephemeral key pairs with offer/accept pattern for interactive key exchange between two parties.
3

4
## Capabilities
5

6
### X25519KeyAgreement Class
7

8
Interactive key agreement protocol implementing the standard offer/accept handshake pattern.
9

10
```typescript { .api }
11
/**
12
 * X25519 key agreement using ephemeral key pairs
13
 * 
14
 * Note: This protocol is vulnerable to man-in-the-middle attacks unless
15
 * combined with authentication methods such as public key signatures.
16
 */
17
class X25519KeyAgreement implements KeyAgreement {
18
  /** Length of offer messages in bytes */
19
  readonly offerMessageLength: number;
20
  /** Length of accept messages in bytes */
21
  readonly acceptMessageLength: number;
22
  /** Length of shared keys in bytes */
23
  readonly sharedKeyLength: number;
24
  /** Length of saved state in bytes */
25
  readonly savedStateLength: number;
26

27
  /**
28
   * Create new key agreement instance
29
   * @param secretSeed - Optional 32-byte seed for deterministic keys
30
   * @param prng - Optional random source for key generation
31
   */
32
  constructor(secretSeed?: Uint8Array, prng?: RandomSource);
33

34
  /** Initiate key agreement by generating offer message */
35
  offer(): Uint8Array;
36
  
37
  /** Accept offer and generate response message */
38
  accept(offerMsg: Uint8Array): Uint8Array;
39
  
40
  /** Complete key agreement using accept message */
41
  finish(acceptMsg: Uint8Array): this;
42
  
43
  /** Get the established shared key */
44
  getSharedKey(): Uint8Array;
45
  
46
  /** Save current state for serialization */
47
  saveState(): Uint8Array;
48
  
49
  /** Restore state from saved data */
50
  restoreState(savedState: Uint8Array): this;
51
  
52
  /** Securely wipe sensitive data from memory */
53
  clean(): void;
54
}
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { X25519KeyAgreement } from "@stablelib/x25519/keyagreement";
61

62
// Server-side (offering party)
63
const server = new X25519KeyAgreement();
64
const offerMessage = server.offer();
65

66
// Send offerMessage to client...
67

68
// Client-side (accepting party)  
69
const client = new X25519KeyAgreement();
70
const acceptMessage = client.accept(offerMessage);
71

72
// Send acceptMessage back to server...
73

74
// Server completes the handshake
75
server.finish(acceptMessage);
76

77
// Both parties now have the same shared key
78
const serverKey = server.getSharedKey();
79
const clientKey = client.getSharedKey();
80

81
// Clean up sensitive data
82
server.clean();
83
client.clean();
84
```
85

86
### Offer Method
87

88
Initiates key agreement by generating the offer message containing the offerer's public key.
89

90
```typescript { .api }
91
/**
92
 * Initiate key agreement by generating offer message
93
 * @returns 32-byte offer message containing public key
94
 * @throws Error if offer() is called multiple times on same instance
95
 */
96
offer(): Uint8Array;
97
```
98

99
### Accept Method
100

101
Accepts an offer message and generates the response message, computing the shared key internally.
102

103
```typescript { .api }
104
/**
105
 * Accept offer and generate response message
106
 * @param offerMsg - 32-byte offer message from the offering party
107
 * @returns 32-byte accept message containing public key
108
 * @throws Error if called by the offering party or if message length is incorrect
109
 */
110
accept(offerMsg: Uint8Array): Uint8Array;
111
```
112

113
### Finish Method
114

115
Completes the key agreement protocol using the accept message from the accepting party.
116

117
```typescript { .api }
118
/**
119
 * Complete key agreement using accept message
120
 * @param acceptMsg - 32-byte accept message from accepting party
121
 * @returns this instance for method chaining
122
 * @throws Error if message length is incorrect, no offer state exists, or finish was already called
123
 */
124
finish(acceptMsg: Uint8Array): this;
125
```
126

127
### Get Shared Key
128

129
Retrieves the established shared key after successful key agreement.
130

131
```typescript { .api }
132
/**
133
 * Get the established shared key
134
 * @returns 32-byte shared key
135
 * @throws Error if no shared key has been established
136
 */
137
getSharedKey(): Uint8Array;
138
```
139

140
### State Management
141

142
Methods for serializing and restoring key agreement state.
143

144
```typescript { .api }
145
/**
146
 * Save current state for serialization
147
 * @returns 32-byte state data
148
 */
149
saveState(): Uint8Array;
150

151
/**
152
 * Restore state from saved data
153
 * @param savedState - 32-byte saved state data
154
 * @returns this instance for method chaining
155
 */
156
restoreState(savedState: Uint8Array): this;
157
```
158

159
**Usage Examples:**
160

161
```typescript
162
import { X25519KeyAgreement } from "@stablelib/x25519/keyagreement";
163

164
// Save and restore state
165
const keyAgreement = new X25519KeyAgreement();
166
const savedState = keyAgreement.saveState();
167

168
// Later...
169
const restoredKeyAgreement = new X25519KeyAgreement();
170
restoredKeyAgreement.restoreState(savedState);
171
```
172

173
### Memory Cleanup
174

175
Securely wipe sensitive data from memory.
176

177
```typescript { .api }
178
/**
179
 * Securely wipe sensitive data from memory
180
 * Clears secret keys and shared keys using secure wiping
181
 */
182
clean(): void;
183
```
184

185
## Constants
186

187
```typescript { .api }
188
/** Length of offer messages in bytes */
189
const OFFER_MESSAGE_LENGTH: 32;
190

191
/** Length of accept messages in bytes */
192
const ACCEPT_MESSAGE_LENGTH: 32;
193

194
/** Length of saved state in bytes */
195
const SAVED_STATE_LENGTH: 32;
196

197
/** Length of secret seed in bytes */
198
const SECRET_SEED_LENGTH: 32;
199
```
200

201
## Types
202

203
```typescript { .api }
204
/** Interface implemented by X25519KeyAgreement */
205
interface KeyAgreement {
206
  readonly offerMessageLength: number;
207
  readonly acceptMessageLength: number;
208
  readonly sharedKeyLength: number;
209
  readonly savedStateLength: number;
210
  
211
  offer(): Uint8Array;
212
  accept(offerMsg: Uint8Array): Uint8Array;
213
  finish(acceptMsg: Uint8Array): this;
214
  getSharedKey(): Uint8Array;
215
  saveState(): Uint8Array;
216
  restoreState(savedState: Uint8Array): this;
217
  clean(): void;
218
}
219
```
220

221
## Protocol Flow
222

223
The key agreement protocol follows this sequence:
224

225
1. **Offer Phase**: Offerer calls `offer()` to generate offer message
226
2. **Accept Phase**: Accepter calls `accept(offerMessage)` to generate accept message
227
3. **Finish Phase**: Offerer calls `finish(acceptMessage)` to complete handshake
228
4. **Key Retrieval**: Both parties call `getSharedKey()` to get identical shared secret
229
5. **Cleanup**: Both parties call `clean()` to wipe sensitive data