opgp-service
    TypeScript icon, indicating that this package has built-in type declarations

    2.4.1 • Public • Published

    opgp-service Join the chat at https://gitter.im/ZenyWay/opgp-service

    NPM build status coverage status Dependency Status

    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}/<john.doe@example.com>.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

    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.

    Install

    npm i opgp-service

    DownloadsWeekly Downloads

    1

    Version

    2.4.1

    License

    SEE LICENSE IN LICENSE

    Unpacked Size

    52 kB

    Total Files

    15

    Last publish

    Collaborators

    • smcatala