0
# @stablelib/x25519
1

2
@stablelib/x25519 implements the X25519 key agreement protocol based on Curve25519 elliptic curve cryptography. It provides both low-level cryptographic primitives for direct scalar multiplication operations and a high-level key agreement interface for building secure communication protocols.
3

4
## Package Information
5

6
- **Package Name**: @stablelib/x25519
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @stablelib/x25519`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  generateKeyPair,
16
  sharedKey,
17
  PUBLIC_KEY_LENGTH,
18
  SECRET_KEY_LENGTH,
19
  SHARED_KEY_LENGTH
20
} from "@stablelib/x25519";
21
import {
22
  X25519KeyAgreement,
23
  OFFER_MESSAGE_LENGTH,
24
  ACCEPT_MESSAGE_LENGTH
25
} from "@stablelib/x25519/keyagreement";
26
```
27

28
For CommonJS:
29

30
```javascript
31
const {
32
  generateKeyPair,
33
  sharedKey,
34
  PUBLIC_KEY_LENGTH,
35
  SECRET_KEY_LENGTH,
36
  SHARED_KEY_LENGTH
37
} = require("@stablelib/x25519");
38
const {
39
  X25519KeyAgreement,
40
  OFFER_MESSAGE_LENGTH,
41
  ACCEPT_MESSAGE_LENGTH
42
} = require("@stablelib/x25519/keyagreement");
43
```
44

45
## Basic Usage
46

47
```typescript
48
import { generateKeyPair, sharedKey } from "@stablelib/x25519";
49

50
// Generate ephemeral key pairs for both parties
51
const alice = generateKeyPair();
52
const bob = generateKeyPair();
53

54
// Compute shared secret (both parties compute the same value)
55
const aliceShared = sharedKey(alice.secretKey, bob.publicKey);
56
const bobShared = sharedKey(bob.secretKey, alice.publicKey);
57

58
// aliceShared equals bobShared - use this for symmetric encryption
59
console.log("Shared key established:", aliceShared);
60
```
61

62
## Architecture
63

64
@stablelib/x25519 is built around two main components:
65

66
- **Low-level primitives**: Direct access to X25519 scalar multiplication, key generation, and shared key computation for maximum flexibility
67
- **High-level protocol**: `X25519KeyAgreement` class implementing a complete key agreement protocol with offer/accept pattern for interactive key exchange
68
- **Security features**: Secure memory wiping, timing attack protection, and optional validation of shared key results
69
- **TypeScript integration**: Full type safety with proper interfaces for key pairs and protocol messages
70

71
## Capabilities
72

73
### Low-level X25519 Operations
74

75
Core X25519 cryptographic primitives for key generation and shared key computation. Provides direct access to Curve25519 scalar multiplication operations.
76

77
```typescript { .api }
78
function generateKeyPair(prng?: RandomSource): KeyPair;
79
function generateKeyPairFromSeed(seed: Uint8Array): KeyPair;
80
function sharedKey(mySecretKey: Uint8Array, theirPublicKey: Uint8Array, rejectZero?: boolean): Uint8Array;
81

82
interface KeyPair {
83
  publicKey: Uint8Array;
84
  secretKey: Uint8Array;
85
}
86
```
87

88
[Low-level Operations](./low-level-operations.md)
89

90
### High-level Key Agreement Protocol
91

92
Interactive key agreement protocol using ephemeral key pairs with offer/accept pattern. Suitable for building secure communication protocols.
93

94
```typescript { .api }
95
class X25519KeyAgreement implements KeyAgreement {
96
  constructor(secretSeed?: Uint8Array, prng?: RandomSource);
97
  offer(): Uint8Array;
98
  accept(offerMsg: Uint8Array): Uint8Array;
99
  finish(acceptMsg: Uint8Array): this;
100
  getSharedKey(): Uint8Array;
101
}
102
```
103

104
[Key Agreement Protocol](./key-agreement-protocol.md)
105

106
## Constants
107

108
```typescript { .api }
109
const PUBLIC_KEY_LENGTH: number;    // 32 bytes
110
const SECRET_KEY_LENGTH: number;    // 32 bytes  
111
const SHARED_KEY_LENGTH: number;    // 32 bytes
112
```
113

114
## Types
115

116
```typescript { .api }
117
interface KeyPair {
118
  publicKey: Uint8Array;
119
  secretKey: Uint8Array;
120
}
121

122
interface RandomSource {
123
  randomBytes(length: number): Uint8Array;
124
  isAvailable: boolean;
125
}
126
```
127

128
## Security Considerations
129

130
- **Authentication Required**: X25519 by itself does not provide authentication. It must be combined with signatures or other authentication methods to prevent man-in-the-middle attacks.
131
- **Key Material Processing**: The result of `sharedKey()` is raw output from scalar multiplication and **MUST** be processed through a key derivation function (KDF) before use as encryption keys. Never use the raw shared key directly for encryption or authentication.
132
- **Memory Security**: Use the `clean()` method on `X25519KeyAgreement` instances and consider wiping sensitive key material when no longer needed.
133
- **Zero Key Rejection**: The `rejectZero` parameter in `sharedKey()` can detect certain types of invalid public keys that would result in all-zero shared secrets.