Advanced Operations

From Enigmail Wiki
Jump to: navigation, search

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 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 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.7 or newer, then you don't need to do anything. However, if you've got GnuPG version 1.4.x, this is not sufficient any more. Please make sure that the gpg2 or gnupg2 package is installed. To verify that, open a command prompt and type

gpg2 –-version

If it tells you that you've also got GnuPG 2.0.7 or newer, then you are fine and don't have 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 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       ",,"

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       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: 1.9

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:
1: ask (default)

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

<pgpRule email='{}' keyId='0x1234ABCD' sign='1' encrypt='1' pgpMime='1'/>
<pgpRule email='{bob@ {user@domain' keyId='0xCDEF6789' sign='2' encrypt='1' pgpMime='0'/>
<pgpRule email='{} ' keyId='0x11111111 0x22222222 0x33333333' sign='2' encrypt='2' pgpMime='0'/>

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.