0
# Session Key Operations
1

2
Generate, encrypt, and decrypt session keys for advanced encryption workflows, key escrow scenarios, and performance optimization when encrypting multiple messages for the same recipients.
3

4
## Capabilities
5

6
### Session Key Generation
7

8
Generate session keys based on recipient key preferences.
9

10
```javascript { .api }
11
/**
12
 * Generate a new session key for encryption
13
 * @param options - Session key generation options
14
 * @returns Promise resolving to session key object
15
 */
16
function generateSessionKey(options: GenerateSessionKeyOptions): Promise<SessionKey>;
17

18
interface GenerateSessionKeyOptions {
19
  /** Public keys to determine algorithm preferences */
20
  encryptionKeys: PublicKey | PublicKey[];
21
  /** Date for key preference selection */
22
  date?: Date;
23
  /** User IDs for algorithm preferences */
24
  encryptionUserIDs?: UserID | UserID[];
25
  /** Custom configuration */
26
  config?: PartialConfig;
27
}
28

29
interface SessionKey {
30
  /** Session key data */
31
  data: Uint8Array;
32
  /** Symmetric algorithm name */
33
  algorithm: string;
34
  /** AEAD algorithm name (optional) */
35
  aeadAlgorithm?: string;
36
}
37
```
38

39
**Usage Examples:**
40

41
```javascript
42
import { generateSessionKey } from 'openpgp';
43

44
// Generate session key based on recipient preferences
45
const sessionKey = await generateSessionKey({
46
  encryptionKeys: [publicKey1, publicKey2],
47
  encryptionUserIDs: [
48
    { email: 'recipient1@example.com' },
49
    { email: 'recipient2@example.com' }
50
  ]
51
});
52

53
console.log('Algorithm:', sessionKey.algorithm);
54
console.log('Key length:', sessionKey.data.length);
55

56
// Generate session key with default algorithm preferences
57
const defaultSessionKey = await generateSessionKey({
58
  encryptionKeys: []
59
});
60
```
61

62
### Session Key Encryption
63

64
Encrypt session keys with public keys or passwords for key distribution.
65

66
```javascript { .api }
67
/**
68
 * Encrypt a session key with public keys or passwords
69
 * @param options - Session key encryption options
70
 * @returns Promise resolving to encrypted session key message
71
 */
72
function encryptSessionKey(options: EncryptSessionKeyOptions): Promise<string | Uint8Array>;
73

74
interface EncryptSessionKeyOptions {
75
  /** Session key data */
76
  data: Uint8Array;
77
  /** Symmetric algorithm name */
78
  algorithm: string;
79
  /** AEAD algorithm name (optional) */
80
  aeadAlgorithm?: string;
81
  /** Public keys for encryption */
82
  encryptionKeys?: PublicKey | PublicKey[];
83
  /** Passwords for encryption */
84
  passwords?: string | string[];
85
  /** Output format */
86
  format?: 'armored' | 'binary' | 'object';
87
  /** Use wildcard key ID */
88
  wildcard?: boolean;
89
  /** Key IDs for encryption */
90
  encryptionKeyIDs?: KeyID | KeyID[];
91
  /** Override date */
92
  date?: Date;
93
  /** User IDs for encryption */
94
  encryptionUserIDs?: UserID | UserID[];
95
  /** Custom configuration */
96
  config?: PartialConfig;
97
}
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
import { generateSessionKey, encryptSessionKey } from 'openpgp';
104

105
// Generate and encrypt session key
106
const sessionKey = await generateSessionKey({
107
  encryptionKeys: recipientKeys
108
});
109

110
const encryptedSessionKey = await encryptSessionKey({
111
  data: sessionKey.data,
112
  algorithm: sessionKey.algorithm,
113
  encryptionKeys: recipientKeys,
114
  format: 'armored'
115
});
116

117
// Encrypt session key with password
118
const passwordEncryptedKey = await encryptSessionKey({
119
  data: sessionKey.data,
120
  algorithm: sessionKey.algorithm,
121
  passwords: ['shared-secret'],
122
  format: 'armored'
123
});
124

125
// Encrypt for multiple recipients with different methods
126
const multiMethodEncrypted = await encryptSessionKey({
127
  data: sessionKey.data,
128
  algorithm: sessionKey.algorithm,
129
  encryptionKeys: [publicKey1, publicKey2],
130
  passwords: ['backup-password'],
131
  format: 'armored'
132
});
133
```
134

135
### Session Key Decryption
136

137
Decrypt session keys from encrypted messages.
138

139
```javascript { .api }
140
/**
141
 * Decrypt session keys from a message
142
 * @param options - Session key decryption options
143
 * @returns Promise resolving to array of decrypted session keys
144
 */
145
function decryptSessionKeys(options: DecryptSessionKeysOptions): Promise<DecryptedSessionKey[]>;
146

147
interface DecryptSessionKeysOptions {
148
  /** Message containing encrypted session keys */
149
  message: Message;
150
  /** Private keys for decryption */
151
  decryptionKeys?: PrivateKey | PrivateKey[];
152
  /** Passwords for decryption */
153
  passwords?: string | string[];
154
  /** Date for key verification */
155
  date?: Date;
156
  /** Custom configuration */
157
  config?: PartialConfig;
158
}
159

160
interface DecryptedSessionKey {
161
  /** Session key data */
162
  data: Uint8Array;
163
  /** Symmetric algorithm name (null for SEIPDv2) */
164
  algorithm: string | null;
165
}
166
```
167

168
**Usage Examples:**
169

170
```javascript
171
import { readMessage, decryptSessionKeys } from 'openpgp';
172

173
// Decrypt session keys from message
174
const message = await readMessage({ armoredMessage: encryptedData });
175
const sessionKeys = await decryptSessionKeys({
176
  message,
177
  decryptionKeys: privateKey
178
});
179

180
console.log('Found', sessionKeys.length, 'session keys');
181
for (const sk of sessionKeys) {
182
  console.log('Algorithm:', sk.algorithm);
183
  console.log('Key length:', sk.data.length);
184
}
185

186
// Decrypt with password
187
const passwordSessionKeys = await decryptSessionKeys({
188
  message,
189
  passwords: ['shared-secret']
190
});
191

192
// Try multiple decryption methods
193
const multiSessionKeys = await decryptSessionKeys({
194
  message,
195
  decryptionKeys: [privateKey1, privateKey2],
196
  passwords: ['backup-password']
197
});
198
```
199

200
## Advanced Session Key Workflows
201

202
### Bulk Encryption Optimization
203

204
Use session keys to optimize encryption for multiple messages.
205

206
```javascript
207
import { 
208
  generateSessionKey, 
209
  encryptSessionKey, 
210
  createMessage, 
211
  encrypt 
212
} from 'openpgp';
213

214
// Generate session key once
215
const sessionKey = await generateSessionKey({
216
  encryptionKeys: recipientKeys
217
});
218

219
// Encrypt session key for recipients (do this once)
220
const encryptedSessionKey = await encryptSessionKey({
221
  ...sessionKey,
222
  encryptionKeys: recipientKeys
223
});
224

225
// Use session key to encrypt multiple messages efficiently
226
const messages = ['Message 1', 'Message 2', 'Message 3'];
227
const encryptedMessages = [];
228

229
for (const text of messages) {
230
  const message = await createMessage({ text });
231
  const encrypted = await encrypt({
232
    message,
233
    sessionKey,
234
    format: 'armored'
235
  });
236
  encryptedMessages.push(encrypted);
237
}
238

239
console.log('Encrypted', messages.length, 'messages with same session key');
240
```
241

242
### Key Escrow Implementation
243

244
Implement key escrow by encrypting session keys for escrow keys.
245

246
```javascript
247
import { 
248
  generateSessionKey, 
249
  encryptSessionKey, 
250
  createMessage, 
251
  encrypt 
252
} from 'openpgp';
253

254
// Generate session key
255
const sessionKey = await generateSessionKey({
256
  encryptionKeys: recipientKeys
257
});
258

259
// Encrypt session key for both recipients and escrow
260
const recipientEncryptedKey = await encryptSessionKey({
261
  ...sessionKey,
262
  encryptionKeys: recipientKeys,
263
  format: 'armored'
264
});
265

266
const escrowEncryptedKey = await encryptSessionKey({
267
  ...sessionKey,
268
  encryptionKeys: escrowPublicKey,
269
  format: 'armored'
270
});
271

272
// Encrypt message with session key
273
const message = await createMessage({ text: 'Sensitive data' });
274
const encryptedMessage = await encrypt({
275
  message,
276
  sessionKey,
277
  format: 'armored'
278
});
279

280
// Store all components
281
const escrowPackage = {
282
  encryptedMessage,
283
  recipientEncryptedKey,
284
  escrowEncryptedKey,
285
  timestamp: new Date().toISOString()
286
};
287
```
288

289
### Session Key Reuse Pattern
290

291
Safely reuse session keys for performance in high-throughput scenarios.
292

293
```javascript
294
import { 
295
  generateSessionKey, 
296
  encryptSessionKey, 
297
  createMessage, 
298
  encrypt 
299
} from 'openpgp';
300

301
class SessionKeyManager {
302
  constructor(recipientKeys, maxReuse = 1000) {
303
    this.recipientKeys = recipientKeys;
304
    this.maxReuse = maxReuse;
305
    this.currentSessionKey = null;
306
    this.encryptedSessionKey = null;
307
    this.useCount = 0;
308
  }
309
  
310
  async rotateSessionKey() {
311
    this.currentSessionKey = await generateSessionKey({
312
      encryptionKeys: this.recipientKeys
313
    });
314
    
315
    this.encryptedSessionKey = await encryptSessionKey({
316
      ...this.currentSessionKey,
317
      encryptionKeys: this.recipientKeys
318
    });
319
    
320
    this.useCount = 0;
321
  }
322
  
323
  async encryptMessage(text) {
324
    // Rotate key if needed
325
    if (!this.currentSessionKey || this.useCount >= this.maxReuse) {
326
      await this.rotateSessionKey();
327
    }
328
    
329
    const message = await createMessage({ text });
330
    const encrypted = await encrypt({
331
      message,
332
      sessionKey: this.currentSessionKey
333
    });
334
    
335
    this.useCount++;
336
    
337
    return {
338
      encryptedMessage: encrypted,
339
      encryptedSessionKey: this.encryptedSessionKey,
340
      keyRotated: this.useCount === 1
341
    };
342
  }
343
}
344

345
// Usage
346
const manager = new SessionKeyManager(recipientKeys, 500);
347

348
const result1 = await manager.encryptMessage('First message');
349
const result2 = await manager.encryptMessage('Second message');
350
// ... session key is reused until rotation threshold
351
```
352

353
### Cross-Platform Session Key Exchange
354

355
Exchange session keys securely across different platforms.
356

357
```javascript
358
import { 
359
  generateSessionKey, 
360
  encryptSessionKey, 
361
  decryptSessionKeys,
362
  readMessage 
363
} from 'openpgp';
364

365
// Sender side - create portable session key package
366
async function createSessionKeyPackage(recipientKeys, senderPrivateKey) {
367
  const sessionKey = await generateSessionKey({
368
    encryptionKeys: recipientKeys
369
  });
370
  
371
  // Create signed and encrypted session key package
372
  const packageData = {
373
    sessionKey: sessionKey,
374
    timestamp: Date.now(),
375
    sender: 'sender@example.com'
376
  };
377
  
378
  const message = await createMessage({ 
379
    text: JSON.stringify(packageData) 
380
  });
381
  
382
  const encryptedPackage = await encrypt({
383
    message,
384
    encryptionKeys: recipientKeys,
385
    signingKeys: senderPrivateKey,
386
    format: 'armored'
387
  });
388
  
389
  return {
390
    sessionKey,
391
    encryptedPackage
392
  };
393
}
394

395
// Receiver side - extract session key from package
396
async function extractSessionKey(encryptedPackage, recipientPrivateKey, senderPublicKey) {
397
  const message = await readMessage({ armoredMessage: encryptedPackage });
398
  
399
  const decrypted = await decrypt({
400
    message,
401
    decryptionKeys: recipientPrivateKey,
402
    verificationKeys: senderPublicKey
403
  });
404
  
405
  const packageData = JSON.parse(decrypted.data);
406
  return packageData.sessionKey;
407
}
408
```