Module: openpgp

The openpgp base module should provide all of the functionality to consume the openpgp.js library. All additional classes are documented for extending and developing on top of the base library.

Source:

Requires

Members

(static) armor

Source:
See:

(static) AsyncProxy

Source:
See:

(static) cleartext

Source:
See:

(static) config

Source:
See:
  • module:config/config

(static) crypto

Source:
See:

(static) ECDHSymmetricKey

Source:
See:

(static) enums

Source:
See:

(static) HKP

Source:
See:

(static) KDFParams

Source:
See:

(static) key

Source:
See:

(static) Keyid

Source:
See:

(static) Keyring

Source:
See:

(static) message

Source:
See:

(static) MPI

Source:
See:

(static) OID

Source:
See:

(static) packet

Source:
See:

(static) S2K

Source:
See:

(static) signature

Source:
See:

(static) stream

Source:
See:
  • streams

(static) util

Source:
See:

(static) WKD

Source:
See:

Methods

(async, static) decrypt(message, privateKeys, passwords, sessionKeys, publicKeys, format, streaming, signature, date) → {Promise.<Object>}

Decrypts a message with the user's private key, a session key or a password. Either a private key, a session key or a password must be specified.

Parameters:
Name Type Description
message Message

the message object with the encrypted data

privateKeys Key | Array.<Key>

(optional) private keys with decrypted secret key data or session key

passwords String | Array.<String>

(optional) passwords to decrypt the message

sessionKeys Object | Array.<Object>

(optional) session keys in the form: { data:Uint8Array, algorithm:String }

publicKeys Key | Array.<Key>

(optional) array of public keys or single key, to verify signatures

format String

(optional) return data format either as 'utf8' or 'binary'

streaming 'web' | 'node' | false

(optional) whether to return data as a stream. Defaults to the type of stream message was created from, if any.

signature Signature

(optional) detached signature for verification

date Date

(optional) use the given date for verification instead of the current time

Source:
Returns:

Object containing decrypted and verified message in the form:

{
  data: String|ReadableStream<String>|NodeStream, (if format was 'utf8', the default)
  data: Uint8Array|ReadableStream<Uint8Array>|NodeStream, (if format was 'binary')
  filename: String,
  signatures: [
    {
      keyid: module:type/keyid,
      verified: Promise<Boolean>,
      valid: Boolean (if streaming was false)
    }, ...
  ]
}
Type
Promise.<Object>

(async, static) decryptKey(privateKey, passphrase) → {Promise.<Object>}

Unlock a private key with your passphrase.

Parameters:
Name Type Description
privateKey Key

the private key that is to be decrypted

passphrase String | Array.<String>

the user's passphrase(s) chosen during key generation

Source:
Returns:

the unlocked key object in the form: { key:Key }

Type
Promise.<Object>

(async, static) decryptSessionKeys(message, privateKeys, passwords) → {Promise.<(Object|undefined)>}

Decrypt symmetric session keys with a private key or password. Either a private key or a password must be specified.

Parameters:
Name Type Description
message Message

a message object containing the encrypted session key packets

privateKeys Key | Array.<Key>

(optional) private keys with decrypted secret key data

passwords String | Array.<String>

(optional) passwords to decrypt the session key

Source:
Returns:

Array of decrypted session key, algorithm pairs in form: { data:Uint8Array, algorithm:String } or 'undefined' if no key packets found

Type
Promise.<(Object|undefined)>

(static) destroyWorker()

Cleanup the current instance of the web worker.

Source:

(async, static) encrypt(message, publicKeys, privateKeys, passwords, sessionKey, compression, armor, streaming, detached, signature, returnSessionKey, wildcard, date, fromUserId, toUserId) → {Promise.<Object>}

Encrypts message text/data with public keys, passwords or both at once. At least either public keys or passwords must be specified. If private keys are specified, those will be used to sign the message.

Parameters:
Name Type Description
message Message

message to be encrypted as created by openpgp.message.fromText or openpgp.message.fromBinary

publicKeys Key | Array.<Key>

(optional) array of keys or single key, used to encrypt the message

privateKeys Key | Array.<Key>

(optional) private keys for signing. If omitted message will not be signed

passwords String | Array.<String>

(optional) array of passwords or a single password to encrypt the message

sessionKey Object

(optional) session key in the form: { data:Uint8Array, algorithm:String }

compression module:enums.compression

(optional) which compression algorithm to compress the message with, defaults to what is specified in config

armor Boolean

(optional) if the return values should be ascii armored or the message/signature objects

streaming 'web' | 'node' | false

(optional) whether to return data as a stream. Defaults to the type of stream message was created from, if any.

detached Boolean

(optional) if the signature should be detached (if true, signature will be added to returned object)

signature Signature

(optional) a detached signature to add to the encrypted message

returnSessionKey Boolean

(optional) if the unencrypted session key should be added to returned object

wildcard Boolean

(optional) use a key ID of 0 instead of the public key IDs

date Date

(optional) override the creation date of the message signature

fromUserId Object

(optional) user ID to sign with, e.g. { name:'Steve Sender', email:'[email protected]' }

toUserId Object

(optional) user ID to encrypt for, e.g. { name:'Robert Receiver', email:'[email protected]' }

Source:
Returns:

Object containing encrypted (and optionally signed) message in the form:

{
  data: String|ReadableStream<String>|NodeStream, (if `armor` was true, the default)
  message: Message, (if `armor` was false)
  signature: String|ReadableStream<String>|NodeStream, (if `detached` was true and `armor` was true)
  signature: Signature (if `detached` was true and `armor` was false)
  sessionKey: { data, algorithm, aeadAlgorithm } (if `returnSessionKey` was true)
}
Type
Promise.<Object>

(async, static) encryptKey(privateKey, passphrase) → {Promise.<Object>}

Lock a private key with your passphrase.

Parameters:
Name Type Description
privateKey Key

the private key that is to be decrypted

passphrase String | Array.<String>

the user's passphrase(s) chosen during key generation

Source:
Returns:

the locked key object in the form: { key:Key }

Type
Promise.<Object>

(async, static) encryptSessionKey(data, algorithm, aeadAlgorithm, publicKeys, passwords, wildcard, date, toUserId) → {Promise.<Message>}

Encrypt a symmetric session key with public keys, passwords, or both at once. At least either public keys or passwords must be specified.

Parameters:
Name Type Description
data Uint8Array

the session key to be encrypted e.g. 16 random bytes (for aes128)

algorithm String

algorithm of the symmetric session key e.g. 'aes128' or 'aes256'

aeadAlgorithm String

(optional) aead algorithm, e.g. 'eax' or 'ocb'

publicKeys Key | Array.<Key>

(optional) array of public keys or single key, used to encrypt the key

passwords String | Array.<String>

(optional) passwords for the message

wildcard Boolean

(optional) use a key ID of 0 instead of the public key IDs

date Date

(optional) override the date

toUserId Object

(optional) user ID to encrypt for, e.g. { name:'Phil Zimmermann', email:'[email protected]' }

Source:
Returns:

the encrypted session key packets contained in a message object

Type
Promise.<Message>

(async, static) generateKey(userIds, passphrase, numBits, keyExpirationTime, curve, date, subkeys) → {Promise.<Object>}

Generates a new OpenPGP key pair. Supports RSA and ECC keys. Primary and subkey will be of same type.

Parameters:
Name Type Description
userIds Array.<Object>

array of user IDs e.g. [{ name:'Phil Zimmermann', email:'[email protected]' }]

passphrase String

(optional) The passphrase used to encrypt the resulting private key

numBits Number

(optional) number of bits for RSA keys: 2048 or 4096.

keyExpirationTime Number

(optional) The number of seconds after the key creation time that the key expires

curve String

(optional) elliptic curve for ECC keys: curve25519, p256, p384, p521, secp256k1, brainpoolP256r1, brainpoolP384r1, or brainpoolP512r1.

date Date

(optional) override the creation date of the key and the key signatures

subkeys Array.<Object>

(optional) options for each subkey, default to main key options. e.g. [{sign: true, passphrase: '123'}] sign parameter defaults to false, and indicates whether the subkey should sign rather than encrypt

Source:
Returns:

The generated key object in the form: { key:Key, privateKeyArmored:String, publicKeyArmored:String, revocationCertificate:String }

Type
Promise.<Object>

(static) getWorker() → {module:worker/async_proxy.AsyncProxy|null}

Returns a reference to the async proxy if the worker was initialized with openpgp.initWorker()

Source:
Returns:

the async proxy or null if not initialized

Type
module:worker/async_proxy.AsyncProxy | null

(static) initWorker(path, n, workers)

Set the path for the web worker script and create an instance of the async proxy

Parameters:
Name Type Description
path String

relative path to the worker scripts, default: 'openpgp.worker.js'

n Number

number of workers to initialize

workers Array.<Object>

alternative to path parameter: web workers initialized with 'openpgp.worker.js'

Source:

(async, static) reformatKey(privateKey, userIds, passphrase, keyExpirationTime, revocationCertificate) → {Promise.<Object>}

Reformats signature packets for a key and rewraps key object.

Parameters:
Name Type Description
privateKey Key

private key to reformat

userIds Array.<Object>

array of user IDs e.g. [{ name:'Phil Zimmermann', email:'[email protected]' }]

passphrase String

(optional) The passphrase used to encrypt the resulting private key

keyExpirationTime Number

(optional) The number of seconds after the key creation time that the key expires

revocationCertificate Boolean

(optional) Whether the returned object should include a revocation certificate to revoke the public key

Source:
Returns:

The generated key object in the form: { key:Key, privateKeyArmored:String, publicKeyArmored:String, revocationCertificate:String }

Type
Promise.<Object>

(static) revokeKey(key, revocationCertificate, reasonForRevocation) → {Promise.<Object>}

Revokes a key. Requires either a private key or a revocation certificate. If a revocation certificate is passed, the reasonForRevocation parameters will be ignored.

Parameters:
Name Type Description
key Key

(optional) public or private key to revoke

revocationCertificate String

(optional) revocation certificate to revoke the key with

reasonForRevocation Object

(optional) object indicating the reason for revocation

Properties
Name Type Description
flag module:enums.reasonForRevocation

(optional) flag indicating the reason for revocation

string String

(optional) string explaining the reason for revocation

Source:
Returns:

The revoked key object in the form: { privateKey:Key, privateKeyArmored:String, publicKey:Key, publicKeyArmored:String } (if private key is passed) or { publicKey:Key, publicKeyArmored:String } (otherwise)

Type
Promise.<Object>

(async, static) sign(message, privateKeys, armor, streaming, detached, date, fromUserId) → {Promise.<Object>}

Signs a cleartext message.

Parameters:
Name Type Description
message CleartextMessage | Message

(cleartext) message to be signed

privateKeys Key | Array.<Key>

array of keys or single key with decrypted secret key data to sign cleartext

armor Boolean

(optional) if the return value should be ascii armored or the message object

streaming 'web' | 'node' | false

(optional) whether to return data as a stream. Defaults to the type of stream message was created from, if any.

detached Boolean

(optional) if the return value should contain a detached signature

date Date

(optional) override the creation date of the signature

fromUserId Object

(optional) user ID to sign with, e.g. { name:'Steve Sender', email:'[email protected]' }

Source:
Returns:

Object containing signed message in the form:

{
  data: String|ReadableStream<String>|NodeStream, (if `armor` was true, the default)
  message: Message (if `armor` was false)
}

Or, if detached was true:

{
  signature: String|ReadableStream<String>|NodeStream, (if `armor` was true, the default)
  signature: Signature (if `armor` was false)
}
Type
Promise.<Object>

(async, static) verify(publicKeys, message, streaming, signature, date) → {Promise.<Object>}

Verifies signatures of cleartext signed message

Parameters:
Name Type Description
publicKeys Key | Array.<Key>

array of publicKeys or single key, to verify signatures

message CleartextMessage | Message

(cleartext) message object with signatures

streaming 'web' | 'node' | false

(optional) whether to return data as a stream. Defaults to the type of stream message was created from, if any.

signature Signature

(optional) detached signature for verification

date Date

(optional) use the given date for verification instead of the current time

Source:
Returns:

Object containing verified message in the form:

{
  data: String|ReadableStream<String>|NodeStream, (if `message` was a CleartextMessage)
  data: Uint8Array|ReadableStream<Uint8Array>|NodeStream, (if `message` was a Message)
  signatures: [
    {
      keyid: module:type/keyid,
      verified: Promise<Boolean>,
      valid: Boolean (if `streaming` was false)
    }, ...
  ]
}
Type
Promise.<Object>

(inner) checkString()

Input validation

Source:

(async, inner) convertStream(data, streaming) → {Object}

Convert data to or from Stream

Parameters:
Name Type Description
data Object

the data to convert

streaming 'web' | 'node' | false

(optional) whether to return a ReadableStream

Source:
Returns:

the data in the respective format

Type
Object

(async, inner) convertStreams(obj, streaming, keys) → {Object}

Convert object properties from Stream

Parameters:
Name Type Description
obj Object

the data to convert

streaming 'web' | 'node' | false

(optional) whether to return ReadableStreams

keys Array.<String>

(optional) which keys to return as streams, if possible

Source:
Returns:

the data in the respective format

Type
Object

(inner) linkStreams(result, message, erroringStream) → {Object}

Link result.data to the message stream for cancellation. Also, forward errors in the message to result.data.

Parameters:
Name Type Description
result Object

the data to convert

message Message

message object

erroringStream ReadableStream

(optional) stream which either errors or gets closed without data

Source:
Returns:
Type
Object

(inner) nativeAEAD() → {Boolean}

Check for native AEAD support and configuration by the user. Only browsers that implement the current WebCrypto specification support native GCM. Native EAX is built on CTR and CBC, which current browsers support. OCB and CFB are not natively supported.

Source:
Returns:

If authenticated encryption should be used

Type
Boolean

(inner) onError(message, error)

Global error handler that logs the stack trace and rethrows a high lvl error message.

Parameters:
Name Type Description
message String

A human readable high level error Message

error Error

The internal error that caused the failure

Source:

(async, inner) prepareSignatures(signatures)

Wait until signature objects have been verified

Parameters:
Name Type Description
signatures Object

list of signatures

Source:

(inner) toArray(param) → {Array.<Object>|undefined}

Normalize parameter to an array if it is not undefined.

Parameters:
Name Type Description
param Object

the parameter to be normalized

Source:
Returns:

the resulting array or undefined

Type
Array.<Object> | undefined