JSDoc: Global

Methods

armor(messageType, body, partIndexopt, partTotalopt, customCommentopt) → {String|ReadableStream.<String>}

Armor an OpenPGP binary packet block

Parameters:

Name	Type	Attributes	Description
`messageType`	module:enums.armor		Type of the message
`body`	Uint8Array \| ReadableStream.<Uint8Array>		The message body to armor
`partIndex`	Integer	<optional>
`partTotal`	Integer	<optional>
`customComment`	String	<optional>	Additional comment to add to the armored string

Source:

encoding/armor.js, line 362

Returns:

Armored text.

Type: String | ReadableStream.<String>

(async) createCleartextMessage(options)

Creates a new CleartextMessage object from text

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`text`	String

Source:

cleartext.js, line 206

createKey(packetlist) → {Key}

Creates a PublicKey or PrivateKey depending on the packetlist in input

Parameters:

Name	Type	Description
`packetlist`	PacketList	packets to parse

Source:

key/key.js, line 684

Throws:

if no key packet was found

Returns:

parsed key

Type: Key

(async) createMessage(options) → {Promise.<Message>}

Creates new message object from text or binary data.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`text`	String \| ReadableStream.<String>	<optional>		The text message contents
`binary`	Uint8Array \| ReadableStream.<Uint8Array>	<optional>		The binary message contents
`filename`	String	<optional>	""	Name of the file (if any)
`date`	Date	<optional>	current date	Date of the message, or modification date of the file
`format`	'utf8' \| 'binary' \| 'text' \| 'mime'	<optional>	'utf8' if text is passed, 'binary' otherwise	Data packet type

Source:

message.js, line 848

Returns:

New message object.

Type: Promise.<Message>

(async) decrypt(options) → {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

options

Object

Properties

Name	Type	Attributes	Default	Description
`message`	Message			The message object with the encrypted data
`decryptionKeys`	PrivateKey \| Array.<PrivateKey>	<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 }
`verificationKeys`	PublicKey \| Array.<PublicKey>	<optional>		Array of public keys or single key, to verify signatures
`expectSigned`	Boolean	<optional>	false	If true, data decryption fails if the message is not signed with the provided publicKeys
`format`	'utf8' \| 'binary'	<optional>	'utf8'	Whether to return data as a string(Stream) or Uint8Array(Stream). If 'utf8' (the default), also normalize newlines.
`signature`	Signature	<optional>		Detached signature for verification
`date`	Date	<optional>	current date	Use the given date for verification instead of the current time
`config`	Object	<optional>		Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 308

Returns:

Object containing decrypted and verified message in the form:

{
  data: MaybeStream<String>, (if format was 'utf8', the default)
  data: MaybeStream<Uint8Array>, (if format was 'binary')
  filename: String,
  signatures: [
    {
      keyID: module:type/keyid~KeyID,
      verified: Promise<Boolean>,
      valid: Boolean (if `message` was not created from a stream)
    }, ...
  ]
}

Type: Promise.<Object>

(async) decryptKey(options) → {Promise.<PrivateKey>}

Unlock a private key with the given passphrase. This method does not change the original key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`privateKey`	PrivateKey		The private key to decrypt
`passphrase`	String \| Array.<String>		The user's passphrase(s)
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 164

Returns:

The unlocked key object.

Type: Promise.<PrivateKey>

(async) decryptSessionKeys(options) → {Promise.<Object>}

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

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`message`	Message		A message object containing the encrypted session key packets
`decryptionKeys`	PrivateKey \| Array.<PrivateKey>	<optional>	Private keys with decrypted secret key data
`passwords`	String \| Array.<String>	<optional>	Passwords to decrypt the session key
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 525

Throws:

if no session key could be found or decrypted

Returns:

Array of decrypted session key, algorithm pairs in the form: { data:Uint8Array, algorithm:String }

Type: Promise.<Object>

(async) encrypt(options) → {Promise.<(MaybeStream.<String>|MaybeStream.<Uint8Array>)>}

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

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`message`	Message			Message to be encrypted as created by createMessage
`encryptionKeys`	PublicKey \| Array.<PublicKey>	<optional>		Array of keys or single key, used to encrypt the message
`signingKeys`	PrivateKey \| Array.<PrivateKey>	<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 }`
`armor`	Boolean	<optional>	true	Whether the return values should be ascii armored (true, the default) or binary (false)
`signature`	Signature	<optional>		A detached signature to add to the encrypted message
`wildcard`	Boolean	<optional>	false	Use a key ID of 0 instead of the public key IDs
`signingKeyIDs`	Array.<module:type/keyid~KeyID>	<optional>	latest-created valid signing (sub)keys	Array of key IDs to use for signing. Each `signingKeyIDs[i]` corresponds to `signingKeys[i]`
`encryptionKeyIDs`	Array.<module:type/keyid~KeyID>	<optional>	latest-created valid encryption (sub)keys	Array of key IDs to use for encryption. Each `encryptionKeyIDs[i]` corresponds to `encryptionKeys[i]`
`date`	Date	<optional>	current date	Override the creation date of the message signature
`signingUserIDs`	Array.<Object>	<optional>	primary user IDs	Array of user IDs to sign with, one per key in `signingKeys`, e.g. `[{ name: 'Steve Sender', email: 'steve@openpgp.org' }]`
`encryptionUserIDs`	Array.<Object>	<optional>	primary user IDs	Array of user IDs to encrypt for, one per key in `encryptionKeys`, e.g. `[{ name: 'Robert Receiver', email: 'robert@openpgp.org' }]`
`config`	Object	<optional>		Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 252

Returns:

Encrypted message (string if armor was true, the default; Uint8Array if armor was false).

Type: Promise.<(MaybeStream.<String>|MaybeStream.<Uint8Array>)>

(async) encryptKey(options) → {Promise.<PrivateKey>}

Lock a private key with the given passphrase. This method does not change the original key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`privateKey`	PrivateKey		The private key to encrypt
`passphrase`	String \| Array.<String>		If multiple passphrases, they should be in the same order as the packets each should encrypt
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 196

Returns:

The locked key object.

Type: Promise.<PrivateKey>

(async) encryptSessionKey(options) → {Promise.<(String|Uint8Array)>}

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

options

Object

Properties

Name	Type	Attributes	Default	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'
`encryptionKeys`	PublicKey \| Array.<PublicKey>	<optional>		Array of public keys or single key, used to encrypt the key
`passwords`	String \| Array.<String>	<optional>		Passwords for the message
`armor`	Boolean	<optional>	true	Whether the return values should be ascii armored (true, the default) or binary (false)
`wildcard`	Boolean	<optional>	false	Use a key ID of 0 instead of the public key IDs
`encryptionKeyIDs`	Array.<module:type/keyid~KeyID>	<optional>	latest-created valid encryption (sub)keys	Array of key IDs to use for encryption. Each encryptionKeyIDs[i] corresponds to encryptionKeys[i]
`date`	Date	<optional>	current date	Override the date
`encryptionUserIDs`	Array	<optional>	primary user IDs	Array of user IDs to encrypt for, one per key in `encryptionKeys`, e.g. `[{ name: 'Phil Zimmermann', email: 'phil@openpgp.org' }]`
`config`	Object	<optional>		Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 499

Returns:

Encrypted session keys (string if armor was true, the default; Uint8Array if armor was false).

Type: Promise.<(String|Uint8Array)>

(async) generateKey(options) → {Promise.<Object>}

Generates a new OpenPGP key pair. Supports RSA and ECC keys. By default, primary and subkeys will be of same type.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`userIDs`	Object \| Array.<Object>			User IDs as objects: `{ name: 'Jo Doe', email: 'info@jo.com' }`
`type`	'ecc' \| 'rsa'	<optional>	'ecc'	The primary key algorithm type: ECC (default) or RSA
`passphrase`	String	<optional>	(not protected)	The passphrase used to encrypt the generated private key. If omitted, the key won't be encrypted.
`rsaBits`	Number	<optional>	4096	Number of bits for RSA keys
`curve`	String	<optional>	'curve25519'	Elliptic curve for ECC keys: curve25519 (default), p256, p384, p521, secp256k1, brainpoolP256r1, brainpoolP384r1, or brainpoolP512r1
`date`	Date	<optional>	current date	Override the creation date of the key and the key signatures
`keyExpirationTime`	Number	<optional>	0 (never expires)	Number of seconds from the key creation time after which the key expires
`subkeys`	Array.<Object>	<optional>	a single encryption subkey	Options for each subkey e.g. `[{sign: true, passphrase: '123'}]` default to main key options, except for `sign` parameter that defaults to false, and indicates whether the subkey should sign rather than encrypt
`config`	Object	<optional>		Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 53

Returns:

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

Type: Promise.<Object>

(async) generateSessionKey(options) → {Promise.<{data: Uint8Array, algorithm: String}>}

Generate a new session key object, taking the algorithm preferences of the passed public keys into account.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`encryptionKeys`	PublicKey \| Array.<PublicKey>			Array of public keys or single key used to select algorithm preferences for
`date`	Date	<optional>	current date	Date to select algorithm preferences at
`encryptionUserIDs`	Array	<optional>	primary user IDs	User IDs to select algorithm preferences for
`config`	Object	<optional>		Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 469

Returns:

Object with session key data and algorithm.

Type: Promise.<{data: Uint8Array, algorithm: String}>

newPacketFromTag(tag, allowedPackets) → {Object}

Instantiate a new packet given its tag

Parameters:

Name	Type	Description
`tag`	module:enums.packet	Property value from module:enums.packet
`allowedPackets`	Object	mapping where keys are allowed packet tags, pointing to their Packet class

Source:

packet/packetlist.js, line 12

Returns:

New packet object with type based on tag

Type: Object

(async) readCleartextMessage(options) → {Promise.<CleartextMessage>}

Reads an OpenPGP cleartext signed message and returns a CleartextMessage object

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`cleartextMessage`	String		Text to be parsed
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

cleartext.js, line 135

Returns:

New cleartext message object.

Type: Promise.<CleartextMessage>

(async) readKey(options) → {Promise.<Key>}

Reads an (optionally armored) OpenPGP key and returns a key object

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`armoredKey`	String	<optional>	Armored key to be parsed
`binaryKey`	Uint8Array	<optional>	Binary key to be parsed
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

key/factory.js, line 263

Returns:

Key object.

Type: Promise.<Key>

(async) readKeys(options) → {Promise.<Array.<Key>>}

Reads an (optionally armored) OpenPGP key block and returns a list of key objects

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`armoredKeys`	String	<optional>	Armored keys to be parsed
`binaryKeys`	Uint8Array	<optional>	Binary keys to be parsed
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

key/factory.js, line 333

Returns:

Key objects.

Type: Promise.<Array.<Key>>

(async) readMessage(options) → {Promise.<Message>}

Reads an (optionally armored) OpenPGP message and returns a Message object

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`armoredMessage`	String \| ReadableStream.<String>	<optional>	Armored message to be parsed
`binaryMessage`	Uint8Array \| ReadableStream.<Uint8Array>	<optional>	Binary to be parsed
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

message.js, line 806

Returns:

New message object.

Type: Promise.<Message>

(async) readPrivateKey(options) → {Promise.<PrivateKey>}

Reads an (optionally armored) OpenPGP private key and returns a PrivateKey object

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`armoredKey`	String	<optional>	Armored key to be parsed
`binaryKey`	Uint8Array	<optional>	Binary key to be parsed
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

key/factory.js, line 298

Returns:

Key object.

Type: Promise.<PrivateKey>

(async) readPrivateKeys(options) → {Promise.<Array.<PrivateKey>>}

Reads an (optionally armored) OpenPGP private key block and returns a list of PrivateKey objects

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`armoredKeys`	String	<optional>	Armored keys to be parsed
`binaryKeys`	Uint8Array	<optional>	Binary keys to be parsed
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

key/factory.js, line 376

Returns:

Key objects.

Type: Promise.<Array.<PrivateKey>>

(async) readSignature(options) → {Promise.<Signature>}

reads an (optionally armored) OpenPGP signature and returns a signature object

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Description
`armoredSignature`	String	<optional>	Armored signature to be parsed
`binarySignature`	Uint8Array	<optional>	Binary signature to be parsed
`config`	Object	<optional>	Custom configuration settings to overwrite those in config

Source:

signature.js, line 66

Returns:

New signature object.

Type: Promise.<Signature>

(async) reformatKey(options) → {Promise.<Object>}

Reformats signature packets for a key and rewraps key object.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`privateKey`	PrivateKey			Private key to reformat
`userIDs`	Object \| Array.<Object>			User IDs as objects: `{ name: 'Jo Doe', email: 'info@jo.com' }`
`passphrase`	String	<optional>	(not protected)	The passphrase used to encrypt the reformatted private key. If omitted, the key won't be encrypted.
`keyExpirationTime`	Number	<optional>	0 (never expires)	Number of seconds from the key creation time after which the key expires
`date`	Date	<optional>		Override the creation date of the key signatures
`config`	Object	<optional>		Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 93

Returns:

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

Type: Promise.<Object>

(async) revokeKey(options) → {Promise.<Object>}

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

Parameters:

Name Type Description

options

Object

Properties

Name Type Attributes Description

key

Key

Public or private key to revoke

revocationCertificate

String

Revocation certificate to revoke the key with

reasonForRevocation

Object

Object indicating the reason for revocation

Properties

Name	Type	Attributes	Default	Description
`flag`	module:enums.reasonForRevocation	<optional>	noReason	Flag indicating the reason for revocation
`string`	String	<optional>	""	String explaining the reason for revocation

config

Object

Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 129

Returns:

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

Type: Promise.<Object>

(async) sign(options) → {Promise.<(MaybeStream.<String>|MaybeStream.<Uint8Array>)>}

Signs a message.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`message`	CleartextMessage \| Message			(cleartext) message to be signed
`signingKeys`	PrivateKey \| Array.<PrivateKey>			Array of keys or single key with decrypted secret key data to sign cleartext
`armor`	Boolean	<optional>	true	Whether the return values should be ascii armored (true, the default) or binary (false)
`detached`	Boolean	<optional>	false	If the return value should contain a detached signature
`signingKeyIDs`	Array.<module:type/keyid~KeyID>	<optional>	latest-created valid signing (sub)keys	Array of key IDs to use for signing. Each signingKeyIDs[i] corresponds to signingKeys[i]
`date`	Date	<optional>	current date	Override the creation date of the signature
`signingUserIDs`	Array.<Object>	<optional>	primary user IDs	Array of user IDs to sign with, one per key in `signingKeys`, e.g. `[{ name: 'Steve Sender', email: 'steve@openpgp.org' }]`
`config`	Object	<optional>		Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 365

Returns:

Signed message (string if armor was true, the default; Uint8Array if armor was false).

Type: Promise.<(MaybeStream.<String>|MaybeStream.<Uint8Array>)>

(async) unarmor(input) → {Promise.<Object>}

Dearmor an OpenPGP armored message; verify the checksum and return the encoded bytes

Parameters:

Name	Type	Description
`input`	String	OpenPGP armored message

Source:

encoding/armor.js, line 231

Returns:

An object with attribute "text" containing the message text, an attribute "data" containing a stream of bytes and "type" for the ASCII armor type

Type: Promise.<Object>

(async) verify(options) → {Promise.<Object>}

Verifies signatures of cleartext signed message

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`message`	CleartextMessage \| Message			(cleartext) message object with signatures
`verificationKeys`	PublicKey \| Array.<PublicKey>			Array of publicKeys or single key, to verify signatures
`expectSigned`	Boolean	<optional>	false	If true, verification throws if the message is not signed with the provided publicKeys
`format`	'utf8' \| 'binary'	<optional>	'utf8'	Whether to return data as a string(Stream) or Uint8Array(Stream). If 'utf8' (the default), also normalize newlines.
`signature`	Signature	<optional>		Detached signature for verification
`date`	Date	<optional>	current date	Use the given date for verification instead of the current time
`config`	Object	<optional>		Custom configuration settings to overwrite those in config

Source:

openpgp.js, line 418

Returns:

Object containing verified message in the form:

{
  data: MaybeStream<String>, (if `message` was a CleartextMessage)
  data: MaybeStream<Uint8Array>, (if `message` was a Message)
  signatures: [
    {
      keyID: module:type/keyid~KeyID,
      verified: Promise<Boolean>,
      valid: Boolean (if `message` was not created from a stream)
    }, ...
  ]
}

Type: Promise.<Object>