0
# Key Management
1

2
Complete key lifecycle management for OpenPGP keys including generation, reading, encryption, decryption, reformatting, and revocation. Supports RSA, ECC, and modern curve algorithms with full type safety.
3

4
## Capabilities
5

6
### Key Generation
7

8
Generate new OpenPGP key pairs with support for multiple algorithms and configurations.
9

10
```javascript { .api }
11
/**
12
 * Generates a new OpenPGP key pair with specified options
13
 * @param options - Key generation configuration
14
 * @returns Promise resolving to key pair with revocation certificate
15
 */
16
function generateKey(options: GenerateKeyOptions): Promise<{
17
  privateKey: string | Uint8Array | PrivateKey,
18
  publicKey: string | Uint8Array | PublicKey,
19
  revocationCertificate: string
20
}>;
21

22
interface GenerateKeyOptions {
23
  /** User IDs as objects: { name: 'Jo Doe', email: 'info@jo.com' } */
24
  userIDs: UserID | UserID[];
25
  /** Passphrase to encrypt the private key. If omitted, key won't be encrypted */
26
  passphrase?: string;
27
  /** Primary key algorithm type */
28
  type?: 'ecc' | 'rsa' | 'curve25519' | 'curve448';
29
  /** Elliptic curve for ECC keys */
30
  curve?: EllipticCurveName;
31
  /** Number of bits for RSA keys (default: 4096) */
32
  rsaBits?: number;
33
  /** Key expiration time in seconds from creation (default: 0, never expires) */
34
  keyExpirationTime?: number;
35
  /** Override creation date */
36
  date?: Date;
37
  /** Subkey options */
38
  subkeys?: SubkeyOptions[];
39
  /** Output format */
40
  format?: 'armored' | 'object' | 'binary';
41
  /** Custom configuration */
42
  config?: PartialConfig;
43
}
44

45
interface SubkeyOptions {
46
  type?: 'ecc' | 'rsa' | 'curve25519' | 'curve448';
47
  curve?: EllipticCurveName;
48
  rsaBits?: number;
49
  keyExpirationTime?: number;
50
  date?: Date;
51
  /** Whether subkey should sign rather than encrypt */
52
  sign?: boolean;
53
  config?: PartialConfig;
54
}
55
```
56

57
**Usage Examples:**
58

59
```javascript
60
import { generateKey } from 'openpgp';
61

62
// Generate ECC key pair
63
const { privateKey, publicKey, revocationCertificate } = await generateKey({
64
  type: 'ecc',
65
  curve: 'curve25519Legacy',
66
  userIDs: [{ name: 'Alice Smith', email: 'alice@example.com' }],
67
  passphrase: 'super-secret-passphrase',
68
  format: 'armored'
69
});
70

71
// Generate RSA key pair
72
const rsaKeys = await generateKey({
73
  type: 'rsa',
74
  rsaBits: 4096,
75
  userIDs: [{ name: 'Bob Jones', email: 'bob@company.com' }],
76
  keyExpirationTime: 365 * 24 * 60 * 60, // 1 year
77
  format: 'object'
78
});
79

80
// Generate key with multiple subkeys
81
const complexKeys = await generateKey({
82
  type: 'ecc',
83
  userIDs: [{ name: 'Charlie Brown', email: 'charlie@org.com' }],
84
  subkeys: [
85
    { sign: false }, // encryption subkey (default)
86
    { sign: true }   // signing subkey
87
  ]
88
});
89
```
90

91
### Key Reading
92

93
Read OpenPGP keys from armored or binary data.
94

95
```javascript { .api }
96
/**
97
 * Read a single key from armored data
98
 * @param options - Key reading options
99
 * @returns Promise resolving to Key object
100
 */
101
function readKey(options: { 
102
  armoredKey: string, 
103
  config?: PartialConfig 
104
}): Promise<Key>;
105

106
/**
107
 * Read a single key from binary data
108
 * @param options - Key reading options
109
 * @returns Promise resolving to Key object
110
 */
111
function readKey(options: { 
112
  binaryKey: Uint8Array, 
113
  config?: PartialConfig 
114
}): Promise<Key>;
115

116
/**
117
 * Read multiple keys from armored data
118
 * @param options - Key reading options
119
 * @returns Promise resolving to array of Key objects
120
 */
121
function readKeys(options: { 
122
  armoredKeys: string, 
123
  config?: PartialConfig 
124
}): Promise<Key[]>;
125

126
/**
127
 * Read multiple keys from binary data
128
 * @param options - Key reading options
129
 * @returns Promise resolving to array of Key objects
130
 */
131
function readKeys(options: { 
132
  binaryKeys: Uint8Array, 
133
  config?: PartialConfig 
134
}): Promise<Key[]>;
135

136
/**
137
 * Read a private key from armored data
138
 * @param options - Key reading options
139
 * @returns Promise resolving to PrivateKey object
140
 */
141
function readPrivateKey(options: { 
142
  armoredKey: string, 
143
  config?: PartialConfig 
144
}): Promise<PrivateKey>;
145

146
/**
147
 * Read a private key from binary data
148
 * @param options - Key reading options
149
 * @returns Promise resolving to PrivateKey object
150
 */
151
function readPrivateKey(options: { 
152
  binaryKey: Uint8Array, 
153
  config?: PartialConfig 
154
}): Promise<PrivateKey>;
155

156
/**
157
 * Read multiple private keys from armored data
158
 * @param options - Key reading options
159
 * @returns Promise resolving to array of PrivateKey objects
160
 */
161
function readPrivateKeys(options: { 
162
  armoredKeys: string, 
163
  config?: PartialConfig 
164
}): Promise<PrivateKey[]>;
165

166
/**
167
 * Read multiple private keys from binary data
168
 * @param options - Key reading options
169
 * @returns Promise resolving to array of PrivateKey objects
170
 */
171
function readPrivateKeys(options: { 
172
  binaryKeys: Uint8Array, 
173
  config?: PartialConfig 
174
}): Promise<PrivateKey[]>;
175
```
176

177
**Usage Examples:**
178

179
```javascript
180
import { readKey, readPrivateKey } from 'openpgp';
181

182
// Read public key from armored format
183
const publicKey = await readKey({
184
  armoredKey: `-----BEGIN PGP PUBLIC KEY BLOCK-----
185
  
186
  mQENBF...
187
  -----END PGP PUBLIC KEY BLOCK-----`
188
});
189

190
// Read private key
191
const privateKey = await readPrivateKey({
192
  armoredKey: armoredPrivateKeyString
193
});
194

195
// Get key information
196
console.log('Key ID:', publicKey.getKeyID().toHex());
197
console.log('Fingerprint:', publicKey.getFingerprint());
198
console.log('User IDs:', publicKey.getUserIDs());
199
```
200

201
### Key Encryption and Decryption
202

203
Encrypt (lock) and decrypt (unlock) private keys with passphrases.
204

205
```javascript { .api }
206
/**
207
 * Unlock a private key with passphrase(s)
208
 * @param options - Decryption options
209
 * @returns Promise resolving to unlocked PrivateKey
210
 */
211
function decryptKey(options: { 
212
  privateKey: PrivateKey, 
213
  passphrase: string | string[], 
214
  config?: PartialConfig 
215
}): Promise<PrivateKey>;
216

217
/**
218
 * Lock a private key with passphrase(s)
219
 * @param options - Encryption options
220
 * @returns Promise resolving to locked PrivateKey
221
 */
222
function encryptKey(options: { 
223
  privateKey: PrivateKey, 
224
  passphrase: string | string[], 
225
  config?: PartialConfig 
226
}): Promise<PrivateKey>;
227
```
228

229
**Usage Examples:**
230

231
```javascript
232
import { generateKey, decryptKey, encryptKey } from 'openpgp';
233

234
// Generate encrypted key
235
const { privateKey } = await generateKey({
236
  userIDs: [{ name: 'Test User', email: 'test@example.com' }],
237
  passphrase: 'original-passphrase',
238
  format: 'object'
239
});
240

241
// Decrypt key to use for operations
242
const decryptedKey = await decryptKey({
243
  privateKey,
244
  passphrase: 'original-passphrase'
245
});
246

247
// Change passphrase by encrypting with new one
248
const reencryptedKey = await encryptKey({
249
  privateKey: decryptedKey,
250
  passphrase: 'new-passphrase'
251
});
252
```
253

254
### Key Reformatting
255

256
Reformat signature packets for a key and rewrap the key object.
257

258
```javascript { .api }
259
/**
260
 * Reformat signature packets for a key
261
 * @param options - Reformatting options
262
 * @returns Promise resolving to reformatted key pair with revocation certificate
263
 */
264
function reformatKey(options: ReformatKeyOptions): Promise<{
265
  privateKey: string | Uint8Array | PrivateKey,
266
  publicKey: string | Uint8Array | PublicKey,
267
  revocationCertificate: string
268
}>;
269

270
interface ReformatKeyOptions {
271
  /** Private key to reformat */
272
  privateKey: PrivateKey;
273
  /** User IDs for the reformatted key */
274
  userIDs?: UserID | UserID[];
275
  /** New passphrase for the reformatted key */
276
  passphrase?: string;
277
  /** New key expiration time */
278
  keyExpirationTime?: number;
279
  /** Override creation date of key signatures */
280
  date?: Date;
281
  /** Output format */
282
  format?: 'armored' | 'object' | 'binary';
283
  /** Custom configuration */
284
  config?: PartialConfig;
285
}
286
```
287

288
### Key Revocation
289

290
Revoke keys using private keys or revocation certificates.
291

292
```javascript { .api }
293
/**
294
 * Revoke a key with private key or revocation certificate
295
 * @param options - Revocation options
296
 * @returns Promise resolving to revoked key(s)
297
 */
298
function revokeKey(options: RevokeKeyOptions): Promise<{
299
  privateKey: string | Uint8Array | PrivateKey | null,
300
  publicKey: string | Uint8Array | PublicKey
301
}>;
302

303
interface RevokeKeyOptions {
304
  /** Key to revoke */
305
  key: PrivateKey | PublicKey;
306
  /** Revocation certificate (alternative to reasonForRevocation) */
307
  revocationCertificate?: string;
308
  /** Reason for revocation */
309
  reasonForRevocation?: ReasonForRevocation;
310
  /** Override revocation date */
311
  date?: Date;
312
  /** Output format */
313
  format?: 'armored' | 'object' | 'binary';
314
  /** Custom configuration */
315
  config?: PartialConfig;
316
}
317

318
interface ReasonForRevocation {
319
  /** Revocation reason flag */
320
  flag?: enums.reasonForRevocation;
321
  /** Explanation string */
322
  string?: string;
323
}
324
```
325

326
**Usage Examples:**
327

328
```javascript
329
import { revokeKey, enums } from 'openpgp';
330

331
// Revoke key with reason
332
const revokedKey = await revokeKey({
333
  key: privateKey,
334
  reasonForRevocation: {
335
    flag: enums.reasonForRevocation.keyCompromised,
336
    string: 'Private key was compromised'
337
  }
338
});
339

340
// Revoke key with revocation certificate
341
const revokedWithCert = await revokeKey({
342
  key: publicKey,
343
  revocationCertificate: revocationCertString
344
});
345
```
346

347
## Key Classes
348

349
### Key Base Class
350

351
```javascript { .api }
352
abstract class Key {
353
  /** Primary key packet */
354
  readonly keyPacket: PublicKeyPacket | SecretKeyPacket;
355
  /** Array of subkeys */
356
  subkeys: Subkey[];
357
  /** Array of users */
358
  users: User[];
359
  /** Revocation signatures */
360
  revocationSignatures: SignaturePacket[];
361
  
362
  /** Get binary representation */
363
  write(): Uint8Array;
364
  /** Get ASCII armored representation */
365
  armor(config?: Config): string;
366
  /** Get key expiration time */
367
  getExpirationTime(userID?: UserID, config?: Config): Promise<Date | typeof Infinity | null>;
368
  /** Get all key IDs */
369
  getKeyIDs(): KeyID[];
370
  /** Get primary user */
371
  getPrimaryUser(date?: Date, userID?: UserID, config?: Config): Promise<PrimaryUser>;
372
  /** Get user ID strings */
373
  getUserIDs(): string[];
374
  /** Check if this is a private key */
375
  isPrivate(): this is PrivateKey;
376
  /** Convert to public key */
377
  toPublic(): PublicKey;
378
  /** Get key fingerprint */
379
  getFingerprint(): string;
380
  /** Get key creation time */
381
  getCreationTime(): Date;
382
  /** Get key algorithm info */
383
  getAlgorithmInfo(): AlgorithmInfo;
384
  /** Get primary key ID */
385
  getKeyID(): KeyID;
386
}
387
```
388

389
### PublicKey Class
390

391
```javascript { .api }
392
class PublicKey extends Key {
393
  constructor(packetlist: PacketList<any>);
394
}
395
```
396

397
### PrivateKey Class
398

399
```javascript { .api }
400
class PrivateKey extends PublicKey {
401
  constructor(packetlist: PacketList<any>);
402
  
403
  /** Check if key is decrypted */
404
  isDecrypted(): boolean;
405
  /** Add a subkey */
406
  addSubkey(options: SubkeyOptions): Promise<PrivateKey>;
407
  /** Get decryption keys */
408
  getDecryptionKeys(keyID?: KeyID, date?: Date, userID?: UserID, config?: Config): Promise<(PrivateKey | Subkey)[]>;
409
  /** Revoke this key */
410
  revoke(reason?: ReasonForRevocation, date?: Date, config?: Config): Promise<PrivateKey>;
411
}
412
```
413

414
### Subkey Class
415

416
```javascript { .api }
417
class Subkey {
418
  constructor(subkeyPacket: SecretSubkeyPacket | PublicSubkeyPacket, mainKey: PublicKey);
419
  
420
  /** Subkey packet */
421
  readonly keyPacket: SecretSubkeyPacket | PublicSubkeyPacket;
422
  /** Main key this subkey belongs to */
423
  readonly mainKey: PublicKey;
424
  /** Binding signatures */
425
  bindingSignatures: SignaturePacket[];
426
  /** Revocation signatures */
427
  revocationSignatures: SignaturePacket[];
428
  
429
  /** Verify subkey binding */
430
  verify(date?: Date, config?: Config): Promise<SignaturePacket>;
431
  /** Check if subkey is decrypted */
432
  isDecrypted(): boolean;
433
  /** Get subkey fingerprint */
434
  getFingerprint(): string;
435
  /** Get subkey creation time */
436
  getCreationTime(): Date;
437
  /** Get subkey algorithm info */
438
  getAlgorithmInfo(): AlgorithmInfo;
439
  /** Get subkey ID */
440
  getKeyID(): KeyID;
441
  /** Get subkey expiration time */
442
  getExpirationTime(date?: Date, config?: Config): Promise<Date | typeof Infinity | null>;
443
  /** Check if subkey is revoked */
444
  isRevoked(signature: SignaturePacket, key: AnyKeyPacket, date?: Date, config?: Config): Promise<boolean>;
445
  /** Update subkey with another subkey */
446
  update(subKey: Subkey, date?: Date, config?: Config): Promise<void>;
447
  /** Revoke this subkey */
448
  revoke(primaryKey: SecretKeyPacket, reasonForRevocation?: ReasonForRevocation, date?: Date, config?: Config): Promise<Subkey>;
449
}
450
```
451

452
### User Class
453

454
```javascript { .api }
455
class User {
456
  constructor(userPacket: UserIDPacket | UserAttributePacket, mainKey: Key);
457
  
458
  /** User ID packet (null if user attribute) */
459
  readonly userID: UserIDPacket | null;
460
  /** User attribute packet (null if user ID) */
461
  readonly userAttribute: UserAttributePacket | null;
462
  /** Self-certifications */
463
  selfCertifications: SignaturePacket[];
464
  /** Other certifications */
465
  otherCertifications: SignaturePacket[];
466
  /** Revocation signatures */
467
  revocationSignatures: SignaturePacket[];
468
  /** Main key this user belongs to */
469
  readonly mainKey: Key;
470
  
471
  /** Convert to packet list */
472
  toPacketList(): PacketList<any>;
473
  /** Clone user */
474
  clone(): User;
475
  /** Certify user with signing keys */
476
  certify(signingKeys: PrivateKey[], date?: Date, config?: Config): Promise<User>;
477
  /** Check if user is revoked */
478
  isRevoked(
479
    certificate: SignaturePacket,
480
    keyPacket?: PublicSubkeyPacket | SecretSubkeyPacket | PublicKeyPacket | SecretKeyPacket,
481
    date?: Date,
482
    config?: Config
483
  ): Promise<boolean>;
484
  /** Verify a certificate */
485
  verifyCertificate(certificate: SignaturePacket, verificationKeys: PublicKey[], date?: Date, config?: Config): Promise<true | null>;
486
  /** Verify all certifications */
487
  verifyAllCertifications(verificationKeys: PublicKey[], date?: Date, config?: Config): Promise<{ keyID: KeyID; valid: boolean | null }[]>;
488
  /** Verify user */
489
  verify(date?: Date, config?: Config): Promise<true>;
490
  /** Update user with another user */
491
  update(sourceUser: User, date?: Date, config?: Config): Promise<void>;
492
  /** Revoke this user */
493
  revoke(primaryKey: SecretKeyPacket, reasonForRevocation?: ReasonForRevocation, date?: Date, config?: Config): Promise<User>;
494
}
495
```
496

497
### Supporting Types
498

499
```javascript { .api }
500
interface PrimaryUser {
501
  index: number;
502
  user: User;
503
  selfCertification: SignaturePacket;
504
}
505

506
interface AlgorithmInfo {
507
  algorithm: string;
508
  bits?: number;
509
  curve?: EllipticCurveName;
510
}
511

512
class KeyID {
513
  /** Key ID bytes as string */
514
  bytes: string;
515
  
516
  /** Read key ID from bytes */
517
  read(bytes: Uint8Array): number;
518
  /** Write key ID to bytes */
519
  write(): Uint8Array;
520
  /** Convert to hexadecimal string */
521
  toHex(): string;
522
  /** Check equality with another KeyID */
523
  equals(keyID: KeyID, matchWildcard?: boolean): boolean;
524
  /** Check if KeyID is null/unset */
525
  isNull(): boolean;
526
  /** Check if KeyID is wildcard (all zeros) */
527
  isWildcard(): boolean;
528
  
529
  /** Create KeyID from hexadecimal string */
530
  static fromID(hex: string): KeyID;
531
  /** Create wildcard KeyID */
532
  static wildcard(): KeyID;
533
  /** Map KeyID to hex string */
534
  static mapToHex(keyID: KeyID): string;
535
}
536
```