GnuPG

opt::rt3::lib::RT::CryUserGContributed Perl opt::rt3::lib::RT::Crypt::GnuPG(3)

NAME

RT::Crypt::GnuPG - encrypt/decrypt and sign/verify email messages with the GNU Privacy Guard (GPG)

DESCRIPTION

This module provides support for encryption and signing of outgoing messages, as well as the decryption and verification of incoming email.

CONFIGURATION

    You can control the configuration of this subsystem from RT's configuration file.  Some options are available via the web interface, but to enable this functionality, you MUST start in the configuration file.

    There are two hashes, GnuPG and GnuPGOptions in the configuration file. The first one controls RT specific options. It enables you to enable/disable facility or change the format of messages. The second one is a hash with
    options for the 'gnupg' utility. You can use it to define a keyserver, enable auto-retrieval keys and set almost any option '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::GnuPG' email filter to enable the handling of incoming encrypted/signed messages.

    Format of outgoing messages

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

    This framework implements two formats of signing and encrypting of email messages:

    RFC This format is also known as GPG/MIME and described in RFC3156 and RFC1847.  Technique described in these RFCs is well supported by many mail user agents (MUA), but some MUAs support only inline signatures and
        encryption, so it's possible to use inline format (see below).

    Inline
        This format doesn't take advantage of MIME, but some mail clients do not support GPG/MIME.

        We sign text parts using clear signatures. For each attachments another attachment with a signature is added with '.sig' extension.

        Encryption of text parts is implemented using inline format, other parts are replaced with attachments with the filename extension '.pgp'.

        This format is discouraged because modern mail clients typically don't support it well.

    Encrypting data in the database

    You can allow users to encrypt data in the database using option "AllowEncryptDataInDB". By default it's disabled.  Users must have rights to see and modify tickets to use this feature.

%GnuPGOptions
    Use this hash to set options of the 'gnupg' program. You can define almost any option you want which  gnupg supports, but never try to set options which change output format or gnupg's commands, such as --sign (command),
    --list-options (option) and other.

    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 option just 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 '-' character and such options MUST be quoted, otherwise you can see quite cryptic error 'gpg: Invalid option "--0"'.

    --homedir
        The GnuPG home directory, by default it is set to /opt/rt3/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, but if you're 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.

        However, granting access to the dir to many users makes your setup less secure, some features, such as auto-import of keys, may not be available if you do not.  To enable this features and suppress warnings about
        permissions on the dir use --no-permission-warning.

    --digest-algo
        This option is required in advance when RFC format for outgoing messages is used. We can not get default algorithm from gpg program so RT uses 'SHA1' by default. You may want to override it. You can use MD5, SHA1,
        RIPEMD160, SHA256 or other, however use 'gpg --version' command to get information about supported algorithms by your gpg. These algorithms are listed as hash-functions.

    --use-agent
        This option lets you use GPG Agent to cache the passphrase of RT's key. 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 isn't passed directly to GPG, but 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 instead.

    other
        Read 'man gpg' to get list of all options this program support.

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 'Configuration' 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::GnuPG' mail plugin.

        Set(@MailPlugins, 'Auth::MailFrom', 'Auth::GnuPG', ...other filter...);

    See also 'perldoc lib/RT/Interface/Email/Auth/GnuPG.pm'.

Errors handling
    There are several global templates created in the database by default. RT uses these templates to send error messages to users or RT's owner. These templates have 'Error:' or 'Error to RT owner:' prefix in the name. You
    can adjust the text of the messages using the web interface.

    Note that $TicketObj, $TransactionObj and other variable usually available in RT's templates are not available in these templates, but each template used for errors reporting has set of available data structures you can
    use to build better messages. See default templates and descriptions below.

    As well, you can disable particular notification by deleting content of a template. You can delete a template too, but in this case you'll see error messages in the logs when RT can not load template you've deleted.

    Problems with public keys

    Template 'Error: public key' is used to inform the user that RT has problems with his public key and won't be able to send him encrypted content. There are several reasons why RT can't use a key. However, the actual reason
    is not sent to the user, but sent to RT owner using 'Error to RT owner: public key'.

    The possible reasons: "Not Found", "Ambiguous specification", "Wrong key usage", "Key revoked", "Key expired", "No CRL known", "CRL too old", "Policy mismatch", "Not a secret key", "Key not trusted" or "No specific reason
    given".

    Due to limitations of GnuPG, it's impossible to encrypt to an untrusted key, unless 'always trust' mode is enabled.

    In the 'Error: public key' template there are a few additional variables available:

    $Message - user friendly error message
    $Reason - short reason as listed above
    $Recipient - recipient's identification
    $AddressObj - Email::Address object containing recipient's email address

    A message can have several invalid recipients, to avoid sending many emails to the RT owner the system sends one message to the owner, grouped by recipient. In the 'Error to RT owner: public key' template a @BadRecipients
    array is available where each element is a hash reference that describes one recipient using the same fields as described above. So it's something like:

        @BadRecipients = (
            { Message => '...', Reason => '...', Recipient => '...', ...},
            { Message => '...', Reason => '...', Recipient => '...', ...},
            ...
        )

    Private key doesn't exist

    Template 'Error: no private key' is used to inform the user that he sent an encrypted email, but we have no private key to decrypt it.

    In this template $Message object of MIME::Entity class available. It's the message RT received.

    Invalid data

    Template 'Error: bad GnuPG data' used to inform the user that a message he sent has invalid data and can not be handled.

    There are several reasons for this error, but most of them are data corruption or absence of expected information.

    In this template @Messages array is available and contains list of error messages.

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.

SignEncrypt Entity => MIME::Entity, [ Encrypt => 1, Sign => 1, ... ]
    Signs and/or encrypts an email message with GnuPG utility.

    Signing
        During signing you can pass "Signer" argument to set key we sign with this option overrides gnupg's "default-key" option. If "Signer" argument is not provided then address of a message sender is used.

        As well you can pass "Passphrase", but if value is undefined then "GetPassphrase" called to get it.

    Encrypting
        During encryption you can pass a "Recipients" array, otherwise "To", "Cc" and "Bcc" fields of the message are used to fetch the list.

    Returns a hash with the following keys:

    * exit_code * error * logger * status * message

VerifyDecrypt Entity => undef, [ Detach => 1, Passphrase => undef ]
GetPassphrase [ Address => undef ]
    Returns passphrase, called whenever it's required with Address as a named argument.

ParseStatus
    Takes a string containing output of gnupg status stream. Parses it and returns array of hashes. Each element of array is a hash ref and represents line or group of lines in the status message.

    All hashes have Operation, Status and Message elements.

    Operation
        Classification of operations gnupg performs. Now we have support for Sign, Encrypt, Decrypt, Verify, PassphraseCheck, RecipientsCheck and Data values.

    Status
        Informs about success. Value is 'DONE' on success, other values means that an operation failed, for example 'ERROR', 'BAD', 'MISSING' and may be other.

    Message
        User friendly message.

    This parser is based on information from GnuPG distribution, see also docs/design_docs/gnupg_details_on_output_formats in the RT distribution.

UseKeyForSigning
    Returns or sets identifier of the key that should be used for signing.

    Returns the current value when called without arguments.

    Sets new value when called with one argument and unsets if it's undef.

GetKeysForEncryption
    Takes identifier and returns keys suitable for encryption.

    Note that keys for which trust level is not set are also listed.

KEY
    Signs a small message with the key, to make sure the key exists and we have a useable passphrase. The first argument MUST be a key identifier of the signer: either email address, key id or finger print.

    Returns a true value if all went well.

Probe
    This routine returns true if RT's GnuPG support is configured and working properly (and false otherwise).

perl v5.8.8 2009-05-28opt::rt3::lib::RT::Crypt::GnuPG(3)