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 | BEGIN@6 | Digest::SHA::
1 | 1 | 2 | 97µs | 97µs | bootstrap (xsub) | Digest::SHA::
3 | 1 | 2 | 89µs | 89µs | hmac_sha256_base64 (xsub) | Digest::SHA::
1 | 1 | 1 | 15µs | 18µs | BEGIN@5 | Digest::SHA::
1 | 1 | 1 | 8µs | 67µs | BEGIN@7 | Digest::SHA::
0 | 0 | 0 | 0s | 0s | Addfile | Digest::SHA::
0 | 0 | 0 | 0s | 0s | DESTROY | Digest::SHA::
0 | 0 | 0 | 0s | 0s | _addfile | Digest::SHA::
0 | 0 | 0 | 0s | 0s | _bail | Digest::SHA::
0 | 0 | 0 | 0s | 0s | add_bits | Digest::SHA::
0 | 0 | 0 | 0s | 0s | clone | Digest::SHA::
0 | 0 | 0 | 0s | 0s | dump | Digest::SHA::
0 | 0 | 0 | 0s | 0s | load | Digest::SHA::
0 | 0 | 0 | 0s | 0s | new | Digest::SHA::
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 | 4 | 8.48ms | eval { | ||
31 | require MIME::Base64; | ||||
32 | require Digest::base; | ||||
33 | 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 |