0
# OpenPGP.js
1

2
OpenPGP.js is a comprehensive JavaScript implementation of the OpenPGP protocol (RFC 9580/4880) that enables developers to implement end-to-end encryption, digital signatures, and key management in web browsers and Node.js applications. It provides a complete cryptographic toolkit with support for modern and legacy algorithms, streaming operations, and cross-platform compatibility.
3

4
## Package Information
5

6
- **Package Name**: openpgp
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install openpgp`
10

11
## Core Imports
12

13
For ES Modules (recommended):
14

15
```javascript
16
import { encrypt, decrypt, generateKey, readKey } from 'openpgp';
17
import { PrivateKey, PublicKey, Message, enums, config } from 'openpgp';
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { encrypt, decrypt, generateKey, readKey } = require('openpgp');
24
const { PrivateKey, PublicKey, Message, enums, config } = require('openpgp');
25
```
26

27
For browsers:
28

29
```html
30
<script src="https://unpkg.com/openpgp@6.2.2/dist/openpgp.min.js"></script>
31
<script>
32
  const { encrypt, decrypt, generateKey } = openpgp;
33
</script>
34
```
35

36
## Basic Usage
37

38
```javascript
39
import { generateKey, encrypt, decrypt, readKey, readMessage, createMessage } from 'openpgp';
40

41
// Generate a new key pair
42
const { privateKey, publicKey } = await generateKey({
43
  type: 'ecc',
44
  curve: 'curve25519Legacy',
45
  userIDs: [{ name: 'John Doe', email: 'john@example.com' }],
46
  passphrase: 'super-secret-passphrase'
47
});
48

49
// Create and encrypt a message
50
const message = await createMessage({ text: 'Hello, World!' });
51
const encrypted = await encrypt({
52
  message,
53
  encryptionKeys: publicKey,
54
  signingKeys: privateKey
55
});
56

57
// Decrypt the message
58
const decrypted = await decrypt({
59
  message: await readMessage({ armoredMessage: encrypted }),
60
  decryptionKeys: privateKey,
61
  verificationKeys: publicKey
62
});
63

64
console.log(decrypted.data); // 'Hello, World!'
65
```
66

67
## Architecture
68

69
OpenPGP.js is built around several key architectural components:
70

71
- **High-Level API**: Simplified functions for common operations (encrypt, decrypt, sign, verify, generateKey)
72
- **Object Model**: Rich classes representing keys, messages, signatures, and packets
73
- **Streaming Support**: Full Web Streams API integration for handling large data efficiently
74
- **Packet System**: Low-level OpenPGP packet implementation following RFC specifications
75
- **Multi-Platform**: Works in browsers (with Web Crypto API) and Node.js environments
76
- **Type Safety**: Complete TypeScript definitions for all APIs
77

78
## Capabilities
79

80
### Key Management
81

82
Complete key lifecycle management including generation, reading, encryption, decryption, and revocation. Supports RSA, ECC, and modern curve algorithms.
83

84
```javascript { .api }
85
function generateKey(options: GenerateKeyOptions): Promise<{
86
  privateKey: string | Uint8Array | PrivateKey,
87
  publicKey: string | Uint8Array | PublicKey,
88
  revocationCertificate: string
89
}>;
90

91
function readKey(options: { 
92
  armoredKey: string, 
93
  config?: PartialConfig 
94
}): Promise<Key>;
95

96
function decryptKey(options: { 
97
  privateKey: PrivateKey, 
98
  passphrase: string | string[], 
99
  config?: PartialConfig 
100
}): Promise<PrivateKey>;
101

102
interface GenerateKeyOptions {
103
  userIDs: UserID | UserID[];
104
  passphrase?: string;
105
  type?: 'ecc' | 'rsa' | 'curve25519' | 'curve448';
106
  curve?: EllipticCurveName;
107
  rsaBits?: number;
108
  keyExpirationTime?: number;
109
  date?: Date;
110
  subkeys?: SubkeyOptions[];
111
  format?: 'armored' | 'object' | 'binary';
112
  config?: PartialConfig;
113
}
114
```
115

116
[Key Management](./key-management.md)
117

118
### Message Encryption and Decryption
119

120
Encrypt and decrypt messages using public keys, passwords, or session keys. Supports both streaming and non-streaming operations with integrity protection.
121

122
```javascript { .api }
123
function encrypt(options: EncryptOptions): Promise<string | Uint8Array>;
124

125
function decrypt(options: DecryptOptions): Promise<{
126
  data: string | Uint8Array,
127
  signatures: VerificationResult[],
128
  filename: string
129
}>;
130

131
interface EncryptOptions {
132
  message: Message;
133
  encryptionKeys?: PublicKey | PublicKey[];
134
  signingKeys?: PrivateKey | PrivateKey[];
135
  passwords?: string | string[];
136
  format?: 'armored' | 'binary' | 'object';
137
  config?: PartialConfig;
138
}
139

140
interface DecryptOptions {
141
  message: Message;
142
  decryptionKeys?: PrivateKey | PrivateKey[];
143
  passwords?: string | string[];
144
  verificationKeys?: PublicKey | PublicKey[];
145
  format?: 'utf8' | 'binary';
146
  config?: PartialConfig;
147
}
148
```
149

150
[Encryption and Decryption](./encryption-decryption.md)
151

152
### Message Signing and Verification
153

154
Create and verify digital signatures for messages and cleartext. Supports detached signatures and multiple signing keys.
155

156
```javascript { .api }
157
function sign(options: SignOptions): Promise<string | Uint8Array>;
158

159
function verify(options: VerifyOptions): Promise<{
160
  data: string | Uint8Array,
161
  signatures: VerificationResult[]
162
}>;
163

164
interface SignOptions {
165
  message: CleartextMessage | Message;
166
  signingKeys: PrivateKey | PrivateKey[];
167
  format?: 'armored' | 'binary' | 'object';
168
  detached?: boolean;
169
  config?: PartialConfig;
170
}
171

172
interface VerificationResult {
173
  keyID: KeyID;
174
  verified: Promise<true>;
175
  signature: Promise<Signature>;
176
}
177
```
178

179
[Signing and Verification](./signing-verification.md)
180

181
### Session Key Operations
182

183
Generate, encrypt, and decrypt session keys for advanced encryption workflows and key escrow scenarios.
184

185
```javascript { .api }
186
function generateSessionKey(options: {
187
  encryptionKeys: PublicKey | PublicKey[],
188
  date?: Date,
189
  encryptionUserIDs?: UserID | UserID[],
190
  config?: PartialConfig
191
}): Promise<SessionKey>;
192

193
function encryptSessionKey(options: EncryptSessionKeyOptions): Promise<string | Uint8Array>;
194

195
function decryptSessionKeys(options: {
196
  message: Message,
197
  decryptionKeys?: PrivateKey | PrivateKey[],
198
  passwords?: string | string[],
199
  config?: PartialConfig
200
}): Promise<DecryptedSessionKey[]>;
201

202
interface SessionKey {
203
  data: Uint8Array;
204
  algorithm: string;
205
  aeadAlgorithm?: string;
206
}
207
```
208

209
[Session Key Operations](./session-keys.md)
210

211
### Low-Level Packet API
212

213
Direct access to OpenPGP packet system for advanced use cases, custom implementations, and protocol-level operations.
214

215
```javascript { .api }
216
class PublicKeyPacket extends BasePacket {
217
  algorithm: enums.publicKey;
218
  created: Date;
219
  version: number;
220
  getFingerprint(): string;
221
  getKeyID(): KeyID;
222
}
223

224
class SignaturePacket extends BasePacket {
225
  version: number;
226
  signatureType: enums.signature | null;
227
  hashAlgorithm: enums.hash | null;
228
  created: Date | null;
229
  sign(key: SecretKeyPacket, data: Uint8Array): Promise<void>;
230
  verify(key: PublicKeyPacket, data: Uint8Array): Promise<void>;
231
}
232

233
class PacketList<T> extends Array<T> {
234
  static fromBinary(bytes: Uint8Array): PacketList<any>;
235
  write(): Uint8Array;
236
  filterByTag(...tags: enums.packet[]): PacketList<T>;
237
}
238
```
239

240
[Low-Level Packet API](./packet-api.md)
241

242
### ASCII Armor Operations
243

244
Encode and decode OpenPGP data with ASCII armor format for text-safe transmission.
245

246
```javascript { .api }
247
function armor(
248
  messagetype: enums.armor, 
249
  body: object, 
250
  partindex?: number, 
251
  parttotal?: number, 
252
  customComment?: string, 
253
  emitChecksum?: boolean, 
254
  config?: Config
255
): string;
256

257
function unarmor(input: string, config?: Config): Promise<{
258
  text: string,
259
  data: ReadableStream<Uint8Array>,
260
  type: enums.armor
261
}>;
262
```
263

264
## Core Types
265

266
```javascript { .api }
267
interface UserID {
268
  name?: string;
269
  email?: string;
270
  comment?: string;
271
}
272

273
interface PartialConfig {
274
  preferredHashAlgorithm?: enums.hash;
275
  preferredSymmetricAlgorithm?: enums.symmetric;
276
  preferredCompressionAlgorithm?: enums.compression;
277
  aeadProtect?: boolean;
278
  v6Keys?: boolean;
279
}
280

281
type EllipticCurveName = 
282
  | 'ed25519Legacy' 
283
  | 'curve25519Legacy' 
284
  | 'nistP256' 
285
  | 'nistP384' 
286
  | 'nistP521' 
287
  | 'secp256k1' 
288
  | 'brainpoolP256r1' 
289
  | 'brainpoolP384r1' 
290
  | 'brainpoolP512r1';
291

292
type MaybeStream<T> = T | ReadableStream<T>;
293

294
// Enums namespace containing all OpenPGP constants
295
declare const enums: {
296
  armor: { [key: string]: number };
297
  compression: { [key: string]: number };
298
  hash: { [key: string]: number };
299
  packet: { [key: string]: number };
300
  publicKey: { [key: string]: number };
301
  symmetric: { [key: string]: number };
302
  signature: { [key: string]: number };
303
  reasonForRevocation: { [key: string]: number };
304
  literal: { [key: string]: number };
305
  aead: { [key: string]: number };
306
};
307
```