RT 4.4.0 Documentation
- FOR DEVELOPERS
RT::Crypt::GnuPG - GNU Privacy Guard encryption/decryption/verification/signing
This module provides support for encryption and signing of outgoing messages using GnuPG, as well as the decryption and verification of incoming email.
There are two reveant configuration options, both of which are hashes:
GnuPGOptions. The first one controls RT specific options; it enables you to enable/disable the GPG protocol or change the format of messages. The second one is a hash with options which are passed to the
gnupg utility. You can use it to define a keyserver, enable auto-retrieval of keys, or set almost any option which
gnupg supports on your system.
Set to true value to enable this subsystem:
Set( %GnuPG, Enable => 1, ... other options ... );
Format of outgoing messages
The format of outgoing messages can be controlled using the
OutgoingMessagesFormat option in the RT config:
Set( %GnuPG, ... other options ... OutgoingMessagesFormat => 'RFC', ... other options ... );
Set( %GnuPG, ... other options ... OutgoingMessagesFormat => 'Inline', ... other options ... );
The two formats for GPG mail are as follows:
This format, the default, is also known as GPG/MIME, and is described in RFC3156 and RFC1847. The technique described in these RFCs is well supported by many mail user agents (MUA); however, some older MUAs only support inline signatures and encryption.
This format doesn't take advantage of MIME, but some mail clients do not support GPG/MIME. In general, this format is discouraged because modern mail clients typically do not support it well.
Text parts are signed using clear-text signatures. For each attachment, the signature is attached separately as a file with a '.sig' extension added to the filename. Encryption of text parts is implemented using inline format, while other parts are replaced with attachments with the filename extension '.pgp'.
Passphrases for keys may be set by passing
Passphrase. It may be set to a scalar (to use for all keys), an anonymous function, or a hash (to look up by address). If the hash is used, the '' key is used as a default.
Use this hash to set additional options of the 'gnupg' program. The only options which are diallowed are options which alter the output format or attempt to run commands; thiss includes
Some GnuPG options take arguments, while others take none. (Such as
--use-agent). For options without specific value use
undef as hash value. To disable these options, you may comment them out or delete them from the hash:
Set(%GnuPGOptions, 'option-with-value' => 'value', 'enabled-option-without-value' => undef, # 'commented-option' => 'value or undef', );
NOTE that options may contain the '-' character and such options MUST be quoted, otherwise you will see the quite cryptic error
gpg: Invalid option "--0".
Common options include:
The GnuPG home directory where the keyrings are stored; by default it is set to /opt/rt4/var/data/gpg.
You can manage this data with the 'gpg' commandline utility using the GNUPGHOME environment variable or
--homediroption. Other utilities may be used as well.
In a standard installation, access to this directory should be granted to the web server user which is running RT's web interface; however, if you are running cronjobs or other utilities that access RT directly via API, and may generate encrypted/signed notifications, then the users you execute these scripts under must have access too.
Be aware that granting access to the directory to many users makes the keys less secure -- and some features, such as auto-import of keys, may not be available if directory permissions are too permissive. To enable these features and suppress warnings about permissions on the directory, add the
This option is required when the
RFCformat for outgoing messages is used. RT defaults to 'SHA1' by default, but you may wish to override it.
gnupng --versionwill list the algorithms supported by your
gnupginstallation under 'hash functions'; these generally include MD5, SHA1, RIPEMD160, and SHA256.
This option lets you use GPG Agent to cache the passphrase of secret keys. See http://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html for information about GPG Agent.
This option lets you set the passphrase of RT's key directly. This option is special in that it is not passed directly to GPG; rather, it is put into a file that GPG then reads (which is more secure). The downside is that anyone who has read access to your RT_SiteConfig.pm file can see the passphrase -- thus we recommend the --use-agent option whenever possible.
man gpgto get list of all options this program supports.
Using the web interface it's possible to enable signing and/or encrypting by default. As an administrative user of RT, open 'Admin' then 'Queues', and select a queue. On the page you can see information about the queue's keys at the bottom and two checkboxes to choose default actions.
As well, encryption is enabled for autoreplies and other notifications when an encypted message enters system via mailgate interface even if queue's option is disabled.
Encrypting to untrusted keys
Due to limitations of GnuPG, it's impossible to encrypt to an untrusted key, unless 'always trust' mode is enabled.
Documentation and references
Security Multiparts for MIME: Multipart/Signed and Multipart/Encrypted. Describes generic MIME security framework, "mulitpart/signed" and "multipart/encrypted" MIME types.
MIME Security with Pretty Good Privacy (PGP), updates RFC2015.