1 # BEGIN BPS TAGGED BLOCK {{{
5 # This software is Copyright (c) 1996-2015 Best Practical Solutions, LLC
6 # <sales@bestpractical.com>
8 # (Except where explicitly superseded by other copyright notices)
13 # This work is made available to you under the terms of Version 2 of
14 # the GNU General Public License. A copy of that license should have
15 # been provided with this software, but in any event can be snarfed
18 # This work is distributed in the hope that it will be useful, but
19 # WITHOUT ANY WARRANTY; without even the implied warranty of
20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 # General Public License for more details.
23 # You should have received a copy of the GNU General Public License
24 # along with this program; if not, write to the Free Software
25 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
26 # 02110-1301 or visit their web page on the internet at
27 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
30 # CONTRIBUTION SUBMISSION POLICY:
32 # (The following paragraph is not intended to limit the rights granted
33 # to you to modify and distribute this software under the terms of
34 # the GNU General Public License and is only of importance to you if
35 # you choose to contribute your changes and enhancements to the
36 # community by submitting them to Best Practical Solutions, LLC.)
38 # By intentionally submitting any modifications, corrections or
39 # derivatives to this work, or any other work intended for use with
40 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
41 # you are the copyright holder for those contributions and you grant
42 # Best Practical Solutions, LLC a nonexclusive, worldwide, irrevocable,
43 # royalty-free, perpetual, license to use, copy, create derivative
44 # works based on those contributions, and sublicense and distribute
45 # those contributions and any derivatives thereof.
47 # END BPS TAGGED BLOCK }}}
52 package RT::Crypt::Role;
57 RT::Crypt::Role - Common requirements for encryption implementations
63 This routine is called only if the protocol is enabled, and should
64 return true if all binaries required by the protocol are installed. It
65 should produce any warnings necessary to describe any issues it
72 =head2 GetPassphrase Address => ADDRESS
74 Returns the passphrase for the given address. It looks at the relevant
75 configuration option for the encryption protocol
76 (e.g. L<RT_Config/GnuPG> for GnuPG), and examines the Passphrase key.
77 It it does not exist, returns the empty string. If it is a scalar, it
78 returns that value. If it is an anonymous subroutine, it calls it. If
79 it is a hash, it looks up the address (using '' as a fallback key).
85 my %args = ( Address => undef, @_ );
87 my $class = ref($self) || $self;
88 $class =~ s/^RT::Crypt:://;
90 my $config = RT->Config->Get($class)->{Passphrase};
92 return '' unless defined $config;
94 if (not ref $config) {
96 } elsif (ref $config eq "HASH") {
97 return $config->{$args{Address}}
99 } elsif (ref $config eq "CODE") {
100 return $config->( @_ );
102 warn "Unknown Passphrase type for $class: ".ref($config);
106 =head2 SignEncrypt Entity => MIME::Entity, [ Encrypt => 1, Sign => 1, ... ]
108 Signs and/or encrypts a MIME entity. All arguments and return values
109 are identical to L<RT::Crypt/SignEncrypt>, with the omission of
114 requires 'SignEncrypt';
116 =head2 SignEncryptContent Content => STRINGREF, [ Encrypt => 1, Sign => 1, ... ]
118 Signs and/or encrypts a string, which is passed by reference. All
119 arguments and return values are identical to
120 L<RT::Crypt/SignEncryptContent>, with the omission of C<Protocol>.
124 requires 'SignEncryptContent';
126 =head2 VerifyDecrypt Info => HASHREF, [ Passphrase => undef ]
128 The C<Info> key is a hashref as returned from L</FindScatteredParts> or
129 L</CheckIfProtected>. This method should alter the mime objects
130 in-place as necessary during signing and decryption.
132 Returns a hash with at least the following keys:
138 True if there was an error encrypting or signing.
142 An un-localized error message desribing the problem.
148 requires 'VerifyDecrypt';
150 =head2 DecryptContent Content => STRINGREF, [ Passphrase => undef ]
152 Decrypts the content in the string reference in-place. All arguments
153 and return values are identical to L<RT::Crypt/DecryptContent>, with the
154 omission of C<Protocol>.
158 requires 'DecryptContent';
160 =head2 ParseStatus STRING
162 Takes a string describing the status of verification/decryption, usually
163 as stored in a MIME header. Parses and returns it as described in
164 L<RT::Crypt/ParseStatus>.
168 requires 'ParseStatus';
170 =head2 FindScatteredParts Parts => ARRAYREF, Parents => HASHREF, Skip => HASHREF
172 Passed the list of unclaimed L<MIME::Entity> objects in C<Parts>, this
173 method should examine them as a whole to determine if there are any that
174 could not be claimed by the single-entity-at-a-time L</CheckIfProtected>
175 method. This is generally only necessary in the case of signatures
176 manually attached in parallel, and the like.
178 If found, the relevant entities should be inserted into C<Skip> with a
179 true value, to signify to other encryption protols that they have been
180 claimed. The method should return a list of hash references, each
181 containing a C<Type> key which is either C<signed> or C<encrypted>. The
182 remaining keys are protocol-dependent; the hashref will be provided to
187 requires 'FindScatteredParts';
189 =head2 CheckIfProtected Entity => MIME::Entity
191 Examines the provided L<MIME::Entity>, and returns an empty list if it
192 is not signed or encrypted using the protocol. If it is, returns a hash
193 reference containing a C<Type> which is either C<encrypted> or
194 C<signed>. The remaining keys are protocol-dependent; the hashref will
195 be provided to L</VerifyDecrypt>.
199 requires 'CheckIfProtected';
201 =head2 GetKeysInfo Type => ('public'|'private'), Key => EMAIL
203 Returns a list of keys matching the email C<Key>, as described in
204 L<RT::Crypt/GetKeysInfo>.
208 requires 'GetKeysInfo';
210 =head2 GetKeysForEncryption Recipient => EMAIL
212 Returns a list of keys suitable for encryption, as described in
213 L<RT::Crypt/GetKeysForEncryption>.
217 requires 'GetKeysForEncryption';
219 =head2 GetKeysForSigning Signer => EMAIL
221 Returns a list of keys suitable for encryption, as described in
222 L<RT::Crypt/GetKeysForSigning>.
226 requires 'GetKeysForSigning';
228 =head2 ParseDate STRING
230 Takes a string, and parses and returns a L<RT::Date>; if the string is
231 purely numeric, assumes is a epoch timestamp.
240 return $value unless $value;
243 my $obj = RT::Date->new( RT->SystemUser );
245 if ( $value =~ /^\d+$/ ) {
246 $obj->Set( Value => $value );
248 $obj->Set( Format => 'unknown', Value => $value, Timezone => 'utc' );