OpenPGP.js 
+ OpenPGP.js 
OpenPGP.js is a JavaScript implementation of the OpenPGP protocol. It implements RFC4880 and parts of RFC4880bis.
Table of Contents
-
@@ -265,7 +265,7 @@ import * as openpgp from './openpgp.min.mjs';
const encrypted = await openpgp.encrypt({
message, // input as Message object
passwords: ['secret stuff'], // multiple passwords possible
- armor: false // don't ASCII armor (for Uint8Array output)
+ format: 'binary' // don't ASCII armor (for Uint8Array output)
});
console.log(encrypted); // Uint8Array
@@ -281,7 +281,7 @@ import * as openpgp from './openpgp.min.mjs';
})();
Encrypt and decrypt String data with PGP keys
-Encryption will use the algorithm preferred by the public key (defaults to aes256 for keys generated in OpenPGP.js), and decryption will use the algorithm used for encryption.
+Encryption will use the algorithm preferred by the public (encryption) key (defaults to aes256 for keys generated in OpenPGP.js), and decryption will use the algorithm used for encryption.
const openpgp = require('openpgp'); // use as CommonJS, AMD, ES6 module or via window.openpgp
(async () => {
@@ -297,14 +297,14 @@ import * as openpgp from './openpgp.min.mjs';
const publicKey = await openpgp.readKey({ armoredKey: publicKeyArmored });
const privateKey = await openpgp.decryptKey({
- privateKey: await openpgp.readKey({ armoredKey: privateKeyArmored }),
+ privateKey: await openpgp.readPrivateKey({ armoredKey: privateKeyArmored }),
passphrase
});
const encrypted = await openpgp.encrypt({
message: await openpgp.createMessage({ text: 'Hello, World!' }), // input as Message object
- publicKeys: publicKey, // for encryption
- privateKeys: privateKey // for signing (optional)
+ encryptionKeys: publicKey,
+ signingKeys: privateKey // optional
});
console.log(encrypted); // '-----BEGIN PGP MESSAGE ... END PGP MESSAGE-----'
@@ -313,11 +313,17 @@ import * as openpgp from './openpgp.min.mjs';
});
const { data: decrypted, signatures } = await openpgp.decrypt({
message,
- publicKeys: publicKey, // for verification (optional)
- privateKeys: privateKey // for decryption
+ verificationKeys: publicKey, // optional
+ decryptionKeys: privateKey
});
console.log(decrypted); // 'Hello, World!'
- console.log(signatures[0].valid) // signature validity (signed messages only)
+ // check signature validity (signed messages only)
+ try {
+ await signatures[0].verified; // throws on invalid signature
+ console.log('Signature is valid');
+ } catch (e) {
+ throw new Error('Signature could not be verified: ' + e.message);
+ }
})();
Encrypt to multiple public keys:
@@ -334,7 +340,7 @@ import * as openpgp from './openpgp.min.mjs'; ... -----END PGP PRIVATE KEY BLOCK-----`; // encrypted private key const passphrase = `yourPassphrase`; // what the private key is encrypted with - const message = 'Hello, World!'; + const plaintext = 'Hello, World!'; const publicKeys = await Promise.all(publicKeysArmored.map(armoredKey => openpgp.readKey({ armoredKey }))); @@ -343,11 +349,11 @@ import * as openpgp from './openpgp.min.mjs'; passphrase }); - const message = await openpgp.createMessage({ text: message }); + const message = await openpgp.createMessage({ text: plaintext }); const encrypted = await openpgp.encrypt({ - message:, // input as Message object - publicKeys, // for encryption - privateKeys: privateKey // for signing (optional) + message, // input as Message object + encryptionKeys: publicKeys, + signingKeys: privateKey // optional }); console.log(encrypted); // '-----BEGIN PGP MESSAGE ... END PGP MESSAGE-----' })(); @@ -366,7 +372,7 @@ import * as openpgp from './openpgp.min.mjs'; const publicKey = await openpgp.readKey({ armoredKey: publicKeyArmored }); const privateKey = await openpgp.decryptKey({ - privateKey: await openpgp.readKey({ armoredKey: privateKeyArmored }), + privateKey: await openpgp.readPrivateKey({ armoredKey: privateKeyArmored }), passphrase }); @@ -380,15 +386,15 @@ import * as openpgp from './openpgp.min.mjs'; // decryption will fail if all signatures are invalid or missing const { data: decrypted, signatures } = await openpgp.decrypt({ message, - privateKeys: privateKey // for decryption + decryptionKeys: privateKey, expectSigned: true, - publicKeys: publicKey, // for verification (mandatory with expectSigned=true) + verificationKeys: publicKey, // mandatory with expectSigned=true }); console.log(decrypted); // 'Hello, World!' })();Encrypt symmetrically with compression
-By default, encrypt will not use any compression when encrypting symmetrically only (i.e. when no publicKeys are given).
+
By default, encrypt will not use any compression when encrypting symmetrically only (i.e. when no encryptionKeys are given).
It's possible to change that behaviour by enabling compression through the config, either for the single encryption:
(async () => {
const message = await openpgp.createMessage({ binary: new Uint8Array([0x01, 0x02, 0x03]) }); // or createMessage({ text: 'string' })
@@ -421,7 +427,7 @@ It's possible to change that behaviour by enabling compression through the confi
const encrypted = await openpgp.encrypt({
message, // input as Message object
passwords: ['secret stuff'], // multiple passwords possible
- armor: false // don't ASCII armor (for Uint8Array output)
+ format: 'binary' // don't ASCII armor (for Uint8Array output)
});
console.log(encrypted); // raw encrypted packets as ReadableStream<Uint8Array>
@@ -443,7 +449,7 @@ can .pipe() to a Writable stream, for example.
const publicKeyArmored = `-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----`; // Public key
- const [privateKeyArmored] = `-----BEGIN PGP PRIVATE KEY BLOCK-----
+ const privateKeyArmored = `-----BEGIN PGP PRIVATE KEY BLOCK-----
...
-----END PGP PRIVATE KEY BLOCK-----`; // Encrypted private key
const passphrase = `yourPassphrase`; // Password that private key is encrypted with
@@ -451,7 +457,7 @@ can .pipe() to a Writable stream, for example.
const publicKey = await openpgp.readKey({ armoredKey: publicKeyArmored });
const privateKey = await openpgp.decryptKey({
- privateKey: await openpgp.readKey({ armoredKey: privateKeyArmored }),
+ privateKey: await openpgp.readPrivateKey({ armoredKey: privateKeyArmored }),
passphrase
});
@@ -464,8 +470,8 @@ can .pipe() to a Writable stream, for example.
const encrypted = await openpgp.encrypt({
message: await openpgp.createMessage({ text: readableStream }), // input as Message object
- publicKeys: publicKey, // for encryption
- privateKeys: privateKey // for signing (optional)
+ encryptionKeys: publicKey,
+ signingKeys: privateKey // optional
});
console.log(encrypted); // ReadableStream containing '-----BEGIN PGP MESSAGE ... END PGP MESSAGE-----'
@@ -474,8 +480,8 @@ can .pipe() to a Writable stream, for example.
});
const decrypted = await openpgp.decrypt({
message,
- publicKeys: publicKey, // for verification (optional)
- privateKeys: privateKey // for decryption
+ verificationKeys: publicKey, // optional
+ decryptionKeys: privateKey
});
const chunks = [];
for await (const chunk of decrypted.data) {
@@ -492,21 +498,22 @@ can .pipe() to a Writable stream, for example.
Note that both the curve25519 and ed25519 options generate a primary key for signing using Ed25519
and a subkey for encryption using Curve25519.
(async () => {
- const { privateKeyArmored, publicKeyArmored, revocationCertificate } = await openpgp.generateKey({
+ const { privateKey, publicKey, revocationCertificate } = await openpgp.generateKey({
type: 'ecc', // Type of the key, defaults to ECC
curve: 'curve25519', // ECC curve name, defaults to curve25519
userIDs: [{ name: 'Jon Smith', email: 'jon@example.com' }], // you can pass multiple user IDs
- passphrase: 'super long and hard to guess secret' // protects the private key
+ passphrase: 'super long and hard to guess secret', // protects the private key
+ format: 'armored' // output key format, defaults to 'armored' (other options: 'binary' or 'object')
});
- console.log(privateKeyArmored); // '-----BEGIN PGP PRIVATE KEY BLOCK ... '
- console.log(publicKeyArmored); // '-----BEGIN PGP PUBLIC KEY BLOCK ... '
+ console.log(privateKey); // '-----BEGIN PGP PRIVATE KEY BLOCK ... '
+ console.log(publicKey); // '-----BEGIN PGP PUBLIC KEY BLOCK ... '
console.log(revocationCertificate); // '-----BEGIN PGP PUBLIC KEY BLOCK ... '
})();
RSA keys (increased compatibility):
(async () => {
- const key = await openpgp.generateKey({
+ const { privateKey, publicKey } = await openpgp.generateKey({
type: 'rsa', // Type of the key
rsaBits: 4096, // RSA key size (defaults to 4096 bits)
userIDs: [{ name: 'Jon Smith', email: 'jon@example.com' }], // you can pass multiple user IDs
@@ -517,18 +524,21 @@ and a subkey for encryption using Curve25519.
Revoke a key
Using a revocation certificate:
(async () => {
- const { publicKeyArmored: revokedKeyArmored } = await openpgp.revokeKey({
+ const { publicKey: revokedKeyArmored } = await openpgp.revokeKey({
key: await openpgp.readKey({ armoredKey: publicKeyArmored }),
- revocationCertificate
+ revocationCertificate,
+ format: 'armored' // output armored keys
});
console.log(revokedKeyArmored); // '-----BEGIN PGP PUBLIC KEY BLOCK ... '
})();
Using the private key:
(async () => {
- const { publicKeyArmored, publicKey } = await openpgp.revokeKey({
- key: await openpgp.readKey({ armoredKey: privateKeyArmored })
+ const { publicKey: revokedKeyArmored } = await openpgp.revokeKey({
+ key: await openpgp.readKey({ armoredKey: privateKeyArmored }),
+ format: 'armored' // output armored keys
});
+ console.log(revokedKeyArmored); // '-----BEGIN PGP PUBLIC KEY BLOCK ... '
})();
Sign and verify cleartext messages
@@ -544,29 +554,30 @@ and a subkey for encryption using Curve25519.
const publicKey = await openpgp.readKey({ armoredKey: publicKeyArmored });
const privateKey = await openpgp.decryptKey({
- privateKey: await openpgp.readKey({ armoredKey: privateKeyArmored }),
+ privateKey: await openpgp.readPrivateKey({ armoredKey: privateKeyArmored }),
passphrase
});
const unsignedMessage = await openpgp.createCleartextMessage({ text: 'Hello, World!' });
const cleartextMessage = await openpgp.sign({
message: unsignedMessage, // CleartextMessage or Message object
- privateKeys: privateKey // for signing
+ signingKeys: privateKey
});
console.log(cleartextMessage); // '-----BEGIN PGP SIGNED MESSAGE ... END PGP SIGNATURE-----'
const signedMessage = await openpgp.readCleartextMessage({
cleartextMessage // parse armored message
});
- const verified = await openpgp.verify({
+ const verificationResult = await openpgp.verify({
message: signedMessage,
- publicKeys: publicKey // for verification
+ verificationKeys: publicKey
});
- const { valid } = verified.signatures[0];
- if (valid) {
- console.log('signed by key id ' + verified.signatures[0].keyID.toHex());
- } else {
- throw new Error('signature could not be verified');
+ const { verified, keyID } = verificationResult.signatures[0];
+ try {
+ await verified; // throws on invalid signature
+ console.log('Signed by key id ' + keyID.toHex());
+ } catch (e) {
+ throw new Error('Signature could not be verified: ' + e.message);
}
})();
@@ -583,14 +594,14 @@ and a subkey for encryption using Curve25519.
const publicKey = await openpgp.readKey({ armoredKey: publicKeyArmored });
const privateKey = await openpgp.decryptKey({
- privateKey: await openpgp.readKey({ armoredKey: privateKeyArmored }),
+ privateKey: await openpgp.readPrivateKey({ armoredKey: privateKeyArmored }),
passphrase
});
- const cleartextMessage = await openpgp.createCleartextMessage({ text: 'Hello, World!' });
+ const message = await openpgp.createMessage({ text: 'Hello, World!' });
const detachedSignature = await openpgp.sign({
- message: cleartextMessage, // CleartextMessage or Message object
- privateKeys: privateKey, // for signing
+ message, // Message object
+ signingKeys: privateKey,
detached: true
});
console.log(detachedSignature);
@@ -598,16 +609,17 @@ and a subkey for encryption using Curve25519.
const signature = await openpgp.readSignature({
armoredSignature: detachedSignature // parse detached signature
});
- const verified = await openpgp.verify({
- message: cleartextMessage, // CleartextMessage or Message object
+ const verificationResult = await openpgp.verify({
+ message, // Message object
signature,
- publicKeys: publicKey // for verification
+ verificationKeys: publicKey
});
- const { valid } = verified.signatures[0];
- if (valid) {
- console.log('signed by key id ' + verified.signatures[0].keyID.toHex());
- } else {
- throw new Error('signature could not be verified');
+ const { verified, keyID } = verificationResult.signatures[0];
+ try {
+ await verified; // throws on invalid signature
+ console.log('Signed by key id ' + keyID.toHex());
+ } catch (e) {
+ throw new Error('Signature could not be verified: ' + e.message);
}
})();
diff --git a/docs/module-config.html b/docs/module-config.html index 90f3d7b1..4689838c 100644 --- a/docs/module-config.html +++ b/docs/module-config.html @@ -89,7 +89,7 @@
diff --git a/docs/module-crypto_random-RandomBuffer.html b/docs/module-crypto_random-RandomBuffer.html index 6d565c43..135e0bb8 100644 --- a/docs/module-crypto_random-RandomBuffer.html +++ b/docs/module-crypto_random-RandomBuffer.html @@ -95,7 +95,7 @@
diff --git a/docs/module-enums.html b/docs/module-enums.html index 1c9348b7..b192b1bc 100644 --- a/docs/module-enums.html +++ b/docs/module-enums.html @@ -212,7 +212,7 @@