Installation

This guide covers installing the LocalPGP browser extension and the required system dependencies.

Requirements

• GnuPG with gpgme-json support
• Chrome or Firefox browser

Step 1: Install gpgme-json

The gpgme-json binary is required for the extension to communicate with GnuPG.

Debian/Ubuntu:

sudo apt install gpgme-json

Fedora:

sudo dnf install gpgme

Arch Linux:

sudo pacman -S gpgme

Verify the installation:

which gpgme-json
# Should output: /usr/bin/gpgme-json

Step 2: Install the Browser Extension

Chrome

Install from the Chrome Web Store:

1. Visit the LocalPGP Chrome Extension page
2. Click “Add to Chrome”
3. Click “Add extension” in the confirmation dialog

Firefox

Install from Firefox Add-ons:

1. Visit the LocalPGP Firefox Add-on page
2. Click “Add to Firefox”
3. Click “Add” in the confirmation dialog

Step 3: Configure Native Messaging Host

Native messaging allows the browser extension to communicate with gpgme-json on your system. You need to create a configuration file to enable this.

Chrome/Chromium

Create the configuration file at the appropriate location:

• Chromium: ~/.config/chromium/NativeMessagingHosts/gpgmejson.json
• Chrome: ~/.config/google-chrome/NativeMessagingHosts/gpgmejson.json

# For Chrome
mkdir -p ~/.config/google-chrome/NativeMessagingHosts/
cat > ~/.config/google-chrome/NativeMessagingHosts/gpgmejson.json << 'EOF'
{
  "name": "gpgmejson",
  "description": "Integration with GnuPG",
  "path": "/usr/bin/gpgme-json",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension://ckgehekhpgcaaikpadklkkjgdgoebdnh/"
  ]
}
EOF

# For Chromium
mkdir -p ~/.config/chromium/NativeMessagingHosts/
cat > ~/.config/chromium/NativeMessagingHosts/gpgmejson.json << 'EOF'
{
  "name": "gpgmejson",
  "description": "Integration with GnuPG",
  "path": "/usr/bin/gpgme-json",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension://ckgehekhpgcaaikpadklkkjgdgoebdnh/"
  ]
}
EOF

Firefox

Create the configuration file at ~/.mozilla/native-messaging-hosts/gpgmejson.json:

mkdir -p ~/.mozilla/native-messaging-hosts/
cat > ~/.mozilla/native-messaging-hosts/gpgmejson.json << 'EOF'
{
  "name": "gpgmejson",
  "description": "Integration with GnuPG",
  "path": "/usr/bin/gpgme-json",
  "type": "stdio",
  "allowed_extensions": ["localpgp@localpgp.org"]
}
EOF

Step 4: Verify Installation

After installing the extension and configuring native messaging:

1. Click on the LocalPGP extension icon in your browser toolbar
2. The popup should show “Connected” status with a green indicator
3. If you have GPG keys, they should be listed in the extension popup

If you see “Disconnected” or an error:

• Verify gpgme-json is installed: which gpgme-json
• Check the native messaging configuration file is in the correct location
• Ensure the file contains valid JSON with no syntax errors
• Restart your browser after making changes

Allowing Websites

Before a website can use LocalPGP for OpenPGP operations, you must explicitly allow it. This is a security feature to prevent unauthorized websites from accessing your keys.

Using the Extension Popup

1. Navigate to the website you want to allow (e.g., https://example.com)
2. Click on the LocalPGP extension icon in your browser toolbar
3. The popup will show the current site’s origin under “Current Site”
4. If the site is not allowed, you’ll see a status like “Not allowed”
5. Click the “Allow” button to grant the website access
6. The status will change to “Allowed” with a green indicator

Using the Extension Options Page

1. Right-click on the LocalPGP extension icon
2. Select “Options” (Chrome) or “Manage Extension” → “Preferences” (Firefox)
3. In the “Allowed Origins” section, you can:
   • See all currently allowed websites
   • Add new origins by entering the URL (e.g., https://example.com) and clicking “Add Origin”
   • Remove origins by clicking the “Remove” button next to them

Security Notes

• Only allow websites you trust
• The extension will only respond to requests from allowed origins
• You can revoke access at any time by removing the origin from the allowed list
• The extension never sends your private keys to websites - all cryptographic operations happen locally