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) decrypt(options) → {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
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 'utf8' | 'binary' <optional>
 'utf8'

Whether to return data as a string(Stream) or Uint8Array(Stream). If 'utf8' (the default), also normalize newlines.
streaming 'web' | 'ponyfill' | 'node' | false <optional>
 type of stream `message` was created from, if any

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>
 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: 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~Keyid,
      verified: Promise<Boolean>,
      valid: Boolean (if streaming was false)
    }, ...
  ]
}
Type
Object

(async) decryptKey(options) → {Key}

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 Key

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
Key

(async) decryptSessionKeys(options) → {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
options Object
Properties
Name Type Attributes 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
config Object <optional>

Custom configuration settings to overwrite those in config
Source:
Returns:

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

Type
Object | undefined

(async) encrypt(options) → {String|ReadableStream.<String>|NodeStream.<String>|Uint8Array|ReadableStream.<Uint8Array>|NodeStream.<Uint8Array>}

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
options Object
Properties
Name Type Attributes Default Description
message Message

Message to be encrypted as created by Message.fromText or 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 }
armor Boolean <optional>
 true

Whether the return values should be ascii armored (true, the default) or binary (false)
streaming 'web' | 'ponyfill' | 'node' | false <optional>
 type of stream `message` was created from, if any

Whether to return data as a stream
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 privateKeys[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 publicKeys[i]
date Date <optional>
 current date

Override the creation date of the message signature
fromUserIds Array.<Object> <optional>
 primary user IDs

Array of user IDs to sign with, one per key in privateKeys, e.g. [{ name: 'Steve Sender', email: 'steve@openpgp.org' }]
toUserIds Array.<Object> <optional>
 primary user IDs

Array of user IDs to encrypt for, one per key in publicKeys, e.g. [{ name: 'Robert Receiver', email: 'robert@openpgp.org' }]
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
String | ReadableStream.<String> | NodeStream.<String> | Uint8Array | ReadableStream.<Uint8Array> | NodeStream.<Uint8Array>

(async) encryptKey(options) → {Key}

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 Key

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
Key

(async) encryptSessionKey(options) → {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'
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
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 publicKeys[i]
date Date <optional>
 current date

Override the date
toUserIds Array <optional>
 primary user IDs

Array of user IDs to encrypt for, one per key in publicKeys, e.g. [{ name: 'Phil Zimmermann', email: 'phil@openpgp.org' }]
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
String | Uint8Array

(async) generateKey(options) → {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
type 'ecc' | 'rsa' <optional>
 'ecc'

The primary key algorithm type: ECC (default) or RSA
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 generated private key
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, 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
config Object <optional>

Custom configuration settings to overwrite those in config
Source:
Returns:

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

Type
Object

(async) generateSessionKey(options) → {Object}

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
publicKeys Key | Array.<Key>

Array of public keys or single key used to select algorithm preferences for
date Date <optional>
 current date

Date to select algorithm preferences at
toUserIds Array <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
Object

(async) readCleartextMessage(options) → {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 | ReadableStream.<String>

Text to be parsed
config Object <optional>

Custom configuration settings to overwrite those in config
Source:
Returns:

New cleartext message object.

Type
CleartextMessage

(async) readKey(options) → {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 | ReadableStream.<String> <optional>

Armored key to be parsed
binaryKey Uint8Array | ReadableStream.<Uint8Array> <optional>

Binary key to be parsed
config Object <optional>

Custom configuration settings to overwrite those in config
Source:
Returns:

Key object.

Type
Key

(async) readKeys(options) → {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 | ReadableStream.<String> <optional>

Armored keys to be parsed
binaryKeys Uint8Array | ReadableStream.<Uint8Array> <optional>

Binary keys to be parsed
config Object <optional>

Custom configuration settings to overwrite those in config
Source:
Returns:

Key objects.

Type
Array.<Key>

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

(async) readSignature(options) → {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 | ReadableStream.<String> <optional>

Armored signature to be parsed
binarySignature Uint8Array | ReadableStream.<Uint8Array> <optional>

Binary signature to be parsed
config Object <optional>

Custom configuration settings to overwrite those in config
Source:
Returns:

New signature object.

Type
Signature

(async) reformatKey(options) → {Object}

Reformats signature packets for a key and rewraps key object.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Default Description
privateKey Key

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 generated private key
keyExpirationTime Number <optional>
 0 (never expires)

Number of seconds from the key creation time after which the key expires
config Object <optional>

Custom configuration settings to overwrite those in config
Source:
Returns:

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

Type
Object

(async) revokeKey(options) → {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 <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
config Object <optional>

Custom configuration settings to overwrite those in config
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
Object

(async) sign(options) → {String|ReadableStream.<String>|NodeStream.<String>|Uint8Array|ReadableStream.<Uint8Array>|NodeStream.<Uint8Array>}

Signs a message.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Default 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>
 true

Whether the return values should be ascii armored (true, the default) or binary (false)
streaming 'web' | 'ponyfill' | 'node' | false <optional>
 type of stream `message` was created from, if any

Whether to return data as a stream. Defaults to the type of stream message was created from, if any.
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 privateKeys[i]
date Date <optional>
 current date

Override the creation date of the signature
fromUserIds Array.<Object> <optional>
 primary user IDs

Array of user IDs to sign with, one per key in privateKeys, e.g. [{ name: 'Steve Sender', email: 'steve@openpgp.org' }]
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
String | ReadableStream.<String> | NodeStream.<String> | Uint8Array | ReadableStream.<Uint8Array> | NodeStream.<Uint8Array>

(async) unarmor(input) → {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
Object

(async) verify(options) → {Object}

Verifies signatures of cleartext signed message

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

Array of publicKeys or single key, to verify signatures
message CleartextMessage | Message

(cleartext) message object with signatures
format 'utf8' | 'binary' <optional>
 'utf8'

Whether to return data as a string(Stream) or Uint8Array(Stream). If 'utf8' (the default), also normalize newlines.
streaming 'web' | 'ponyfill' | 'node' | false <optional>
 type of stream `message` was created from, if any

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