| 1 | package RWDE::CCR; | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | use warnings; | ||
| 5 | use Error qw(:try); | ||
| 6 | |||
| 7 | use RWDE::Exceptions; | ||
| 8 | |||
| 9 | use Digest::MD5 qw(md5_hex); | ||
| 10 | |||
| 11 | use vars qw($VERSION); | ||
| 12 | $VERSION = sprintf "%d", q$Revision: 558 $ =~ /(\d+)/; | ||
| 13 | |||
| 14 | =pod | ||
| 15 | |||
| 16 | =head1 RWDE::CCR | ||
| 17 | |||
| 18 | Base object to add methods for CCR verification | ||
| 19 | |||
| 20 | =cut | ||
| 21 | |||
| 22 | =head2 get_ccrcontext() | ||
| 23 | |||
| 24 | Return back the class declared ccrcontext if it exists, otherwise generate one from the class name. | ||
| 25 | |||
| 26 | We use a pretty general hashing scheme here, it's suggested that this be replaced. | ||
| 27 | |||
| 28 | ccrcontext is ultimately used to generate web-safe ids that can't easily be guessed by web robots (or jerks) - although | ||
| 29 | depending on your hashing scheme you could make this pretty strong, but that has the cost of tying up the webserver | ||
| 30 | if you frequently end up using these ids in the application. | ||
| 31 | |||
| 32 | =cut | ||
| 33 | |||
| 34 | sub get_ccrcontext { | ||
| 35 | my ($self, $params) = @_; | ||
| 36 | |||
| 37 | my $ccrcontext; | ||
| 38 | |||
| 39 | if (defined($self->{_ccrcontext})) { | ||
| 40 | $ccrcontext = $self->{_ccrcontext}; | ||
| 41 | } | ||
| 42 | else { | ||
| 43 | $ccrcontext = join '', map ord($_), split //, ref $self; | ||
| 44 | } | ||
| 45 | |||
| 46 | return $ccrcontext; | ||
| 47 | } | ||
| 48 | |||
| 49 | =head2 fetch_by_id() | ||
| 50 | |||
| 51 | This method is a macro for fetching a single record from the database using either id.enc or ccr. | ||
| 52 | This could manually be done using more complicated methods found within the items class, which | ||
| 53 | is probably what you want to do if you are trying to do anything fancy. | ||
| 54 | |||
| 55 | =cut | ||
| 56 | |||
| 57 | sub fetch_by_id { | ||
| 58 | my ($self, $params) = @_; | ||
| 59 | |||
| 60 | #this element is used to lookup static variables from the give type | ||
| 61 | my $term = $self->new(); | ||
| 62 | |||
| 63 | my $id; | ||
| 64 | |||
| 65 | if (defined $$params{ $term->get_id_name() }) { | ||
| 66 | $id = $$params{ $term->get_id_name() }; | ||
| 67 | } | ||
| 68 | |||
| 69 | elsif (defined $$params{ $term->get_ccr_name() }) { | ||
| 70 | $id = $term->ccr_to_id($$params{ $term->get_ccr_name() }); | ||
| 71 | throw RWDE::DevelException({ info => "ID hasn't passed the ccr check (check ccr_context): " . $$params{$term->get_ccr_name()} }) | ||
| 72 | unless defined $id; | ||
| 73 | |||
| 74 | } | ||
| 75 | |||
| 76 | elsif (defined($$params{ $term->get_enc_name() })) { | ||
| 77 | $id = $term->decode($$params{ $term->get_enc_name() }); | ||
| 78 | throw RWDE::DevelException({ info => "ID hasn't passed the ccr or decode check: " . $$params{ $term->get_enc_name() } }) | ||
| 79 | unless defined $id; | ||
| 80 | |||
| 81 | } | ||
| 82 | |||
| 83 | else { | ||
| 84 | throw RWDE::DevelException({ info => 'Called with no initialization parameter (has to be one of: id, ccr or enc)' }); | ||
| 85 | } | ||
| 86 | |||
| 87 | |||
| 88 | |||
| 89 | return $term->_fetch_by_id({ $term->get_id_name() => $id }); | ||
| 90 | } | ||
| 91 | |||
| 92 | =head2 append_ccr($integer[,$context]) | ||
| 93 | |||
| 94 | Append the check-character to the integer and return the result. | ||
| 95 | Verify by calling the verify_ccr() method. Zero-pads the integer to a | ||
| 96 | five character minimum length string. | ||
| 97 | |||
| 98 | The C<$context> parameter acts as a salt to change the code based on | ||
| 99 | context such as owner ID, user ID, etc. | ||
| 100 | |||
| 101 | =cut | ||
| 102 | |||
| 103 | sub append_ccr { | ||
| 104 | my $self = shift; | ||
| 105 | my $int = shift; | ||
| 106 | my $context = shift || 0; | ||
| 107 | |||
| 108 | my $code = '0' x (5 - length($int)) . $int; | ||
| 109 | |||
| 110 | my $ccr = _compute_ccr($code, $context); | ||
| 111 | $ccr = lc($ccr) unless $ccr eq 'L'; # help make sure it is easy to read | ||
| 112 | return $code . $ccr; | ||
| 113 | } | ||
| 114 | |||
| 115 | =head2 verify_ccr($string[,$context]) | ||
| 116 | |||
| 117 | Compares the check-character (last character) of C<$string> to a new | ||
| 118 | one computed against the remaining digits. Returns $string without | ||
| 119 | CCR if they match or undef if not. C<$string> should be of the form | ||
| 120 | C<\d+[A-Z]> and C<$context> is as above. | ||
| 121 | |||
| 122 | =cut | ||
| 123 | |||
| 124 | sub verify_ccr { | ||
| 125 | my $self = shift; | ||
| 126 | my $str = shift; | ||
| 127 | my $context = shift || 0; | ||
| 128 | |||
| 129 | return | ||
| 130 | unless $str; | ||
| 131 | |||
| 132 | my $check = uc(chop($str)); # last character, force upper case. | ||
| 133 | |||
| 134 | # not valid unless within [A..Z] | ||
| 135 | return | ||
| 136 | if (ord($check) < ord('A') or ord($check) > ord('Z')); | ||
| 137 | |||
| 138 | return $check eq _compute_ccr($str, $context) ? $str : undef; | ||
| 139 | } | ||
| 140 | |||
| 141 | =head2 _compute_ccr($string[,$context]) | ||
| 142 | |||
| 143 | Internal routine to do the math to compute the Character Checksum characteR | ||
| 144 | (ccr) code for a string. | ||
| 145 | |||
| 146 | Basically multiplies the ordinal value of each character of the string by | ||
| 147 | an exponential weight based on its position in the string, and keeps the | ||
| 148 | sum of these modulo 26. Returns the letter corresponding to that value. | ||
| 149 | |||
| 150 | The intent of this encoding as opposed to the encode() methods above | ||
| 151 | is to provide a check to prevent typos and quick hack attempts on simple | ||
| 152 | email messages involving the user/owner ID values. | ||
| 153 | |||
| 154 | The $context parameter acts as a salt to change the code based on context | ||
| 155 | such as owner ID, user ID, etc. | ||
| 156 | |||
| 157 | =cut | ||
| 158 | |||
| 159 | sub _compute_ccr { | ||
| 160 | my $s = shift; | ||
| 161 | my $context = shift || 0; | ||
| 162 | |||
| 163 | use integer; | ||
| 164 | |||
| 165 | my $c = 17 + $context; # some random value | ||
| 166 | my $m = 1; # multiplier weight. | ||
| 167 | foreach my $d (split //, $s) { | ||
| 168 | $c += ord($d) * $m; | ||
| 169 | $c %= 26; | ||
| 170 | $m *= 2; | ||
| 171 | } | ||
| 172 | |||
| 173 | return chr(ord('A') + $c); | ||
| 174 | } | ||
| 175 | |||
| 176 | =head2 compute_security_code($string) | ||
| 177 | |||
| 178 | Method to do the math to compute the MD5 checksum for a string, and | ||
| 179 | return the last 8 characters to use as a "security" code for | ||
| 180 | verifying some data. | ||
| 181 | |||
| 182 | The $context parameter acts as a salt to change the code based on context | ||
| 183 | such as owner ID, user ID, etc. | ||
| 184 | |||
| 185 | =cut | ||
| 186 | |||
| 187 | sub compute_security_code { | ||
| 188 | my $self = shift; | ||
| 189 | my $s = shift; | ||
| 190 | my $context = shift || 'aVmK'; | ||
| 191 | |||
| 192 | return substr(md5_hex($context, $s), -8); | ||
| 193 | } | ||
| 194 | |||
| 195 | =head2 ccr_to_id($string) | ||
| 196 | |||
| 197 | Convert the string to an id number. Returns undef on failure. | ||
| 198 | |||
| 199 | =cut | ||
| 200 | |||
| 201 | sub ccr_to_id { | ||
| 202 | my $self = shift; | ||
| 203 | my $string = shift; | ||
| 204 | |||
| 205 | use integer; | ||
| 206 | |||
| 207 | $string = $self->verify_ccr($string, $self->get_ccrcontext()) or return; | ||
| 208 | |||
| 209 | my $i = $string; | ||
| 210 | |||
| 211 | $string = ($i - 6_000_000) / 42 - 1; | ||
| 212 | |||
| 213 | $string =~ s/^\+//; # remove leading "+" from BigInt. | ||
| 214 | |||
| 215 | return $string; | ||
| 216 | } | ||
| 217 | |||
| 218 | =head2 get_ccr() | ||
| 219 | |||
| 220 | Returns the encoded value of the derived objects id | ||
| 221 | |||
| 222 | =cut | ||
| 223 | |||
| 224 | sub get_ccr { | ||
| 225 | use integer; | ||
| 226 | my ($self) = @_; | ||
| 227 | |||
| 228 | if (!$self->{ccr}) { | ||
| 229 | my $id = $self->{_data}->{ $self->{_id} }; | ||
| 230 | |||
| 231 | $id = ($id + 1) * 42 + 6_000_000; | ||
| 232 | $id =~ s/^\+//; # remove leading "+" from BigInt. | ||
| 233 | $self->{ccr} = $self->append_ccr($id, $self->get_ccrcontext); | ||
| 234 | } | ||
| 235 | |||
| 236 | return $self->{ccr}; | ||
| 237 | } | ||
| 238 | |||
| 239 | =head2 encode($string) | ||
| 240 | |||
| 241 | Returns the value with CCR appended and a hash both based on | ||
| 242 | $ccrcontext appended to that. Useful for passing information from form | ||
| 243 | to form via hidden fields that need to be secured from tampering. The | ||
| 244 | string may B<not> contain a dash (-) or comma character. | ||
| 245 | |||
| 246 | This produces a shorter encoded result without funny characters in it | ||
| 247 | that may cause the longer form to break, so is useful for creating | ||
| 248 | links that people may need to cut-and-paste. | ||
| 249 | |||
| 250 | =cut | ||
| 251 | |||
| 252 | sub encode { | ||
| 253 | my ($self, $val) = @_; | ||
| 254 | |||
| 255 | $val = $self->append_ccr($val, $self->get_ccrcontext); | ||
| 256 | |||
| 257 | return "$val-" . $self->compute_security_code($val, $self->get_ccrcontext); | ||
| 258 | } | ||
| 259 | |||
| 260 | =head2 get_enc() | ||
| 261 | |||
| 262 | Returns the encoded value of the derived objects id | ||
| 263 | |||
| 264 | =cut | ||
| 265 | |||
| 266 | sub get_enc { | ||
| 267 | my ($self) = @_; | ||
| 268 | if (!$self->{enc}) { | ||
| 269 | $self->{enc} = $self->encode($self->{_data}->{ $self->{_id} }); | ||
| 270 | } | ||
| 271 | return $self->{enc}; | ||
| 272 | } | ||
| 273 | |||
| 274 | =head2 decode($encodedString) | ||
| 275 | |||
| 276 | Return the value decoded from the return value of the encode method. | ||
| 277 | Throws 'undef' exception if fails. | ||
| 278 | |||
| 279 | =cut | ||
| 280 | |||
| 281 | sub decode ($) { | ||
| 282 | my ($self, $code) = @_; | ||
| 283 | |||
| 284 | throw RWDE::DataMissingException({ info => 'No code provided.' }) unless $code; | ||
| 285 | |||
| 286 | my ($id, $hash) = split /-/, $code; | ||
| 287 | |||
| 288 | throw RWDE::DevelException({ info => "Malformed code hash instantiated from $self string: $code" }) | ||
| 289 | unless (defined $id and defined $hash); | ||
| 290 | |||
| 291 | if ( $self->compute_security_code($id, $self->get_ccrcontext) eq $hash | ||
| 292 | and $id = $self->verify_ccr($id, $self->get_ccrcontext)) { | ||
| 293 | return $id + 0; | ||
| 294 | } | ||
| 295 | else { | ||
| 296 | throw RWDE::DevelException({ info => "Cannot decode '$code'" }); | ||
| 297 | } | ||
| 298 | } | ||
| 299 | |||
| 300 | |||
| 301 | =head2 get_ccr_name() | ||
| 302 | |||
| 303 | Determine the exact label used within the object for storing the ccr value. By convention it's a variation | ||
| 304 | on the class id label. | ||
| 305 | |||
| 306 | =cut | ||
| 307 | |||
| 308 | sub get_ccr_name { | ||
| 309 | my ($self, $params) = @_; | ||
| 310 | |||
| 311 | my $id_name = $self->get_id_name(); | ||
| 312 | |||
| 313 | $id_name =~ s/_id/_ccr/; | ||
| 314 | |||
| 315 | return $id_name; | ||
| 316 | } | ||
| 317 | |||
| 318 | =head2 get_enc_name() | ||
| 319 | |||
| 320 | Determine the exact label used within the object for storing the enc value. By convention it's a variation | ||
| 321 | on the class id label. | ||
| 322 | |||
| 323 | =cut | ||
| 324 | |||
| 325 | sub get_enc_name { | ||
| 326 | my ($self, $params) = @_; | ||
| 327 | |||
| 328 | my $id_name = $self->get_id_name(); | ||
| 329 | |||
| 330 | $id_name =~ s/_id/_enc/; | ||
| 331 | |||
| 332 | return $id_name; | ||
| 333 | } | ||
| 334 | |||
| 335 | =head2 compute_md5_rand($string) | ||
| 336 | |||
| 337 | Method to do the math to evenly distribute a non-uniformly distributed string input for use as in cases | ||
| 338 | where we want to randomly select based on a non-random input (ip address for example). | ||
| 339 | |||
| 340 | =cut | ||
| 341 | |||
| 342 | sub compute_md5_rand { | ||
| 343 | my ($params) = @_; | ||
| 344 | |||
| 345 | #generate hex encoded version | ||
| 346 | my $encoded = md5_hex($$params{string}); | ||
| 347 | |||
| 348 | #extract first digit | ||
| 349 | my $digit; | ||
| 350 | if ($encoded =~ m/(\d)/) { | ||
| 351 | $digit = $1; | ||
| 352 | } | ||
| 353 | |||
| 354 | return $digit; | ||
| 355 | } | ||
| 356 | |||
| 357 | 1; |