Advanced Operations

In this part of the documentation we'll provide some additional details about the inner workings and advanced customization of Enigmail. You do not need to read it, especially if you aren't an experienced user.

Manual installation of GnuPG
You only need to read this part if you did not let the Setup Wizard install GnuPG for you on your computer or you must do it for other reasons.

Installing GnuPG on Microsoft Windows
Most people prefer to use Gpg4win, a sibling project to GnuPG.

There are several types of downloads:
 * The normal (full) installer, providing a GUI for key management, encryption, and decryption. The Gpg4win installer also contains additional optional components such as a plug-in for MS Outlook, and a mail client (Claws Mail) already integrated with the GnuPG plug-in.
 * The "light" installer, without Keymanager and documentation.
 * The "vanilla" installer, containing only the GnuPG components.

You don't need to modify anything in the configuration of GnuPG; the default settings will work fine.

Learning how to use the command-line GnuPG is not required; once installed, all operations will be achieved via Enigmail.

Installing GnuPG on Mac OS X
You have three basic ways to install GnuPG on OS X. Most users will choose the first option.

The first and most popular option is to use the MacGPG package. It provides prebuilt binaries of GnuPG 2.0.22 and later for users running OS X 10.6 (Snow Leopard) or later. Download the GPG Suite and install it. If you don't want to use the other components (Certificate Manager, Apple-Mail plugin and Services application) you can deselect them during the installation process. Only the MacGPG component is required for Enigmail.

The next two options are only for those familiar with building software from source. They require the Xcode development software from Apple.

One of these sources is the Homebrew project which has grown popular during the last years. Open up Terminal.app and type sudo brew install gnupg2 sudo brew install pinentry-mac

The other source is the MacPorts project which keeps a current version of GnuPG in their source tree. If you're using MacPorts, open up Terminal.app and type sudo port install gnupg2 sudo port install pinentry-mac

Installing GnuPG on Linux / UNIX
The best thing is to get a precompiled version of GnuPG for your UNIX system using the package manager of your platform. Compiling GnuPG from source is not recommended for beginners.

Most Linux distributions today include GnuPG by default. To find out if this is the case, open a command prompt and type

gpg –-version

If it tells you that you've got GnuPG 1.4.9 or some later version, then you don't need to do anything.

You are encouraged to additionally install the GnuPG 2.0 package using your packet manager software, e.g. apt, yum, or yast. On many distributions the package is called "gnupg2" or "gpg2".

The various flavours of BSD UNIX have a common way of installing software. Please see the instructions for MacPorts above.

Manually editing the preferences
Manual editing of preferences is intended for advanced users only.

Enigmail preferences are stored together with Mozilla global preferences inside the user.js and prefs.js files in your profile directory. Mozilla first reads the preferences in user.js, if this file exists, and copies them into prefs.js. You can create the file user.js in order to keep your custom preferences that you do not wish to be ever changed; this file, unlike prefs.js, won't be modified by Mozilla.

The preferences are accessible in Thunderbird under Tools → Preferences → Advanced → General → Config Editor. From there you can change the preferences values, which will then be written in prefs.js under the format user_pref("preference_name",value);

You can review the default preferences settings in the enigmail.js file.

If you want to edit any of these files by hand (via a text editor), remember to quit Thunderbird beforehand, and make sure you have a backup. Editing these files may result in misbehaviour and data loss if a syntax error is introduced.

In the following sections we'll provide a reference to the various Enigmail preferences. First is printed the preference name and its default value. Then follows its meaning. If the preference can also be changed via GUI, we provide the relevant command to do so.

The first section lists all general preferences, and the second section lists the identity/account settings.

General preferences
 extensions.enigmail.advancedUser      false 

Shows the advanced settings.

Enigmail → Preferences → Display/Hide Expert Settings

 extensions.enigmail.agentPath      "" 

The path to (and including) the GnuPG executable. If it is already in the PATH, this setting can be left blank. Note: This is not the path to GPG-agent.

Enigmail → Preferences → Basic → GnuPG executable path

 extensions.enigmail.agentAdditionalParam      "" 

Additional parameters passed to the GnuPG executable. Default value is empty.

Enigmail → Preferences → Advanced → Additional parameters for GnuPG

 extensions.enigmail.acceptedKeys      1 

Which keys to accept for sending. 0: accept valid/authenticated keys 1: accept all keys except disabled or expired keys (default)

Enigmail → Preferences → Sending → Manual encryption settings → To send encrypted, accept

 extensions.enigmail.assignKeysByRules      true 

Use Per-Recipient Rules to select keys.

Enigmail → Preferences → Key Selection → By Per-Recipient Rules

 extensions.enigmail.assignKeysByEmailAddr      true 

Use email address to select keys.

Enigmail → Preferences → Key Selection → By Email Addresses according to the key manager

 extensions.enigmail.assignKeysManuallyIfMissing      true 

Select keys manually if missing.

Enigmail → Preferences → Key Selection → Manually if keys are missing

 extensions.enigmail.assignKeysManuallyAlways      false 

Always select keys manually. May be used in combination with other selections.

Enigmail → Preferences → Key Selection → Always (also) Manually

 extensions.enigmail.autoDecrypt      true 

Automatically decrypt/verify received messages.

Enigmail → Automatically Decrypt/Verify Messages

 extensions.enigmail.autoKeyRetrieve       "" 

Name of the keyserver from which automatically retrieve keys if missing (e.g. during signature verification). Default is empty string (no keyserver specified).

Enigmail → Preferences → Keyserver → Automatically download keys for signature verification from the following keyserver

 extensions.enigmail.autoSendEncrypted       1 

Automatically send encrypted if all keys are valid. 0: never 1: if possible (all keys are found and accepted)

Enigmail → Preferences → Manual encryption settings → Automatically send encrypted

 extensions.enigmail.confirmBeforeSending       0 

Pop up a confirmation dialog before sending a message. 0: never (default) 1: always 2: if sent encrypted 3: if sent unencrypted 4: if per-recipient rules changed the default encryption setting

Enigmail → Preferences → Sending → Manual encryption settings → Confirm before sending

 extensions.enigmail.doubleDashSeparator       true 

Handle the double dash (--) as a signature separator.

Enigmail → Preferences → Advanced → '--' is a signature separator

 extensions.enigmail.encryptionModel      0 

Controls how Enigmail will select the settings for messages to be encrypted. Available values are: 0: convenient encryption settings (default) 1: manual encryption settings

Enigmail → Preferences → Sending → Convenient encryption settings / Manual encryption settings

 extensions.enigmail.hushMailSupport       false 

Enable support for Hushmail.

Enigmail → Preferences → Advanced → Use '<' and '>' to specify email addresses

 extensions.enigmail.keepSettingsForReply      true 

Encrypt replies to encrypted messages.

Enigmail → Preferences → Sending → Encrypt replies to encrypted message

 extensions.enigmail.keyManShowAllKeys       true 

If set to true (default), all keys are displayed. If set to false, the Key Management window shows only those keys that match the search terms entered in the field Search for.

Enigmail → Key Management → Display All Keys by Default

 extensions.enigmail.keyserver       "pool.sks-keyservers.net, keys.gnupg.net, pgp.mit.edu" 

The list of keyservers to use.

Enigmail → Preferences → Keyserver → Specify your keyserver(s)

 extensions.enigmail.maxIdleMinutes       5 

Cache the passphrase for the specified time. Default is 5 minutes.

Enigmail → Preferences → Remember passphrase for [ ] minutes of idle time

 extensions.enigmail.noPassphrase       false 

Tell Enigmail to never ask for a passphrase. Note: This option will not be shown if you use GnuPG version 2.x.

Enigmail → Preferences → Basic → Never ask for any passphrase

 extensions.enigmail.useDefaultComment      true 

If set to false, adds an Enigmail comment in OpenPGP signature.

Enigmail → Preferences → Advanced → Add Enigmail comment in OpenPGP signature

 extensions.enigmail.useGpgAgent      false 

Use GPG-agent to handle passphrases. Note: if GnuPG v2.x is used, then the use of GPG-agent is mandatory and the option is therefore not shown.

Enigmail → Preferences → Advanced → Use gpg-agent for passphrases

 extensions.enigmail.wrapHtmlBeforeSend       true 

Re-wrap HTML text in signed messages before sending. Default is on.

Enigmail → Preferences → Advanced → Re-wrap signed HTML text before sending

Identity/Account Settings
These settings are per-account and per-identity. You can have multiple identities per account and you should take care to configure all of those you want to use with Enigmail, especially if you added them after running the Enigmail Setup Wizard.

The account settings can be accessed via Tools → Account settings → (your account) → OpenPGP security. The identities settings can be accessed via Tools → Account settings → (your account) → Manage identities → (your identity) → Edit → OpenPGP Security.

 mail.identity.default.autoEncryptDrafts       true 

Encrypt draft messages on saving.

Encrypt draft messages on saving

 mail.identity.default.attachPgpKey      false 

Attach your own public key to all outgoing messages.

Advanced → Attach my public key to messages

 mail.identity.default.defaultSigningPolicy      0 

Sign messages by default: 0: Off (default) nonzero: On

Sign messages by default

 mail.identity.default.defaultEncryptionPolicy      0 

Encrypt messages by default: 0: Off (default) nonzero: On

Encrypt messages by default

 mail.identity.default.openPgpHeaderMode      0 

This option controls whether to add a PGP header to outgoing mail, and what to put in it. 0: Off (default) 0x1: Send Key ID as set in the mail.identity.default.pgpkeyId preference, see below 0x10: Send URL for key retrieval as set in the mail.identity.default.openPgpUrlName preference, see below 0x11: Send both

Advanced → Send OpenPGP Key ID and Advanced → Send URL for key retrieval

 mail.identity.default.openPgpUrlName      "" 

Add an URL, from which to retrieve the public key, in the PGP header. Empty string by default.

Advanced → Send URL for key retrieval

 mail.identity.default.pgpkeyId      "" 

Add the public key ID in the PGP header. Empty string by default.

Advanced → Use specific OpenPGP key ID

 mail.identity.default.pgpKeyMode      0 

How to choose the Key ID for this account: 0: Get Key ID from email address (default) nonzero: Use Key ID from pgpkeyId preference (recommended)

Radio buttons Use specific OpenPGP key ID or Use email address of this identity to identify OpenPGP key

 mail.identity.default.pgpMimeMode	     false 

Whether to use Inline PGP or PGP/MIME as cryptographic method: false: Inline PGP (default) true: PGP/MIME

Use PGP/MIME by default

 mail.identity.default.pgpSignPlain     	false 

Sign non-encrypted messages. Off by default.

Sign non-encrypted messages

 mail.identity.default.pgpSignEncrypted      false 

Sign encrypted messages. Off by default.

Sign encrypted messages

JavaScript preferences
The following preferences are set in the prefs.js or user.js files.

 extensions.enigmail.addHeaders      false 

Adds custom X-Enigmail mail headers to all outgoing messages. These headers are not currently used for any function, but may be used by Enigmail in the future. Currently the added header is: X-Enigmail-Version: 1.8

 extensions.enigmail.composeHtmlAlertCount      3 

Sets the number of times a warning message is shown when composing in HTML and attempting to send a signed message using inline PGP.

 extensions.enigmail.configuredVersion      "" 

The last configured Enigmail version. This setting should not be changed.

 extensions.enigmail.displayPartiallySigned     	true 

Handles the display of the Enigmail status bar [[media:4-19.png|if only part of the message is signed]], which may happen for instance when a person replies quoting a signed message. If set to false, PGP headers that appear within the message body will be ignored and displayed literally. This does not apply for the PGP headers at the beginning and the end of the message body, which are present there when the message is normally signed in full; in this case, the Enigmail status bar will appear. If set to true (default), Enigmail removes even the quote prefix character ( > ) from signed text embedded in the rest of the body if the message itself as a whole is not signed. This only works if the embedded quote has not been modified at all.

 extensions.enigmail.displaySecondaryUid      true 

Forces Enigmail to search your keyring for secondary IDs in order to match the sender address of a received message, and displays it instead of the default key ID.

 extensions.enigmail.displaySignWarn      true 

Warns you when you change the signing status by clicking on the sign icon in the bottom right corner of the message composition window.

 extensions.enigmail.encryptAttachments      1 

This setting stores the value of the last encryption method used to send a message with attachment.

 extensions.enigmail.encryptAttachmentsSkipDlg      0 

Controls whether to skip the attachment dialog, where the user is asked how attachments should be encrypted/signed.

 extensions.enigmail.encryptToNews      false 

If set to false (default), won't allow user to send an encrypted message to a newsgroup.

 extensions.enigmail.encryptToSelf      true 

Automatically encrypts outgoing messages with your public key too. This is necessary if you want to be able to read messages you sent. Default is true.

 extensions.enigmail.handleDoubleClick      true 

Normally, to decrypt and open an encrypted attachment you right-click on it and select Decrypt and Open from the pop-up menu. This option enables automatic decryption and opening if you double-click on the attachment.

 extensions.enigmail.initAlert      true 

Displays a warning if Enigmail fails to initialize.

 extensions.enigmail.inlineAttachAsciiArmor     	false 

Encrypts attachments in ASCII-armored format when sending inline PGP encrypted messages.

 extensions.enigmail.inlineAttachExt      ".pgp" 

Sets the extension to be appended when creating attachments to Inline PGP encrypted messages. Default is .pgp (i.e. a file filename.ext will be renamed to filename.ext.pgp when encrypted).

 extensions.enigmail.inlineSigAttachExt      ".sig" 

Sets the extension to be appended when creating attachments to Inline PGP signed messages. Default is .sig (i.e. a file filename.ext will be accompanied by an additional file named filename.ext.sig</tt> containing its signature).

 extensions.enigmail.logDirectory      "" 

Specifies the log directory. Default is empty (logging is turned off).

 extensions.enigmail.mimeHashAlgorithm      0 

Specifies the hash algorithm used by GnuPG for its cryptographic operations: 0: automatic selection, let GnuPG choose (default, recommended) 1: SHA1 2: RIPEMD160 3: SHA256 4: SHA384 5: SHA512

 extensions.enigmail.mimePreferPgp	     1 

Specifies whether to use S/MIME or PGP/MIME. Due to technical reasons it is not possible to use both PGP/MIME and S/MIME in a message. This option decides which standard is chosen if both are activated (after Per-Recipient rules are processed). Available values are: 0: PGP/MIME 1: ask (default) 2: S/MIME

 extensions.enigmail.parseAllHeaders      true 

Tells Enigmail to parse all MIME headers in the message. This value is for testing purposes only, and must be left enabled.

 extensions.enigmail.quotedPrintableWarn      0 

Issues a warning when Enigmail detects that a message going to be sent contains 8-bit characters and will use Quoted Printable encoding. Default is off. This setting remembers the selected state.

 extensions.enigmail.respectHttpProxy      true 

If set, use the same HTTP proxy settings that were defined in Thunderbird to retrieve keys from keyservers.

 extensions.enigmail.supportMultiPass      false 

Support for multiple passphrase on the same key pair. Reserved for future use; do not change this setting.

 extensions.enigmail.useGpgKeysTool     	true 

Enables Enigmail to use the gpgkeys_hkp, gpgkeys_ldap, and gpgkeys_http tools to retrieve keys from keyservers without using gpg itself.

 extensions.enigmail.warnClearPassphrase      true 

Has Enigmail pop up a confirmation message informing you that the passphrase has been cleared.

 extensions.enigmail.warnGpgAgentAndIdleTime      true 

Warns if GPG-agent should be used, but cannot be found and the option to remember the passphrase for X minutes is active (and remember selected state). The warning is shown if Enigmail cannot connect to GPG-agent although it must be used (using GnuPG 2.0 and later). This is the case when your system uses a specialized tool for passphrase handling such as gnome-keyring or seahorse-agent. Unfortunately Enigmail cannot control the passphrase timeout for those tools. Therefore the passphrase timeout settings in Enigmail are disregarded.

 extensions.enigmail.warnOnRulesConflict      0 

Issues a warning when sending a message to multiple addresses with conflicting Per-Recipient Rules. Default is 0 (off). This setting remembers the selected state.

 extensions.enigmail.warnOnSendingNewsgroups      true 

Issues a warning when trying to send an encrypted message to a newsgroup.

 extensions.enigmail.warnRefreshAll     	true 

Enables a warning about lengthy download when all keys are to be refreshed (which can be a lengthy process, depending on network speed and number of contacts). This setting remembers the selected state.

 extensions.enigmail.warnDownloadContactKeys      true 

Enables a warning about lengthy download when getting keys for all contacts (which can be a lengthy process, depending on network speed and number of contacts). This setting remembers the selected state.

XML format of Per-Recipient Rules
Here we'll detail the format of pgprules.xml, which is an XML file generated by Enigmail and contains the Per-Recipient Rules. This is intended as a technical reference for developers only; normal users should never edit the XML file manually.

The pgprules.xml file has the following structure:

<pgpRuleList> <pgpRule email='{alice@example.com}' keyId='0x1234ABCD' sign='1' encrypt='1' pgpMime='1'/> <pgpRule email='{bob@ {user@domain' keyId='0xCDEF6789' sign='2' encrypt='1' pgpMime='0'/> <pgpRule email='{mailinglist@domain.org} ' keyId='0x11111111 0x22222222 0x33333333' sign='2' encrypt='2' pgpMime='0'/> ... </pgpRuleList>

Each <pgpRule .../></tt> line is a per-recipient rule stating how Enigmail should enable or disable encryption, signing, and PGP/MIME, and which key to use. The file is processed sequentially; if a rule contains a Key ID attribute with some value, the rule is applied, but the address that matched will not be rechecked in any following rule. The attributes are defined as follows.

email</tt> defines the recipient address(es) to match. Multiple email addresses are separated by spaces. The matching is done on substrings, with curly brackets ({}</tt>) defining substring boundaries: {user@domain}</tt> matches exactly and only user@domain user@domain}</tt> matches anything that ends with user@domain {user@domain</tt> matches anything that starts with user@domain user@domain</tt> matches anything containing user@domain

keyId</tt> is the list of key IDs to use for the recipient. The key ID is specified in the 8-byte format (e.g. 0x1234ABCD) or in the 16-byte format (e.g. 0x1234567890ABCDEF). Multiple keys are separated by spaces. If a dot (.</tt>) is the only value in the field, Enigmail does not use a specific key ID and finds the correct key using the email address. Any further rule for this recipient will be ignored.

sign</tt> specifies message signing, encrypt</tt> specifies message encryption, and pgpMime</tt> specifies PGP/MIME use. All these attributes must have one of the following values: 0 – Disables the action even if it was enabled in the Message Composition window. This is equivalent to the Never option in the GUI. 1 – Uses the setting specified in the Message Composition window. This is equivalent to the Yes, if selected in Message Composition option in the GUI. 2 – Enables the action even if it was not enabled in the Message Composition window. This is equivalent to the Always option in the GUI.

When a message is sent to multiple recipients, and multiple rules are applied, the value 0 overrides the value 2: if one of the rules disables the action, the action will not be applied for the message, regardless of any other rule with value 2.

Available languages
Enigmail is translated in many languages. The following locales are already included in Enigmail 1.8:

ar		Arabic bg-BG		Bulgarian ca		Catalan cs		Czech de		German el		Greek en-US		English (USA) es-ES		Spanish fi-FI		Finnish fr-FR		French gl-ES		Galician hu-HU		Hungarian it-IT		Italian ja-JP		Japanese ko-KR		Korean lt-LT		Lithuanian nb-NO		Norwegian nl		Dutch pl-PL		Polish pt-BR		Portuguese (Brazil) pt-PT		Portuguese (Portugal) ru-RU		Russian sk-SK		Slovak sl-SI		Slovenian sv-SE		Swedish tr		Turkish vi		Vietnamese zh-CN		Chinese

A note for testers: Enigmail nightly builds may be not fully localized. Untranslated items appear in English.

Advanced users of Enigmail, fluent in English and in another language are welcome to contribute to translations.