a fully async API for openpgp that builds on ephemeral immutable keys and that does not leak cryptographic material.
ES5. Typescript support. 36kB gzip, excluding openpgp.
cryptographic material is encapsulated
client code operates on mere proxies of the openpgp keys, not the latter.
each key proxy includes a handle (reference) to the corresponding openpgp key.
the handle is a unique cryptographically secure random string,
completely independent from the referenced cryptographic material,
which remains well contained within the
and does not leak into client code.
keys are ephemeral
the service invalidates proxy handles if not used during a defined time lapse. after a key proxy is invalidated, client code can still fetch a new instance from the service, whenever required.
keys are immutable
the service also invalidates a proxy handle when an openpgp operation mutates a key's state.
in the current API, only the
lock method, which encrypts a private key,
mutates the key.
when a key is locked, all proxies to the unlocked state become stale.
key proxies always represent a key in an immutable state. this hinders coupling in client code through the service API.
fully async: reads like sync
async all the way makes it easy to write code that reads like synchronous code, and streamlines error-control flow.
- all API method arguments may be either immediately available
Promiseinstances that eventually resolve,
- all API methods return a
- any exception thrown by
openpgpis converted into a rejected
const resolve =const log =const toKeyRing =const service = // use defaultsconst armor = fsconst passphrase = 'passphrase to decrypt private key'const secret = 'rob says wow!'const key = serviceconst keys =// encrypt with public key, sign with privateconst cipher = service// '-----BEGIN PGP MESSAGE----- ... -----END PGP MESSAGE-----'// decrypt with private key, verify signature with publicconst plain = service// 'rob says wow!'
note that although the above code reads like synchronous code, it is in fact fully async.
the files of this example are available in the
a live version of this example can be viewed in the browser console, or by cloning this repository and running the following commands from a terminal:
npm installnpm run example
the current version exposes the following service methods:
- isValidKeyHandle, generateKey, getPublicKey, getKeysFromArmor, getArmorFromKey
- unlock, lock
- encrypt, decrypt
- sign, verify
for a detailed specification of the API
see the contribution guidelines
Copyright 2018 Stéphane M. Catala
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and Limitations under the License.