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:
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:

createKey(packetlist) → {Key}

Creates a PublicKey or PrivateKey depending on the packetlist in input

Parameters:
Name Type Description
packetlist PacketList

packets to parse

Source:
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:
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. One of decryptionKeys, sessionkeys or passwords must be specified (passing a combination of these options is not supported).

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:
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<true>,
      signature: Promise<Signature>
    }, ...
  ]
}

where `signatures` contains a separate entry for each signature packet found in the input message.
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:
Returns:

The unlocked key object.

Type
Promise.<PrivateKey>

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

Decrypt symmetric session keys using private keys or passwords (not both). One of decryptionKeys or passwords 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

date Date <optional>

Date to use for key verification instead of the current time

config Object <optional>

Custom configuration settings to overwrite those in config

Source:
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.<Array.<Object>>

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

Encrypts a message using public keys, passwords or both at once. At least one of encryptionKeys 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 }

format 'armored' | 'binary' | 'object' <optional>
'armored'

Format of the returned message

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 KeyID | Array.<KeyID> <optional>
latest-created valid signing (sub)keys

Array of key IDs to use for signing. Each signingKeyIDs[i] corresponds to signingKeys[i]

encryptionKeyIDs KeyID | Array.<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 Object | Array.<Object> <optional>
primary user IDs

Array of user IDs to sign with, one per key in signingKeys, e.g. [{ name: 'Steve Sender', email: '[email protected]' }]

encryptionUserIDs Object | Array.<Object> <optional>
primary user IDs

Array of user IDs to encrypt for, one per key in encryptionKeys, e.g. [{ name: 'Robert Receiver', email: '[email protected]' }]

config Object <optional>

Custom configuration settings to overwrite those in config

Source:
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:
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 one of encryptionKeys 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

format 'armored' | 'binary' <optional>
'armored'

Format of the returned value

wildcard Boolean <optional>
false

Use a key ID of 0 instead of the public key IDs

encryptionKeyIDs KeyID | Array.<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 Object | Array.<Object> <optional>
primary user IDs

Array of user IDs to encrypt for, one per key in encryptionKeys, e.g. [{ name: 'Phil Zimmermann', email: '[email protected]' }]

config Object <optional>

Custom configuration settings to overwrite those in config

Source:
Returns:

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

Type
Promise.<(String|Uint8Array)>

formatObject(object, format, config) → {String|Uint8Array|Object}

Convert the object to the given format

Parameters:
Name Type Description
object Key | Message
format 'armored' | 'binary' | 'object'
config Object

Full configuration

Source:
Returns:
Type
String | Uint8Array | Object

(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. The generated primary key will have signing capabilities. By default, one subkey with encryption capabilities is also generated.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Default Description
userIDs Object | Array.<Object>

User IDs as objects: { name: 'Jo Doe', email: '[email protected]' }

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

format 'armored' | 'binary' | 'object' <optional>
'armored'

format of the output keys

config Object <optional>

Custom configuration settings to overwrite those in config

Source:
Returns:

The generated key object in the form: { privateKey:PrivateKey|Uint8Array|String, publicKey:PublicKey|Uint8Array|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 Object | Array.<Object> <optional>
primary user IDs

User IDs to select algorithm preferences for

config Object <optional>

Custom configuration settings to overwrite those in config

Source:
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:
Throws:

for disallowed or unknown packets

Type
Error | UnsupportedError
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:
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:
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:
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:
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:
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:
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:
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: '[email protected]' }

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

format 'armored' | 'binary' | 'object' <optional>
'armored'

format of the output keys

config Object <optional>

Custom configuration settings to overwrite those in config

Source:
Returns:

The generated key object in the form: { privateKey:PrivateKey|Uint8Array|String, publicKey:PublicKey|Uint8Array|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 Default Description
key Key

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 Attributes Default Description
flag module:enums.reasonForRevocation <optional>
noReason

Flag indicating the reason for revocation

string String <optional>
""

String explaining the reason for revocation

date Date <optional>

Use the given date instead of the current time to verify validity of revocation certificate (if provided), or as creation time of the revocation signature

format 'armored' | 'binary' | 'object' <optional>
'armored'

format of the output key(s)

config Object <optional>

Custom configuration settings to overwrite those in config

Source:
Returns:

The revoked key in the form: { privateKey:PrivateKey|Uint8Array|String, publicKey:PublicKey|Uint8Array|String } if private key is passed, or { privateKey: null, publicKey:PublicKey|Uint8Array|String } otherwise

Type
Promise.<Object>

(async) sign(options) → {Promise.<MaybeStream.<(String|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

format 'armored' | 'binary' | 'object' <optional>
'armored'

Format of the returned message

detached Boolean <optional>
false

If the return value should contain a detached signature

signingKeyIDs KeyID | Array.<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 Object | Array.<Object> <optional>
primary user IDs

Array of user IDs to sign with, one per key in signingKeys, e.g. [{ name: 'Steve Sender', email: '[email protected]' }]

config Object <optional>

Custom configuration settings to overwrite those in config

Source:
Returns:

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

Type
Promise.<MaybeStream.<(String|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:
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:
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<true>,
      signature: Promise<Signature>
    }, ...
  ]
}

where `signatures` contains a separate entry for each signature packet found in the input message.
Type
Promise.<Object>

(async) wrapKeyObject(secretKeyPacket, secretSubkeyPackets, options, config) → {PrivateKey}

Construct PrivateKey object from the given key packets, add certification signatures and set passphrase protection The new key includes a revocation certificate that must be removed before returning the key, otherwise the key is considered revoked.

Parameters:
Name Type Description
secretKeyPacket SecretKeyPacket
secretSubkeyPackets SecretSubkeyPacket
options Object
config Object

Full configuration

Source:
Returns:
Type
PrivateKey