Google Chrome

Click on the icon below to go to the Chrome Web Store. Choose + Add to Chrome to install Mailvelope as an extension in your browser.

After installation, a lock icon is displayed in the main Google Chrome toolbar, to the right of the address bar, which goes to Mailvelope's main menu.

browser action menu

Browser action popup


Click on the icon below to download Mailvelope from Choose + Add to Firefox to install Mailvelope as an add-on in your browser.

Public-Key Cryptography

OpenPGP and therefore Mailvelope use public-key cryptography which means a key is split into two parts: public and private keys with different purposes:

  • Public key – Used to encrypt a message. Can and should be available to everybody.
  • Private key – Used to decrypt a message. Needs to be stored securely. Access is restricted by password.
This concept is illustrated on the page "How Gpg4win works". Gpg4win is another application based on OpenPGP and the same principles also apply to Mailvelope.

Key Exchange

In order to send encrypted emails to a peer, you must have the public key of the recipient. Therefore, before secure communication can happen between two people, they must exchange their public keys with each other. There are multiple ways that public keys can be distributed:

  • Sent via email to specific correspondence partners. See the section Key Export for how this can be done with Mailvelope
  • Publish the key on a website for everyone to access.
  • Upload a key to a keyserver.

Message Formats

Public and private keys, as well as encrypted messages in OpenPGP, are encoded in a certain text format that allows them to be exchanged or stored as text files.

For example, a public key would look like this:

Version: OpenPGP.js v.1.20121015


We see encoded data surrounded by lines that mark the beginning and end of this key.

Click on Mailvelope's lock icon in the browser extension toolbar to open the main menu. Choose Options to navigate to the key ring, which holds all your keys:

key ring

Key ring view

Key Generation

To use Mailvelope, at least one key pair (consisting of a public and private key) must be available. We can either generate a new key pair as explained in this section, or import an existing key pair as described below.

Click on Generate Key to open the key generation dialog:

key generation

Key generation dialog

Fill in all required information. After clicking Submit, the key generation process will start and the result can be viewed by navigating back to the key list with Display Keys

Key Import

Existing keys can be imported in the Import Key dialog:

key import

Key import dialog

Paste any keys in text format as shown above in the section Message Formats into the textarea. Again, check Display Keys after a successful import to view the result.

Key Export

Key export functionality is used to extract keys in text format. We can use this to publish public keys or to make a backup of a public-private-keypair in a secure place.

Key export is available in the Display Keys view. Select a key and press Export to view the dialog:

key export

Key export dialog

The following options are available:

  • Display public key – A popup appears with the public key. Possible options are Copy to Clipboard and Create file.
  • Send public key via email – This will try to open your email application and insert the public key as text into a new email. Limitations: will only work if the public key does not exceed a certain length.
  • Display private key – Same options as public key.
  • Display key pair – Same as above. Key pair is displayed in two separate key blocks. Preferred method to make a backup of complete key pair.

Mailvelope extends the user interface of webmail (e.g. Gmail, Yahoo® Mail etc.) with controls that allow for encryption and decryption of email.

Message Encryption

Encryption in External Editor

Starting with Mailvelope v0.6 the default behavior is to compose and encrypt messages in an external editor.

The compose button is displayed in all email compose areas of the webmail provider and will launch Mailvelope's external editor.

launch editor button

Compose button

Clicking on the compose button will open a new popup with a separate editor. This ensures that the email creation and encryption process is completely isolated from the webmail provider.

Mailvelope's external editor

Compose popup

The email can now be composed. Next, click on the encrypt button to display the encrypt dialog. Here you can choose the recipients, or more specifically the people that should be allowed to decrypt the message and Add them to the list. Their public keys must already be imported as described in Key Import.

encrypt dialog

Encrypt dialog

The following encodings are available:

  • HTML (default if available) – messages are extracted from the compose area in HTML. This preserves the rich text format of the email. Safe to use if the sender also uses Mailvelope or any other OpenPGP application that supports HTML.
  • Text – Message is encrypted as plain text.
Multiple recipients can be added to the Encrypt for section. All persons listed here will be able to decrypt the message. It can be useful to add here also yourself as it is then possible to decrypt and read the messages in your Sent folder.
Mailvelope tries to identify the recipient's email address. It will be preselected once the decrypt dialog opens.

Click on Ok to encrypt the email. The email text will be replaced with the encrypted message.

encrypted message

Encrypted message

The undo button will revert the content back to the unencrypted text and you can restart the process.

The final step is to copy the encrypted message back to the email provider. A click on Transfer will do this and close the external editor.

encrypted message transfer

Encrypted message copied back to webmail provider

Now the encrypted message can be sent as usual.

Warning: don't use the webmail provider's main window while the external editor is open. To transfer the encrypted message successfully, it's important that you don't navigate away from the compose view of your webmail provider.

Encryption in Webmail Editor

Mailvelope offers also a second mode where messages are encrypted directly in the webmail provider's page. See the Security section for instructions on activating this mode and details on what the security implications of this mode are.

encrypt dialog

Encrypt dialog

Message Decryption

Whenever Mailvelope detects an encrypted message in an email it marks it with an overlay:

decrypt message

Marked encrypted message

If you click inside this area the password dialog opens.

password dialog

Password dialog

Mailvelope tries to find the private key that is required to decrypt the message. If the correct key is found in the key ring then the corresponding User and Key ID are displayed.

After unlocking the key with the password the message is decrypted and directly shown in the marked area.

decrypted email

Decrypted email

At any time the overlay can be closed with x or reloaded by clicking on the locker icon in the browser extension toolbar and then Reload.

Mailvelope comes preconfigured to work with the following webmail services:

  • Gmail
  • GMX
  • Yahoo!® Mail

Using this general approach it can be configured to work with any webmail provider. This can be done in the Preferences section of the Options view.

watch list

Watch list

The watch list defines a set of websites that are enhanced with the functionality provided by Mailvelope.

Deactivate Mailvelope for a site

By default Mailvelope is active for all sites in the watch list. To deactivate a site click on Edit in the corresponding row and change the Active value. Confirm with Update.

Add Website to Watch List

Load the website you want to add to the watch list in a browser tab (the active tab). Click on the lock icon in the browser extension toolbar to open the main menu. Choose Add page. The browser will open a new tab with Mailvelope's Options page and will add the website to the watch list. Reload the website to activate Mailvelope.

By choosing Add page Mailvelope analyzes the website's frame structure and adds this information to the watch list. As the internal structure of the website might change in different scenarios, the following procedure is recommended when adding new websites:
  1. Open your webmail provider's website and log in
  2. Navigate to your inbox and open an email
  3. Choose Add page from Mailvelope's main menu
  4. A new tab opens and a new item is added to the watch list
  5. Switch back to the webmail site and compose a new email
  6. Again click on the lock icon and choose Add page
  7. Reload the tab with F5
Advanced: when expanding a row in the watch list we see the frames that will be scanned for encrypted emails and email compose areas. If we can identify irrelevant frames (e.g., from ads) we can set the Scan value to false and thereby minimize the scanning effort.
It is also possible to manually add websites and their frame structure to the watch list, however this is beyond the scope of this documentation.

Remove Website from Watch List

Load the website you want to remove from the watch list in a browser tab (the active tab). Click on the lock icon in the browser extension toolbar to open the main menu. Choose Remove page. The browser will open a new tab with Mailvelope's Options page and after confirmation will remove the web site from the watch list.

Alternative: directly remove entries in the watch list with Delete button.

Mailvelope offers end-to-end encryption which means it must ensure that at no time secret data can leave the browser of the user.

Mailvelope's user interface consists of a set of isolated elements floating on top of the webmail provider's UI elements. This tight integration improves usability, but also requires measures to prevent any data leakage.

The security goals for Mailvelope are as follows. All data must be safe even if:

  • A rogue sender is part of the communication
  • The webmail provider has malicious intent
  • The webmail provider was attacked or the user has a malicious tab opened

This attack scenario was thoroughly tested in a penetration test by Cure53 who also helped with the design of the security concepts used by Mailvelope v0.6

In this section we look at security from an end user perspective. Further information is also available in the security section of the FAQ. The relevant settings can be found in the following dialog.

security settings

Security settings

Security Token Concept

The security token consists of a three character code and a color that is known only to the user. It is generated randomly in the installation process of Mailvelope and can be changed in the above settings to a custom pattern.

All dialog windows of Mailvelope (password entry, mail compose editor, mail decrypt popup) will display the security token, thereby clearly identifying their origin. A spoofed dialog can be identified by a missing or wrong security token. Mailvelope cannot prevent certain manipulations but with this approach the user can always identify if something is wrong.

security token

Security token

Decryption Mode

Two different modes to display the encrypted messages are available:

Inline (on the page of the webmail provider)

This offers the best usability. The encrypted messages are displayed inside an isolated sandbox that is not accessible by the webmail provider.

The watermark shown in the background of the decrypted message has the same purpose as the security token concept: we can clearly identify that the displayed message is the one decrypted by Mailvelope.

decrypted message with watermark

Watermark behind decrypted message

For the watermark, the characters of the security token are used, displayed in light gray.

This variant is vulnerable to clickjacking attacks, which means that Mailvelope cannot guarantee that a click on a link in a decrypted message results in navigation to the page that was intended by the author of the message. For most users this should be an acceptable risk. If in doubt use the following popup mode, which is immune to such attacks.

Popup (in a separate dialog)

Decrypted messages are displayed in a separate modal popup.

Encryption Mode

Two different modes are available to compose a secure message:

In a separate editor window

The mail is composed in a separate popup window and only transferred in encrypted form back to the webmail provider's editor. In this variant the clear text of the message will never leave Mailvelope.

In the compose editor of the webmail provider

You compose your email in the editor of the webmail provider. That means before you encrypt the email, the provider potentially has access to what you type. This comes often as a feature with the auto-save drafts function: the incomplete (and unencrypted) mail is stored every few seconds on the server. This variant might make sense for your special use case, but be aware that this violates the concept of client-side encryption as the unencrypted message or parts of it can leave your browser.

Remember Password

Mailvelope can cache passwords for private keys in local memory. You can activate the cache in the security settings or with the password dialog. Passwords have a lifetime which can be adjusted in the settings and are always deleted when you close the browser window.

  • Mailvelope currently does not support encrypting attachments.