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) util

Source:
See:

Methods

(async, static) decrypt(message, privateKeys, passwords, sessionKeys, publicKeys, format, 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'

signature Signature

(optional) detached signature for verification

date Date

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

Source:
Returns:

decrypted and verified message in the form: { data:Uint8Array|String, filename:String, signatures:[{ keyid:String, valid:Boolean }] }

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

the user's passphrase 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(data, publicKeys, privateKeys, passwords, sessionKey, filename, compression, armor, detached, signature, returnSessionKey, wildcard, date) → {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
data String | Uint8Array

text/data to be encrypted as JavaScript binary string or Uint8Array

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 }

filename String

(optional) a filename for the literal data packet

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

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 and the message signature

Source:
Returns:

encrypted (and optionally signed message) in the form: {data: ASCII armored message if 'armor' is true, message: full Message object if 'armor' is false, signature: detached signature if 'detached' is 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

the user's passphrase chosen during key generation

Source:
Returns:

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

Type
Promise.<Object>

(async, static) encryptSessionKey(data, algorithm, publicKeys, passwords, wildcard) → {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'

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

Source:
Returns:

the encrypted session key packets contained in a message object

Type
Promise.<Message>

(async, static) generateKey(userIds, passphrase, numBits, curve, unlocked, keyExpirationTime) → {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.

curve String

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

unlocked Boolean

(optional) If the returned secret part of the generated key is unlocked

keyExpirationTime Number

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

Source:
Returns:

The generated key object in the form: { key:Key, privateKeyArmored:String, publicKeyArmored: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, unlocked, keyExpirationTime) → {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

unlocked Boolean

(optional) If the returned secret part of the generated key is unlocked

keyExpirationTime Number

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

Source:
Returns:

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

Type
Promise.<Object>

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

Signs a cleartext message.

Parameters:
Name Type Description
data String | Uint8Array

cleartext input 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

detached Boolean

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

date Date

(optional) override the creation date signature

Source:
Returns:

signed cleartext in the form: {data: ASCII armored message if 'armor' is true, message: full Message object if 'armor' is false, signature: detached signature if 'detached' is true}

Type
Promise.<Object>

(async, static) verify(publicKeys, message, 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

cleartext message object with signatures

signature Signature

(optional) detached signature for verification

date Date

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

Source:
Returns:

cleartext with status of verified signatures in the form of: { data:String, signatures: [{ keyid:String, valid:Boolean }] }

Type
Promise.<Object>

(inner) checkString()

Input validation

Source:

(inner) createMessage(data, filename, date) → {Message}

Creates a message obejct either from a Uint8Array or a string.

Parameters:
Name Type Description
data String | Uint8Array

the payload for the message

filename String

the literal data packet's filename

date Date

the creation date of the package

Source:
Returns:

a message object

Type
Message

(inner) formatUserIds()

Format user ids for internal use.

Source:

(inner) nativeAEAD() → {Boolean}

Check for AES-GCM support and configuration by the user. Only browsers that implement the current WebCrypto specification support native AES-GCM.

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:

(inner) parseMessage(message, format) → {Object}

Parse the message given a certain format.

Parameters:
Name Type Description
message Message

the message object to be parse

format String

the output format e.g. 'utf8' or 'binary'

Source:
Returns:

the parse data in the respective format

Type
Object

(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