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