0
# Public Key Encryption
1

2
Asymmetric authenticated encryption using Curve25519 elliptic curve cryptography for secure communication between parties with public/private key pairs.
3

4
## Capabilities
5

6
### Key Pair Generation
7

8
Generates a random Curve25519 key pair for public key encryption.
9

10
```javascript { .api }
11
/**
12
 * Generate random Curve25519 key pair
13
 * @param pk - Output buffer for public key (must be PUBLICKEYBYTES long)
14
 * @param sk - Output buffer for secret key (must be SECRETKEYBYTES long)
15
 * @throws Error if buffer sizes are incorrect or generation fails
16
 */
17
function crypto_box_keypair(pk: Buffer, sk: Buffer): void;
18
```
19

20
### Seed-based Key Pair Generation
21

22
Generates a deterministic Curve25519 key pair from a seed.
23

24
```javascript { .api }
25
/**
26
 * Generate Curve25519 key pair from seed
27
 * @param pk - Output buffer for public key (must be PUBLICKEYBYTES long)
28
 * @param sk - Output buffer for secret key (must be SECRETKEYBYTES long)
29
 * @param seed - Seed buffer (must be SEEDBYTES long)
30
 * @throws Error if buffer sizes are incorrect or generation fails
31
 */
32
function crypto_box_seed_keypair(pk: Buffer, sk: Buffer, seed: Buffer): void;
33
```
34

35
**Usage Example:**
36

37
```javascript
38
const sodium = require('sodium-native');
39

40
// Generate Alice's key pair
41
const alicePk = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
42
const aliceSk = Buffer.alloc(sodium.crypto_box_SECRETKEYBYTES);
43
sodium.crypto_box_keypair(alicePk, aliceSk);
44

45
// Generate Bob's key pair  
46
const bobPk = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
47
const bobSk = Buffer.alloc(sodium.crypto_box_SECRETKEYBYTES);
48
sodium.crypto_box_keypair(bobPk, bobSk);
49
```
50

51
### Easy Mode Encryption
52

53
Encrypts a message from sender to recipient using their public key and sender's secret key.
54

55
```javascript { .api }
56
/**
57
 * Encrypt message using recipient's public key and sender's secret key
58
 * @param c - Output buffer for ciphertext (must be m.length + MACBYTES)
59
 * @param m - Message buffer to encrypt
60
 * @param n - Nonce buffer (must be NONCEBYTES long)
61
 * @param pk - Recipient's public key (must be PUBLICKEYBYTES long)
62
 * @param sk - Sender's secret key (must be SECRETKEYBYTES long)
63
 * @throws Error if buffer sizes are incorrect or encryption fails
64
 */
65
function crypto_box_easy(c: Buffer, m: Buffer, n: Buffer, pk: Buffer, sk: Buffer): void;
66
```
67

68
### Easy Mode Decryption
69

70
Decrypts and verifies a message using recipient's secret key and sender's public key.
71

72
```javascript { .api }
73
/**
74
 * Decrypt and verify message using recipient's secret key and sender's public key
75
 * @param m - Output buffer for plaintext (must be c.length - MACBYTES)
76
 * @param c - Ciphertext buffer to decrypt
77
 * @param n - Nonce buffer (must be NONCEBYTES long)
78
 * @param pk - Sender's public key (must be PUBLICKEYBYTES long)
79
 * @param sk - Recipient's secret key (must be SECRETKEYBYTES long)
80
 * @returns true if decryption successful, false if verification fails
81
 * @throws Error if buffer sizes are incorrect
82
 */
83
function crypto_box_open_easy(m: Buffer, c: Buffer, n: Buffer, pk: Buffer, sk: Buffer): boolean;
84
```
85

86
**Usage Example:**
87

88
```javascript
89
const sodium = require('sodium-native');
90

91
// Alice wants to send a message to Bob
92
const message = Buffer.from('Hello Bob!');
93
const nonce = Buffer.alloc(sodium.crypto_box_NONCEBYTES);
94
sodium.randombytes_buf(nonce);
95

96
// Alice encrypts using Bob's public key and her secret key
97
const ciphertext = Buffer.alloc(message.length + sodium.crypto_box_MACBYTES);
98
sodium.crypto_box_easy(ciphertext, message, nonce, bobPk, aliceSk);
99

100
// Bob decrypts using Alice's public key and his secret key
101
const plaintext = Buffer.alloc(ciphertext.length - sodium.crypto_box_MACBYTES);
102
if (sodium.crypto_box_open_easy(plaintext, ciphertext, nonce, alicePk, bobSk)) {
103
  console.log('Bob received:', plaintext.toString());
104
}
105
```
106

107
### Detached Mode Encryption
108

109
Encrypts a message with the authentication tag stored separately.
110

111
```javascript { .api }
112
/**
113
 * Encrypt message with detached authentication tag
114
 * @param c - Output buffer for ciphertext (must be same length as message)
115
 * @param mac - Output buffer for authentication tag (must be MACBYTES long)
116
 * @param m - Message buffer to encrypt
117
 * @param n - Nonce buffer (must be NONCEBYTES long)
118
 * @param pk - Recipient's public key (must be PUBLICKEYBYTES long)
119
 * @param sk - Sender's secret key (must be SECRETKEYBYTES long)
120
 * @throws Error if buffer sizes are incorrect or encryption fails
121
 */
122
function crypto_box_detached(c: Buffer, mac: Buffer, m: Buffer, n: Buffer, pk: Buffer, sk: Buffer): void;
123
```
124

125
### Detached Mode Decryption
126

127
Decrypts a message using a separate authentication tag.
128

129
```javascript { .api }
130
/**
131
 * Decrypt message with detached authentication tag
132
 * @param m - Output buffer for plaintext (must be same length as ciphertext)
133
 * @param c - Ciphertext buffer to decrypt
134
 * @param mac - Authentication tag buffer (must be MACBYTES long)
135
 * @param n - Nonce buffer (must be NONCEBYTES long)
136
 * @param pk - Sender's public key (must be PUBLICKEYBYTES long)
137
 * @param sk - Recipient's secret key (must be SECRETKEYBYTES long)
138
 * @returns true if decryption successful, false if verification fails
139
 * @throws Error if buffer sizes are incorrect
140
 */
141
function crypto_box_open_detached(m: Buffer, c: Buffer, mac: Buffer, n: Buffer, pk: Buffer, sk: Buffer): boolean;
142
```
143

144
### Anonymous Encryption (Sealed Box)
145

146
Encrypts a message to a recipient using only their public key (anonymous sender).
147

148
```javascript { .api }
149
/**
150
 * Encrypt message anonymously using only recipient's public key
151
 * @param c - Output buffer for sealed ciphertext (must be m.length + SEALBYTES)
152
 * @param m - Message buffer to encrypt
153
 * @param pk - Recipient's public key (must be PUBLICKEYBYTES long)
154
 * @throws Error if buffer sizes are incorrect or encryption fails
155
 */
156
function crypto_box_seal(c: Buffer, m: Buffer, pk: Buffer): void;
157
```
158

159
### Anonymous Decryption (Sealed Box)
160

161
Decrypts an anonymously encrypted message using the recipient's key pair.
162

163
```javascript { .api }
164
/**
165
 * Decrypt anonymously encrypted message
166
 * @param m - Output buffer for plaintext (must be c.length - SEALBYTES)
167
 * @param c - Sealed ciphertext buffer to decrypt
168
 * @param pk - Recipient's public key (must be PUBLICKEYBYTES long)
169
 * @param sk - Recipient's secret key (must be SECRETKEYBYTES long)
170
 * @returns true if decryption successful, false if verification fails
171
 */
172
function crypto_box_seal_open(m: Buffer, c: Buffer, pk: Buffer, sk: Buffer): boolean;
173
```
174

175
**Usage Example:**
176

177
```javascript
178
const sodium = require('sodium-native');
179

180
// Anonymous encryption to Bob
181
const message = Buffer.from('Anonymous message');
182
const sealedBox = Buffer.alloc(message.length + sodium.crypto_box_SEALBYTES);
183
sodium.crypto_box_seal(sealedBox, message, bobPk);
184

185
// Bob can decrypt without knowing sender
186
const plaintext = Buffer.alloc(sealedBox.length - sodium.crypto_box_SEALBYTES);
187
if (sodium.crypto_box_seal_open(plaintext, sealedBox, bobPk, bobSk)) {
188
  console.log('Anonymous message:', plaintext.toString());
189
}
190
```
191

192
## Constants
193

194
```javascript { .api }
195
// Seed size for deterministic key generation
196
const crypto_box_SEEDBYTES: number;
197

198
// Public key size in bytes
199
const crypto_box_PUBLICKEYBYTES: number;
200

201
// Secret key size in bytes  
202
const crypto_box_SECRETKEYBYTES: number;
203

204
// Nonce size in bytes
205
const crypto_box_NONCEBYTES: number;
206

207
// Authentication tag size in bytes
208
const crypto_box_MACBYTES: number;
209

210
// Additional bytes for sealed box encryption
211
const crypto_box_SEALBYTES: number;
212
```
213

214
## Security Considerations
215

216
- **Key Reuse**: Public keys can be safely reused, but each message must use a unique nonce.
217
- **Nonce Management**: Never reuse nonces between the same key pairs.
218
- **Sealed Boxes**: Provide anonymity but prevent reply without additional key exchange.
219
- **Forward Secrecy**: Consider ephemeral key pairs for forward secrecy in long-term communications.
220

221
## Common Patterns
222

223
### Secure Messaging
224

225
```javascript
226
const sodium = require('sodium-native');
227

228
class SecureMessaging {
229
  constructor() {
230
    this.publicKey = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
231
    this.secretKey = Buffer.alloc(sodium.crypto_box_SECRETKEYBYTES);
232
    sodium.crypto_box_keypair(this.publicKey, this.secretKey);
233
  }
234
  
235
  encryptTo(message, recipientPublicKey) {
236
    const nonce = Buffer.alloc(sodium.crypto_box_NONCEBYTES);
237
    sodium.randombytes_buf(nonce);
238
    
239
    const ciphertext = Buffer.alloc(message.length + sodium.crypto_box_MACBYTES);
240
    sodium.crypto_box_easy(ciphertext, message, nonce, recipientPublicKey, this.secretKey);
241
    
242
    return { ciphertext, nonce };
243
  }
244
  
245
  decryptFrom(ciphertext, nonce, senderPublicKey) {
246
    const plaintext = Buffer.alloc(ciphertext.length - sodium.crypto_box_MACBYTES);
247
    if (sodium.crypto_box_open_easy(plaintext, ciphertext, nonce, senderPublicKey, this.secretKey)) {
248
      return plaintext;
249
    }
250
    return null;
251
  }
252
  
253
  encryptAnonymous(message, recipientPublicKey) {
254
    const sealedBox = Buffer.alloc(message.length + sodium.crypto_box_SEALBYTES);
255
    sodium.crypto_box_seal(sealedBox, message, recipientPublicKey);
256
    return sealedBox;
257
  }
258
  
259
  decryptAnonymous(sealedBox) {
260
    const plaintext = Buffer.alloc(sealedBox.length - sodium.crypto_box_SEALBYTES);
261
    if (sodium.crypto_box_seal_open(plaintext, sealedBox, this.publicKey, this.secretKey)) {
262
      return plaintext;
263
    }
264
    return null;
265
  }
266
}
267
```