• NAME
• DESCRIPTION
• CONFIGURATION
  • %GnuPG
    • Enabling GnuPG
    • Setting the GnuPG Command
    • Format of outgoing messages
    • Passphrases
  • %GnuPGOptions
  • Per-queue options
  • Encrypting to untrusted keys
• FOR DEVELOPERS
  • Documentation and references

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 relevant 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 ...
    );

Setting the GnuPG Command

By default, RT looks for a command named gpg in your $PATH to run GnuPG. If the command has a different name or is outside the $PATH on your system, you can specify the full path of the GnuPG command using the GnuPG option:

    Set( %GnuPG,
        Enable => 1,
        GnuPG  => '/usr/local/bin/gpg2',
        ... 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 ...
    );

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 disallowed are options which alter the output format or attempt to run commands; this 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/rt5/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 to GnuPGOptions.

--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. gnupg --version will list the algorithms supported by your gnupg 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 auto-replies and other notifications when an encrypted 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.

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.

← Back to index