Mailvelope GnuPG integration

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

Short description of the integration

Mailvelope uses native messaging to connect to gpgme-json which is an optional package of gpgme (GnuPG made Easy).

For a successful integration, the following is required:

• Mailvelope (min. version 3.0) is installed in the browser
• GnuPG (min. version 2.2) is installed on the system
• gpgme (min. version 1.12.0) is installed
• app manifest file is installed

Permissions

Mailvelope requires the nativeMessaging permission in the browser:

• for Firefox this permission is requested during the installation of Mailvelope, no further action required.
• for Chrome this is an optional permission, go to the Mailvelope settings -> Options -> General -> OpenPGP -> "Do you prefer to use GnuPG?" -> "Allow us to check availability" and confirm the additional permission in the browser popup.

Installation of gpgme

Windows

Gpg4win (since version 3.1.3) has all required components for the integration with Mailvelope. Important: the option "browser integration" has to be checked during the installation setup. This process will also create and register the app manifest files for Firefox and Chrome.

If Gpg4win is already installed on the system without browser integration, then a re-installation with a current version of Gpg4win would be the most comfortable way to setup the browser integration.

macOS

gpgme needs to be build from the sources.

Follow the instructions at https://github.com/mailvelope/mailvelope/issues/699#issuecomment-572539370 if you have already GPGTools installed.

Alternatively, check out https://github.com/mailvelope/mailvelope/issues/699#issuecomment-572550390 if you would like to install gpg and its dependencies via Homebrew.

Manual installation of app manifest file is required, see next section.

Linux

Packaging for Linux based distributions is still under development.

You may need to build gpgme by yourself from: https://dev.gnupg.org/source/gpgme.git

Manual installation of app manifest file is required, see next section.

App manifest file

For the Mailvelope extension to successfully communicate with gpgme, an app manifest file is needed for the browser. It contains the path to the native messaging app gpgme-json, and the permitted browser extension IDs (in the examples below the standard extension ID of Mailvelope is used).

Chrome

Create a file gpgmejson.json with the following content. Adjust "path" to the location of your gpgme-json.

{
  "name": "gpgmejson",
  "description": "JavaScript binding for GnuPG",
  "path": "/usr/bin/gpgme-json",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://kajibbejlbohfaggdiogboambcijhkke/"]
}

For macOS store the file in: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/gpgmejson.json

For Linux: ~/.config/google-chrome/NativeMessagingHosts/gpgmejson.json

Firefox

Create a file gpgmejson.json with the following content. Adjust "path" to the location of your gpgme-json.

{
  "name": "gpgmejson",
  "description": "JavaScript binding for GnuPG",
  "path": "/usr/bin/gpgme-json",
  "type": "stdio",
  "allowed_extensions": ["jid1-AQqSMBYb0a8ADg@jetpack"]
}

For macOS store the file in: ~/Library/Application Support/Mozilla/NativeMessagingHosts/gpgmejson.json

For Linux: ~/.mozilla/native-messaging-hosts/gpgmejson.json

Settings

The preferred backend can be set in the Mailvelope App -> Options -> General

After successful installation the GnuPG keyring is available in the keyring selection

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

2. 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.

3. 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.