- 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