tessl/npm-openpgp

OpenPGP.js is a Javascript implementation of the OpenPGP protocol for end-to-end encryption, digital signatures, and key management in web browsers and Node.js applications.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

OpenPGP.js

Name: tessl/npm-openpgp
Author: tessl

OpenPGP.js is a comprehensive JavaScript implementation of the OpenPGP protocol (RFC 9580/4880) that enables developers to implement end-to-end encryption, digital signatures, and key management in web browsers and Node.js applications. It provides a complete cryptographic toolkit with support for modern and legacy algorithms, streaming operations, and cross-platform compatibility.

Package Information

Package Name: openpgp
Package Type: npm
Language: JavaScript/TypeScript
Installation: npm install openpgp

Core Imports

For ES Modules (recommended):

import { encrypt, decrypt, generateKey, readKey } from 'openpgp';
import { PrivateKey, PublicKey, Message, enums, config } from 'openpgp';

For CommonJS:

const { encrypt, decrypt, generateKey, readKey } = require('openpgp');
const { PrivateKey, PublicKey, Message, enums, config } = require('openpgp');

For browsers:

<script src="https://unpkg.com/openpgp@6.2.2/dist/openpgp.min.js"></script>
<script>
  const { encrypt, decrypt, generateKey } = openpgp;
</script>

Basic Usage

import { generateKey, encrypt, decrypt, readKey, readMessage, createMessage } from 'openpgp';

// Generate a new key pair
const { privateKey, publicKey } = await generateKey({
  type: 'ecc',
  curve: 'curve25519Legacy',
  userIDs: [{ name: 'John Doe', email: 'john@example.com' }],
  passphrase: 'super-secret-passphrase'
});

// Create and encrypt a message
const message = await createMessage({ text: 'Hello, World!' });
const encrypted = await encrypt({
  message,
  encryptionKeys: publicKey,
  signingKeys: privateKey
});

// Decrypt the message
const decrypted = await decrypt({
  message: await readMessage({ armoredMessage: encrypted }),
  decryptionKeys: privateKey,
  verificationKeys: publicKey
});

console.log(decrypted.data); // 'Hello, World!'

Architecture

OpenPGP.js is built around several key architectural components:

High-Level API: Simplified functions for common operations (encrypt, decrypt, sign, verify, generateKey)
Object Model: Rich classes representing keys, messages, signatures, and packets
Streaming Support: Full Web Streams API integration for handling large data efficiently
Packet System: Low-level OpenPGP packet implementation following RFC specifications
Multi-Platform: Works in browsers (with Web Crypto API) and Node.js environments
Type Safety: Complete TypeScript definitions for all APIs

Capabilities

Key Management

Complete key lifecycle management including generation, reading, encryption, decryption, and revocation. Supports RSA, ECC, and modern curve algorithms.

function generateKey(options: GenerateKeyOptions): Promise<{
  privateKey: string | Uint8Array | PrivateKey,
  publicKey: string | Uint8Array | PublicKey,
  revocationCertificate: string
}>;

function readKey(options: { 
  armoredKey: string, 
  config?: PartialConfig 
}): Promise<Key>;

function decryptKey(options: { 
  privateKey: PrivateKey, 
  passphrase: string | string[], 
  config?: PartialConfig 
}): Promise<PrivateKey>;

interface GenerateKeyOptions {
  userIDs: UserID | UserID[];
  passphrase?: string;
  type?: 'ecc' | 'rsa' | 'curve25519' | 'curve448';
  curve?: EllipticCurveName;
  rsaBits?: number;
  keyExpirationTime?: number;
  date?: Date;
  subkeys?: SubkeyOptions[];
  format?: 'armored' | 'object' | 'binary';
  config?: PartialConfig;
}

Key Management

Message Encryption and Decryption

Encrypt and decrypt messages using public keys, passwords, or session keys. Supports both streaming and non-streaming operations with integrity protection.

function encrypt(options: EncryptOptions): Promise<string | Uint8Array>;

function decrypt(options: DecryptOptions): Promise<{
  data: string | Uint8Array,
  signatures: VerificationResult[],
  filename: string
}>;

interface EncryptOptions {
  message: Message;
  encryptionKeys?: PublicKey | PublicKey[];
  signingKeys?: PrivateKey | PrivateKey[];
  passwords?: string | string[];
  format?: 'armored' | 'binary' | 'object';
  config?: PartialConfig;
}

interface DecryptOptions {
  message: Message;
  decryptionKeys?: PrivateKey | PrivateKey[];
  passwords?: string | string[];
  verificationKeys?: PublicKey | PublicKey[];
  format?: 'utf8' | 'binary';
  config?: PartialConfig;
}

Encryption and Decryption

Message Signing and Verification

Create and verify digital signatures for messages and cleartext. Supports detached signatures and multiple signing keys.

function sign(options: SignOptions): Promise<string | Uint8Array>;

function verify(options: VerifyOptions): Promise<{
  data: string | Uint8Array,
  signatures: VerificationResult[]
}>;

interface SignOptions {
  message: CleartextMessage | Message;
  signingKeys: PrivateKey | PrivateKey[];
  format?: 'armored' | 'binary' | 'object';
  detached?: boolean;
  config?: PartialConfig;
}

interface VerificationResult {
  keyID: KeyID;
  verified: Promise<true>;
  signature: Promise<Signature>;
}

Signing and Verification

Session Key Operations

Generate, encrypt, and decrypt session keys for advanced encryption workflows and key escrow scenarios.

function generateSessionKey(options: {
  encryptionKeys: PublicKey | PublicKey[],
  date?: Date,
  encryptionUserIDs?: UserID | UserID[],
  config?: PartialConfig
}): Promise<SessionKey>;

function encryptSessionKey(options: EncryptSessionKeyOptions): Promise<string | Uint8Array>;

function decryptSessionKeys(options: {
  message: Message,
  decryptionKeys?: PrivateKey | PrivateKey[],
  passwords?: string | string[],
  config?: PartialConfig
}): Promise<DecryptedSessionKey[]>;

interface SessionKey {
  data: Uint8Array;
  algorithm: string;
  aeadAlgorithm?: string;
}

Session Key Operations

Low-Level Packet API

Direct access to OpenPGP packet system for advanced use cases, custom implementations, and protocol-level operations.

class PublicKeyPacket extends BasePacket {
  algorithm: enums.publicKey;
  created: Date;
  version: number;
  getFingerprint(): string;
  getKeyID(): KeyID;
}

class SignaturePacket extends BasePacket {
  version: number;
  signatureType: enums.signature | null;
  hashAlgorithm: enums.hash | null;
  created: Date | null;
  sign(key: SecretKeyPacket, data: Uint8Array): Promise<void>;
  verify(key: PublicKeyPacket, data: Uint8Array): Promise<void>;
}

class PacketList<T> extends Array<T> {
  static fromBinary(bytes: Uint8Array): PacketList<any>;
  write(): Uint8Array;
  filterByTag(...tags: enums.packet[]): PacketList<T>;
}

Low-Level Packet API

ASCII Armor Operations

Encode and decode OpenPGP data with ASCII armor format for text-safe transmission.

function armor(
  messagetype: enums.armor, 
  body: object, 
  partindex?: number, 
  parttotal?: number, 
  customComment?: string, 
  emitChecksum?: boolean, 
  config?: Config
): string;

function unarmor(input: string, config?: Config): Promise<{
  text: string,
  data: ReadableStream<Uint8Array>,
  type: enums.armor
}>;

Core Types

interface UserID {
  name?: string;
  email?: string;
  comment?: string;
}

interface PartialConfig {
  preferredHashAlgorithm?: enums.hash;
  preferredSymmetricAlgorithm?: enums.symmetric;
  preferredCompressionAlgorithm?: enums.compression;
  aeadProtect?: boolean;
  v6Keys?: boolean;
}

type EllipticCurveName = 
  | 'ed25519Legacy' 
  | 'curve25519Legacy' 
  | 'nistP256' 
  | 'nistP384' 
  | 'nistP521' 
  | 'secp256k1' 
  | 'brainpoolP256r1' 
  | 'brainpoolP384r1' 
  | 'brainpoolP512r1';

type MaybeStream<T> = T | ReadableStream<T>;

// Enums namespace containing all OpenPGP constants
declare const enums: {
  armor: { [key: string]: number };
  compression: { [key: string]: number };
  hash: { [key: string]: number };
  packet: { [key: string]: number };
  publicKey: { [key: string]: number };
  symmetric: { [key: string]: number };
  signature: { [key: string]: number };
  reasonForRevocation: { [key: string]: number };
  literal: { [key: string]: number };
  aead: { [key: string]: number };
};

Install with Tessl CLI