The goal of our OpenPGPjs project is to make public-key cryptography not only available to users, but also to the global developer community. We believe the widespread availability of open-source and secure cryptography libraries is a prerequisite of the privacy revolution.
OpenPGPjs version 4.0 introduces streaming cryptography. This makes it possible for users of the library to encrypt, decrypt, sign, and verify files while they are simultaneously being downloaded or uploaded, meaning that large files no longer need to be stored in memory in order to perform these operations. The associated performance and storage benefits will allow us to speed up the encryption and decryption of email attachments and help us develop new products like ProtonDrive.
Proton Mail is committed to open source, and all the code for OpenPGPjs can be found on Github. You can also download the source code as a .zip file(new window) or as a tar.gz file(new window).
The support of the developer community is essential for the continued development of OpenPGPjs, and we welcome pull requests and comments. Here’s what’s new with OpenPGPjs 4.0:
Streaming Encryption
There are two different types of streaming implemented in this release.
The first can only be used in implementations that support the latest draft of authenticated encryption with associated data (AEAD), which was first added in OpenPGPjs v3.0.9. AEAD is particularly well-suited to streaming, because it allows messages to be divided into chunks, each of which has its own integrity tag that can be used to authenticate it as it is downloaded. In contrast to non-AEAD messages, this allows the client to trust each chunk as it is received, rather than waiting until the end of the data packet to check the integrity tag.
For compatibility with older messages and with other OpenPGP clients that do not support this draft, we have also implemented streaming for non-AEAD OpenPGP messages that use the unauthenticated cipher feedback mode (CFB) encryption rather than the authenticated modes supported in the AEAD implementation (EAX, OCB, and GCM).
Configuration Details
Streaming AEAD
The configuration setting openpgp.config.aead_chunk_size_byte controls the one-octet chunk size defined in the AEAD data packet, and defaults to 12. The size of each message chunk will be 2 ^ (openpgp.config.aead_chunk_size_byte + 6) bytes, and thus defaults to 256KB. This can be adjusted to receive data on the stream more or less frequently.
Streaming CFB
Because CFB-encrypted OpenPGP messages only have a single integrity tag, at the end of the message, it is not possible to authenticate data during stream decryption until the end of the message. Therefore, due to the security issues associated with using unauthenticated data(new window), we do not output any data to the stream by default during decryption. To override this default and allow unauthenticated data to be streamed, set openpgp.config.allow_unauthenticated_stream to true.
Web Streams Implementation
Browser support and Polyfills
This feature relies on the Web Streams API(new window), which Chrome, Safari, Firefox, and Edge currently have partially implemented, with Firefox’s implementation behind feature flags. Chrome is the only browser that implements TransformStreams, which are required in our implementation, so we include a polyfill for all other browsers. Please note that in those browsers, the global ReadableStream property gets overwritten with the polyfill version if it exists. Thus, if you need to use the native ReadableStream, you may need to store a reference to it before loading OpenPGPjs, or use the web-streams-adapter library to convert back and forth between them.In order to avoid separate implementations for web streams, node streams, and non-streamed data, all data is temporarily converted to a web stream internally and then converted back when returning. However, in the future, we might look into re-implementing some of the convenience functions of the web-stream-tools (see below) to not need streams, so that you don’t need to include the streams polyfill when not using streams.
New Web-Stream-Tools library
The OpenPGP spec requires us to manipulate and transform streams in complex ways: a stream of armored encrypted data needs to be parsed, then base64-decoded, then decrypted, then perhaps decompressed, then perhaps UTF8-decoded. Internally, we’re chaining together TransformStreams to achieve this. However, the TransformStream API is not quite sufficient for us: there is no way to control the amount of data that comes in at once, for example. And even if there was, we don’t always know in advance how many bytes we need: often, that depends on a field earlier in the data. To avoid having complex buffering code at every step of the way, we created a library to make this and other aspects of reading and transforming streams easier: web-stream-tools(new window). Contributions to make handling streams even easier are welcome!
High-Level API Changes
- openpgp.message.fromText(), fromBinary(), readArmored() and
read() now accept ReadableStreams as well as Node streams. - The high-level encrypt, decrypt, sign and verify functions now
have an streaming parameter, to control whether the return value
contains a stream. It can take the values “web”, “node”, or false.
It defaults to the type of stream you passed in, if any. - When streaming, the signatures returned by verify and decrypt have
a verified: Promise<Boolean> property instead of valid: Boolean. The
signature property is also a Promise in that case. - openpgp.{message,key,signature,cleartext}.readArmored() and
openpgp.{message,key,signature}.read() are now asynchronous.
For example, instead of writing let publicKey = openpgp.key.readArmored(publicKeyArmored).keys[0]; write, in an async function: let publicKey = (await openpgp.key.readArmored(publicKeyArmored)).keys[0];
- openpgp.encrypt() and openpgp.sign() now take a message
parameter instead of data, dataType and filename. Use
openpgp.message.fromText(), openpgp.message.fromBinary() or
openpgp.cleartext.fromText() to create a message. Note that if you
previously used the date parameter, you should now additionally pass
it to fromText/fromBinary as well. - After calling let keyring = new openpgp.Keyring(), you now have to
call await keyring.load() to read the keys from LocalStorage.
Separate bundle for old browsers
OpenPGPjs has been increasing in size due in part to the many new features (ECC in 3.0, Streaming in 4.0), but also because we supported a wide range of browsers. That meant we had to transpile ES6 to ES5 and include quite a lot of polyfills, both of which increase the library size.
We’ve now eliminated some polyfills from the default openpgp.min.js bundle, so it will now work with only recent versions of Chrome, Firefox, Safari, and Edge. If you need support for Internet Explorer 11 and old versions of Safari, you can use the new compat/openpgp.min.js bundle.
You could even load one or the other depending on which browser the user is using. However, if you’re using the web worker, keep in mind that you also need to pass { path: ‘compat/openpgp.worker.min.js’ } to initWorker whenever you load compat/openpgp.min.js.
Development
- You can now do grunt browsertest –dev to debug using a build with a source map and original module names intact. You can also do grunt browsertest –compat to test a build that’s compatible with IE11 and older versions of Safari. Both the –dev and –compat parameters also work for grunt build and other tasks that depend on it.
- There’s a new npm run build command to build both compat and non-compat bundles.
- The browserify bundles are now cached and built incrementally, speeding up development after the first build.
Other Updates
- Armor and packet parsing are now stricter: previously, missing —–END PGP PUBLIC KEY BLOCK—– or truncated packets wouldn’t throw errors, but do now.
- SHA1 and SHA256 hashing now use asmcrypto(new window), making them faster.
- Encryption and decryption of text now properly supports Unicode surrogate code points in JavaScript strings.
Future Roadmap
- Improve the performance of public-key operations by using asm.js big numbers.
- Re-implement ECC cryptography using asm.js to improve performance and make the primitives constant-time(new window).
- Continue to find ways to make openpgp.js smaller, for example by converting asm.js to WebAssembly
