RT::Crypt - encrypt/decrypt and sign/verify subsystem for RT
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.
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.
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 to encrypt and sign outgoing email; this defaults to the first enabled protocol. You many specify it explicitly via:
Set( %Crypt,
...
Outgoing => 'GnuPG',
...
);
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.
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.
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 usign them.
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:
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 => '...', ...},
...
)
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.
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.
Returns the complete set of encryption protocols that RT implements; not all may be supported by this installation.
Returns the set of enabled and available encryption protocols.
Returns the configured outgoing encryption protocol; see "Crypt" in RT_Config.
Returns the list of encryption protocols that should be used for decryption and verification of incoming email; see "Crypt" in RT_Config.
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.
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
.
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".
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:
True if there was an error encrypting or signing.
An un-localized error message desribing the problem.
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".
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.
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.
Decrypts the content in the string reference in-place. All other arguments and return values are identical to "VerifyDecrypt".
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:
The classification of the process whose status is being reported upon. Valid values include Sign
, Encrypt
, Decrypt
, Verify
, PassphraseCheck
, RecipientsCheck
and Data
.
Whether the operation was successful; contains DONE
on success. Other possible values include ERROR
, BAD
, or MISSING
.
An un-localized user friendly message.
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.
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.
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.
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.
As per "GetKeyInfo", but the Type
is forced to public
.
As per "GetKeyInfo", but the Type
is forced to private
.
As per "GetKeysInfo", but only the first matching key is returned in the info
value of the result.
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:
The name of the protocol of this key
An RT::Date of the date the key was created; undef if unset.
An RT::Date of the date the key expires; undef if the key does not expire.
A fingerprint unique to this key
A formatted string representation of the key
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.