| File | /usr/local/lib/perl5/5.10.1/darwin-2level/Digest/SHA.pm |
| Statements Executed | 24 |
| Statement Execution Time | 9.51ms |
| Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
|---|---|---|---|---|---|
| 1 | 1 | 1 | 163µs | 166µs | Digest::SHA::BEGIN@6 |
| 1 | 1 | 2 | 97µs | 97µs | Digest::SHA::bootstrap (xsub) |
| 3 | 1 | 2 | 89µs | 89µs | Digest::SHA::hmac_sha256_base64 (xsub) |
| 1 | 1 | 1 | 15µs | 18µs | Digest::SHA::BEGIN@5 |
| 1 | 1 | 1 | 8µs | 67µs | Digest::SHA::BEGIN@7 |
| 0 | 0 | 0 | 0s | 0s | Digest::SHA::Addfile |
| 0 | 0 | 0 | 0s | 0s | Digest::SHA::DESTROY |
| 0 | 0 | 0 | 0s | 0s | Digest::SHA::_addfile |
| 0 | 0 | 0 | 0s | 0s | Digest::SHA::_bail |
| 0 | 0 | 0 | 0s | 0s | Digest::SHA::add_bits |
| 0 | 0 | 0 | 0s | 0s | Digest::SHA::clone |
| 0 | 0 | 0 | 0s | 0s | Digest::SHA::dump |
| 0 | 0 | 0 | 0s | 0s | Digest::SHA::load |
| 0 | 0 | 0 | 0s | 0s | Digest::SHA::new |
| Line | State ments |
Time on line |
Calls | Time in subs |
Code |
|---|---|---|---|---|---|
| 1 | package Digest::SHA; | ||||
| 2 | |||||
| 3 | 1 | 46µs | require 5.003000; | ||
| 4 | |||||
| 5 | 3 | 21µs | 2 | 21µs | # spent 18µs (15+3) within Digest::SHA::BEGIN@5 which was called
# once (15µs+3µs) by SimpleDB::Client::BEGIN@47 at line 5 # spent 18µs making 1 call to Digest::SHA::BEGIN@5
# spent 3µs making 1 call to strict::import |
| 6 | 3 | 172µs | 2 | 169µs | # spent 166µs (163+3) within Digest::SHA::BEGIN@6 which was called
# once (163µs+3µs) by SimpleDB::Client::BEGIN@47 at line 6 # spent 166µs making 1 call to Digest::SHA::BEGIN@6
# spent 3µs making 1 call to integer::import |
| 7 | 3 | 722µs | 2 | 127µs | # spent 67µs (8+60) within Digest::SHA::BEGIN@7 which was called
# once (8µs+60µs) by SimpleDB::Client::BEGIN@47 at line 7 # spent 67µs making 1 call to Digest::SHA::BEGIN@7
# spent 60µs making 1 call to vars::import |
| 8 | |||||
| 9 | 1 | 400ns | $VERSION = '5.47'; | ||
| 10 | |||||
| 11 | 1 | 1µs | require Exporter; | ||
| 12 | 1 | 500ns | require DynaLoader; | ||
| 13 | 1 | 11µs | @ISA = qw(Exporter DynaLoader); | ||
| 14 | 1 | 5µs | @EXPORT_OK = qw( | ||
| 15 | hmac_sha1 hmac_sha1_base64 hmac_sha1_hex | ||||
| 16 | hmac_sha224 hmac_sha224_base64 hmac_sha224_hex | ||||
| 17 | hmac_sha256 hmac_sha256_base64 hmac_sha256_hex | ||||
| 18 | hmac_sha384 hmac_sha384_base64 hmac_sha384_hex | ||||
| 19 | hmac_sha512 hmac_sha512_base64 hmac_sha512_hex | ||||
| 20 | sha1 sha1_base64 sha1_hex | ||||
| 21 | sha224 sha224_base64 sha224_hex | ||||
| 22 | sha256 sha256_base64 sha256_hex | ||||
| 23 | sha384 sha384_base64 sha384_hex | ||||
| 24 | sha512 sha512_base64 sha512_hex); | ||||
| 25 | |||||
| 26 | # If possible, inherit from Digest::base (which depends on MIME::Base64) | ||||
| 27 | |||||
| 28 | 1 | 1µs | *addfile = \&Addfile; | ||
| 29 | |||||
| 30 | 1 | 700ns | eval { | ||
| 31 | 1 | 8.38ms | require MIME::Base64; | ||
| 32 | 1 | 72µs | require Digest::base; | ||
| 33 | 1 | 31µs | push(@ISA, 'Digest::base'); | ||
| 34 | }; | ||||
| 35 | 1 | 500ns | if ($@) { | ||
| 36 | *hexdigest = \&Hexdigest; | ||||
| 37 | *b64digest = \&B64digest; | ||||
| 38 | } | ||||
| 39 | |||||
| 40 | # The following routines aren't time-critical, so they can be left in Perl | ||||
| 41 | |||||
| 42 | sub new { | ||||
| 43 | my($class, $alg) = @_; | ||||
| 44 | $alg =~ s/\D+//g if defined $alg; | ||||
| 45 | if (ref($class)) { # instance method | ||||
| 46 | unless (defined($alg) && ($alg != $class->algorithm)) { | ||||
| 47 | sharewind($$class); | ||||
| 48 | return($class); | ||||
| 49 | } | ||||
| 50 | shaclose($$class) if $$class; | ||||
| 51 | $$class = shaopen($alg) || return; | ||||
| 52 | return($class); | ||||
| 53 | } | ||||
| 54 | $alg = 1 unless defined $alg; | ||||
| 55 | my $state = shaopen($alg) || return; | ||||
| 56 | my $self = \$state; | ||||
| 57 | bless($self, $class); | ||||
| 58 | return($self); | ||||
| 59 | } | ||||
| 60 | |||||
| 61 | sub DESTROY { | ||||
| 62 | my $self = shift; | ||||
| 63 | shaclose($$self) if $$self; | ||||
| 64 | } | ||||
| 65 | |||||
| 66 | sub clone { | ||||
| 67 | my $self = shift; | ||||
| 68 | my $state = shadup($$self) || return; | ||||
| 69 | my $copy = \$state; | ||||
| 70 | bless($copy, ref($self)); | ||||
| 71 | return($copy); | ||||
| 72 | } | ||||
| 73 | |||||
| 74 | 1 | 3µs | *reset = \&new; | ||
| 75 | |||||
| 76 | sub add_bits { | ||||
| 77 | my($self, $data, $nbits) = @_; | ||||
| 78 | unless (defined $nbits) { | ||||
| 79 | $nbits = length($data); | ||||
| 80 | $data = pack("B*", $data); | ||||
| 81 | } | ||||
| 82 | shawrite($data, $nbits, $$self); | ||||
| 83 | return($self); | ||||
| 84 | } | ||||
| 85 | |||||
| 86 | sub _bail { | ||||
| 87 | my $msg = shift; | ||||
| 88 | |||||
| 89 | require Carp; | ||||
| 90 | Carp::croak("$msg: $!"); | ||||
| 91 | } | ||||
| 92 | |||||
| 93 | sub _addfile { # this is "addfile" from Digest::base 1.00 | ||||
| 94 | my ($self, $handle) = @_; | ||||
| 95 | |||||
| 96 | my $n; | ||||
| 97 | my $buf = ""; | ||||
| 98 | |||||
| 99 | while (($n = read($handle, $buf, 4096))) { | ||||
| 100 | $self->add($buf); | ||||
| 101 | } | ||||
| 102 | _bail("Read failed") unless defined $n; | ||||
| 103 | |||||
| 104 | $self; | ||||
| 105 | } | ||||
| 106 | |||||
| 107 | sub Addfile { | ||||
| 108 | my ($self, $file, $mode) = @_; | ||||
| 109 | |||||
| 110 | return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR'; | ||||
| 111 | |||||
| 112 | $mode = defined($mode) ? $mode : ""; | ||||
| 113 | my ($binary, $portable) = map { $_ eq $mode } ("b", "p"); | ||||
| 114 | my $text = -T $file; | ||||
| 115 | |||||
| 116 | local *FH; | ||||
| 117 | # protect any leading or trailing whitespace in $file; | ||||
| 118 | # otherwise, 2-arg "open" will ignore them | ||||
| 119 | $file =~ s#^(\s)#./$1#; | ||||
| 120 | open(FH, "< $file\0") or _bail("Open failed"); | ||||
| 121 | binmode(FH) if $binary || $portable; | ||||
| 122 | |||||
| 123 | unless ($portable && $text) { | ||||
| 124 | $self->_addfile(*FH); | ||||
| 125 | close(FH); | ||||
| 126 | return($self); | ||||
| 127 | } | ||||
| 128 | |||||
| 129 | my ($n1, $n2); | ||||
| 130 | my ($buf1, $buf2) = ("", ""); | ||||
| 131 | |||||
| 132 | while (($n1 = read(FH, $buf1, 4096))) { | ||||
| 133 | while (substr($buf1, -1) eq "\015") { | ||||
| 134 | $n2 = read(FH, $buf2, 4096); | ||||
| 135 | _bail("Read failed") unless defined $n2; | ||||
| 136 | last unless $n2; | ||||
| 137 | $buf1 .= $buf2; | ||||
| 138 | } | ||||
| 139 | $buf1 =~ s/\015?\015\012/\012/g; # DOS/Windows | ||||
| 140 | $buf1 =~ s/\015/\012/g; # early MacOS | ||||
| 141 | $self->add($buf1); | ||||
| 142 | } | ||||
| 143 | _bail("Read failed") unless defined $n1; | ||||
| 144 | close(FH); | ||||
| 145 | |||||
| 146 | $self; | ||||
| 147 | } | ||||
| 148 | |||||
| 149 | sub dump { | ||||
| 150 | my $self = shift; | ||||
| 151 | my $file = shift || ""; | ||||
| 152 | |||||
| 153 | shadump($file, $$self) || return; | ||||
| 154 | return($self); | ||||
| 155 | } | ||||
| 156 | |||||
| 157 | sub load { | ||||
| 158 | my $class = shift; | ||||
| 159 | my $file = shift || ""; | ||||
| 160 | if (ref($class)) { # instance method | ||||
| 161 | shaclose($$class) if $$class; | ||||
| 162 | $$class = shaload($file) || return; | ||||
| 163 | return($class); | ||||
| 164 | } | ||||
| 165 | my $state = shaload($file) || return; | ||||
| 166 | my $self = \$state; | ||||
| 167 | bless($self, $class); | ||||
| 168 | return($self); | ||||
| 169 | } | ||||
| 170 | |||||
| 171 | 1 | 15µs | 1 | 355µs | Digest::SHA->bootstrap($VERSION); # spent 355µs making 1 call to DynaLoader::bootstrap |
| 172 | |||||
| 173 | 1 | 30µs | 1; | ||
| 174 | __END__ | ||||
| 175 | |||||
| 176 | =head1 NAME | ||||
| 177 | |||||
| 178 | Digest::SHA - Perl extension for SHA-1/224/256/384/512 | ||||
| 179 | |||||
| 180 | =head1 SYNOPSIS | ||||
| 181 | |||||
| 182 | In programs: | ||||
| 183 | |||||
| 184 | # Functional interface | ||||
| 185 | |||||
| 186 | use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...); | ||||
| 187 | |||||
| 188 | $digest = sha1($data); | ||||
| 189 | $digest = sha1_hex($data); | ||||
| 190 | $digest = sha1_base64($data); | ||||
| 191 | |||||
| 192 | $digest = sha256($data); | ||||
| 193 | $digest = sha384_hex($data); | ||||
| 194 | $digest = sha512_base64($data); | ||||
| 195 | |||||
| 196 | # Object-oriented | ||||
| 197 | |||||
| 198 | use Digest::SHA; | ||||
| 199 | |||||
| 200 | $sha = Digest::SHA->new($alg); | ||||
| 201 | |||||
| 202 | $sha->add($data); # feed data into stream | ||||
| 203 | |||||
| 204 | $sha->addfile(*F); | ||||
| 205 | $sha->addfile($filename); | ||||
| 206 | |||||
| 207 | $sha->add_bits($bits); | ||||
| 208 | $sha->add_bits($data, $nbits); | ||||
| 209 | |||||
| 210 | $sha_copy = $sha->clone; # if needed, make copy of | ||||
| 211 | $sha->dump($file); # current digest state, | ||||
| 212 | $sha->load($file); # or save it on disk | ||||
| 213 | |||||
| 214 | $digest = $sha->digest; # compute digest | ||||
| 215 | $digest = $sha->hexdigest; | ||||
| 216 | $digest = $sha->b64digest; | ||||
| 217 | |||||
| 218 | From the command line: | ||||
| 219 | |||||
| 220 | $ shasum files | ||||
| 221 | |||||
| 222 | $ shasum --help | ||||
| 223 | |||||
| 224 | =head1 SYNOPSIS (HMAC-SHA) | ||||
| 225 | |||||
| 226 | # Functional interface only | ||||
| 227 | |||||
| 228 | use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...); | ||||
| 229 | |||||
| 230 | $digest = hmac_sha1($data, $key); | ||||
| 231 | $digest = hmac_sha224_hex($data, $key); | ||||
| 232 | $digest = hmac_sha256_base64($data, $key); | ||||
| 233 | |||||
| 234 | =head1 ABSTRACT | ||||
| 235 | |||||
| 236 | Digest::SHA is a complete implementation of the NIST Secure Hash | ||||
| 237 | Standard. It gives Perl programmers a convenient way to calculate | ||||
| 238 | SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 message digests. | ||||
| 239 | The module can handle all types of input, including partial-byte | ||||
| 240 | data. | ||||
| 241 | |||||
| 242 | =head1 DESCRIPTION | ||||
| 243 | |||||
| 244 | Digest::SHA is written in C for speed. If your platform lacks a | ||||
| 245 | C compiler, you can install the functionally equivalent (but much | ||||
| 246 | slower) L<Digest::SHA::PurePerl> module. | ||||
| 247 | |||||
| 248 | The programming interface is easy to use: it's the same one found | ||||
| 249 | in CPAN's L<Digest> module. So, if your applications currently | ||||
| 250 | use L<Digest::MD5> and you'd prefer the stronger security of SHA, | ||||
| 251 | it's a simple matter to convert them. | ||||
| 252 | |||||
| 253 | The interface provides two ways to calculate digests: all-at-once, | ||||
| 254 | or in stages. To illustrate, the following short program computes | ||||
| 255 | the SHA-256 digest of "hello world" using each approach: | ||||
| 256 | |||||
| 257 | use Digest::SHA qw(sha256_hex); | ||||
| 258 | |||||
| 259 | $data = "hello world"; | ||||
| 260 | @frags = split(//, $data); | ||||
| 261 | |||||
| 262 | # all-at-once (Functional style) | ||||
| 263 | $digest1 = sha256_hex($data); | ||||
| 264 | |||||
| 265 | # in-stages (OOP style) | ||||
| 266 | $state = Digest::SHA->new(256); | ||||
| 267 | for (@frags) { $state->add($_) } | ||||
| 268 | $digest2 = $state->hexdigest; | ||||
| 269 | |||||
| 270 | print $digest1 eq $digest2 ? | ||||
| 271 | "whew!\n" : "oops!\n"; | ||||
| 272 | |||||
| 273 | To calculate the digest of an n-bit message where I<n> is not a | ||||
| 274 | multiple of 8, use the I<add_bits()> method. For example, consider | ||||
| 275 | the 446-bit message consisting of the bit-string "110" repeated | ||||
| 276 | 148 times, followed by "11". Here's how to display its SHA-1 | ||||
| 277 | digest: | ||||
| 278 | |||||
| 279 | use Digest::SHA; | ||||
| 280 | $bits = "110" x 148 . "11"; | ||||
| 281 | $sha = Digest::SHA->new(1)->add_bits($bits); | ||||
| 282 | print $sha->hexdigest, "\n"; | ||||
| 283 | |||||
| 284 | Note that for larger bit-strings, it's more efficient to use the | ||||
| 285 | two-argument version I<add_bits($data, $nbits)>, where I<$data> is | ||||
| 286 | in the customary packed binary format used for Perl strings. | ||||
| 287 | |||||
| 288 | The module also lets you save intermediate SHA states to disk, or | ||||
| 289 | display them on standard output. The I<dump()> method generates | ||||
| 290 | portable, human-readable text describing the current state of | ||||
| 291 | computation. You can subsequently retrieve the file with I<load()> | ||||
| 292 | to resume where the calculation left off. | ||||
| 293 | |||||
| 294 | To see what a state description looks like, just run the following: | ||||
| 295 | |||||
| 296 | use Digest::SHA; | ||||
| 297 | Digest::SHA->new->add("Shaw" x 1962)->dump; | ||||
| 298 | |||||
| 299 | As an added convenience, the Digest::SHA module offers routines to | ||||
| 300 | calculate keyed hashes using the HMAC-SHA-1/224/256/384/512 | ||||
| 301 | algorithms. These services exist in functional form only, and | ||||
| 302 | mimic the style and behavior of the I<sha()>, I<sha_hex()>, and | ||||
| 303 | I<sha_base64()> functions. | ||||
| 304 | |||||
| 305 | # Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt | ||||
| 306 | |||||
| 307 | use Digest::SHA qw(hmac_sha256_hex); | ||||
| 308 | print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n"; | ||||
| 309 | |||||
| 310 | =head1 NIST STATEMENT ON SHA-1 | ||||
| 311 | |||||
| 312 | I<NIST was recently informed that researchers had discovered a way | ||||
| 313 | to "break" the current Federal Information Processing Standard SHA-1 | ||||
| 314 | algorithm, which has been in effect since 1994. The researchers | ||||
| 315 | have not yet published their complete results, so NIST has not | ||||
| 316 | confirmed these findings. However, the researchers are a reputable | ||||
| 317 | research team with expertise in this area.> | ||||
| 318 | |||||
| 319 | I<Due to advances in computing power, NIST already planned to phase | ||||
| 320 | out SHA-1 in favor of the larger and stronger hash functions (SHA-224, | ||||
| 321 | SHA-256, SHA-384 and SHA-512) by 2010. New developments should use | ||||
| 322 | the larger and stronger hash functions.> | ||||
| 323 | |||||
| 324 | ref. L<http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20Statement/Burr_Mar2005.html> | ||||
| 325 | |||||
| 326 | =head1 PADDING OF BASE64 DIGESTS | ||||
| 327 | |||||
| 328 | By convention, CPAN Digest modules do B<not> pad their Base64 output. | ||||
| 329 | Problems can occur when feeding such digests to other software that | ||||
| 330 | expects properly padded Base64 encodings. | ||||
| 331 | |||||
| 332 | For the time being, any necessary padding must be done by the user. | ||||
| 333 | Fortunately, this is a simple operation: if the length of a Base64-encoded | ||||
| 334 | digest isn't a multiple of 4, simply append "=" characters to the end | ||||
| 335 | of the digest until it is: | ||||
| 336 | |||||
| 337 | while (length($b64_digest) % 4) { | ||||
| 338 | $b64_digest .= '='; | ||||
| 339 | } | ||||
| 340 | |||||
| 341 | To illustrate, I<sha256_base64("abc")> is computed to be | ||||
| 342 | |||||
| 343 | ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0 | ||||
| 344 | |||||
| 345 | which has a length of 43. So, the properly padded version is | ||||
| 346 | |||||
| 347 | ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0= | ||||
| 348 | |||||
| 349 | =head1 EXPORT | ||||
| 350 | |||||
| 351 | None by default. | ||||
| 352 | |||||
| 353 | =head1 EXPORTABLE FUNCTIONS | ||||
| 354 | |||||
| 355 | Provided your C compiler supports a 64-bit type (e.g. the I<long | ||||
| 356 | long> of C99, or I<__int64> used by Microsoft C/C++), all of these | ||||
| 357 | functions will be available for use. Otherwise, you won't be able | ||||
| 358 | to perform the SHA-384 and SHA-512 transforms, both of which require | ||||
| 359 | 64-bit operations. | ||||
| 360 | |||||
| 361 | I<Functional style> | ||||
| 362 | |||||
| 363 | =over 4 | ||||
| 364 | |||||
| 365 | =item B<sha1($data, ...)> | ||||
| 366 | |||||
| 367 | =item B<sha224($data, ...)> | ||||
| 368 | |||||
| 369 | =item B<sha256($data, ...)> | ||||
| 370 | |||||
| 371 | =item B<sha384($data, ...)> | ||||
| 372 | |||||
| 373 | =item B<sha512($data, ...)> | ||||
| 374 | |||||
| 375 | Logically joins the arguments into a single string, and returns | ||||
| 376 | its SHA-1/224/256/384/512 digest encoded as a binary string. | ||||
| 377 | |||||
| 378 | =item B<sha1_hex($data, ...)> | ||||
| 379 | |||||
| 380 | =item B<sha224_hex($data, ...)> | ||||
| 381 | |||||
| 382 | =item B<sha256_hex($data, ...)> | ||||
| 383 | |||||
| 384 | =item B<sha384_hex($data, ...)> | ||||
| 385 | |||||
| 386 | =item B<sha512_hex($data, ...)> | ||||
| 387 | |||||
| 388 | Logically joins the arguments into a single string, and returns | ||||
| 389 | its SHA-1/224/256/384/512 digest encoded as a hexadecimal string. | ||||
| 390 | |||||
| 391 | =item B<sha1_base64($data, ...)> | ||||
| 392 | |||||
| 393 | =item B<sha224_base64($data, ...)> | ||||
| 394 | |||||
| 395 | =item B<sha256_base64($data, ...)> | ||||
| 396 | |||||
| 397 | =item B<sha384_base64($data, ...)> | ||||
| 398 | |||||
| 399 | =item B<sha512_base64($data, ...)> | ||||
| 400 | |||||
| 401 | Logically joins the arguments into a single string, and returns | ||||
| 402 | its SHA-1/224/256/384/512 digest encoded as a Base64 string. | ||||
| 403 | |||||
| 404 | It's important to note that the resulting string does B<not> contain | ||||
| 405 | the padding characters typical of Base64 encodings. This omission is | ||||
| 406 | deliberate, and is done to maintain compatibility with the family of | ||||
| 407 | CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details. | ||||
| 408 | |||||
| 409 | =back | ||||
| 410 | |||||
| 411 | I<OOP style> | ||||
| 412 | |||||
| 413 | =over 4 | ||||
| 414 | |||||
| 415 | =item B<new($alg)> | ||||
| 416 | |||||
| 417 | Returns a new Digest::SHA object. Allowed values for I<$alg> are | ||||
| 418 | 1, 224, 256, 384, or 512. It's also possible to use common string | ||||
| 419 | representations of the algorithm (e.g. "sha256", "SHA-384"). If | ||||
| 420 | the argument is missing, SHA-1 will be used by default. | ||||
| 421 | |||||
| 422 | Invoking I<new> as an instance method will not create a new object; | ||||
| 423 | instead, it will simply reset the object to the initial state | ||||
| 424 | associated with I<$alg>. If the argument is missing, the object | ||||
| 425 | will continue using the same algorithm that was selected at creation. | ||||
| 426 | |||||
| 427 | =item B<reset($alg)> | ||||
| 428 | |||||
| 429 | This method has exactly the same effect as I<new($alg)>. In fact, | ||||
| 430 | I<reset> is just an alias for I<new>. | ||||
| 431 | |||||
| 432 | =item B<hashsize> | ||||
| 433 | |||||
| 434 | Returns the number of digest bits for this object. The values are | ||||
| 435 | 160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, | ||||
| 436 | and SHA-512, respectively. | ||||
| 437 | |||||
| 438 | =item B<algorithm> | ||||
| 439 | |||||
| 440 | Returns the digest algorithm for this object. The values are 1, | ||||
| 441 | 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and | ||||
| 442 | SHA-512, respectively. | ||||
| 443 | |||||
| 444 | =item B<clone> | ||||
| 445 | |||||
| 446 | Returns a duplicate copy of the object. | ||||
| 447 | |||||
| 448 | =item B<add($data, ...)> | ||||
| 449 | |||||
| 450 | Logically joins the arguments into a single string, and uses it to | ||||
| 451 | update the current digest state. In other words, the following | ||||
| 452 | statements have the same effect: | ||||
| 453 | |||||
| 454 | $sha->add("a"); $sha->add("b"); $sha->add("c"); | ||||
| 455 | $sha->add("a")->add("b")->add("c"); | ||||
| 456 | $sha->add("a", "b", "c"); | ||||
| 457 | $sha->add("abc"); | ||||
| 458 | |||||
| 459 | The return value is the updated object itself. | ||||
| 460 | |||||
| 461 | =item B<add_bits($data, $nbits)> | ||||
| 462 | |||||
| 463 | =item B<add_bits($bits)> | ||||
| 464 | |||||
| 465 | Updates the current digest state by appending bits to it. The | ||||
| 466 | return value is the updated object itself. | ||||
| 467 | |||||
| 468 | The first form causes the most-significant I<$nbits> of I<$data> | ||||
| 469 | to be appended to the stream. The I<$data> argument is in the | ||||
| 470 | customary binary format used for Perl strings. | ||||
| 471 | |||||
| 472 | The second form takes an ASCII string of "0" and "1" characters as | ||||
| 473 | its argument. It's equivalent to | ||||
| 474 | |||||
| 475 | $sha->add_bits(pack("B*", $bits), length($bits)); | ||||
| 476 | |||||
| 477 | So, the following two statements do the same thing: | ||||
| 478 | |||||
| 479 | $sha->add_bits("111100001010"); | ||||
| 480 | $sha->add_bits("\xF0\xA0", 12); | ||||
| 481 | |||||
| 482 | =item B<addfile(*FILE)> | ||||
| 483 | |||||
| 484 | Reads from I<FILE> until EOF, and appends that data to the current | ||||
| 485 | state. The return value is the updated object itself. | ||||
| 486 | |||||
| 487 | =item B<addfile($filename [, $mode])> | ||||
| 488 | |||||
| 489 | Reads the contents of I<$filename>, and appends that data to the current | ||||
| 490 | state. The return value is the updated object itself. | ||||
| 491 | |||||
| 492 | By default, I<$filename> is simply opened and read; no special modes | ||||
| 493 | or I/O disciplines are used. To change this, set the optional I<$mode> | ||||
| 494 | argument to one of the following values: | ||||
| 495 | |||||
| 496 | "b" read file in binary mode | ||||
| 497 | |||||
| 498 | "p" use portable mode | ||||
| 499 | |||||
| 500 | The "p" mode is handy since it ensures that the digest value of | ||||
| 501 | I<$filename> will be the same when computed on different operating | ||||
| 502 | systems. It accomplishes this by internally translating all newlines in | ||||
| 503 | text files to UNIX format before calculating the digest. Binary files | ||||
| 504 | are read in raw mode with no translation whatsoever. | ||||
| 505 | |||||
| 506 | For a fuller discussion of newline formats, refer to CPAN module | ||||
| 507 | L<File::LocalizeNewlines>. Its "universal line separator" regex forms | ||||
| 508 | the basis of I<addfile>'s portable mode processing. | ||||
| 509 | |||||
| 510 | =item B<dump($filename)> | ||||
| 511 | |||||
| 512 | Provides persistent storage of intermediate SHA states by writing | ||||
| 513 | a portable, human-readable representation of the current state to | ||||
| 514 | I<$filename>. If the argument is missing, or equal to the empty | ||||
| 515 | string, the state information will be written to STDOUT. | ||||
| 516 | |||||
| 517 | =item B<load($filename)> | ||||
| 518 | |||||
| 519 | Returns a Digest::SHA object representing the intermediate SHA | ||||
| 520 | state that was previously dumped to I<$filename>. If called as a | ||||
| 521 | class method, a new object is created; if called as an instance | ||||
| 522 | method, the object is reset to the state contained in I<$filename>. | ||||
| 523 | If the argument is missing, or equal to the empty string, the state | ||||
| 524 | information will be read from STDIN. | ||||
| 525 | |||||
| 526 | =item B<digest> | ||||
| 527 | |||||
| 528 | Returns the digest encoded as a binary string. | ||||
| 529 | |||||
| 530 | Note that the I<digest> method is a read-once operation. Once it | ||||
| 531 | has been performed, the Digest::SHA object is automatically reset | ||||
| 532 | in preparation for calculating another digest value. Call | ||||
| 533 | I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the | ||||
| 534 | original digest state. | ||||
| 535 | |||||
| 536 | =item B<hexdigest> | ||||
| 537 | |||||
| 538 | Returns the digest encoded as a hexadecimal string. | ||||
| 539 | |||||
| 540 | Like I<digest>, this method is a read-once operation. Call | ||||
| 541 | I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve | ||||
| 542 | the original digest state. | ||||
| 543 | |||||
| 544 | This method is inherited if L<Digest::base> is installed on your | ||||
| 545 | system. Otherwise, a functionally equivalent substitute is used. | ||||
| 546 | |||||
| 547 | =item B<b64digest> | ||||
| 548 | |||||
| 549 | Returns the digest encoded as a Base64 string. | ||||
| 550 | |||||
| 551 | Like I<digest>, this method is a read-once operation. Call | ||||
| 552 | I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve | ||||
| 553 | the original digest state. | ||||
| 554 | |||||
| 555 | This method is inherited if L<Digest::base> is installed on your | ||||
| 556 | system. Otherwise, a functionally equivalent substitute is used. | ||||
| 557 | |||||
| 558 | It's important to note that the resulting string does B<not> contain | ||||
| 559 | the padding characters typical of Base64 encodings. This omission is | ||||
| 560 | deliberate, and is done to maintain compatibility with the family of | ||||
| 561 | CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details. | ||||
| 562 | |||||
| 563 | =back | ||||
| 564 | |||||
| 565 | I<HMAC-SHA-1/224/256/384/512> | ||||
| 566 | |||||
| 567 | =over 4 | ||||
| 568 | |||||
| 569 | =item B<hmac_sha1($data, $key)> | ||||
| 570 | |||||
| 571 | =item B<hmac_sha224($data, $key)> | ||||
| 572 | |||||
| 573 | =item B<hmac_sha256($data, $key)> | ||||
| 574 | |||||
| 575 | =item B<hmac_sha384($data, $key)> | ||||
| 576 | |||||
| 577 | =item B<hmac_sha512($data, $key)> | ||||
| 578 | |||||
| 579 | Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>, | ||||
| 580 | with the result encoded as a binary string. Multiple I<$data> | ||||
| 581 | arguments are allowed, provided that I<$key> is the last argument | ||||
| 582 | in the list. | ||||
| 583 | |||||
| 584 | =item B<hmac_sha1_hex($data, $key)> | ||||
| 585 | |||||
| 586 | =item B<hmac_sha224_hex($data, $key)> | ||||
| 587 | |||||
| 588 | =item B<hmac_sha256_hex($data, $key)> | ||||
| 589 | |||||
| 590 | =item B<hmac_sha384_hex($data, $key)> | ||||
| 591 | |||||
| 592 | =item B<hmac_sha512_hex($data, $key)> | ||||
| 593 | |||||
| 594 | Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>, | ||||
| 595 | with the result encoded as a hexadecimal string. Multiple I<$data> | ||||
| 596 | arguments are allowed, provided that I<$key> is the last argument | ||||
| 597 | in the list. | ||||
| 598 | |||||
| 599 | =item B<hmac_sha1_base64($data, $key)> | ||||
| 600 | |||||
| 601 | =item B<hmac_sha224_base64($data, $key)> | ||||
| 602 | |||||
| 603 | =item B<hmac_sha256_base64($data, $key)> | ||||
| 604 | |||||
| 605 | =item B<hmac_sha384_base64($data, $key)> | ||||
| 606 | |||||
| 607 | =item B<hmac_sha512_base64($data, $key)> | ||||
| 608 | |||||
| 609 | Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>, | ||||
| 610 | with the result encoded as a Base64 string. Multiple I<$data> | ||||
| 611 | arguments are allowed, provided that I<$key> is the last argument | ||||
| 612 | in the list. | ||||
| 613 | |||||
| 614 | It's important to note that the resulting string does B<not> contain | ||||
| 615 | the padding characters typical of Base64 encodings. This omission is | ||||
| 616 | deliberate, and is done to maintain compatibility with the family of | ||||
| 617 | CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details. | ||||
| 618 | |||||
| 619 | =back | ||||
| 620 | |||||
| 621 | =head1 SEE ALSO | ||||
| 622 | |||||
| 623 | L<Digest>, L<Digest::SHA::PurePerl> | ||||
| 624 | |||||
| 625 | The Secure Hash Standard (FIPS PUB 180-2) can be found at: | ||||
| 626 | |||||
| 627 | L<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf> | ||||
| 628 | |||||
| 629 | The Keyed-Hash Message Authentication Code (HMAC): | ||||
| 630 | |||||
| 631 | L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf> | ||||
| 632 | |||||
| 633 | =head1 AUTHOR | ||||
| 634 | |||||
| 635 | Mark Shelor <mshelor@cpan.org> | ||||
| 636 | |||||
| 637 | =head1 ACKNOWLEDGMENTS | ||||
| 638 | |||||
| 639 | The author is particularly grateful to | ||||
| 640 | |||||
| 641 | Gisle Aas | ||||
| 642 | Chris Carey | ||||
| 643 | Alexandr Ciornii | ||||
| 644 | Jim Doble | ||||
| 645 | Julius Duque | ||||
| 646 | Jeffrey Friedl | ||||
| 647 | Robert Gilmour | ||||
| 648 | Brian Gladman | ||||
| 649 | Adam Kennedy | ||||
| 650 | Andy Lester | ||||
| 651 | Alex Muntada | ||||
| 652 | Steve Peters | ||||
| 653 | Chris Skiscim | ||||
| 654 | Martin Thurn | ||||
| 655 | Gunnar Wolf | ||||
| 656 | Adam Woodbury | ||||
| 657 | |||||
| 658 | for their valuable comments and suggestions. | ||||
| 659 | |||||
| 660 | =head1 COPYRIGHT AND LICENSE | ||||
| 661 | |||||
| 662 | Copyright (C) 2003-2008 Mark Shelor | ||||
| 663 | |||||
| 664 | This library is free software; you can redistribute it and/or modify | ||||
| 665 | it under the same terms as Perl itself. | ||||
| 666 | |||||
| 667 | L<perlartistic> | ||||
| 668 | |||||
| 669 | =cut | ||||
# spent 97µs within Digest::SHA::bootstrap which was called
# once (97µs+0s) by DynaLoader::bootstrap at line 227 of DynaLoader.pm | |||||
# spent 89µs within Digest::SHA::hmac_sha256_base64 which was called 3 times, avg 30µs/call:
# 3 times (89µs+0s) by SimpleDB::Client::construct_request at line 173 of ../lib/SimpleDB/Client.pm, avg 30µs/call |