RT 5.0.3 Documentation
RT::Crypt
- NAME
- DESCRIPTION
- CONFIGURATION
- METHODS
- Protocols
- EnabledProtocols
- UseForOutgoing (Queue => QUEUE)
- EnabledOnIncoming
- LoadImplementation CLASS
- SimpleImplementationCall Protocol => NAME, Queue => QUEUE, [...]
- FindProtectedParts Entity => MIME::Entity
- SignEncrypt Entity => ENTITY, [Sign => 1], [Encrypt => 1], [Recipients => ARRAYREF], [Signer => NAME], [Protocol => NAME], [Passphrase => VALUE], [Queue => QUEUE]
- SignEncryptContent Content => STRINGREF, [Sign => 1], [Encrypt => 1], [Recipients => ARRAYREF], [Signer => NAME], [Protocol => NAME], [Passphrase => VALUE]
- DrySign Queue => QUEUE, Signer => KEY
- VerifyDecrypt Entity => ENTITY [, Passphrase => undef ]
- DecryptContent Protocol => NAME, Content => STRINGREF, [Passphrase => undef]
- ParseStatus Protocol => NAME, Status => STRING
- UseKeyForSigning [KEY]
- UseKeyForEncryption [KEY [, VALUE]]
- CheckRecipients Queue => QUEUE, Recipients => [ @RECIPIENTS ]
- GetKeysForEncryption Recipient => EMAIL, Protocol => NAME, Queue => QUEUE
- GetKeysForSigning Signer => EMAIL, Protocol => NAME, Queue => QUEUE
- GetPublicKeyInfo Protocol => NAME, KEY => EMAIL
- GetPrivateKeyInfo Protocol => NAME, KEY => EMAIL
- GetKeyInfo Protocol => NAME, Type => ('public'|'private'), KEY => EMAIL
- GetKeysInfo Protocol => NAME, Queue => QUEUE, Type => ('public'|'private'), Key => EMAIL
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 usign 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 desribing 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
andData
. - Status
-
Whether the operation was successful; contains
DONE
on success. Other possible values includeERROR
,BAD
, orMISSING
. - 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 aAlice Example <alice@example.com>
style email address. Each may also containCreated
andExpire
keys, which are RT::Date objects.