RT 5.0.6 Documentation

RT::Crypt

NAME
DESCRIPTION
CONFIGURATION
METHODS

NAME

RT::Crypt - encrypt/decrypt and sign/verify subsystem for RT

DESCRIPTION

This module provides support for encryption and signing of outgoing messages, as well as the decryption and verification of incoming emails using various encryption standards. Currently, GnuPG and SMIME protocols are supported.

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.

For each protocol there is a hash with the same name in the configuration file. This hash controls RT-specific options regarding the protocol. It allows you to enable/disable each facility or change the format of messages; for example, GnuPG uses the following config:

    Set( %GnuPG,
        Enable => 1,
        ... other options ...
    );

Enable is the only key that is generic for all protocols. A protocol may have additional options to fine-tune behaviour.

%Crypt

This config option hash chooses which protocols are decrypted and verified in incoming messages, which protocol is used for outgoing emails, and RT's behaviour on errors during decrypting and verification.

RT will provide sane defaults for all of these options. By default, all enabled encryption protocols are decrypted on incoming mail; if you wish to limit this to a subset, you may, via:

    Set( %Crypt,
        ...
        Incoming => ['SMIME'],
        ...
    );

RT can currently only use one protocol per queue to encrypt and sign outgoing email; this defaults to the first enabled protocol. You may specify it explicitly via:

    Set( %Crypt,
        ...
        Outgoing => 'GnuPG',
        ...
    );

which sets the protocol for all queues. Alternatively, you can use:

    Set( %Crypt,
        ...
        Outgoing => { Queue1 => 'GnuPG', Queue2 => 'SMIME', '' => 'GnuPG' },
        ...
    );

which sets the outgoing protocol for Queue1 to GnuPG, for Queue2 to SMIME, and for all other queues to GnuPG (the '' key.)

You can allow users to encrypt data in the database by setting the AllowEncryptDataInDB key to a true value; by default, this is disabled. Be aware that users must have rights to see and modify tickets to use this feature.

Per-queue options

Using the web interface, it is possible to enable signing and/or encrypting by default. As an administrative user of RT, navigate to the 'Admin' and 'Queues' menus, and select a queue. If at least one encryption protocol is enabled, information concerning available keys will be displayed, as well as options to enable signing and encryption.

Error 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 an 'Error:' or 'Error to RT owner:' prefix in the name. You can adjust the text of the messages using the web interface.

Note that while $TicketObj, $TransactionObj and other variables usually available in RT's templates are not available in these templates, but each is passed alternate data structures can be used to build better messages; see the default templates and descriptions below.

You can disable any particular notification by simply deleting the content of a template. Deleting the templates entirely is not suggested, as RT will log error messages when attempting to send mail using them.

Problems with public keys

The 'Error: public key' template is used to inform the user that RT had problems with their public key, and thus will not be able to send encrypted content. There are several reasons why RT might fail to use a key; by default, the actual reason is not sent to the user, but sent to the RT owner using the 'Error to RT owner: public key' template.

Possible reasons include "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".

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

As a message may 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:

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

Private key doesn't exist

The 'Error: no private key' template is used to inform the user that they sent an encrypted email to RT, but RT does not have the private key to decrypt it.

In this template MIME::Entity object $Message is available, which is the originally received message.

Invalid data

The 'Error: bad encrypted data' template is used to inform the user that a message they sent had invalid data, and could not be handled. There are several possible reasons for this error, but most of them are data corruption or absence of expected information.

In this template, the @Messages array is available, and will contain a list of error messages.

METHODS

Protocols

Returns the complete set of encryption protocols that RT implements; not all may be supported by this installation.

EnabledProtocols

Returns the set of enabled and available encryption protocols.

UseForOutgoing (Queue => QUEUE)

Returns the configured outgoing encryption protocol for the given queue; see "Crypt" in RT_Config. The Queue argument can be either a queue name or an RT::Queue object.

EnabledOnIncoming

Returns the list of encryption protocols that should be used for decryption and verification of incoming email; see "Crypt" in RT_Config.

LoadImplementation CLASS

Given the name of an encryption implementation (e.g. "GnuPG"), loads the RT::Crypt class associated with it; return the classname on success, and undef on failure.

SimpleImplementationCall Protocol => NAME, Queue => QUEUE, [...]

Examines the caller of this method, and dispatches to the method of the same name on the correct RT::Crypt::Role class based on the provided Protocol.

If Protocol is not supplied, then Queue will be used to figure out which outgoing protocol to use. Queue can be a queue name or an RT::Queue object.

FindProtectedParts Entity => MIME::Entity

Looks for encrypted or signed parts of the given Entity, using all "EnabledOnIncoming" encryption protocols. For each node in the MIME hierarchy, "CheckIfProtected" in RT::Crypt::Role for that MIME::Entity is called on each "EnabledOnIncoming" protocol. Any multipart nodes not claimed by those protocols are recursed into.

Finally, "FindScatteredParts" in RT::Crypt::Role is called on the top-most entity for each "EnabledOnIncoming" protocol.

Returns a list of hash references; each hash reference is guaranteed to contain a Protocol key describing the protocol of the found part, and a Type which is either encrypted or signed. The remaining keys are protocol-dependent; the hashref will be provided to "VerifyDecrypt".

SignEncrypt Entity => ENTITY, [Sign => 1], [Encrypt => 1], [Recipients => ARRAYREF], [Signer => NAME], [Protocol => NAME], [Passphrase => VALUE], [Queue => QUEUE]

Takes a MIME::Entity object, and signs and/or encrypts it using the given Protocol. If not set, Recipients for encryption will be set by examining the To, Cc, and Bcc headers of the MIME entity. If not set, Signer defaults to the From of the MIME entity.

Passphrase, if not provided, will be retrieved using "GetPassphrase" in RT::Crypt::Role.

Returns a hash with at least the following keys:

exit_code: True if there was an error encrypting or signing.
message: An un-localized error message describing the problem.

SignEncryptContent Content => STRINGREF, [Sign => 1], [Encrypt => 1], [Recipients => ARRAYREF], [Signer => NAME], [Protocol => NAME], [Passphrase => VALUE]

Signs and/or encrypts a string, which is passed by reference. Recipients defaults to /UseKeyForSigning, and Recipients defaults to the global "CorrespondAddress" in RT::Config. All other arguments and return values are identical to "SignEncrypt".

DrySign Queue => QUEUE, Signer => KEY

Signs a small message with the key, to make sure the key exists and we have a useable passphrase. The Signer 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.

VerifyDecrypt Entity => ENTITY [, Passphrase => undef ]

Locates all protected parts of the MIME::Entity object ENTITY, as found by "FindProtectedParts", and calls "VerifyDecrypt" in RT::Crypt::Role from the appropriate RT::Crypt::Role class on each.

Passphrase, if not provided, will be retrieved using "GetPassphrase" in RT::Crypt::Role.

Returns a list of the hash references returned from "VerifyDecrypt" in RT::Crypt::Role.

DecryptContent Protocol => NAME, Content => STRINGREF, [Passphrase => undef]

Decrypts the content in the string reference in-place. All other arguments and return values are identical to "VerifyDecrypt".

ParseStatus Protocol => NAME, Status => STRING

Takes a String describing the status of verification/decryption, usually as stored in a MIME header. Parses it and returns array of hash references, one for each operation. Each hashref contains at least three keys:

Operation: The classification of the process whose status is being reported upon. Valid values include Sign, Encrypt, Decrypt, Verify, PassphraseCheck, RecipientsCheck and Data.
Status: Whether the operation was successful; contains DONE on success. Other possible values include ERROR, BAD, or MISSING.
Message: An un-localized user friendly message.

UseKeyForSigning [KEY]

Returns or sets the identifier of the key that should be used for signing. Returns the current value when called without arguments; sets the new value when called with one argument and unsets if it's undef.

This cache is cleared at the end of every request.

UseKeyForEncryption [KEY [, VALUE]]

Gets or sets keys to use for encryption. When passed no arguments, clears the cache. When passed just a key, returns the encryption key previously stored for that key. When passed two (or more) keys, stores them associatively.

This cache is reset at the end of every request.

CheckRecipients Queue => QUEUE, Recipients => [ @RECIPIENTS ]

Check a list of recipients to make sure we have trustable public keys for all of them. Returns (1, ()) if everything is OK, or (0, @list_of_problem_messages) if there are errors.

GetKeysForEncryption Recipient => EMAIL, Protocol => NAME, Queue => QUEUE

Returns the list of keys which are suitable for encrypting mail to the given Recipient. Generally this is equivalent to "GetKeysInfo" with a Type of <private>, but encryption protocols may further limit which keys can be used for encryption, as opposed to signing.

GetKeysForSigning Signer => EMAIL, Protocol => NAME, Queue => QUEUE

Returns the list of keys which are suitable for signing mail from the given Signer. Generally this is equivalent to "GetKeysInfo" with a Type of <private>, but encryption protocols may further limit which keys can be used for signing, as opposed to encryption.

GetPublicKeyInfo Protocol => NAME, KEY => EMAIL

As per "GetKeyInfo", but the Type is forced to public.

GetPrivateKeyInfo Protocol => NAME, KEY => EMAIL

As per "GetKeyInfo", but the Type is forced to private.

GetKeyInfo Protocol => NAME, Type => ('public'|'private'), KEY => EMAIL

As per "GetKeysInfo", but only the first matching key is returned in the info value of the result.

GetKeysInfo Protocol => NAME, Queue => QUEUE, Type => ('public'|'private'), Key => EMAIL

Looks up information about the public or private keys (as determined by Type) for the email address Key. As each protocol has its own key store, Protocol is also required. If no Key is provided and a true value for Force is given, returns all keys.

The return value is a hash containing exit_code and message in the case of failure, or info, which is an array reference of key information. Each key is represented as a hash reference; the keys are protocol-dependent, but will at least contain:

Protocol: The name of the protocol of this key
Queue: An RT::Queue or queue name. This is to infer the protocol to use from Outgoing in "%Crypt" configuration, only needed if Protocol is not provided.
Created: An RT::Date of the date the key was created; undef if unset.
Expire: An RT::Date of the date the key expires; undef if the key does not expire.
Fingerprint: A fingerprint unique to this key
Formatted: A formatted string representation of the key
User: An array reference of associated user data, each of which is a hashref containing at least a String value, which is a Alice Example <alice@example.com> style email address. Each may also contain Created and Expire keys, which are RT::Date objects.

← Back to index