pmcrypto

v7

Changed:

• init no longer accepts a openpgp instance: the OpenPGP.js lightweight build for browsers is always used.

• In encryptMessage:

  • input message: options.data has been replaced by options.textData/binaryData, and options.message has been removed
  • options.data used to have trailing spaces automatically stripped. Now pass options.stripTrailingSpaces = true for the same behaviour
  • options.returnSessionKey has been removed, now separately generate a session key using e.g. generateSessionKey and pass it via options.sessionKey.
  • options.publicKeys has been renamed to options.encryptionKeys, options.privateKeys to options.signingKeys.
  • options.armor has been replaced by options.format taking 'armored'|'binary'|'object', where armor: false corresponds to format: 'object' (but it is recommended to use 'binary' or 'armored' instead).
  • output message: result.message is always returned for encrypted data (result.data has been removed)

• In decryptMessage:

  • options.privateKeys has been renamed to options.decryptionKeys, options.publicKeys to options.verificationKeys.
  • errors has been renamed to verificationErrors
  • if the message is signed, and verificationKeys are given but none corresponds to the original signing key, a verification error is returned (previously, this didn't return any errors).

• In signMessage:

  • input message: options.data has been replaced by options.textData/binaryData, and options.message has been removed
  • options.data used to automatically create a cleartext message. For the same behaviour, if detached = true, now pass textData with stripTrailingSpaces. The equivalent for detached = false (namely CleartextMessage signing) is not implemented (unused).
  • options.privateKeys has been renamed to options.signingKeys.
  • options.armor has been replaced by options.format taking 'armored'|'binary'|'object', where armor: false corresponds to format: 'object' (but it is recommended to use 'binary' or 'armored' instead).

• In verifyMessage:

  • options.publicKeys has been renamed to options.verificationKeys.
  • pass options.stripTrailingSpaces: true if the message could contain trailing whitespaces on any line and it was signed by passing options.data in previous versions.
  • as in decryptMessage, if verificationKeys are given but none matches the original, a verification error is returned (previously, this didn't return any errors).

• generateSessionKey now takes recipient public keys in input and generates a session key compatible with their key preferences. The former function, which generates a key for a given symmetric algo was renamed generateSessionKeyForAlgorithm.

Replaced:

• getMessage, getSignature, getCleartextMessage, getKey(s): use the corresponding read* functions instead, which take named inputs to preserve type info (e.g. readMessage({ armoredMessage }))
• decryptPrivateKey, encryptPrivateKey: these performed both parsing/serialization and decryption/encryption. Now, separately parse a binary/armored key using readPrivateKey and then pass the result to decryptKey or encryptKey. These function still do not modify the original privateKey instance.

Added

• readPrivateKey(s): similar to readKey(s) but expect and return a PrivateKey instance
• generateSessionKeyForAlgorithm: same as generateSessionKey for v6

Removed:

• createMessage, createCleartextMessage: serialized data is now taken as input directly by sign/verify/encryptMessage as options.text/binaryData
• decryptMIMEMessage (unused)
• keyCheck and keyInfo (unused)
• snake_case aliases for base64 utils (e.g. encode_base64)
• createWorker : OpenPGP.js no longer includes a worker. For performance reasons, apps are encouraged to create their own workers.

Usage

pmcrypto must be initialized using the init function, to apply changes to the underlying OpenPGP.js configuration.

1import { init } from 'pmcrypto';
2
3init();

Examples

1const recipientPublicKey = await readKey({ armoredKey: '...' }); // or `binaryKey`
2const senderPrivateKey = await decryptKey({
3  privateKey: await readPrivateKey({ armoredKey: '...' }),
4  passphrase: 'personal key passphrase'
5});

1const { 
2  message: armoredMessage,
3  encryptedSignature: armoredEncryptedSignature
4} = await encryptMessage({
5  textData: 'text data to encrypt', // or `binaryData` for Uint8Arrays
6  encryptionKeys: recipientPublicKey, // and/or `passwords`
7  signingKeys: senderPrivateKey,
8  detached: true,
9  format: 'armored' // or 'binary' to output a binary message and signature
10});
11
12// share `armoredMessage`

1// load the required keys
2const senderPublicKey = await readKey(...);
3const recipientPrivateKey = await decryptKey(...);
4
5const { data: decryptedData, verified } = await decryptMessage({
6  message: await readMessage({ armoredMessage }), // or `binaryMessage`
7  encryptedSignature: await readMessage({ armoredMessage: armoredEncryptedSignature })
8  decryptionKeys: recipientPrivateKey // and/or 'passwords'
9  verificationKeys: senderPublicKey
10});

1const { data: dataStream, verified: verifiedPromise } = await decryptMessage({
2  message: await readMessage({ armoredMessage: streamedArmoredMessage }),
3  ... // other options
4});
5
6// you need to read `dataStream` before resolving `verifiedPromise`, even if you do not need the decrypted data
7const decryptedData = await readToEnd(dataStream);
8const verificationStatus = await verified;

1// First generate the session key
2const sessionKey = await generateSessionKey({ recipientKeys: recipientPublicKey });
3
4// Then encrypt the data with it
5const { message: armoredMessage } = await encryptMessage({
6  textData: 'text data to encrypt', // or `binaryData` for Uint8Arrays
7  sessionKey,
8  encryptionKeys: recipientPublicKey, // and/or `passwords`, used to encrypt the session key
9  signingKeys: senderPrivateKey,
10});

1
2// Then encrypt the data with it
3const { data } = await decryptMessage({
4  message: await readMessage({ armoredMessage }),
5  sessionKeys: sessionKey,
6  verificationKeys: senderPublicKey,
7});

1const armoredEncryptedSessionKey = await encryptSessionKey({
2  sessionKey,
3  encryptionKeys, // and/or passwords
4  format: 'armored'
5});
6
7// And decrypt it with:
8const sessionKey = await decryptSessionKey({
9  message: await readMessage({ armoredMessage: armoredEncryptedSessionKey }),
10  decryptionsKeys // and/or passwords
11});
12

Testing

Headless Chrome (or Chromium), Firefox and Webkit are used for the tests. To install any missing browsers automatically, you can run npx playwright install-deps <chromium|firefox|webkit>. Alternatively, you can install them manually as you normally would on your platform. If you'd like to test on a subset of browsers, use e.g. npm test -- --browsers ChromeHeadless,FirefoxHeadless.