/usr/share/doc/rt4-doc-html/RT/Crypt.html is in rt4-doc-html 4.4.2-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 | <ul id="index">
<li><a href="#NAME">NAME</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#CONFIGURATION">CONFIGURATION</a>
<ul>
<li><a href="#Crypt">%Crypt</a></li>
<li><a href="#Per-queue-options">Per-queue options</a></li>
<li><a href="#Error-handling">Error handling</a>
<ul>
<li><a href="#Problems-with-public-keys">Problems with public keys</a></li>
<li><a href="#Private-key-doesnt-exist">Private key doesn't exist</a></li>
<li><a href="#Invalid-data">Invalid data</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#METHODS">METHODS</a>
<ul>
<li><a href="#Protocols">Protocols</a></li>
<li><a href="#EnabledProtocols">EnabledProtocols</a></li>
<li><a href="#UseForOutgoing">UseForOutgoing</a></li>
<li><a href="#EnabledOnIncoming">EnabledOnIncoming</a></li>
<li><a href="#LoadImplementation-CLASS">LoadImplementation CLASS</a></li>
<li><a href="#SimpleImplementationCall-Protocol-NAME">SimpleImplementationCall Protocol => NAME, [...]</a></li>
<li><a href="#FindProtectedParts-Entity-MIME::Entity">FindProtectedParts Entity => MIME::Entity</a></li>
<li><a href="#SignEncrypt-Entity-ENTITY-Sign-1-Encrypt-1-Recipients-ARRAYREF-Signer-NAME-Protocol-NAME-Passphrase-VALUE">SignEncrypt Entity => ENTITY, [Sign => 1], [Encrypt => 1], [Recipients => ARRAYREF], [Signer => NAME], [Protocol => NAME], [Passphrase => VALUE]</a></li>
<li><a href="#SignEncryptContent-Content-STRINGREF-Sign-1-Encrypt-1-Recipients-ARRAYREF-Signer-NAME-Protocol-NAME-Passphrase-VALUE">SignEncryptContent Content => STRINGREF, [Sign => 1], [Encrypt => 1], [Recipients => ARRAYREF], [Signer => NAME], [Protocol => NAME], [Passphrase => VALUE]</a></li>
<li><a href="#DrySign-Signer-KEY">DrySign Signer => KEY</a></li>
<li><a href="#VerifyDecrypt-Entity-ENTITY-Passphrase-undef">VerifyDecrypt Entity => ENTITY [, Passphrase => undef ]</a></li>
<li><a href="#DecryptContent-Protocol-NAME-Content-STRINGREF-Passphrase-undef">DecryptContent Protocol => NAME, Content => STRINGREF, [Passphrase => undef]</a></li>
<li><a href="#ParseStatus-Protocol-NAME-Status-STRING">ParseStatus Protocol => NAME, Status => STRING</a></li>
<li><a href="#UseKeyForSigning-KEY">UseKeyForSigning [KEY]</a></li>
<li><a href="#UseKeyForEncryption-KEY-VALUE">UseKeyForEncryption [KEY [, VALUE]]</a></li>
<li><a href="#GetKeysForEncryption-Recipient-EMAIL-Protocol-NAME">GetKeysForEncryption Recipient => EMAIL, Protocol => NAME</a></li>
<li><a href="#GetKeysForSigning-Signer-EMAIL-Protocol-NAME">GetKeysForSigning Signer => EMAIL, Protocol => NAME</a></li>
<li><a href="#GetPublicKeyInfo-Protocol-NAME-KEY-EMAIL">GetPublicKeyInfo Protocol => NAME, KEY => EMAIL</a></li>
<li><a href="#GetPrivateKeyInfo-Protocol-NAME-KEY-EMAIL">GetPrivateKeyInfo Protocol => NAME, KEY => EMAIL</a></li>
<li><a href="#GetKeyInfo-Protocol-NAME-Type-public-private-KEY-EMAIL">GetKeyInfo Protocol => NAME, Type => ('public'|'private'), KEY => EMAIL</a></li>
<li><a href="#GetKeysInfo-Protocol-NAME-Type-public-private-Key-EMAIL">GetKeysInfo Protocol => NAME, Type => ('public'|'private'), Key => EMAIL</a></li>
</ul>
</li>
</ul>
<h1 id="NAME"><a href="#___top">NAME</a></h1>
<p>RT::Crypt - encrypt/decrypt and sign/verify subsystem for RT</p>
<h1 id="DESCRIPTION"><a href="#___top">DESCRIPTION</a></h1>
<p>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, <a href="../../../rt/latest/RT/Crypt/GnuPG.html">GnuPG</a> and <a href="../../../rt/latest/RT/Crypt/SMIME.html">SMIME</a> protocols are supported.</p>
<h1 id="CONFIGURATION"><a href="#___top">CONFIGURATION</a></h1>
<p>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.</p>
<p>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:</p>
<pre><code> Set( %GnuPG,
Enable => 1,
... other options ...
);</code></pre>
<p><code>Enable</code> is the only key that is generic for all protocols. A protocol may have additional options to fine-tune behaviour.</p>
<h2 id="Crypt"><a href="#___top">%Crypt</a></h2>
<p>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.</p>
<p>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:</p>
<pre><code> Set( %Crypt,
...
Incoming => ['SMIME'],
...
);</code></pre>
<p>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:</p>
<pre><code> Set( %Crypt,
...
Outgoing => 'GnuPG',
...
);</code></pre>
<p>You can allow users to encrypt data in the database by setting the <code>AllowEncryptDataInDB</code> 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.</p>
<h2 id="Per-queue-options"><a href="#___top">Per-queue options</a></h2>
<p>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.</p>
<h2 id="Error-handling"><a href="#___top">Error handling</a></h2>
<p>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.</p>
<p>Note that while <code>$TicketObj</code>, <code>$TransactionObj</code> 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.</p>
<p>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.</p>
<h3 id="Problems-with-public-keys"><a href="#___top">Problems with public keys</a></h3>
<p>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.</p>
<p>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".</p>
<p>In the 'Error: public key' template there are a few additional variables available:</p>
<dl>
<dt id="Message---user-friendly-error-message">$Message - user friendly error message</dt>
<dd>
</dd>
<dt id="Reason---short-reason-as-listed-above">$Reason - short reason as listed above</dt>
<dd>
</dd>
<dt id="Recipient---recipients-identification">$Recipient - recipient's identification</dt>
<dd>
</dd>
<dt id="AddressObj---Email::Address-object-containing-recipients-email-address">$AddressObj - <a href="http://metacpan.org/module/Email::Address">Email::Address</a> object containing recipient's email address</dt>
<dd>
</dd>
</dl>
<p>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 <code>@BadRecipients</code> array is available where each element is a hash reference that describes one recipient using the same fields as described above:</p>
<pre><code> @BadRecipients = (
{ Message => '...', Reason => '...', Recipient => '...', ...},
{ Message => '...', Reason => '...', Recipient => '...', ...},
...
)</code></pre>
<h3 id="Private-key-doesnt-exist"><a href="#___top">Private key doesn't exist</a></h3>
<p>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.</p>
<p>In this template <a href="http://metacpan.org/module/MIME::Entity">MIME::Entity</a> object <code>$Message</code> is available, which is the originally received message.</p>
<h3 id="Invalid-data"><a href="#___top">Invalid data</a></h3>
<p>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.</p>
<p>In this template, the <code>@Messages</code> array is available, and will contain a list of error messages.</p>
<h1 id="METHODS"><a href="#___top">METHODS</a></h1>
<h2 id="Protocols"><a href="#___top">Protocols</a></h2>
<p>Returns the complete set of encryption protocols that RT implements; not all may be supported by this installation.</p>
<h2 id="EnabledProtocols"><a href="#___top">EnabledProtocols</a></h2>
<p>Returns the set of enabled and available encryption protocols.</p>
<h2 id="UseForOutgoing"><a href="#___top">UseForOutgoing</a></h2>
<p>Returns the configured outgoing encryption protocol; see <a href="../../../rt/latest/RT_Config.html#Crypt">"Crypt" in RT_Config</a>.</p>
<h2 id="EnabledOnIncoming"><a href="#___top">EnabledOnIncoming</a></h2>
<p>Returns the list of encryption protocols that should be used for decryption and verification of incoming email; see <a href="../../../rt/latest/RT_Config.html#Crypt">"Crypt" in RT_Config</a>.</p>
<h2 id="LoadImplementation-CLASS"><a href="#___top">LoadImplementation CLASS</a></h2>
<p>Given the name of an encryption implementation (e.g. "GnuPG"), loads the <a href="../../../rt/latest/RT/Crypt.html">RT::Crypt</a> class associated with it; return the classname on success, and undef on failure.</p>
<h2 id="SimpleImplementationCall-Protocol-NAME"><a href="#___top">SimpleImplementationCall Protocol => NAME, [...]</a></h2>
<p>Examines the caller of this method, and dispatches to the method of the same name on the correct <a href="../../../rt/latest/RT/Crypt/Role.html">RT::Crypt::Role</a> class based on the provided <code>Protocol</code>.</p>
<h2 id="FindProtectedParts-Entity-MIME::Entity"><a href="#___top">FindProtectedParts Entity => MIME::Entity</a></h2>
<p>Looks for encrypted or signed parts of the given <code>Entity</code>, using all <a href="#EnabledOnIncoming">"EnabledOnIncoming"</a> encryption protocols. For each node in the MIME hierarchy, <a href="../../../rt/latest/RT/Crypt/Role.html#CheckIfProtected">"CheckIfProtected" in RT::Crypt::Role</a> for that <a href="http://metacpan.org/module/MIME::Entity">MIME::Entity</a> is called on each <a href="#EnabledOnIncoming">"EnabledOnIncoming"</a> protocol. Any multipart nodes not claimed by those protocols are recursed into.</p>
<p>Finally, <a href="../../../rt/latest/RT/Crypt/Role.html#FindScatteredParts">"FindScatteredParts" in RT::Crypt::Role</a> is called on the top-most entity for each <a href="#EnabledOnIncoming">"EnabledOnIncoming"</a> protocol.</p>
<p>Returns a list of hash references; each hash reference is guaranteed to contain a <code>Protocol</code> key describing the protocol of the found part, and a <code>Type</code> which is either <code>encrypted</code> or <code>signed</code>. The remaining keys are protocol-dependent; the hashref will be provided to <a href="#VerifyDecrypt">"VerifyDecrypt"</a>.</p>
<h2 id="SignEncrypt-Entity-ENTITY-Sign-1-Encrypt-1-Recipients-ARRAYREF-Signer-NAME-Protocol-NAME-Passphrase-VALUE"><a href="#___top">SignEncrypt Entity => ENTITY, [Sign => 1], [Encrypt => 1], [Recipients => ARRAYREF], [Signer => NAME], [Protocol => NAME], [Passphrase => VALUE]</a></h2>
<p>Takes a <a href="http://metacpan.org/module/MIME::Entity">MIME::Entity</a> object, and signs and/or encrypts it using the given <code>Protocol</code>. If not set, <code>Recipients</code> for encryption will be set by examining the <code>To</code>, <code>Cc</code>, and <code>Bcc</code> headers of the MIME entity. If not set, <code>Signer</code> defaults to the <code>From</code> of the MIME entity.</p>
<p><code>Passphrase</code>, if not provided, will be retrieved using <a href="../../../rt/latest/RT/Crypt/Role.html#GetPassphrase">"GetPassphrase" in RT::Crypt::Role</a>.</p>
<p>Returns a hash with at least the following keys:</p>
<dl>
<dt id="exit_code">exit_code</dt>
<dd>
<p>True if there was an error encrypting or signing.</p>
</dd>
<dt id="message">message</dt>
<dd>
<p>An un-localized error message desribing the problem.</p>
</dd>
</dl>
<h2 id="SignEncryptContent-Content-STRINGREF-Sign-1-Encrypt-1-Recipients-ARRAYREF-Signer-NAME-Protocol-NAME-Passphrase-VALUE"><a href="#___top">SignEncryptContent Content => STRINGREF, [Sign => 1], [Encrypt => 1], [Recipients => ARRAYREF], [Signer => NAME], [Protocol => NAME], [Passphrase => VALUE]</a></h2>
<p>Signs and/or encrypts a string, which is passed by reference. <code>Recipients</code> defaults to <code>/UseKeyForSigning</code>, and <code>Recipients</code> defaults to the global <a href="../RT/Config.html#CorrespondAddress">"CorrespondAddress" in RT::Config</a>. All other arguments and return values are identical to <a href="#SignEncrypt">"SignEncrypt"</a>.</p>
<h2 id="DrySign-Signer-KEY"><a href="#___top">DrySign Signer => KEY</a></h2>
<p>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.</p>
<p>Returns a true value if all went well.</p>
<h2 id="VerifyDecrypt-Entity-ENTITY-Passphrase-undef"><a href="#___top">VerifyDecrypt Entity => ENTITY [, Passphrase => undef ]</a></h2>
<p>Locates all protected parts of the <a href="http://metacpan.org/module/MIME::Entity">MIME::Entity</a> object <code>ENTITY</code>, as found by <a href="#FindProtectedParts">"FindProtectedParts"</a>, and calls <a href="../../../rt/latest/RT/Crypt/Role.html#VerifyDecrypt">"VerifyDecrypt" in RT::Crypt::Role</a> from the appropriate <a href="../../../rt/latest/RT/Crypt/Role.html">RT::Crypt::Role</a> class on each.</p>
<p><code>Passphrase</code>, if not provided, will be retrieved using <a href="../../../rt/latest/RT/Crypt/Role.html#GetPassphrase">"GetPassphrase" in RT::Crypt::Role</a>.</p>
<p>Returns a list of the hash references returned from <a href="../../../rt/latest/RT/Crypt/Role.html#VerifyDecrypt">"VerifyDecrypt" in RT::Crypt::Role</a>.</p>
<h2 id="DecryptContent-Protocol-NAME-Content-STRINGREF-Passphrase-undef"><a href="#___top">DecryptContent Protocol => NAME, Content => STRINGREF, [Passphrase => undef]</a></h2>
<p>Decrypts the content in the string reference in-place. All other arguments and return values are identical to <a href="#VerifyDecrypt">"VerifyDecrypt"</a>.</p>
<h2 id="ParseStatus-Protocol-NAME-Status-STRING"><a href="#___top">ParseStatus Protocol => NAME, Status => STRING</a></h2>
<p>Takes a <code>String</code> 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:</p>
<dl>
<dt id="Operation">Operation</dt>
<dd>
<p>The classification of the process whose status is being reported upon. Valid values include <code>Sign</code>, <code>Encrypt</code>, <code>Decrypt</code>, <code>Verify</code>, <code>PassphraseCheck</code>, <code>RecipientsCheck</code> and <code>Data</code>.</p>
</dd>
<dt id="Status">Status</dt>
<dd>
<p>Whether the operation was successful; contains <code>DONE</code> on success. Other possible values include <code>ERROR</code>, <code>BAD</code>, or <code>MISSING</code>.</p>
</dd>
<dt id="Message">Message</dt>
<dd>
<p>An un-localized user friendly message.</p>
</dd>
</dl>
<h2 id="UseKeyForSigning-KEY"><a href="#___top">UseKeyForSigning [KEY]</a></h2>
<p>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.</p>
<p>This cache is cleared at the end of every request.</p>
<h2 id="UseKeyForEncryption-KEY-VALUE"><a href="#___top">UseKeyForEncryption [KEY [, VALUE]]</a></h2>
<p>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.</p>
<p>This cache is reset at the end of every request.</p>
<h2 id="GetKeysForEncryption-Recipient-EMAIL-Protocol-NAME"><a href="#___top">GetKeysForEncryption Recipient => EMAIL, Protocol => NAME</a></h2>
<p>Returns the list of keys which are suitable for encrypting mail to the given <code>Recipient</code>. Generally this is equivalent to <a href="#GetKeysInfo">"GetKeysInfo"</a> with a <code>Type</code> of <private>, but encryption protocols may further limit which keys can be used for encryption, as opposed to signing.</p>
<h2 id="GetKeysForSigning-Signer-EMAIL-Protocol-NAME"><a href="#___top">GetKeysForSigning Signer => EMAIL, Protocol => NAME</a></h2>
<p>Returns the list of keys which are suitable for signing mail from the given <code>Signer</code>. Generally this is equivalent to <a href="#GetKeysInfo">"GetKeysInfo"</a> with a <code>Type</code> of <private>, but encryption protocols may further limit which keys can be used for signing, as opposed to encryption.</p>
<h2 id="GetPublicKeyInfo-Protocol-NAME-KEY-EMAIL"><a href="#___top">GetPublicKeyInfo Protocol => NAME, KEY => EMAIL</a></h2>
<p>As per <a href="#GetKeyInfo">"GetKeyInfo"</a>, but the <code>Type</code> is forced to <code>public</code>.</p>
<h2 id="GetPrivateKeyInfo-Protocol-NAME-KEY-EMAIL"><a href="#___top">GetPrivateKeyInfo Protocol => NAME, KEY => EMAIL</a></h2>
<p>As per <a href="#GetKeyInfo">"GetKeyInfo"</a>, but the <code>Type</code> is forced to <code>private</code>.</p>
<h2 id="GetKeyInfo-Protocol-NAME-Type-public-private-KEY-EMAIL"><a href="#___top">GetKeyInfo Protocol => NAME, Type => ('public'|'private'), KEY => EMAIL</a></h2>
<p>As per <a href="#GetKeysInfo">"GetKeysInfo"</a>, but only the first matching key is returned in the <code>info</code> value of the result.</p>
<h2 id="GetKeysInfo-Protocol-NAME-Type-public-private-Key-EMAIL"><a href="#___top">GetKeysInfo Protocol => NAME, Type => ('public'|'private'), Key => EMAIL</a></h2>
<p>Looks up information about the public or private keys (as determined by <code>Type</code>) for the email address <code>Key</code>. As each protocol has its own key store, <code>Protocol</code> is also required. If no <code>Key</code> is provided and a true value for <code>Force</code> is given, returns all keys.</p>
<p>The return value is a hash containing <code>exit_code</code> and <code>message</code> in the case of failure, or <code>info</code>, 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:</p>
<dl>
<dt id="Protocol">Protocol</dt>
<dd>
<p>The name of the protocol of this key</p>
</dd>
<dt id="Created">Created</dt>
<dd>
<p>An <a href="../../../rt/latest/RT/Date.html">RT::Date</a> of the date the key was created; undef if unset.</p>
</dd>
<dt id="Expire">Expire</dt>
<dd>
<p>An <a href="../../../rt/latest/RT/Date.html">RT::Date</a> of the date the key expires; undef if the key does not expire.</p>
</dd>
<dt id="Fingerprint">Fingerprint</dt>
<dd>
<p>A fingerprint unique to this key</p>
</dd>
<dt id="Formatted">Formatted</dt>
<dd>
<p>A formatted string representation of the key</p>
</dd>
<dt id="User">User</dt>
<dd>
<p>An array reference of associated user data, each of which is a hashref containing at least a <code>String</code> value, which is a <code>Alice Example <alice@example.com></code> style email address. Each may also contain <code>Created</code> and <code>Expire</code> keys, which are <a href="../../../rt/latest/RT/Date.html">RT::Date</a> objects.</p>
</dd>
</dl>
<a href="./../">← Back to index</a>
|