opgp-service

a fully async API for openpgp that builds on ephemeral immutable keys and that does not leak cryptographic material.

together with worker-proxy, this service can easily be run in a WebWorker, confining the cryptographic material into a dedicated thread.

ES5. Typescript support. 36kB gzip, excluding openpgp.

based on openpgp@^3.1.2, audited by Cure53 in summer 2018.

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 opgp-service instance 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 or Promise instances that eventually resolve,
• all API methods return a Promise,
• any exception thrown by openpgp is converted into a rejected Promise.

EXAMPLE

import getService from 'opgp-service'
import getResolve from 'resolve-call'
const resolve = getResolve()
import fs = require('fs')
import debug = require('debug')
const log = resolve(debug('example:'))
 
const toKeyRing = resolve((key: OpgpProxyKey) => ({ cipher: key, auth: key }))
 
const service = getService() // use defaults
 
const armor = fs.readFileSync(`${__dirname}/<[e-mail]>.private.key`, 'utf8')
const passphrase = 'passphrase to decrypt private key'
const secret = 'rob says wow!'
 
log('import key...')
const key = service.getKeysFromArmor(armor)
const keys = toKeyRing(service.unlock(key, passphrase))
 
// encrypt with public key, sign with private
const cipher = service.encrypt(keys, secret)
log(cipher) // '-----BEGIN PGP MESSAGE----- ... -----END PGP MESSAGE-----'
 
// decrypt with private key, verify signature with public
const plain = service.decrypt(keys, cipher)
log(plain) // '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 example folder.

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 install
npm run example

API 2.4 stable

the current version exposes the following service methods:

• configure
• isValidKeyHandle, generateKey, getPublicKey, getKeysFromArmor, getArmorFromKey
• unlock, lock
• encrypt, decrypt
• sign, verify

for a detailed specification of the API

• run the unit tests in your browser,
• or check the public interface declaration in the source code.

CONTRIBUTING

see the contribution guidelines

LICENSE

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

http://www.apache.org/licenses/LICENSE-2.0

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.