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