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.
Contents
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. The installer contains several packages, such as a GUI for key management, a plug-in for MS Outlook, and a mail client (Claws Mail) already integrated with the GnuPG plug-in.
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 easiest option is to use GnuPG for OSX. It provides prebuilt binaries of the latest stable version of GnuPG. Download the Package and install it. It installs those components that are 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 version 2.0.16 or newer, then you don't need to do anything. However, if you've got GnuPG version 1.4.x, this is no longer supported. Please make sure that the gpg2 or gnupg2 package is installed. To verify this, open a command prompt and type
gpg2 –-version
If it tells you that you've also got GnuPG 2.0.16 or newer, then you are fine and don't need to do anything.
If your system can't find the gpg2 command, then you need to install gpg2 or gnupg2 package using your packet manager software, e.g apt, yum, yast or their graphical counterparts. On many distributions the package is called "gnupg2" or "gpg2". The package managers also install the required prerequisites.
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 on Postbox by pressing Alt + Shift + B, and on Interlink via Edit → 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 defaultPrefs.js file.
If you want to edit any of these files by hand (via a text editor), remember to quit your mail client first, 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 Edit → Account settings → (your account) → OpenPGP security.
The identities settings can be accessed via Edit → 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 true
Whether to use Inline PGP or PGP/MIME as cryptographic method:
false: Inline PGP
true: PGP/MIME (default)
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: 2.1
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 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.
Versions of Enigmail prior to 1.8 used to include an option Add my own key to the recipients list. This option has since been removed from the GUI because there aren't many reasons to disable it.
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 containing its signature).
extensions.enigmail.logDirectory ""
Specifies the log directory. Default is empty (logging is turned off).
extensions.enigmail.keyCheckResult ""
Holds the result of the last key expiry check (see extensions.enigmail.warnKeyExpiryNumDays).
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.protectHeaders false
Protect sensitive headers of encrypted messages, such as the subject. The original header is moved into the encrypted message and replaced by a dummy value (such as "Encrypted Message"). This is part of the Memory Hole standard that is currently being developed.
extensions.enigmail.protectedSubjectText ""
Text to use as replacement for the subject, following the Memory Hole standard. If nothing is defined, then "Encrypted Message" is used.
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 your mail client 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 false
Enables Enigmail to use the gpgkeys_hkp, gpgkeys_ldap, and gpgkeys_http tools to retrieve keys from keyservers without using gpg itself.
extensions.enigmail.keyRefreshOn true
Enable or disable automatic key refreshing in Enigmail.
extensions.enigmail.warnClearPassphrase true
Has Enigmail pop up a confirmation message informing you that the passphrase has been cleared.
extensions.enigmail.warnKeyExpiryNumDays 30
Warns if a key used in one of the identities configured for Enigmail expires in less than N days. Setting the value to 0 disables the warning.
extensions.enigmail.warnGpgAgentAndIdleTime true
Warns if GPG-agent 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. This is e.g. 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='{This email address is being protected from spambots. You need JavaScript enabled to view it. }' keyId='0x1234ABCD' sign='1' encrypt='1' pgpMime='1'/>
<pgpRule email='{bob@ {user@domain' keyId='0xCDEF6789' sign='2' encrypt='1' pgpMime='0'/>
<pgpRule email='{This email address is being protected from spambots. You need JavaScript enabled to view it. } ' keyId='0x11111111 0x22222222 0x33333333' sign='2' encrypt='2' pgpMime='0'/>
...
</pgpRuleList>
Each <pgpRule .../> 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 defines the recipient address(es) to match. Multiple email addresses are separated by spaces. The matching is done on substrings, with curly brackets ({}) defining substring boundaries:
{user@domain} matches exactly and only user@domain
user@domain} matches anything that ends with user@domain
{user@domain matches anything that starts with user@domain
user@domain matches anything containing user@domain
keyId 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 (.) 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 specifies message signing, encrypt specifies message encryption, and pgpMime 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 the latest version of Enigmail:
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 gd Gaelic, Scottish gl-ES Galician hr Croatian 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 sq Albanian sv-SE Swedish tr Turkish vi Vietnamese zh-CN Chinese (China) zh-TW Chinese (Taiwan)
A note for testers: Enigmail nightly builds may be not fully localized. Untranslated items will appear in English.
Advanced users of Enigmail which are fluent in English and in another language are welcome to contribute to translations.