RT 4.2.12 Documentation
RT::Crypt::GnuPG
NAME
RT::Crypt::GnuPG - GNU Privacy Guard encryption/decryption/verification/signing
DESCRIPTION
This module provides support for encryption and signing of outgoing messages using GnuPG, as well as the decryption and verification of incoming email.
CONFIGURATION
There are two reveant configuration options, both of which are hashes: GnuPG
and 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.
%GnuPG
Enabling GnuPG
Set to true value to enable this subsystem:
Set( %GnuPG,
Enable => 1,
... other options ...
);
However, note that you must add the 'Auth::Crypt' email filter to enable the handling of incoming encrypted/signed messages.
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 ...
);
or
Set( %GnuPG,
... other options ...
OutgoingMessagesFormat => 'Inline',
... other options ...
);
The two formats for GPG mail are as follows:
- RFC
-
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.
- Inline
-
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
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.
%GnuPGOptions
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 --sign
, --list-options
, etc.
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:
- --homedir
-
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
--homedir
option. 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
--no-permission-warning
option toGnuPGOptions
. - --digest-algo
-
This option is required when the
RFC
format for outgoing messages is used. RT defaults to 'SHA1' by default, but you may wish to override it.gnupng --version
will list the algorithms supported by yourgnupg
installation under 'hash functions'; these generally include MD5, SHA1, RIPEMD160, and SHA256. - --use-agent
-
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.
- --passphrase
-
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.
- other
-
Read
man gpg
to get list of all options this program supports.
Per-queue options
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.
Handling incoming messages
To enable handling of encrypted and signed message in the RT you should add 'Auth::Crypt' mail plugin.
Set(@MailPlugins, 'Auth::MailFrom', 'Auth::Crypt', ...other filter...);
See also `perldoc lib/RT/Interface/Email/Auth/Crypt.pm`.
Encrypting to untrusted keys
Due to limitations of GnuPG, it's impossible to encrypt to an untrusted key, unless 'always trust' mode is enabled.
FOR DEVELOPERS
Documentation and references
- RFC1847
-
Security Multiparts for MIME: Multipart/Signed and Multipart/Encrypted. Describes generic MIME security framework, "mulitpart/signed" and "multipart/encrypted" MIME types.
- RFC3156
-
MIME Security with Pretty Good Privacy (PGP), updates RFC2015.