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