This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to Digest-SHA-5.41
[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.41';
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         local *F;
122         _bail("Open failed") unless open(F, "<$file");
123         binmode(F) if $binary || $portable;
124
125         unless ($portable && $text) {
126                 $self->_addfile(*F);
127                 close(F);
128                 return($self);
129         }
130
131         my ($n1, $n2);
132         my ($buf1, $buf2) = ("", "");
133
134         while (($n1 = read(F, $buf1, 4096))) {
135                 while (substr($buf1, -1) eq "\015") {
136                         $n2 = read(F, $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(F);
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 EXPORT
327
328 None by default.
329
330 =head1 EXPORTABLE FUNCTIONS
331
332 Provided your C compiler supports a 64-bit type (e.g. the I<long
333 long> of C99, or I<__int64> used by Microsoft C/C++), all of these
334 functions will be available for use.  Otherwise, you won't be able
335 to perform the SHA-384 and SHA-512 transforms, both of which require
336 64-bit operations.
337
338 I<Functional style>
339
340 =over 4
341
342 =item B<sha1($data, ...)>
343
344 =item B<sha224($data, ...)>
345
346 =item B<sha256($data, ...)>
347
348 =item B<sha384($data, ...)>
349
350 =item B<sha512($data, ...)>
351
352 Logically joins the arguments into a single string, and returns
353 its SHA-1/224/256/384/512 digest encoded as a binary string.
354
355 =item B<sha1_hex($data, ...)>
356
357 =item B<sha224_hex($data, ...)>
358
359 =item B<sha256_hex($data, ...)>
360
361 =item B<sha384_hex($data, ...)>
362
363 =item B<sha512_hex($data, ...)>
364
365 Logically joins the arguments into a single string, and returns
366 its SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
367
368 =item B<sha1_base64($data, ...)>
369
370 =item B<sha224_base64($data, ...)>
371
372 =item B<sha256_base64($data, ...)>
373
374 =item B<sha384_base64($data, ...)>
375
376 =item B<sha512_base64($data, ...)>
377
378 Logically joins the arguments into a single string, and returns
379 its SHA-1/224/256/384/512 digest encoded as a Base64 string.
380
381 =back
382
383 I<OOP style>
384
385 =over 4
386
387 =item B<new($alg)>
388
389 Returns a new Digest::SHA object.  Allowed values for I<$alg> are
390 1, 224, 256, 384, or 512.  It's also possible to use common string
391 representations of the algorithm (e.g. "sha256", "SHA-384").  If
392 the argument is missing, SHA-1 will be used by default.
393
394 Invoking I<new> as an instance method will not create a new object;
395 instead, it will simply reset the object to the initial state
396 associated with I<$alg>.  If the argument is missing, the object
397 will continue using the same algorithm that was selected at creation.
398
399 =item B<reset($alg)>
400
401 This method has exactly the same effect as I<new($alg)>.  In fact,
402 I<reset> is just an alias for I<new>.
403
404 =item B<hashsize>
405
406 Returns the number of digest bits for this object.  The values are
407 160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384,
408 and SHA-512, respectively.
409
410 =item B<algorithm>
411
412 Returns the digest algorithm for this object.  The values are 1,
413 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and
414 SHA-512, respectively.
415
416 =item B<clone>
417
418 Returns a duplicate copy of the object.
419
420 =item B<add($data, ...)>
421
422 Logically joins the arguments into a single string, and uses it to
423 update the current digest state.  In other words, the following
424 statements have the same effect:
425
426         $sha->add("a"); $sha->add("b"); $sha->add("c");
427         $sha->add("a")->add("b")->add("c");
428         $sha->add("a", "b", "c");
429         $sha->add("abc");
430
431 The return value is the updated object itself.
432
433 =item B<add_bits($data, $nbits)>
434
435 =item B<add_bits($bits)>
436
437 Updates the current digest state by appending bits to it.  The
438 return value is the updated object itself.
439
440 The first form causes the most-significant I<$nbits> of I<$data>
441 to be appended to the stream.  The I<$data> argument is in the
442 customary binary format used for Perl strings.
443
444 The second form takes an ASCII string of "0" and "1" characters as
445 its argument.  It's equivalent to
446
447         $sha->add_bits(pack("B*", $bits), length($bits));
448
449 So, the following two statements do the same thing:
450
451         $sha->add_bits("111100001010");
452         $sha->add_bits("\xF0\xA0", 12);
453
454 =item B<addfile(*FILE)>
455
456 Reads from I<FILE> until EOF, and appends that data to the current
457 state.  The return value is the updated object itself.
458
459 =item B<addfile($filename [, $mode])>
460
461 Reads the contents of I<$filename>, and appends that data to the current
462 state.  The return value is the updated object itself.
463
464 By default, I<$filename> is simply opened and read; no special modes
465 or I/O disciplines are used.  To change this, set the optional I<$mode>
466 argument to one of the following values:
467
468         "b"     read file in binary mode
469
470         "p"     use portable mode
471
472 The "p" mode is handy since it ensures that the digest value of
473 I<$filename> will be the same when computed on different operating
474 systems.  It accomplishes this by internally translating all newlines
475 in text files to UNIX format before calculating the digest; on the other
476 hand, binary files are read in raw mode with no translation whatsoever.
477
478 For a fuller discussion of newline formats, refer to CPAN module
479 L<File::LocalizeNewlines>.  Its "universal line separator" regex forms
480 the basis of I<addfile>'s portable mode processing.
481
482 =item B<dump($filename)>
483
484 Provides persistent storage of intermediate SHA states by writing
485 a portable, human-readable representation of the current state to
486 I<$filename>.  If the argument is missing, or equal to the empty
487 string, the state information will be written to STDOUT.
488
489 =item B<load($filename)>
490
491 Returns a Digest::SHA object representing the intermediate SHA
492 state that was previously dumped to I<$filename>.  If called as a
493 class method, a new object is created; if called as an instance
494 method, the object is reset to the state contained in I<$filename>.
495 If the argument is missing, or equal to the empty string, the state
496 information will be read from STDIN.
497
498 =item B<digest>
499
500 Returns the digest encoded as a binary string.
501
502 Note that the I<digest> method is a read-once operation. Once it
503 has been performed, the Digest::SHA object is automatically reset
504 in preparation for calculating another digest value.  Call
505 I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
506 original digest state.
507
508 =item B<hexdigest>
509
510 Returns the digest encoded as a hexadecimal string.
511
512 Like I<digest>, this method is a read-once operation.  Call
513 I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve
514 the original digest state.
515
516 This method is inherited if L<Digest::base> is installed on your
517 system.  Otherwise, a functionally equivalent substitute is used.
518
519 =item B<b64digest>
520
521 Returns the digest encoded as a Base64 string.
522
523 Like I<digest>, this method is a read-once operation.  Call
524 I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve
525 the original digest state.
526
527 This method is inherited if L<Digest::base> is installed on your
528 system.  Otherwise, a functionally equivalent substitute is used.
529
530 =back
531
532 I<HMAC-SHA-1/224/256/384/512>
533
534 =over 4
535
536 =item B<hmac_sha1($data, $key)>
537
538 =item B<hmac_sha224($data, $key)>
539
540 =item B<hmac_sha256($data, $key)>
541
542 =item B<hmac_sha384($data, $key)>
543
544 =item B<hmac_sha512($data, $key)>
545
546 Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
547 with the result encoded as a binary string.  Multiple I<$data>
548 arguments are allowed, provided that I<$key> is the last argument
549 in the list.
550
551 =item B<hmac_sha1_hex($data, $key)>
552
553 =item B<hmac_sha224_hex($data, $key)>
554
555 =item B<hmac_sha256_hex($data, $key)>
556
557 =item B<hmac_sha384_hex($data, $key)>
558
559 =item B<hmac_sha512_hex($data, $key)>
560
561 Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
562 with the result encoded as a hexadecimal string.  Multiple I<$data>
563 arguments are allowed, provided that I<$key> is the last argument
564 in the list.
565
566 =item B<hmac_sha1_base64($data, $key)>
567
568 =item B<hmac_sha224_base64($data, $key)>
569
570 =item B<hmac_sha256_base64($data, $key)>
571
572 =item B<hmac_sha384_base64($data, $key)>
573
574 =item B<hmac_sha512_base64($data, $key)>
575
576 Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
577 with the result encoded as a Base64 string.  Multiple I<$data>
578 arguments are allowed, provided that I<$key> is the last argument
579 in the list.
580
581 =back
582
583 =head1 SEE ALSO
584
585 L<Digest>, L<Digest::SHA::PurePerl>
586
587 The Secure Hash Standard (FIPS PUB 180-2) can be found at:
588
589 L<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>
590
591 The Keyed-Hash Message Authentication Code (HMAC):
592
593 L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
594
595 =head1 AUTHOR
596
597         Mark Shelor     <mshelor@cpan.org>
598
599 =head1 ACKNOWLEDGMENTS
600
601 The author is particularly grateful to
602
603         Gisle Aas
604         Chris Carey
605         Julius Duque
606         Jeffrey Friedl
607         Robert Gilmour
608         Brian Gladman
609         Adam Kennedy
610         Andy Lester
611         Alex Muntada
612         Steve Peters
613         Chris Skiscim
614         Martin Thurn
615         Gunnar Wolf
616         Adam Woodbury
617
618 for their valuable comments and suggestions.
619
620 =head1 COPYRIGHT AND LICENSE
621
622 Copyright (C) 2003-2006 Mark Shelor
623
624 This library is free software; you can redistribute it and/or modify
625 it under the same terms as Perl itself.
626
627 L<perlartistic>
628
629 =cut