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.97
[perl5.git] / cpan / Digest-SHA / lib / Digest / SHA.pm
1 package Digest::SHA;
2
3 require 5.003000;
4
5 use strict;
6 use warnings;
7 use vars qw($VERSION @ISA @EXPORT_OK);
8 use Fcntl qw(O_RDONLY);
9 use integer;
10
11 $VERSION = '5.97';
12
13 require Exporter;
14 require DynaLoader;
15 @ISA = qw(Exporter DynaLoader);
16 @EXPORT_OK = qw(
17         hmac_sha1       hmac_sha1_base64        hmac_sha1_hex
18         hmac_sha224     hmac_sha224_base64      hmac_sha224_hex
19         hmac_sha256     hmac_sha256_base64      hmac_sha256_hex
20         hmac_sha384     hmac_sha384_base64      hmac_sha384_hex
21         hmac_sha512     hmac_sha512_base64      hmac_sha512_hex
22         hmac_sha512224  hmac_sha512224_base64   hmac_sha512224_hex
23         hmac_sha512256  hmac_sha512256_base64   hmac_sha512256_hex
24         sha1            sha1_base64             sha1_hex
25         sha224          sha224_base64           sha224_hex
26         sha256          sha256_base64           sha256_hex
27         sha384          sha384_base64           sha384_hex
28         sha512          sha512_base64           sha512_hex
29         sha512224       sha512224_base64        sha512224_hex
30         sha512256       sha512256_base64        sha512256_hex);
31
32 # Inherit from Digest::base if possible
33
34 eval {
35         require Digest::base;
36         push(@ISA, 'Digest::base');
37 };
38
39 # The following routines aren't time-critical, so they can be left in Perl
40
41 sub new {
42         my($class, $alg) = @_;
43         $alg =~ s/\D+//g if defined $alg;
44         if (ref($class)) {      # instance method
45                 if (!defined($alg) || ($alg == $class->algorithm)) {
46                         sharewind($class);
47                         return($class);
48                 }
49                 return shainit($class, $alg) ? $class : undef;
50         }
51         $alg = 1 unless defined $alg;
52         return $class->newSHA($alg);
53 }
54
55 BEGIN { *reset = \&new }
56
57 sub add_bits {
58         my($self, $data, $nbits) = @_;
59         unless (defined $nbits) {
60                 $nbits = length($data);
61                 $data = pack("B*", $data);
62         }
63         $nbits = length($data) * 8 if $nbits > length($data) * 8;
64         shawrite($data, $nbits, $self);
65         return($self);
66 }
67
68 sub _bail {
69         my $msg = shift;
70
71         $msg .= ": $!";
72         require Carp;
73         Carp::croak($msg);
74 }
75
76 {
77         my $_can_T_filehandle;
78
79         sub _istext {
80                 local *FH = shift;
81                 my $file = shift;
82
83                 if (! defined $_can_T_filehandle) {
84                         local $^W = 0;
85                         my $istext = eval { -T FH };
86                         $_can_T_filehandle = $@ ? 0 : 1;
87                         return $_can_T_filehandle ? $istext : -T $file;
88                 }
89                 return $_can_T_filehandle ? -T FH : -T $file;
90         }
91 }
92
93 sub _addfile {
94         my ($self, $handle) = @_;
95
96         my $n;
97         my $buf = "";
98
99         while (($n = read($handle, $buf, 4096))) {
100                 $self->add($buf);
101         }
102         _bail("Read failed") unless defined $n;
103
104         $self;
105 }
106
107 sub addfile {
108         my ($self, $file, $mode) = @_;
109
110         return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR';
111
112         $mode = defined($mode) ? $mode : "";
113         my ($binary, $UNIVERSAL, $BITS, $portable) =
114                 map { $_ eq $mode } ("b", "U", "0", "p");
115
116                 ## Always interpret "-" to mean STDIN; otherwise use
117                 ## sysopen to handle full range of POSIX file names
118
119         local *FH;
120         $file eq '-' and open(FH, '< -')
121                 or sysopen(FH, $file, O_RDONLY)
122                         or _bail('Open failed');
123
124         if ($BITS) {
125                 my ($n, $buf) = (0, "");
126                 while (($n = read(FH, $buf, 4096))) {
127                         $buf =~ s/[^01]//g;
128                         $self->add_bits($buf);
129                 }
130                 _bail("Read failed") unless defined $n;
131                 close(FH);
132                 return($self);
133         }
134
135         binmode(FH) if $binary || $portable || $UNIVERSAL;
136         if ($UNIVERSAL && _istext(*FH, $file)) {
137                 $self->_addfileuniv(*FH);
138         }
139         elsif ($portable && _istext(*FH, $file)) {
140                 while (<FH>) {
141                         s/\015?\015\012/\012/g;
142                         s/\015/\012/g;
143                         $self->add($_);
144                 }
145         }
146         else { $self->_addfilebin(*FH) }
147         close(FH);
148
149         $self;
150 }
151
152 sub getstate {
153         my $self = shift;
154
155         my $alg = $self->algorithm or return;
156         my $state = $self->_getstate or return;
157         my $nD = $alg <= 256 ?  8 :  16;
158         my $nH = $alg <= 256 ? 32 :  64;
159         my $nB = $alg <= 256 ? 64 : 128;
160         my($H, $block, $blockcnt, $lenhh, $lenhl, $lenlh, $lenll) =
161                 $state =~ /^(.{$nH})(.{$nB})(.{4})(.{4})(.{4})(.{4})(.{4})$/s;
162         for ($alg, $H, $block, $blockcnt, $lenhh, $lenhl, $lenlh, $lenll) {
163                 return unless defined $_;
164         }
165
166         my @s = ();
167         push(@s, "alg:" . $alg);
168         push(@s, "H:" . join(":", unpack("H*", $H) =~ /.{$nD}/g));
169         push(@s, "block:" . join(":", unpack("H*", $block) =~ /.{2}/g));
170         push(@s, "blockcnt:" . unpack("N", $blockcnt));
171         push(@s, "lenhh:" . unpack("N", $lenhh));
172         push(@s, "lenhl:" . unpack("N", $lenhl));
173         push(@s, "lenlh:" . unpack("N", $lenlh));
174         push(@s, "lenll:" . unpack("N", $lenll));
175         join("\n", @s) . "\n";
176 }
177
178 sub putstate {
179         my($class, $state) = @_;
180
181         my %s = ();
182         for (split(/\n/, $state)) {
183                 s/^\s+//;
184                 s/\s+$//;
185                 next if (/^(#|$)/);
186                 my @f = split(/[:\s]+/);
187                 my $tag = shift(@f);
188                 $s{$tag} = join('', @f);
189         }
190
191         # H and block may contain arbitrary values, but check everything else
192         grep { $_ == $s{'alg'} } (1,224,256,384,512,512224,512256) or return;
193         length($s{'H'}) == ($s{'alg'} <= 256 ? 64 : 128) or return;
194         length($s{'block'}) == ($s{'alg'} <= 256 ? 128 : 256) or return;
195         {
196                 no integer;
197                 for (qw(blockcnt lenhh lenhl lenlh lenll)) {
198                         0 <= $s{$_} or return;
199                         $s{$_} <= 4294967295 or return;
200                 }
201                 $s{'blockcnt'} < ($s{'alg'} <= 256 ? 512 : 1024) or return;
202         }
203
204         my $packed_state = (
205                 pack("H*", $s{'H'}) .
206                 pack("H*", $s{'block'}) .
207                 pack("N",  $s{'blockcnt'}) .
208                 pack("N",  $s{'lenhh'}) .
209                 pack("N",  $s{'lenhl'}) .
210                 pack("N",  $s{'lenlh'}) .
211                 pack("N",  $s{'lenll'})
212         );
213
214         return $class->new($s{'alg'})->_putstate($packed_state);
215 }
216
217 sub dump {
218         my $self = shift;
219         my $file = shift;
220
221         my $state = $self->getstate or return;
222         $file = "-" if (!defined($file) || $file eq "");
223
224         local *FH;
225         open(FH, "> $file") or return;
226         print FH $state;
227         close(FH);
228
229         return($self);
230 }
231
232 sub load {
233         my $class = shift;
234         my $file = shift;
235
236         $file = "-" if (!defined($file) || $file eq "");
237
238         local *FH;
239         open(FH, "< $file") or return;
240         my $str = join('', <FH>);
241         close(FH);
242
243         $class->putstate($str);
244 }
245
246 Digest::SHA->bootstrap($VERSION);
247
248 1;
249 __END__
250
251 =head1 NAME
252
253 Digest::SHA - Perl extension for SHA-1/224/256/384/512
254
255 =head1 SYNOPSIS
256
257 In programs:
258
259                 # Functional interface
260
261         use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
262
263         $digest = sha1($data);
264         $digest = sha1_hex($data);
265         $digest = sha1_base64($data);
266
267         $digest = sha256($data);
268         $digest = sha384_hex($data);
269         $digest = sha512_base64($data);
270
271                 # Object-oriented
272
273         use Digest::SHA;
274
275         $sha = Digest::SHA->new($alg);
276
277         $sha->add($data);               # feed data into stream
278
279         $sha->addfile(*F);
280         $sha->addfile($filename);
281
282         $sha->add_bits($bits);
283         $sha->add_bits($data, $nbits);
284
285         $sha_copy = $sha->clone;        # make copy of digest object
286         $state = $sha->getstate;        # save current state to string
287         $sha->putstate($state);         # restore previous $state
288
289         $digest = $sha->digest;         # compute digest
290         $digest = $sha->hexdigest;
291         $digest = $sha->b64digest;
292
293 From the command line:
294
295         $ shasum files
296
297         $ shasum --help
298
299 =head1 SYNOPSIS (HMAC-SHA)
300
301                 # Functional interface only
302
303         use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
304
305         $digest = hmac_sha1($data, $key);
306         $digest = hmac_sha224_hex($data, $key);
307         $digest = hmac_sha256_base64($data, $key);
308
309 =head1 ABSTRACT
310
311 Digest::SHA is a complete implementation of the NIST Secure Hash Standard.
312 It gives Perl programmers a convenient way to calculate SHA-1, SHA-224,
313 SHA-256, SHA-384, SHA-512, SHA-512/224, and SHA-512/256 message digests.
314 The module can handle all types of input, including partial-byte data.
315
316 =head1 DESCRIPTION
317
318 Digest::SHA is written in C for speed.  If your platform lacks a
319 C compiler, you can install the functionally equivalent (but much
320 slower) L<Digest::SHA::PurePerl> module.
321
322 The programming interface is easy to use: it's the same one found
323 in CPAN's L<Digest> module.  So, if your applications currently
324 use L<Digest::MD5> and you'd prefer the stronger security of SHA,
325 it's a simple matter to convert them.
326
327 The interface provides two ways to calculate digests:  all-at-once,
328 or in stages.  To illustrate, the following short program computes
329 the SHA-256 digest of "hello world" using each approach:
330
331         use Digest::SHA qw(sha256_hex);
332
333         $data = "hello world";
334         @frags = split(//, $data);
335
336         # all-at-once (Functional style)
337         $digest1 = sha256_hex($data);
338
339         # in-stages (OOP style)
340         $state = Digest::SHA->new(256);
341         for (@frags) { $state->add($_) }
342         $digest2 = $state->hexdigest;
343
344         print $digest1 eq $digest2 ?
345                 "whew!\n" : "oops!\n";
346
347 To calculate the digest of an n-bit message where I<n> is not a
348 multiple of 8, use the I<add_bits()> method.  For example, consider
349 the 446-bit message consisting of the bit-string "110" repeated
350 148 times, followed by "11".  Here's how to display its SHA-1
351 digest:
352
353         use Digest::SHA;
354         $bits = "110" x 148 . "11";
355         $sha = Digest::SHA->new(1)->add_bits($bits);
356         print $sha->hexdigest, "\n";
357
358 Note that for larger bit-strings, it's more efficient to use the
359 two-argument version I<add_bits($data, $nbits)>, where I<$data> is
360 in the customary packed binary format used for Perl strings.
361
362 The module also lets you save intermediate SHA states to a string.  The
363 I<getstate()> method generates portable, human-readable text describing
364 the current state of computation.  You can subsequently restore that
365 state with I<putstate()> to resume where the calculation left off.
366
367 To see what a state description looks like, just run the following:
368
369         use Digest::SHA;
370         print Digest::SHA->new->add("Shaw" x 1962)->getstate;
371
372 As an added convenience, the Digest::SHA module offers routines to
373 calculate keyed hashes using the HMAC-SHA-1/224/256/384/512
374 algorithms.  These services exist in functional form only, and
375 mimic the style and behavior of the I<sha()>, I<sha_hex()>, and
376 I<sha_base64()> functions.
377
378         # Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt
379
380         use Digest::SHA qw(hmac_sha256_hex);
381         print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
382
383 =head1 UNICODE AND SIDE EFFECTS
384
385 Perl supports Unicode strings as of version 5.6.  Such strings may
386 contain wide characters, namely, characters whose ordinal values are
387 greater than 255.  This can cause problems for digest algorithms such
388 as SHA that are specified to operate on sequences of bytes.
389
390 The rule by which Digest::SHA handles a Unicode string is easy
391 to state, but potentially confusing to grasp: the string is interpreted
392 as a sequence of byte values, where each byte value is equal to the
393 ordinal value (viz. code point) of its corresponding Unicode character.
394 That way, the Unicode string 'abc' has exactly the same digest value as
395 the ordinary string 'abc'.
396
397 Since a wide character does not fit into a byte, the Digest::SHA
398 routines croak if they encounter one.  Whereas if a Unicode string
399 contains no wide characters, the module accepts it quite happily.
400 The following code illustrates the two cases:
401
402         $str1 = pack('U*', (0..255));
403         print sha1_hex($str1);          # ok
404
405         $str2 = pack('U*', (0..256));
406         print sha1_hex($str2);          # croaks
407
408 Be aware that the digest routines silently convert UTF-8 input into its
409 equivalent byte sequence in the native encoding (cf. utf8::downgrade).
410 This side effect influences only the way Perl stores the data internally,
411 but otherwise leaves the actual value of the data intact.
412
413 =head1 NIST STATEMENT ON SHA-1
414
415 NIST acknowledges that the work of Prof. Xiaoyun Wang constitutes a
416 practical collision attack on SHA-1.  Therefore, NIST encourages the
417 rapid adoption of the SHA-2 hash functions (e.g. SHA-256) for applications
418 requiring strong collision resistance, such as digital signatures.
419
420 ref. L<http://csrc.nist.gov/groups/ST/hash/statement.html>
421
422 =head1 PADDING OF BASE64 DIGESTS
423
424 By convention, CPAN Digest modules do B<not> pad their Base64 output.
425 Problems can occur when feeding such digests to other software that
426 expects properly padded Base64 encodings.
427
428 For the time being, any necessary padding must be done by the user.
429 Fortunately, this is a simple operation: if the length of a Base64-encoded
430 digest isn't a multiple of 4, simply append "=" characters to the end
431 of the digest until it is:
432
433         while (length($b64_digest) % 4) {
434                 $b64_digest .= '=';
435         }
436
437 To illustrate, I<sha256_base64("abc")> is computed to be
438
439         ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
440
441 which has a length of 43.  So, the properly padded version is
442
443         ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
444
445 =head1 EXPORT
446
447 None by default.
448
449 =head1 EXPORTABLE FUNCTIONS
450
451 Provided your C compiler supports a 64-bit type (e.g. the I<long
452 long> of C99, or I<__int64> used by Microsoft C/C++), all of these
453 functions will be available for use.  Otherwise, you won't be able
454 to perform the SHA-384 and SHA-512 transforms, both of which require
455 64-bit operations.
456
457 I<Functional style>
458
459 =over 4
460
461 =item B<sha1($data, ...)>
462
463 =item B<sha224($data, ...)>
464
465 =item B<sha256($data, ...)>
466
467 =item B<sha384($data, ...)>
468
469 =item B<sha512($data, ...)>
470
471 =item B<sha512224($data, ...)>
472
473 =item B<sha512256($data, ...)>
474
475 Logically joins the arguments into a single string, and returns
476 its SHA-1/224/256/384/512 digest encoded as a binary string.
477
478 =item B<sha1_hex($data, ...)>
479
480 =item B<sha224_hex($data, ...)>
481
482 =item B<sha256_hex($data, ...)>
483
484 =item B<sha384_hex($data, ...)>
485
486 =item B<sha512_hex($data, ...)>
487
488 =item B<sha512224_hex($data, ...)>
489
490 =item B<sha512256_hex($data, ...)>
491
492 Logically joins the arguments into a single string, and returns
493 its SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
494
495 =item B<sha1_base64($data, ...)>
496
497 =item B<sha224_base64($data, ...)>
498
499 =item B<sha256_base64($data, ...)>
500
501 =item B<sha384_base64($data, ...)>
502
503 =item B<sha512_base64($data, ...)>
504
505 =item B<sha512224_base64($data, ...)>
506
507 =item B<sha512256_base64($data, ...)>
508
509 Logically joins the arguments into a single string, and returns
510 its SHA-1/224/256/384/512 digest encoded as a Base64 string.
511
512 It's important to note that the resulting string does B<not> contain
513 the padding characters typical of Base64 encodings.  This omission is
514 deliberate, and is done to maintain compatibility with the family of
515 CPAN Digest modules.  See L</"PADDING OF BASE64 DIGESTS"> for details.
516
517 =back
518
519 I<OOP style>
520
521 =over 4
522
523 =item B<new($alg)>
524
525 Returns a new Digest::SHA object.  Allowed values for I<$alg> are 1,
526 224, 256, 384, 512, 512224, or 512256.  It's also possible to use
527 common string representations of the algorithm (e.g. "sha256",
528 "SHA-384").  If the argument is missing, SHA-1 will be used by
529 default.
530
531 Invoking I<new> as an instance method will reset the object to the
532 initial state associated with I<$alg>.  If the argument is missing,
533 the object will continue using the same algorithm that was selected
534 at creation.
535
536 =item B<reset($alg)>
537
538 This method has exactly the same effect as I<new($alg)>.  In fact,
539 I<reset> is just an alias for I<new>.
540
541 =item B<hashsize>
542
543 Returns the number of digest bits for this object.  The values are
544 160, 224, 256, 384, 512, 224, and 256 for SHA-1, SHA-224, SHA-256,
545 SHA-384, SHA-512, SHA-512/224 and SHA-512/256, respectively.
546
547 =item B<algorithm>
548
549 Returns the digest algorithm for this object.  The values are 1,
550 224, 256, 384, 512, 512224, and 512256 for SHA-1, SHA-224, SHA-256,
551 SHA-384, SHA-512, SHA-512/224, and SHA-512/256, respectively.
552
553 =item B<clone>
554
555 Returns a duplicate copy of the object.
556
557 =item B<add($data, ...)>
558
559 Logically joins the arguments into a single string, and uses it to
560 update the current digest state.  In other words, the following
561 statements have the same effect:
562
563         $sha->add("a"); $sha->add("b"); $sha->add("c");
564         $sha->add("a")->add("b")->add("c");
565         $sha->add("a", "b", "c");
566         $sha->add("abc");
567
568 The return value is the updated object itself.
569
570 =item B<add_bits($data, $nbits)>
571
572 =item B<add_bits($bits)>
573
574 Updates the current digest state by appending bits to it.  The
575 return value is the updated object itself.
576
577 The first form causes the most-significant I<$nbits> of I<$data>
578 to be appended to the stream.  The I<$data> argument is in the
579 customary binary format used for Perl strings.
580
581 The second form takes an ASCII string of "0" and "1" characters as
582 its argument.  It's equivalent to
583
584         $sha->add_bits(pack("B*", $bits), length($bits));
585
586 So, the following two statements do the same thing:
587
588         $sha->add_bits("111100001010");
589         $sha->add_bits("\xF0\xA0", 12);
590
591 Note that SHA-1 and SHA-2 use I<most-significant-bit ordering>
592 for their internal state.  This means that
593
594         $sha3->add_bits("110");
595
596 is equivalent to
597
598         $sha3->add_bits("1")->add_bits("1")->add_bits("0");
599
600 =item B<addfile(*FILE)>
601
602 Reads from I<FILE> until EOF, and appends that data to the current
603 state.  The return value is the updated object itself.
604
605 =item B<addfile($filename [, $mode])>
606
607 Reads the contents of I<$filename>, and appends that data to the current
608 state.  The return value is the updated object itself.
609
610 By default, I<$filename> is simply opened and read; no special modes
611 or I/O disciplines are used.  To change this, set the optional I<$mode>
612 argument to one of the following values:
613
614         "b"     read file in binary mode
615
616         "U"     use universal newlines
617
618         "0"     use BITS mode
619
620         "p"     use portable mode (to be deprecated)
621
622 The "U" mode is modeled on Python's "Universal Newlines" concept, whereby
623 DOS and Mac OS line terminators are converted internally to UNIX newlines
624 before processing.  This ensures consistent digest values when working
625 simultaneously across multiple file systems.  B<The "U" mode influences
626 only text files>, namely those passing Perl's I<-T> test; binary files
627 are processed with no translation whatsoever.
628
629 The "p" mode differs from "U" only in that it treats "\r\r\n" as a single
630 newline, a quirky feature designed to accommodate legacy applications that
631 occasionally added an extra carriage return before DOS line terminators.
632 The "p" mode will be phased out eventually in favor of the cleaner and
633 more well-established Universal Newlines concept.
634
635 The BITS mode ("0") interprets the contents of I<$filename> as a logical
636 stream of bits, where each ASCII '0' or '1' character represents a 0 or
637 1 bit, respectively.  All other characters are ignored.  This provides
638 a convenient way to calculate the digest values of partial-byte data
639 by using files, rather than having to write separate programs employing
640 the I<add_bits> method.
641
642 =item B<getstate>
643
644 Returns a string containing a portable, human-readable representation
645 of the current SHA state.
646
647 =item B<putstate($str)>
648
649 Returns a Digest::SHA object representing the SHA state contained
650 in I<$str>.  The format of I<$str> matches the format of the output
651 produced by method I<getstate>.  If called as a class method, a new
652 object is created; if called as an instance method, the object is reset
653 to the state contained in I<$str>.
654
655 =item B<dump($filename)>
656
657 Writes the output of I<getstate> to I<$filename>.  If the argument is
658 missing, or equal to the empty string, the state information will be
659 written to STDOUT.
660
661 =item B<load($filename)>
662
663 Returns a Digest::SHA object that results from calling I<putstate> on
664 the contents of I<$filename>.  If the argument is missing, or equal to
665 the empty string, the state information will be read from STDIN.
666
667 =item B<digest>
668
669 Returns the digest encoded as a binary string.
670
671 Note that the I<digest> method is a read-once operation. Once it
672 has been performed, the Digest::SHA object is automatically reset
673 in preparation for calculating another digest value.  Call
674 I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
675 original digest state.
676
677 =item B<hexdigest>
678
679 Returns the digest encoded as a hexadecimal string.
680
681 Like I<digest>, this method is a read-once operation.  Call
682 I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve
683 the original digest state.
684
685 =item B<b64digest>
686
687 Returns the digest encoded as a Base64 string.
688
689 Like I<digest>, this method is a read-once operation.  Call
690 I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve
691 the original digest state.
692
693 It's important to note that the resulting string does B<not> contain
694 the padding characters typical of Base64 encodings.  This omission is
695 deliberate, and is done to maintain compatibility with the family of
696 CPAN Digest modules.  See L</"PADDING OF BASE64 DIGESTS"> for details.
697
698 =back
699
700 I<HMAC-SHA-1/224/256/384/512>
701
702 =over 4
703
704 =item B<hmac_sha1($data, $key)>
705
706 =item B<hmac_sha224($data, $key)>
707
708 =item B<hmac_sha256($data, $key)>
709
710 =item B<hmac_sha384($data, $key)>
711
712 =item B<hmac_sha512($data, $key)>
713
714 =item B<hmac_sha512224($data, $key)>
715
716 =item B<hmac_sha512256($data, $key)>
717
718 Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
719 with the result encoded as a binary string.  Multiple I<$data>
720 arguments are allowed, provided that I<$key> is the last argument
721 in the list.
722
723 =item B<hmac_sha1_hex($data, $key)>
724
725 =item B<hmac_sha224_hex($data, $key)>
726
727 =item B<hmac_sha256_hex($data, $key)>
728
729 =item B<hmac_sha384_hex($data, $key)>
730
731 =item B<hmac_sha512_hex($data, $key)>
732
733 =item B<hmac_sha512224_hex($data, $key)>
734
735 =item B<hmac_sha512256_hex($data, $key)>
736
737 Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
738 with the result encoded as a hexadecimal string.  Multiple I<$data>
739 arguments are allowed, provided that I<$key> is the last argument
740 in the list.
741
742 =item B<hmac_sha1_base64($data, $key)>
743
744 =item B<hmac_sha224_base64($data, $key)>
745
746 =item B<hmac_sha256_base64($data, $key)>
747
748 =item B<hmac_sha384_base64($data, $key)>
749
750 =item B<hmac_sha512_base64($data, $key)>
751
752 =item B<hmac_sha512224_base64($data, $key)>
753
754 =item B<hmac_sha512256_base64($data, $key)>
755
756 Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
757 with the result encoded as a Base64 string.  Multiple I<$data>
758 arguments are allowed, provided that I<$key> is the last argument
759 in the list.
760
761 It's important to note that the resulting string does B<not> contain
762 the padding characters typical of Base64 encodings.  This omission is
763 deliberate, and is done to maintain compatibility with the family of
764 CPAN Digest modules.  See L</"PADDING OF BASE64 DIGESTS"> for details.
765
766 =back
767
768 =head1 SEE ALSO
769
770 L<Digest>, L<Digest::SHA::PurePerl>
771
772 The Secure Hash Standard (Draft FIPS PUB 180-4) can be found at:
773
774 L<http://csrc.nist.gov/publications/drafts/fips180-4/Draft-FIPS180-4_Feb2011.pdf>
775
776 The Keyed-Hash Message Authentication Code (HMAC):
777
778 L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
779
780 =head1 AUTHOR
781
782         Mark Shelor     <mshelor@cpan.org>
783
784 =head1 ACKNOWLEDGMENTS
785
786 The author is particularly grateful to
787
788         Gisle Aas
789         H. Merijn Brand
790         Sean Burke
791         Chris Carey
792         Alexandr Ciornii
793         Chris David
794         Jim Doble
795         Thomas Drugeon
796         Julius Duque
797         Jeffrey Friedl
798         Robert Gilmour
799         Brian Gladman
800         Jarkko Hietaniemi
801         Adam Kennedy
802         Mark Lawrence
803         Andy Lester
804         Alex Muntada
805         Steve Peters
806         Chris Skiscim
807         Martin Thurn
808         Gunnar Wolf
809         Adam Woodbury
810
811 "who by trained skill rescued life from such great billows and such thick
812 darkness and moored it in so perfect a calm and in so brilliant a light"
813 - Lucretius
814
815 =head1 COPYRIGHT AND LICENSE
816
817 Copyright (C) 2003-2017 Mark Shelor
818
819 This library is free software; you can redistribute it and/or modify
820 it under the same terms as Perl itself.
821
822 L<perlartistic>
823
824 =cut