Skip to content

Mailvelope GnuPG integration

Thomas Oberndörfer edited this page Jun 13, 2019 · 1 revision

GnuPG integration ( Mailvelope >= 3.0 )

Mailvelope 3.0 added the option to directly use the native GnupGP backend. This page should serve as a knowledge collection for debugging if it does not work as expected.

Short description of the integration

Gpgme-json is an optional package of gpgme (GnuPG made Easy) which allows for direct communication with a browser's native Messaging protocol. For a successful integration, the native messaging application (gpgme-json) has to been known to the browser; also, the extension using that application has to be known to the nativeMessaging app.

For Windows, the browser integration is an (optional) part of Gpg4win (since 3.1.3). For linux-based distributions and macOS, packaging is still under development.

Installation

Windows

Gpgme-json is part of Gpg4win if the component 'browser integration' is checked on installation. The installation process will create and register the manifest files for Firefox and Chrome.

If the browser integration is not installed during Gpg4win installation, the browser registration files (gpgme-mozila.json/ gpgme-chrome.json) will not be present. A re-installation would be the most comfortable way to setup the browser integration.

macOS/ Linux

The gpgme-json binary needs to be installed on your machine, and your browser needs to be aware of it. gpgme-json is currently part of gpgme, which you may need to build yourself. A more comfortable packaging method is currently in development.

For the Extensions to successfully communicate with gpgme-json, a manifest file is needed for the browser. It contains the path to the native messaging app, and the permitted browser extension ids.

  • Chromium/Chrome: The typical manifest location is in a subdirectory NativeMessagingHosts the chromium config path: ~/.config/chromium/NativeMessagingHosts/gpgmejson.json The contents are similar to this:
{
  "name": "gpgmejson",
  "description": "Javascript binding for gnupg",
  "path": "/usr/bin/gpgme-json",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://kajibbejlbohfaggdiogboambcijhkke/"]
  }
  • Firefox: The typical manifest location is: ~/.mozilla/native-messaging-hosts/gpgmejson.json. The content is similar to this:
{
  "name": "gpgmejson",
  "description": "Javascript binding for gnupg",
  "path": "/usr/bin/gpgme-json",
  "type": "stdio",
   "allowed_extensions": ["jid1-AQqSMBYb0a8ADg@jetpack"]
}

The allowed extension/origin id should be the one identifying Mailvelope, the path should point to the gpgme-json binary.

Debugging

On installation, Mailvelope states 'GnuPG is not available', although it is installed.

There might be a timeout problem on first configuration. Try closing the browser after installation of Mailvelope, then reopening the browser the Mailvelope configuration again. The gnupg backend might just become available now.

To check if the integration works as expected, you should find a 'GnuPG keyring' in the Mailvelope key management tab, containing the keys known to your native gnupg backend.

[Windows] Is gpgme-json installed and properly configured?

If the browser integration is installed, the nativeMessaging app consists of three parts described below. If it is not integrated, the second and third parts are missing. Currently (as of Gpg4win 3.1.7) the browser integration is not checked by default (see the reasons described in the gnupg bug tracker )

  1. the binary gpgme-json.exe, (installed alongside gp4win, usually in a directory like (C: \Program Files(x86)\gpg4win\bin\). To test this binary, you can open it in a terminal (e.g. Windows PowerShell) in interactive debugging mode:
& 'C:\Propgram Files(x86)\Gpg4win\bin\gpgme-json.exe' -i

The simplest way to test is just one of these commands:

  • {"op": "version"} (followed by two returns) will give information on the backend used.
  • {"op": "keylist"} (followed by two returns) will get a simple key listing actually using the backend.
  • Please note, as it is a program not primarily intended for humans, commands are in json format (thus the double return, the curly brackets and the quotes). The interface can be exited with ctrl-C
  1. The second part is the registry entries so that browsers can find the native app. The path to the definitions are:
  • HKEY_LOCAL_MACHINE/SOFTWARE/Google/Chrome/NativeMessagingHosts/gpgmejson
  • HKEY_LOCAL_MACHINE/SOFTWARE/Mozilla/NativeMessagingHosts/gpgmejson If these entries are not given, or the file specified there is not to be found, the browser cannot use the native messaging app.
  1. the gpgme-chrome.json/gpgme-mozilla.json definition files. The location is specified in the regedit entries specified above. These short json files define the interface as viewed for the browser:
  • How the app is called, where it is, and which extensions are allowed to use it. Currently, it comes with the Mailvelope extension id only.
  • For debugging, this id could be checked if it matches the correct id.
You can’t perform that action at this time.