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