opgp-proxy

abstracting proxy for an openpgp instance, isolated in a web worker, with the following features:

• robust, minimalistic yet flexible API based on keys.
• key instances are immutable and ephemeral.
• hermetic container for cryptographic material. sensitive key content remains contained and never leaves the worker thread.

In addition to its minimalistic yet flexible API, the proxy ensures that key material is well contained and does not leak throughout client code. Key ephemerality and immutability further enhance the robustness of the API.

API v1.0.0 experimental

Typescript compatible.

Note that in its current implementation, only a subset of the openpgp functionality is exposed by the opgp-proxy.

The foundation of the API are the OpgpKey cryptographic keys. These keys can be bundled into OpgpKeyring instances which expose the bundled keys as an Immutable.Map.

Both OpgpKeyring and OpgpKey instances expose the main cryptographic methods to process string text:

• encode
• decode
• sign (authenticate)
• verify (authenticity)

example

import Promise = require('bluebird')
import getOpgpProxy from '../src'

const proxy = getOpgpProxy() // spawn OpgpProxy with default config

const secret = 'very secret information'
const passphrase = 'cryptographically very strong secret passphrase'

// locked signing and decoding keys
const armor = '-----BEGIN PGP PUBLIC KEY BLOCK... END PGP PUBLIC KEY BLOCK-----'
const keys = proxy
.then(proxy => proxy.getKeysFromArmor(armor))

// assume for demo's sake that all keys are locked with the same passphrase
const passphrases = keys
.then(keys => keys.asMap
  .filter(key => isLocked(key))
  .map(key => passphrase))

// first unlock private keys
const unlocked = keys
.then(keys => keys.unlock(passphrases)

// now encode and sign, then verify signature and decode
const cipher = unlocked
.then(keys => keys.encode(secret)) // result: armored string

Promise.join(unlocked, cipher)
.spread((keys, cipher) => keys.decode(armor)) // result: very secret information

function isLocked (val: any): boolean {
  return !!val && (typeof val.isLocked === 'boolean') && val.isLocked
}

module opgp-proxy

description

exports a default OpgpProxyFactory.

example

import getOpgpProxy from 'opgp-proxy'

static factory getOpgpProxy

description

Spawn and initialize an openpgp worker, and return an immutable OpgpProxy.

This factory's optional config argument allows to configure the openpgp worker instance and the new OpgpProxy instance.

syntax

export interface OpgpProxyFactory {
  (config?: OpgpProxyConfig): Promise<OpgpProxy>
}

export interface OpgpProxyConfig {
  // TODO
}

errors

flow	type	message	data	reason
sync	Error	initialization failure	N/A	fail to initialize openpgp worker

example

const proxyConfig = {
  // TODO
}
const proxy = getOpgpProxy(proxyConfig)

proxy.then(proxy => /* do something with proxy */})

interface OpgpProxy

description

Abstracts the openpgp worker functionality into OpgpKeyring bundles of OpgpKey instances.

Both OpgpKeyring and OpgpKey instances are immutable. OpgpKey instances are additionally ephemeral.

• getKeysFromArmor
• getKeysFromList
• terminate
• OpgpKeyring
• OpgpKey

syntax

export interface OpgpProxy {
  getKeysFromArmor (armor: string, opts?: OpgpKeyringOpts): Promise<OpgpKeyring>

  getKeysFromList (list: Array<OpgpKey>|Iterable<any,OpgpKey>,
  opts?: OpgpKeyringOpts): OpgpKeyring

  terminate (): void
}

factory method getKeysFromArmor

description

import OpgpKey instances from an armored openpgp string as a new or an existing OpgpKeyring instance.

syntax

interface OpgpProxy {
  // ...
  getKeysFromArmor (armor: string, opts?: OpgpKeyringOpts): Promise<OpgpKeyring>
}

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	parse error	N/A	fail to parse input string

example

const armor = '-----BEGIN PGP PUBLIC KEY BLOCK... END PGP PUBLIC KEY BLOCK-----'
const keys = proxy.getKeysFromArmor(armor)
keys.then(keys => /* do something with keys */)

factory method getKeysFromList

description

import a list of OpgpKey instances as a new or an existing OpgpKeyring instance.

syntax

interface OpgpProxy {
  // ...
  getKeysFromList (list: Array<OpgpKey>|Iterable<any,OpgpKey>,
  opts?: OpgpKeyringOpts): OpgpKeyring
}

errors

flow	type	message	data	reason
sync	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type

method terminate

description

terminate the openpgp worker of this OpgpProxy.

However, as long as this OpgpProxy instance persists, any call to one of its methods, except the OpgpProxy#terminate method, or to a method of one of the OpgpKeyring or OpgpKey instances it has spawned will restart a new openpgp worker.

Note that when a new openpgp worker is spawned, all OpgpKey instances from previously terminated openpgp workers are stale.

syntax

interface OpgpProxy {
  // ...
  terminate (): void
}

errors

none

interface OpgpKeyring

description

Essentially wraps an Immutable.Map of primary-key fingerprint string to OpgpKey instance and additionally exposes the following methods:

• encode
• decode
• sign
• verify
• lock
• unlock

The corresponding Immutable.Map is exposed as a OpgpProxy.asMap property.

syntax

interface OpgpKeyring extends Map<string,OpgpKey> {
  encode (src: string, opts?: EncodeOpts): Promise<string>
  decode (src: string, opts?: DecodeOpts): Promise<string>
  sign (src: string, opts?: SignOpts): Promise<string>
  verify (src: string, opts?: VerifyOpts): Promise<string>
  lock (passphrases: Iterable<string,string>, opts?: LockOpts): Promise<OpgpKeyring>
  unlock (passphrases: Iterable<string,string>, opts?: LockOpts): Promise<OpgpKeyring>
  asMap: Immutable.Map<string, OpgpKey>
}

method OpgpKeyring#encode

description

Encrypt-then-MAC Authenticated Encryption, or optionally standard openpgp MAC-then-Encrypt AE.

By default, first encode the given src text with all public encryption OpgpKey instances in this OpgpKeyring instance.

If any unlocked private signing OpgpKey instances are bundled in this OpgpKeyring instance, then the encoded text is additionally authenticated with these keys. Typically, only one signing key is necessary.

It is possible to optionally restrict encoding and/or signing to a subset of the encoding and/or signing OpgpKey instances respectively by providing corresponding lists of OpgpKey.hash reference strings in opts.keys.

At least one public encoding key and one private signing key must be included. If strict mode is disabled, it is possible to encrypt without authenticating, although this is usually not recommended.

syntax

encode (src: string, opts?: EncodeOpts): Promise<string>

interface EncodeOpts {
  keys?: {
    /**
     * list of OpgpKey.hash reference strings
     * of public encoding OpgpKey instances in this OpgpKeyring
     * to use for encoding.
     * default: all public encoding OpgpKey instances in this OpgpKeyring.
     */
    encode?: string[]
    /**
     * list of OpgpKey.hash reference strings
     * of private signing OpgpKey instances in this OpgpKeyring
     * to use for signing.
     * default: all private signing OpgpKey instances in this OpgpKeyring.
     */
    sign?: string[]
  }
  /**
   * Encrypt-then-MAC when true.
   * Otherwise force openpgp Mac-then-Encrypt.
   * default: true
   */
  etm?: boolean
  /**
   * require authentication when true:
   * in particular, fail if no private signing keys are included.
   * Otherwise limit authentication to the included public signing keys, if any.
   * default: true
   */
  strict?: boolean
}

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid reference	N/A	one or more OpgpKey.hash reference strings in opts.keys.encode or opts.keys.sign do not match any key in this OpgpKeyring
async	Error	encode error	N/A	this OpgpKeyring does not contain any public encoding OpgpKey instances
async	Error	sign error	N/A	opts.strict is true and this OpgpKeyring does not contain any unlocked private signing OpgpKey instances
async	OpgpError	invalid key: ${data}	Array<string> OpgpKey.hash strings of invalid OpgpKey instances	one or more required OpgpKey instances in this OpgpKeyring are either locked, stale or unknown

method OpgpKeyring#decode

description

For EtM-AE strings, first verify the authenticity of the src string with all required public verification OpgpKey instances. Fail if any required public verification OpgpKey instances are missing from this OpgpKeyring or excluded from the list of OpgpKey.hash reference strings in opts.keys.verify.

If strict mode is disabled, it is possible to limit verification to all public verification OpgpKey instances bundled in this OpgpKeyring instance if any, or to a subset defined by a list of OpgpKey.hash reference strings in opts.keys.verify.

If and only if authenticity is successfully verified, decode the given src string with the unlocked private encryption OpgpKey instance in this OpgpKeyring instance, or with that referenced by a OpgpKey.hash reference string defined in opts.keys.verify.

For MtE-AE strings, first decode, then verify authenticity of the decoded string.

syntax

decode (src: string, opts?: DecodeOpts): Promise<string>

interface DecodeOpts {
  keys?: {
    /**
     * OpgpKey.hash reference string of the private decoding OpgpKey instance
     * in this OpgpKeyring to use for decoding.
     * default: the single private decoding OpgpKey instance in this OpgpKeyring
     */
    decode?: string
    /**
     * list of OpgpKey.hash reference strings
     * of public verification OpgpKey instances in this OpgpKeyring
     * to use for verifying authenticity.
     * default: all public verification OpgpKey instances in this OpgpKeyring
     */
    verify?: string[]
  }
  /**
   * require full verification of all signatures when true:
   * in particular, fail if any keys required for full verification are missing.
   * Otherwise limit verification to the public verification keys
   * in this `OpgpKeyring`.
   * default: true
   */
  strict?: boolean
}

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid reference	N/A	one or more OpgpKey.hash reference strings in opts.keys.decode or opts.keys.verify do not match any key in this OpgpKeyring
async	Error	unknkown cipher	N/A	cipher not supported, or no cipher, or unknown cipher format
async	OpgpError	invalid key: ${data}	Array<string> OpgpKey.hash strings of invalid OpgpKey instances	one or more required OpgpKey instances in this OpgpKeyring are either locked, stale or unknown
async	OpgpError	decode error: ${data}	Array<string> openpgp id strings of all required private decryption keys	none of the required private decryption keys were found or were unlocked in this OpgpKeyring or in opts.keys.decode
async	OpgpError	verify error: ${data}	Array<string> openpgp id strings of all keys for which authentication fails	authenticity verification fails with one or more OpgpKey instances in this OpgpKeyring, or opts.strict is true and one or more required keys were not found

method OpgpKeyring#sign

description

Authenticate the src text with the unlocked private signing OpgpKey instances bundled in this OpgpKeyring instance. Typically, only one signing key is necessary.

It is possible to optionally restrict signing to a subset of the private signing OpgpKey instances by providing a corresponding list of OpgpKey.hash reference strings in opts.keys.sign.

At least one public encoding key and one unlocked private signing key must be included.

syntax

sign (src: string, opts?: SignOpts): Promise<string>

interface SignOpts {
  keys?: {
    /**
     * list of OpgpKey.hash reference strings
     * of private signing OpgpKey instances in this OpgpKeyring
     * to use for signing.
     * default: all private signing OpgpKey instances in this OpgpKeyring.
     */
    sign?: string[]
  }
}

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid reference	N/A	one or more OpgpKey.hash reference strings in opts.keys.sign do not match any key in this OpgpKeyring
async	Error	sign error	N/A	this OpgpKeyring does not contain any unlocked private signing OpgpKey instances
async	OpgpError	invalid key: ${data}	Array<string> OpgpKey.hash strings of invalid OpgpKey instances	one or more required OpgpKey instances in this OpgpKeyring are either locked, stale or unknown

method OpgpKeyring#verify

description

Verify the authenticity of the src string with all required public verification OpgpKey instances. Fail if any required public verification OpgpKey instances are missing from this OpgpKeyring or excluded from opts.keys.verify.

If strict mode is disabled, it is possible to limit verification to all public verification OpgpKey instances bundled in this OpgpKeyring instance if any, or to a subset defined by a list of OpgpKey.hash strings.

Returns the src string upon successful validation of authenticity.

syntax

verify (src: string, opts?: VerifyOpts): Promise<string>

interface VerifyOpts {
  keys?: {
    /**
     * list of OpgpKey.hash reference strings
     * of public verification OpgpKey instances in this OpgpKeyring
     * to use for verifying authenticity.
     * default: all public verification OpgpKey instances in this OpgpKeyring
     */
    verify?: string[]
  }
  /**
   * require full verification of all signatures when true:
   * in particular, fail if any keys required for full verification are missing.
   * Otherwise limit verification to the public verification keys
   * in this `OpgpKeyring`.
   * default: true
   */
  strict?: boolean
}

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid reference	N/A	one or more OpgpKey.hash reference strings in opts.keys.decode or opts.keys.verify do not match any key in this OpgpKeyring
async	OpgpError	invalid key: ${data}	Array<string> OpgpKey.hash strings of invalid OpgpKey instances	one or more OpgpKey instances in this OpgpKeyring are either locked, stale or unknown
async	OpgpError	verify error: ${data}	Array<string> openpgp id strings of all keys for which authentication fails	authenticity verification fails with one or more OpgpKey instances in this OpgpKeyring, or opts.strict is true and one or more required keys were not found, or the string is not authenticated with a supported format

method OpgpKeyring#lock

description

Lock all SecKey instances referenced by their Eposable#hash string in this OpgpKeyring by encoding them with corresponding secret passphrases, or with a common secret passphrase.

• the secret passphrases may be either supplied as an Iterable of Eposable#hash string to secret passphrase string,
• or, a single secret passphrase string may supplied instead of an Iterable in which case all SecKey instances in this OpgpKeyring will be locked with that passphrase.

Since this method mutates the state of the underlying openpgp keys in a security-critical way, it returns a new immutable OpgpKeyring instance with new immutable locked SecKey instances of the same type.

This method by default immediately invalidates all SecKey instances it locks, which then become permanently stale. This behavior can be disabled by setting the opts.invalidate option to false.

syntax

interface Lockable {
  // ...
	lock (secrets: string|Iterable<string,string>, opts?: LockOpts): Promise<this>
}

param secrets: string|Iterable<string,string>

should be a or a map of cryptographically secure random string with which to encode the corresponding SecKey instances.

param opts?: LockOpts

interface LockOpts {
  invalidate: boolean // = true
}

• invalidate: boolean true by default, false disables automatic invalidation of this SecKey instance.

return Promise<string>

new immutable OpgpKeyring instance with new immutable locked SecKey instances of the same type, each encoded with the corresponding secret passphrase.

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid reference	N/A	one or more OpgpKey.hash reference strings in secrets do not match any key in this OpgpKeyring
async	OpgpError	invalid key: ${data}	Array<string> OpgpKey.hash strings of invalid OpgpKey instances	one or more OpgpKey instances in this OpgpKeyring are either stale or unknown
async	Error	lock error	N/A	one or more referenced SecKey intances are already locked, i.e. this.isLocked === true, and must first be unlocked

method OpgpKeyring#unlock

description

Unlock all SecKey instances referenced by their Eposable#hash string in this OpgpKeyring by decoding them with corresponding secret passphrases, or with a common secret passphrase.

• the secret passphrases may be either supplied as an Iterable of Eposable#hash string to secret passphrase string,
• or, a single secret passphrase string may supplied instead of an Iterable in which case all SecKey instances in this OpgpKeyring will be unlocked with that passphrase.

Since this method mutates the state of the underlying openpgp keys in a security-critical way, it returns a new immutable OpgpKeyring instance with new immutable locked SecKey instances of the same type.

When referenced SecKey instances are unlocked, they remain unlocked for a given length of time, as defined by the opts.autolock option, after which the instances automatically become stale. The opts.autolock option defaults to the default value of the OpgpProxy.

syntax

interface Lockable {
  // ...
	unlock (secrets: string|Iterable<string,string>, opts?: UnlockOpts):
  Promise<this>
}

param secret: string|Iterable<string,string>

the secret passphrase or map of secret passphrases with which to decode referenced SecKey instances.

param opts?: UnlockOpts

interface UnlockOpts {
  autolock: number // = OpgpProxy.config.autolock
}

• autolock: number same default value as that of the OpgpProxy, delay after which this SecKey instance is invalidated, i.e. becomes stale, after unlocking.

return Promise<string>

new immutable SecKey instance of the same type as this SecKey instance decoded with the secret passphrase.

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid reference	N/A	one or more OpgpKey.hash reference strings in secrets do not match any key in this OpgpKeyring
async	OpgpError	invalid key: ${data}	Array<string> OpgpKey.hash strings of invalid OpgpKey instances	one or more OpgpKey instances in this OpgpKeyring are either stale or unknown
async	Error	unlock error	N/A	one or more referenced SecKey intances are already unlocked, i.e. this.isLocked === false, or were not encoded with the given secret passphrase

type alias OpgpKey

description

The OpgpKey type alias represents immutable and ephemeral instances that abstract key material from the openpgp worker.

• the sensitive cryptographic key material remains well contained in the openpgp worker, and is not included in the internals of, or exposed by OpgpKey instances.
• OpgpKey instances are immutable
• OpgpKey instances are ephemeral: they become stale if none of their methods are called for a defined length of time, or if the openpgp worker is terminated.

A stale OpgpKey is permanently detached from the key material it represented in the openpgp worker, allowing for the corresponding worker-side key instance to eventually be garbage collected. A new OpgpKey instance may readily be created from a stale instance, e.g. from the latter's OpgpKey.armor string, however, in case of private keys, the new instance will always be locked by default, regardless of whether the stale instance had been unlocked or not.

The OpgpKey type alias is a type union of the following type aliases:

• PubKey type alias that represents public keys
• SecKey type alias that represents private keys
• RootKey type alias that represents primary keys, a special type of SecKey

In other words, the OpgpKey type alias represents either a public, private, or primary key.

All OpgpKey instances extend the [Exposable] interface, which exposes public information about the key.

syntax

type OpgpKey = RootKey | SecKey | PubKey

interface Exposable

description

Instances of the Exposable interface expose public information about these. All OpgpKey instances are Exposable.

syntax

interface Exposable extends Identifiable {
  toString (): string
  hash: string
  id: string
  fingerprint: string
  armor: string
  expiry: number
}

type alias PubKey

description

The PubKey type alias represents public key instances.

More specifically, the PubKey type alias is a type union of the following interfaces:

• PubAuthKey interface that represents public authentication keys for verifying signatures
• PubCodeKey interface that represents public coding keys for encoding a text
• PubUniKey interface that represents public universal keys for both verifying signatures and encoding text

syntax

type PubKey = PubAuthKey | PubCodeKey | PubUniKey

type alias PubAuthKey

description

The PubAuthKey interface represents public authentication keys for verifying signatures, with the Verifiable#verify method from the Verifiable interface.

Like all other OpgpKey types, PubAuthKey instances also expose public information about the key through the [Exposable] interface.

syntax

interface PubAuthKey extends Exposable, Verifiable {}

type alias PubCodeKey

description

The PubCodeKey interface represents public coding keys for encoding a text, with the Encodable#encode method from the Encodable interface.

Like all other OpgpKey types, PubCodeKey instances also expose public information about the key through the [Exposable] interface.

syntax

interface PubCodeKey extends Exposable, Encodable {}

type alias PubUniKey

description

The PubUniKey interface represents public universal keys for both verifying signatures and encoding a text,

• with the Verifiable#verify method from the Verifiable interface, and
• with the Encodable#verify method from the Encodable interface.

Like all other OpgpKey types, PubUniKey instances also expose public information about the key through the [Exposable] interface.

syntax

interface PubUniKey extends Exposable, Encodable, Verifiable {}

type alias SecKey

description

The SecKey type alias represents secret key instances.

More specifically, the SecKey type alias is a type union of the following interfaces:

• SecAuthKey interface that represents private authentication keys for signing a text
• SecCodeKey interface that represents private coding keys for decoding a text
• SecUniKey interface that represents private universal keys for both signing and decoding a text

All SecKey instances expose

• Lockable#lock and Lockable#unlock methods, and an Lockable#isLocked property through the Lockable interface to respectively lock and unlock the key with a secret passphrase, and to obtain the status of the key,
• a publicKey property with their PubKey public key component.

Like all other OpgpKey types, SecAuthKey instances also expose public information about the key through the [Exposable] interface.

A specialized SecKey type is the RootKey type, which represents primary keys, that bundle SecKey subkeys and user id strings.

type alias SecAuthKey

description

The SecAuthKey interface represents private authentication keys for signing a text, with the Signable#sign method from the Signable interface.

Like all other SecKey intances, SecAuthKey instances expose

• Lockable#lock and Lockable#unlock methods and an Lockable#isLocked property through the Lockable interface to respectively lock and unlock the key with a secret passphrase, and to obtain the status of the key,
• a publicKey property with their PubAuthKey public key component.

Like all other OpgpKey types, SecAuthKey instances also expose public information about the key through the [Exposable] interface.

syntax

interface SecAuthKey extends Lockable, Signable {
	publicKey: PubAuthKey
}

type alias SecCodeKey

description

The SecCodeKey interface represents private coding keys for decoding a text, with the Decodable#decode method from the Decodable interface.

Like all other SecKey intances, SecCodeKey instances expose

• Lockable#lock and Lockable#unlock methods and an Lockable#isLocked property through the Lockable interface to respectively lock and unlock the key with a secret passphrase, and to obtain the status of the key,
• a publicKey property with their PubCodeKey public key component.

Like all other OpgpKey types, SecCodeKey instances also expose public information about the key through the [Exposable] interface.

syntax

interface SecCodeKey extends Lockable, Decodable {
	publicKey: PubCodeKey
}

type alias SecCodeKey

description

The SecUniKey interface represents private universal keys for both signing and decoding a text,

• with the Signable#sign method from the Signable interface, and
• with the Decodable#decode method from the Decodable interface.

Like all other SecKey intances, SecUniKey instances expose

• Lockable#lock and Lockable#unlock methods and an Lockable#isLocked property through the Lockable interface to respectively lock and unlock the key with a secret passphrase, and to obtain the status of the key,
• a publicKey property with their PubUniKey public key component.

Like all other OpgpKey types, SecUniKey instances also expose public information about the key through the [Exposable] interface.

syntax

interface SecUniKey extends Lockable, Decodable, Signable {
	publicKey: PubUniKey
}

interface Lockable

description

Instances of the Lockable interface may be locked and unlocked with a secret passphrase.

This interface exposes Lockable#lock and Lockable#unlock methods.

More specifically, locking a Lockable instance is simply encrypting it with a secret passphrase, while unlocking a locked Lockable instance is decrypting it with the passphrase that was used to lock it.

All SecKey instances are Lockable instances.

Since they mutate the state of the underlying openpgp key in a security-critical way, the Lockable#lock and Lockable#unlock methods return a new immutable SecKey instance of the same type.

The Lockable#lock method by default immediately invalidates its Lockable instance, which then becomes permanently stale. This behavior can be disabled by setting the opts.invalidate option of the Lockable#lock method to false.

When a Lockable instance is unlocked, it stays unlocked for a given length of time, as defined by the opts.autolock option of the Lockable#unlock method, after which the instance automatically becomes stale. The opts.autolock option defaults to the default value of the OpgpProxy.

Finally, the immutable state of a Lockable instance is exposed by its isLocked property.

syntax

interface Lockable extends Exposable {
	lock (secret: string, opts?: LockOpts): Promise<this>
	unlock (secret: string, opts?: UnlockOpts): Promise<this>
  isLocked: boolean
}

interface LockOpts {
  invalidate: boolean // = true
}

interface UnlockOpts {
  autolock: number // = OpgpProxy.config.autolock
}

type alias RootKey

description

The type alias represents primary key instances.

All RootKey instances are specialized SecKey instances.

More specifically, the RootKey type alias is a type union of the following interfaces:

• RootAuthKey interface that represents primary authentication keys and exposes the SecAuthKey interface
• RootCodeKey interface that represents primary coding keys and exposes the SecCodeKey interface
• RootUniKey interface that represents primary universal keys and exposes the SecUniKey interface

Additionally, all RootKey instances expose the Belongings interface, with

• an Immutable.List of SecKey subkey instances,
• an Immutable.List of user id strings.

syntax

type RootKey = RootAuthKey | RootCodeKey | RootUniKey

interface Belongings

description

The Belongings interface exposes two immutable properties:

• an Immutable.List of SecKey subkey instances,
• an Immutable.List of user id strings.

All RootKey instances expose the above Belongings properties.

syntax

interface Belongings {
  keys: FList<SecKey>
  userids: FList<string>
}

interface RootAuthKey

description

The RootAuthKey interface represents a primary key that is itself a secret authentication key for signing texts.

More specifically, the RootAuthKey interface exposes both

• the SecAuthKey interface
• the Belongings interface, with an Immutable.List of SecKey subkey instances, and an Immutable.List of user id strings.

syntax

interface RootAuthKey extends SecAuthKey, Belongings {}

interface RootCodeKey

description

The RootCodeKey interface represents a primary key that is itself a secret authentication key for signing texts.

More specifically, the RootCodeKey interface exposes both

• the SecCodeKey interface
• the Belongings interface, with an Immutable.List of SecKey subkey instances, and an Immutable.List of user id strings.

syntax

interface RootCodeKey extends SecCodeKey, Belongings {}

interface RootUniKey

description

The RootUniKey interface represents a primary key that is itself a secret authentication key for signing texts.

More specifically, the RootUniKey interface exposes both

• the SecUniKey interface
• the Belongings interface, with an Immutable.List of SecKey subkey instances, and an Immutable.List of user id strings.

syntax

interface RootUniKey extends SecUniKey, Belongings {}

interface Verifiable

description

The Verifiable interface exposes a single verify method for verifying the signature of an armored authenticated src string with this instance of PubAuthKey or PubUniKey.

syntax

export interface Verifiable {
	verify (src: string, opts?: VerifyOpts): Promise<string>
}

export interface VerifyOpts {} // ignored in current implementation

interface Encodable

description

The Encodable interface exposes a single encode method for encoding a src string with this instance of PubCodeKey or PubUniKey.

syntax

interface Encodable {
	encode (src: string, opts?: EncodeOpts): Promise<string>
}

interface EncodeOpts {} // ignored in current implementation

interface Signable

description

The Signable interface exposes a single sign method for signing the src string with this instance of SecAuthKey or SecUniKey.

syntax

interface Signable {
	sign (src: string, opts?: SignOpts): Promise<string>
}

interface SignOpts {} // ignored in current implementation

interface Decodable

description

The Decodable interface exposes a single decode method for decoding an armored encoded src string with this instance of SecCodeKey or SecUniKey.

syntax

interface Decodable {
	decode (src: string, opts?: DecodeOpts): Promise<string>
}

export interface DecodeOpts {} // ignored in current implementation

method Lockable#lock

description

Lock this instance of SecKey by encoding it with a secret passphrase.

Since this method mutates the state of the underlying openpgp key in a security-critical way, it returns a new immutable SecKey instance of the same type.

This method by default immediately invalidates its SecKey instance, which then becomes permanently stale. This behavior can be disabled by setting the opts.invalidate option to false.

syntax

interface Lockable {
  // ...
	lock (secret: string, opts?: LockOpts): Promise<this>
}

param secret: string

should be a cryptographically secure random string with which to encode this instance of SecKey.

param opts?: LockOpts

interface LockOpts {
  invalidate: boolean // = true
}

• invalidate: boolean true by default, false disables automatic invalidation of this SecKey instance.

return Promise<string>

new immutable SecKey instance of the same type as this SecKey instance encoded with the secret passphrase.

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid key	N/A	this SecKey is either stale or unknown
async	Error	lock error	N/A	this SecKey is already locked, i.e. this.isLocked === true, and must first be unlocked

method Lockable#unlock

description

Unlock this instance of SecKey by decoding it with the secret passphrase with which it was encoded.

Since this method mutates the state of the underlying openpgp key in a security-critical way, it returns a new immutable SecKey instance of the same type.

When a SecKey instance is unlocked, it stays unlocked for a given length of time, as defined by the opts.autolock option, after which the instance automatically becomes stale. The opts.autolock option defaults to the default value of the OpgpProxy.

syntax

interface Lockable {
  // ...
	unlock (secret: string, opts?: UnlockOpts): Promise<this>
}

param secret: string

the secret string with which this instance of SecKey was encoded

param opts?: UnlockOpts

interface UnlockOpts {
  autolock: number // = OpgpProxy.config.autolock
}

• autolock: number same default value as that of the OpgpProxy, delay after which this SecKey instance is invalidated, i.e. becomes stale, after unlocking.

return Promise<string>

new immutable SecKey instance of the same type as this SecKey instance decoded with the secret passphrase.

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid key	N/A	this SecKey is either stale or unknown
async	Error	unlock error	N/A	this SecKey is already unlocked or was not encoded with the given secret passphrase

method Verifiable#verify

description

Verify the signature of an armored authenticated src string with this instance of PubAuthKey or PubUniKey.

syntax

interface Verifiable {
  verify (src: string, opts?: VerifyOpts): Promise<string>
}

param src: string

armored authenticated string

param opts?: VerifyOpts

ignored in current implementation

return Promise<string>

unsigned text extracted from src

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid key	N/A	this PubAuthKey or PubUniKey is either stale or unknown
async	Error	verify error	N/A	the src string was not signed with this OpgpKey, or the string is not authenticated with a supported format

method Encodable#encode

description

Encode a src string with this instance of PubCodehKey or PubUniKey.

syntax

interface Encodable {
  encode (src: string, opts?: EncodeOpts): Promise<string>
}

param src: string

the string to encode

param opts?: EncodeOpts

ignored in current implementation

return Promise<string>

result of encoding the src string with this instance

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid key	N/A	this PubCodeKey or PubUniKey is either stale or unknown

method Signable#sign

description

sign a src string with this instance of SecAuthKey or SecUniKey.

syntax

interface Signable {
	sign (src: string, opts?: SignOpts): Promise<string>
}

param src: string

the string to sign

param opts?: SignOpts

ignored in current implementation

return Promise<string>

signed armored src string

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid key	N/A	this SecAuthKey or SecbUniKey is either locked, stale or unknown

method Decodable#decode

description

Decode an armored src string with this instance of SecCodehKey or SecUniKey.

syntax

interface Decodable {
	decode (src: string, opts?: DecodeOpts): Promise<string>
}

param src: string

the armored encoded string to decode

param opts?: DecodeOpts

ignored in current implementation

return Promise<string>

result of decoding the src string with this instance

errors

flow	type	message	data	reason
async	Error	invalid argument	N/A	one or more argument invariants fail, e.g. wrong argument type
async	Error	invalid key	N/A	this PubAuthKey or PubUniKey is either locked, stale or unknown
async	Error	unknkown cipher	N/A	cipher not supported, or no cipher, or unknown cipher format

LICENSE

Copyright 2016 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.