PGP Suite — Complete Guide for Tor Browser Users

PGP Suite – Encrypt Messages & Files is a Firefox/Tor Browser extension that brings full OpenPGP cryptography directly into your browser sidebar — no external applications, no servers, no tracking.

Table of Contents

1. Why Use PGP Suite with Tor Browser?
2. Architecture Overview
3. Key Management
4. Encrypting & Decrypting Messages
5. Signing & Verifying Messages
6. File Encryption
7. The Persistent Vault — Your Hidden Credential Store
8. Master Password Protection
9. On-Page PGP Detection
10. Security Model
11. Practical Workflows for Tor Users

Why Use PGP Suite with Tor Browser?

Tor Browser routes your traffic through the Tor network, hiding your IP address and providing anonymity. However, anonymity alone does not protect the content of what you type, store, or transmit. PGP Suite fills this gap:

• Onion services (.onion sites) often require you to create accounts with usernames and passwords you need to remember — but writing them down in a plaintext file or a password manager defeats the purpose of compartmentalization.
• Encrypted communication on forums, messaging boards, and email over Tor becomes trivial — you can encrypt and decrypt right inside the browser without switching to another application that might leak data.
• Everything is local. The extension uses browser.storage.local and the Web Crypto API entirely within your browser. No data ever leaves your machine through the extension itself.

Architecture Overview

The extension is composed of four JavaScript modules:

The cryptographic library used is OpenPGP.js, bundled locally as lib/openpgp.min.js. No network requests are made by the library.

Storage keys used in browser.storage.local:

Key Management

Generating a New Key Pair

Navigate to the Keys tab and fill in:

• Name — can be a pseudonym or alias
• Email — can be a fake address; it is embedded in the key's User ID string
• Passphrase — protects your private key; required every time you decrypt or sign
• Key type — RSA (up to 8192-bit) or ECC (Curve25519 recommended for performance)

On generation the extension creates the key pair using openpgp.generateKey(), extracts the fingerprint and Key ID, stores the key pair under MiniPGP_keys, and simultaneously registers the public portion in MiniPGP_public_keys so it immediately appears in encryption dropdowns.

Importing & Exporting Keys

• Import private key — paste ASCII-armored private key block; the extension validates the passphrase before storing it.
• Import public key — paste a contact's public key. You can later edit the display name, email, and a free-text comment for each imported public key without altering the cryptographic data.
• Export — copy or download the armored key block for backup or sharing.

Encrypting & Decrypting Messages

Encrypting

1. Open the Encrypt tab.
2. Type or paste your message.
3. Select the recipient's public key from the dropdown.
4. Optionally select one of your own keys to sign the message simultaneously.
5. Click Encrypt — the extension calls openpgp.encrypt() and outputs an ASCII-armored PGP message block.

Copy the output and paste it anywhere — a forum post, an onion mail service, a chat field.

Decrypting

1. Open the Decrypt tab.
2. Paste the -----BEGIN PGP MESSAGE----- block.
3. Select the private key to decrypt with and enter its passphrase.
4. Optionally provide a sender's public key to verify an embedded signature.
5. Click Decrypt.

The extension handles both standard encrypted messages and the more complex cleartext-signed + encrypted format (a signed outer wrapper containing an encrypted inner payload).

Signing & Verifying Messages

Signing (Cleartext)

The Sign tab produces a -----BEGIN PGP SIGNED MESSAGE----- block. The original text is human-readable; the signature is appended. This proves authorship without hiding content — useful for publishing verified announcements on onion forums.

Verifying

The Verify tab takes a signed message block and a public key, then confirms:

• Whether the signature is cryptographically valid.
• The Key ID that produced the signature.

If the signature cannot be verified because no public key was provided, the extension reports the Key ID of the signer so you can look up or import the right key.

File Encryption

The Files tab allows you to:

• Encrypt any file — select a file from disk, choose a recipient's public key, and download the encrypted .pgp output.
• Decrypt any file — upload a .pgp file, provide your private key and passphrase, and download the recovered plaintext file.

This is particularly useful for securely moving sensitive documents over Tor without exposing their contents to the onion service hosting them.

The Persistent Vault — Your Hidden Credential Store

The Vault is the most powerful feature for Tor Browser users. It solves the fundamental problem of where to keep sensitive operational information — onion addresses, usernames, passwords, PGP fingerprints of contacts, private notes — without storing anything in plaintext.

How It Works

Every Vault entry is encrypted with your own PGP public key before being written to browser.storage.local. The entry persists across browser restarts. The plaintext is never written to disk.

┌──────────────────────────────────────────┐
│  Your plaintext note (in memory only)    │
└───────────────┬──────────────────────────┘
                │  openpgp.encrypt()
                ▼
┌──────────────────────────────────────────┐
│  -----BEGIN PGP MESSAGE-----             │
│  (stored in browser.storage.local)       │
│  -----END PGP MESSAGE-----               │
└──────────────────────────────────────────┘

To read an entry you must supply the passphrase for your private key. This means:

• Even if someone gains access to your browser profile directory, all Vault entries are opaque PGP ciphertext.
• There is no separate master password for the Vault itself — your PGP key passphrase is the access credential.

Creating a Vault Entry

1. Open the Vault tab.
2. Enter a Label — a memorable name like "forum-alpha credentials" or "darkweb email".
3. In the content area, type anything you want to store:

   Site: http://examplexyz.onion
   Username: my_alias
   Password: correct-horse-battery-staple
   Notes: Created 2026-01, use Tor only
   

4. Select which of your private keys to encrypt this entry with.
5. Click Encrypt & Save.

The content is encrypted client-side and stored. The label is stored in plaintext so you can identify entries without decrypting them.

Unlocking and Editing an Entry

1. Find the entry by its label (shown with a 🔒 icon).
2. Enter your key's passphrase and click Unlock & Edit.
3. The decrypted text appears in an editable textarea.
4. Make changes, then click Re-encrypt & Save to persist the updated content.
5. Click Lock at any time to wipe the plaintext from session memory and return the entry to its encrypted state.

Deleting an Entry

An entry can only be deleted after successfully unlocking it. This prevents accidental deletion and proves you hold the key before destroying the record.

What to Store in the Vault

Master Password Protection

In addition to per-key passphrases, the Settings tab offers a Master Password that encrypts all stored private keys at rest inside browser.storage.local.

How It Works

• When a master password is set, every stored private key is re-encrypted using AES-256-GCM with a key derived via PBKDF2-SHA-256 (310,000 iterations) from the master password.
• A small verification blob (__MiniPGP_verify__) is encrypted with the same key and stored under MiniPGP_master_verify. On unlock, this blob is decrypted and checked — if it matches, the session is unlocked.
• The derived key is held in memory only (this._masterPassword). It is never written to storage.
• On browser restart the master password lock is re-applied automatically via browser.runtime.onStartup.

Layered Security for Tor Users

Browser profile on disk
    └─ browser.storage.local
           ├─ MiniPGP_keys  ──── AES-256-GCM (master password, PBKDF2)
           │                          └─ Private key ── OpenPGP passphrase (per-key)
           └─ MiniPGP_vault ──── OpenPGP encryption (public key)

Even without a master password, Vault entries remain protected by OpenPGP encryption. The master password adds a second encryption layer over your private keys themselves.

On-Page PGP Detection

The content script (content.js) scans every page you visit for recognisable PGP blocks:

• -----BEGIN PGP MESSAGE----- → a Decrypt button appears beside the block
• -----BEGIN PGP SIGNED MESSAGE----- → a Verify button appears
• -----BEGIN PGP PUBLIC KEY BLOCK----- → an Import button appears

Clicking these buttons opens the extension sidebar with the detected block pre-populated in the relevant tab. This is especially useful on onion forums where PGP-encrypted posts are common — no manual copy-paste required.

Security Model

Practical Workflows for Tor Users

Workflow 1 — Setting Up a New Tor Identity

1. Generate a new key pair with a pseudonymous name and a throwaway email address.
2. Create a Vault entry labelled "Identity: [alias]" containing the full .onion addresses, account credentials, and any relevant notes for that identity.
3. Enable the master password for an extra layer of protection over your stored private keys.
4. Export and back up your private key (encrypted) to a secure offline location.

Workflow 2 — Communicating on an Onion Forum

1. Publish your public key in your forum profile or in a post.
2. When you receive an encrypted reply, the content script detects the PGP block and shows a Decrypt button — click it to open the sidebar with the ciphertext ready.
3. Enter your passphrase, decrypt, read.
4. To reply privately, encrypt your response to the sender's public key (which you can import directly from their post using the Import button the content script surfaces).

Workflow 3 — Managing Multiple Onion Accounts

1. Create one Vault entry per service, each labelled clearly.
2. Encrypt each entry under the same key or different keys depending on how compartmentalised you need to be.
3. When you need credentials for a site, unlock only that entry, copy what you need, then immediately click Lock to clear it from memory.

Workflow 4 — Sharing Encrypted Files Over Tor

1. Import the recipient's public key (obtained via their onion site or a signed forum post).
2. Use the Files tab to encrypt the file locally.
3. Upload the .pgp file to the onion service — even if the service is compromised, the file content remains encrypted.

PGP Suite performs all operations locally in your browser. Your keys, your Vault, and your plaintext never leave your machine through this extension.

• https://addons.mozilla.org/en-US/firefox/addon/pgpsuite/
• https://github.com/ernos/pgpsuite-firefox-tor-extension
• https://www.yourdev.net/pgpsuite/