This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to Digest-SHA-5.44.
[perl5.git] / ext / Digest / SHA / SHA.pm
1 package Digest::SHA;
2
3 require 5.006000;
4
5 use strict;
6 use warnings;
7 use integer;
8
9 our $VERSION = '5.44';
10
11 require Exporter;
12 our @ISA = qw(Exporter);
13
14 our @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 *addfile = \&Addfile;
29
30 eval {
31         require MIME::Base64;
32         require Digest::base;
33         push(@ISA, 'Digest::base');
34 };
35 if ($@) {
36         *hexdigest = \&Hexdigest;
37         *b64digest = \&B64digest;
38 }
39
40 require XSLoader;
41 XSLoader::load('Digest::SHA', $VERSION);
42
43 # Preloaded methods go here.
44
45 # The following routines aren't time-critical, so they can be left in Perl
46
47 sub new {
48         my($class, $alg) = @_;
49         $alg =~ s/\D+//g if defined $alg;
50         if (ref($class)) {      # instance method
51                 unless (defined($alg) && ($alg != $class->algorithm)) {
52                         sharewind($$class);
53                         return($class);
54                 }
55                 shaclose($$class) if $$class;
56                 $$class = shaopen($alg) || return;
57                 return($class);
58         }
59         $alg = 1 unless defined $alg;
60         my $state = shaopen($alg) || return;
61         my $self = \$state;
62         bless($self, $class);
63         return($self);
64 }
65
66 sub DESTROY {
67         my $self = shift;
68         shaclose($$self) if $$self;
69 }
70
71 sub clone {
72         my $self = shift;
73         my $state = shadup($$self) || return;
74         my $copy = \$state;
75         bless($copy, ref($self));
76         return($copy);
77 }
78
79 *reset = \&new;
80
81 sub add_bits {
82         my($self, $data, $nbits) = @_;
83         unless (defined $nbits) {
84                 $nbits = length($data);
85                 $data = pack("B*", $data);
86         }
87         shawrite($data, $nbits, $$self);
88         return($self);
89 }
90
91 sub _bail {
92         my $msg = shift;
93
94         require Carp;
95         Carp::croak("$msg: $!");
96 }
97
98 sub _addfile {  # this is "addfile" from Digest::base 1.00
99     my ($self, $handle) = @_;
100
101     my $n;
102     my $buf = "";
103
104     while (($n = read($handle, $buf, 4096))) {
105         $self->add($buf);
106     }
107     _bail("Read failed") unless defined $n;
108
109     $self;
110 }
111
112 sub Addfile {
113         my ($self, $file, $mode) = @_;
114
115         return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR';
116
117         $mode = defined($mode) ? $mode : "";
118         my ($binary, $portable) = map { $_ eq $mode } ("b", "p");
119         my $text = -T $file;
120
121         open(my $fh, "<$file")                  ## no critic
122                 or _bail("Open failed");
123         binmode($fh) if $binary || $portable;
124
125         unless ($portable && $text) {
126                 $self->_addfile($fh);
127                 close($fh);
128                 return($self);
129         }
130
131         my ($n1, $n2);
132         my ($buf1, $buf2) = ("", "");
133
134         while (($n1 = read($fh, $buf1, 4096))) {
135                 while (substr($buf1, -1) eq "\015") {
136                         $n2 = read($fh, $buf2, 4096);
137                         _bail("Read failed") unless defined $n2;
138                         last unless $n2;
139                         $buf1 .= $buf2;
140                 }
141                 $buf1 =~ s/\015?\015\012/\012/g;        # DOS/Windows
142                 $buf1 =~ s/\015/\012/g;                 # Apple/MacOS 9
143                 $self->add($buf1);
144         }
145         _bail("Read failed") unless defined $n1;
146         close($fh);
147
148         $self;
149 }
150
151 sub dump {
152         my $self = shift;
153         my $file = shift || "";
154
155         shadump($file, $$self) || return;
156         return($self);
157 }
158
159 sub load {
160         my $class = shift;
161         my $file = shift || "";
162         if (ref($class)) {      # instance method
163                 shaclose($$class) if $$class;
164                 $$class = shaload($file) || return;
165                 return($class);
166         }
167         my $state = shaload($file) || return;
168         my $self = \$state;
169         bless($self, $class);
170         return($self);
171 }
172
173 1;
174 __END__
175
176 =head1 NAME
177
178 Digest::SHA - Perl extension for SHA-1/224/256/384/512
179
180 =head1 SYNOPSIS (SHA)
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</"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
503 in text files to UNIX format before calculating the digest; on the other
504 hand, binary files 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</"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</"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         Julius Duque
644         Jeffrey Friedl
645         Robert Gilmour
646         Brian Gladman
647         Adam Kennedy
648         Andy Lester
649         Alex Muntada
650         Steve Peters
651         Chris Skiscim
652         Martin Thurn
653         Gunnar Wolf
654         Adam Woodbury
655
656 for their valuable comments and suggestions.
657
658 =head1 COPYRIGHT AND LICENSE
659
660 Copyright (C) 2003-2006 Mark Shelor
661
662 This library is free software; you can redistribute it and/or modify
663 it under the same terms as Perl itself.
664
665 L<perlartistic>
666
667 =cut