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
CommitLineData
6bc89f92
SP
1package Digest::SHA;
2
747da336 3require 5.003000;
c7e5c266 4
6bc89f92 5use strict;
207902b1 6use warnings;
e05a9d74
SH
7use vars qw($VERSION @ISA @EXPORT_OK);
8use Fcntl qw(O_RDONLY);
0a178734 9use integer;
6bc89f92 10
f4f12f2f 11$VERSION = '5.97';
6bc89f92
SP
12
13require Exporter;
747da336
RGS
14require DynaLoader;
15@ISA = qw(Exporter DynaLoader);
16@EXPORT_OK = qw(
6bc89f92
SP
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
65484cb9
CBW
22 hmac_sha512224 hmac_sha512224_base64 hmac_sha512224_hex
23 hmac_sha512256 hmac_sha512256_base64 hmac_sha512256_hex
6bc89f92
SP
24 sha1 sha1_base64 sha1_hex
25 sha224 sha224_base64 sha224_hex
26 sha256 sha256_base64 sha256_hex
27 sha384 sha384_base64 sha384_hex
65484cb9
CBW
28 sha512 sha512_base64 sha512_hex
29 sha512224 sha512224_base64 sha512224_hex
30 sha512256 sha512256_base64 sha512256_hex);
6bc89f92 31
207902b1 32# Inherit from Digest::base if possible
c7e5c266 33
6bc89f92 34eval {
6bc89f92
SP
35 require Digest::base;
36 push(@ISA, 'Digest::base');
37};
e7a1ec00 38
6bc89f92
SP
39# The following routines aren't time-critical, so they can be left in Perl
40
41sub new {
42 my($class, $alg) = @_;
43 $alg =~ s/\D+//g if defined $alg;
44 if (ref($class)) { # instance method
207902b1
CBW
45 if (!defined($alg) || ($alg == $class->algorithm)) {
46 sharewind($class);
6bc89f92
SP
47 return($class);
48 }
207902b1 49 return shainit($class, $alg) ? $class : undef;
6bc89f92
SP
50 }
51 $alg = 1 unless defined $alg;
207902b1 52 return $class->newSHA($alg);
6bc89f92
SP
53}
54
207902b1 55BEGIN { *reset = \&new }
6bc89f92
SP
56
57sub add_bits {
58 my($self, $data, $nbits) = @_;
59 unless (defined $nbits) {
60 $nbits = length($data);
61 $data = pack("B*", $data);
62 }
e39652ea 63 $nbits = length($data) * 8 if $nbits > length($data) * 8;
207902b1 64 shawrite($data, $nbits, $self);
6bc89f92
SP
65 return($self);
66}
67
c7e5c266
SP
68sub _bail {
69 my $msg = shift;
70
9dd45029 71 $msg .= ": $!";
207902b1
CBW
72 require Carp;
73 Carp::croak($msg);
c7e5c266 74}
6bc89f92 75
207902b1
CBW
76{
77 my $_can_T_filehandle;
6bc89f92 78
207902b1
CBW
79 sub _istext {
80 local *FH = shift;
81 my $file = shift;
c2de4d02 82
207902b1
CBW
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 }
6bc89f92
SP
91}
92
207902b1
CBW
93sub _addfile {
94 my ($self, $handle) = @_;
626ec6d7 95
207902b1
CBW
96 my $n;
97 my $buf = "";
626ec6d7 98
207902b1
CBW
99 while (($n = read($handle, $buf, 4096))) {
100 $self->add($buf);
626ec6d7 101 }
207902b1
CBW
102 _bail("Read failed") unless defined $n;
103
104 $self;
626ec6d7
AC
105}
106
207902b1 107sub addfile {
c7e5c266
SP
108 my ($self, $file, $mode) = @_;
109
84c0b84e 110 return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR';
c7e5c266
SP
111
112 $mode = defined($mode) ? $mode : "";
207902b1
CBW
113 my ($binary, $UNIVERSAL, $BITS, $portable) =
114 map { $_ eq $mode } ("b", "U", "0", "p");
c7e5c266 115
9cc8ef8a
CBW
116 ## Always interpret "-" to mean STDIN; otherwise use
117 ## sysopen to handle full range of POSIX file names
207902b1 118
747da336 119 local *FH;
65484cb9 120 $file eq '-' and open(FH, '< -')
9cc8ef8a
CBW
121 or sysopen(FH, $file, O_RDONLY)
122 or _bail('Open failed');
c7e5c266 123
e39652ea
CBW
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
207902b1
CBW
135 binmode(FH) if $binary || $portable || $UNIVERSAL;
136 if ($UNIVERSAL && _istext(*FH, $file)) {
137 $self->_addfileuniv(*FH);
c7e5c266 138 }
207902b1
CBW
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 }
c7e5c266 145 }
207902b1 146 else { $self->_addfilebin(*FH) }
747da336 147 close(FH);
c7e5c266
SP
148
149 $self;
150}
151
7123ec76
SH
152sub 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
178sub putstate {
207902b1 179 my($class, $state) = @_;
7123ec76
SH
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
207902b1 204 my $packed_state = (
7123ec76
SH
205 pack("H*", $s{'H'}) .
206 pack("H*", $s{'block'}) .
207902b1
CBW
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'})
7123ec76
SH
212 );
213
207902b1 214 return $class->new($s{'alg'})->_putstate($packed_state);
7123ec76
SH
215}
216
6bc89f92
SP
217sub dump {
218 my $self = shift;
a8c6ff7b 219 my $file = shift;
6bc89f92 220
7123ec76
SH
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
6bc89f92
SP
229 return($self);
230}
231
232sub load {
233 my $class = shift;
a8c6ff7b
CBW
234 my $file = shift;
235
7123ec76 236 $file = "-" if (!defined($file) || $file eq "");
626ec6d7 237
7123ec76
SH
238 local *FH;
239 open(FH, "< $file") or return;
240 my $str = join('', <FH>);
241 close(FH);
242
243 $class->putstate($str);
6bc89f92
SP
244}
245
747da336
RGS
246Digest::SHA->bootstrap($VERSION);
247
6bc89f92
SP
2481;
249__END__
250
251=head1 NAME
252
253Digest::SHA - Perl extension for SHA-1/224/256/384/512
254
747da336 255=head1 SYNOPSIS
6bc89f92
SP
256
257In 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
c7e5c266 278
6bc89f92 279 $sha->addfile(*F);
c7e5c266
SP
280 $sha->addfile($filename);
281
6bc89f92
SP
282 $sha->add_bits($bits);
283 $sha->add_bits($data, $nbits);
284
7123ec76
SH
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
6bc89f92
SP
288
289 $digest = $sha->digest; # compute digest
290 $digest = $sha->hexdigest;
291 $digest = $sha->b64digest;
292
293From 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
65484cb9
CBW
311Digest::SHA is a complete implementation of the NIST Secure Hash Standard.
312It gives Perl programmers a convenient way to calculate SHA-1, SHA-224,
313SHA-256, SHA-384, SHA-512, SHA-512/224, and SHA-512/256 message digests.
314The module can handle all types of input, including partial-byte data.
6bc89f92
SP
315
316=head1 DESCRIPTION
317
318Digest::SHA is written in C for speed. If your platform lacks a
319C compiler, you can install the functionally equivalent (but much
320slower) L<Digest::SHA::PurePerl> module.
321
322The programming interface is easy to use: it's the same one found
323in CPAN's L<Digest> module. So, if your applications currently
324use L<Digest::MD5> and you'd prefer the stronger security of SHA,
325it's a simple matter to convert them.
326
327The interface provides two ways to calculate digests: all-at-once,
328or in stages. To illustrate, the following short program computes
329the 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
347To calculate the digest of an n-bit message where I<n> is not a
348multiple of 8, use the I<add_bits()> method. For example, consider
349the 446-bit message consisting of the bit-string "110" repeated
350148 times, followed by "11". Here's how to display its SHA-1
351digest:
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
358Note that for larger bit-strings, it's more efficient to use the
359two-argument version I<add_bits($data, $nbits)>, where I<$data> is
360in the customary packed binary format used for Perl strings.
361
7123ec76
SH
362The module also lets you save intermediate SHA states to a string. The
363I<getstate()> method generates portable, human-readable text describing
364the current state of computation. You can subsequently restore that
365state with I<putstate()> to resume where the calculation left off.
6bc89f92
SP
366
367To see what a state description looks like, just run the following:
368
369 use Digest::SHA;
7123ec76 370 print Digest::SHA->new->add("Shaw" x 1962)->getstate;
6bc89f92
SP
371
372As an added convenience, the Digest::SHA module offers routines to
373calculate keyed hashes using the HMAC-SHA-1/224/256/384/512
374algorithms. These services exist in functional form only, and
375mimic the style and behavior of the I<sha()>, I<sha_hex()>, and
376I<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
7720cfb2
CBW
383=head1 UNICODE AND SIDE EFFECTS
384
385Perl supports Unicode strings as of version 5.6. Such strings may
386contain wide characters, namely, characters whose ordinal values are
387greater than 255. This can cause problems for digest algorithms such
388as SHA that are specified to operate on sequences of bytes.
389
a5b310e3
CBW
390The rule by which Digest::SHA handles a Unicode string is easy
391to state, but potentially confusing to grasp: the string is interpreted
392as a sequence of byte values, where each byte value is equal to the
393ordinal value (viz. code point) of its corresponding Unicode character.
394That way, the Unicode string 'abc' has exactly the same digest value as
395the ordinary string 'abc'.
7720cfb2 396
a5b310e3
CBW
397Since a wide character does not fit into a byte, the Digest::SHA
398routines croak if they encounter one. Whereas if a Unicode string
399contains no wide characters, the module accepts it quite happily.
400The following code illustrates the two cases:
6bc89f92 401
7720cfb2
CBW
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
408Be aware that the digest routines silently convert UTF-8 input into its
409equivalent byte sequence in the native encoding (cf. utf8::downgrade).
a5b310e3
CBW
410This side effect influences only the way Perl stores the data internally,
411but otherwise leaves the actual value of the data intact.
7720cfb2
CBW
412
413=head1 NIST STATEMENT ON SHA-1
6bc89f92 414
7720cfb2
CBW
415NIST acknowledges that the work of Prof. Xiaoyun Wang constitutes a
416practical collision attack on SHA-1. Therefore, NIST encourages the
417rapid adoption of the SHA-2 hash functions (e.g. SHA-256) for applications
418requiring strong collision resistance, such as digital signatures.
6bc89f92 419
7720cfb2 420ref. L<http://csrc.nist.gov/groups/ST/hash/statement.html>
6bc89f92 421
1bd6a86e 422=head1 PADDING OF BASE64 DIGESTS
cccd5831 423
1bd6a86e
SP
424By convention, CPAN Digest modules do B<not> pad their Base64 output.
425Problems can occur when feeding such digests to other software that
426expects properly padded Base64 encodings.
cccd5831
SP
427
428For the time being, any necessary padding must be done by the user.
1bd6a86e
SP
429Fortunately, this is a simple operation: if the length of a Base64-encoded
430digest isn't a multiple of 4, simply append "=" characters to the end
431of the digest until it is:
cccd5831
SP
432
433 while (length($b64_digest) % 4) {
434 $b64_digest .= '=';
435 }
436
437To illustrate, I<sha256_base64("abc")> is computed to be
438
439 ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
440
441which has a length of 43. So, the properly padded version is
442
443 ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
444
6bc89f92
SP
445=head1 EXPORT
446
447None by default.
448
449=head1 EXPORTABLE FUNCTIONS
450
451Provided your C compiler supports a 64-bit type (e.g. the I<long
452long> of C99, or I<__int64> used by Microsoft C/C++), all of these
453functions will be available for use. Otherwise, you won't be able
454to perform the SHA-384 and SHA-512 transforms, both of which require
45564-bit operations.
456
457I<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
65484cb9
CBW
471=item B<sha512224($data, ...)>
472
473=item B<sha512256($data, ...)>
474
6bc89f92
SP
475Logically joins the arguments into a single string, and returns
476its 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
65484cb9
CBW
488=item B<sha512224_hex($data, ...)>
489
490=item B<sha512256_hex($data, ...)>
491
6bc89f92
SP
492Logically joins the arguments into a single string, and returns
493its 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
65484cb9
CBW
505=item B<sha512224_base64($data, ...)>
506
507=item B<sha512256_base64($data, ...)>
508
6bc89f92
SP
509Logically joins the arguments into a single string, and returns
510its SHA-1/224/256/384/512 digest encoded as a Base64 string.
511
cccd5831
SP
512It's important to note that the resulting string does B<not> contain
513the padding characters typical of Base64 encodings. This omission is
514deliberate, and is done to maintain compatibility with the family of
747da336 515CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details.
cccd5831 516
6bc89f92
SP
517=back
518
519I<OOP style>
520
521=over 4
522
523=item B<new($alg)>
524
340a2f44
CBW
525Returns a new Digest::SHA object. Allowed values for I<$alg> are 1,
526224, 256, 384, 512, 512224, or 512256. It's also possible to use
527common string representations of the algorithm (e.g. "sha256",
528"SHA-384"). If the argument is missing, SHA-1 will be used by
529default.
6bc89f92 530
207902b1
CBW
531Invoking I<new> as an instance method will reset the object to the
532initial state associated with I<$alg>. If the argument is missing,
533the object will continue using the same algorithm that was selected
534at creation.
6bc89f92
SP
535
536=item B<reset($alg)>
537
538This method has exactly the same effect as I<new($alg)>. In fact,
539I<reset> is just an alias for I<new>.
540
541=item B<hashsize>
542
543Returns the number of digest bits for this object. The values are
340a2f44
CBW
544160, 224, 256, 384, 512, 224, and 256 for SHA-1, SHA-224, SHA-256,
545SHA-384, SHA-512, SHA-512/224 and SHA-512/256, respectively.
6bc89f92
SP
546
547=item B<algorithm>
548
549Returns the digest algorithm for this object. The values are 1,
340a2f44
CBW
550224, 256, 384, 512, 512224, and 512256 for SHA-1, SHA-224, SHA-256,
551SHA-384, SHA-512, SHA-512/224, and SHA-512/256, respectively.
6bc89f92
SP
552
553=item B<clone>
554
555Returns a duplicate copy of the object.
556
557=item B<add($data, ...)>
558
559Logically joins the arguments into a single string, and uses it to
560update the current digest state. In other words, the following
561statements 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
568The return value is the updated object itself.
569
570=item B<add_bits($data, $nbits)>
571
572=item B<add_bits($bits)>
573
574Updates the current digest state by appending bits to it. The
575return value is the updated object itself.
576
577The first form causes the most-significant I<$nbits> of I<$data>
578to be appended to the stream. The I<$data> argument is in the
579customary binary format used for Perl strings.
580
581The second form takes an ASCII string of "0" and "1" characters as
582its argument. It's equivalent to
583
584 $sha->add_bits(pack("B*", $bits), length($bits));
585
586So, the following two statements do the same thing:
587
588 $sha->add_bits("111100001010");
589 $sha->add_bits("\xF0\xA0", 12);
590
24278fc4
CBW
591Note that SHA-1 and SHA-2 use I<most-significant-bit ordering>
592for their internal state. This means that
593
594 $sha3->add_bits("110");
595
596is equivalent to
597
598 $sha3->add_bits("1")->add_bits("1")->add_bits("0");
599
6bc89f92
SP
600=item B<addfile(*FILE)>
601
602Reads from I<FILE> until EOF, and appends that data to the current
603state. The return value is the updated object itself.
604
c7e5c266
SP
605=item B<addfile($filename [, $mode])>
606
607Reads the contents of I<$filename>, and appends that data to the current
608state. The return value is the updated object itself.
609
610By default, I<$filename> is simply opened and read; no special modes
611or I/O disciplines are used. To change this, set the optional I<$mode>
612argument to one of the following values:
613
84c0b84e 614 "b" read file in binary mode
c7e5c266 615
207902b1 616 "U" use universal newlines
c7e5c266 617
e39652ea
CBW
618 "0" use BITS mode
619
207902b1
CBW
620 "p" use portable mode (to be deprecated)
621
622The "U" mode is modeled on Python's "Universal Newlines" concept, whereby
623DOS and Mac OS line terminators are converted internally to UNIX newlines
624before processing. This ensures consistent digest values when working
625simultaneously across multiple file systems. B<The "U" mode influences
626only text files>, namely those passing Perl's I<-T> test; binary files
627are processed with no translation whatsoever.
628
629The "p" mode differs from "U" only in that it treats "\r\r\n" as a single
630newline, a quirky feature designed to accommodate legacy applications that
631occasionally added an extra carriage return before DOS line terminators.
632The "p" mode will be phased out eventually in favor of the cleaner and
633more well-established Universal Newlines concept.
c7e5c266 634
e39652ea
CBW
635The BITS mode ("0") interprets the contents of I<$filename> as a logical
636stream of bits, where each ASCII '0' or '1' character represents a 0 or
6371 bit, respectively. All other characters are ignored. This provides
207902b1
CBW
638a convenient way to calculate the digest values of partial-byte data
639by using files, rather than having to write separate programs employing
640the I<add_bits> method.
6bc89f92 641
7123ec76
SH
642=item B<getstate>
643
644Returns a string containing a portable, human-readable representation
645of the current SHA state.
646
647=item B<putstate($str)>
648
649Returns a Digest::SHA object representing the SHA state contained
650in I<$str>. The format of I<$str> matches the format of the output
651produced by method I<getstate>. If called as a class method, a new
652object is created; if called as an instance method, the object is reset
653to the state contained in I<$str>.
654
6bc89f92
SP
655=item B<dump($filename)>
656
7123ec76
SH
657Writes the output of I<getstate> to I<$filename>. If the argument is
658missing, or equal to the empty string, the state information will be
659written to STDOUT.
6bc89f92
SP
660
661=item B<load($filename)>
662
7123ec76
SH
663Returns a Digest::SHA object that results from calling I<putstate> on
664the contents of I<$filename>. If the argument is missing, or equal to
665the empty string, the state information will be read from STDIN.
6bc89f92
SP
666
667=item B<digest>
668
669Returns the digest encoded as a binary string.
670
671Note that the I<digest> method is a read-once operation. Once it
672has been performed, the Digest::SHA object is automatically reset
673in preparation for calculating another digest value. Call
674I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
675original digest state.
676
677=item B<hexdigest>
678
679Returns the digest encoded as a hexadecimal string.
680
681Like I<digest>, this method is a read-once operation. Call
682I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve
683the original digest state.
684
6bc89f92
SP
685=item B<b64digest>
686
687Returns the digest encoded as a Base64 string.
688
689Like I<digest>, this method is a read-once operation. Call
690I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve
691the original digest state.
692
cccd5831
SP
693It's important to note that the resulting string does B<not> contain
694the padding characters typical of Base64 encodings. This omission is
695deliberate, and is done to maintain compatibility with the family of
747da336 696CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details.
cccd5831 697
6bc89f92
SP
698=back
699
700I<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
65484cb9
CBW
714=item B<hmac_sha512224($data, $key)>
715
716=item B<hmac_sha512256($data, $key)>
717
6bc89f92
SP
718Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
719with the result encoded as a binary string. Multiple I<$data>
720arguments are allowed, provided that I<$key> is the last argument
721in 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
65484cb9
CBW
733=item B<hmac_sha512224_hex($data, $key)>
734
735=item B<hmac_sha512256_hex($data, $key)>
736
6bc89f92
SP
737Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
738with the result encoded as a hexadecimal string. Multiple I<$data>
739arguments are allowed, provided that I<$key> is the last argument
740in 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
65484cb9
CBW
752=item B<hmac_sha512224_base64($data, $key)>
753
754=item B<hmac_sha512256_base64($data, $key)>
755
6bc89f92
SP
756Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
757with the result encoded as a Base64 string. Multiple I<$data>
758arguments are allowed, provided that I<$key> is the last argument
759in the list.
760
cccd5831
SP
761It's important to note that the resulting string does B<not> contain
762the padding characters typical of Base64 encodings. This omission is
763deliberate, and is done to maintain compatibility with the family of
747da336 764CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details.
cccd5831 765
6bc89f92
SP
766=back
767
768=head1 SEE ALSO
769
770L<Digest>, L<Digest::SHA::PurePerl>
771
65484cb9 772The Secure Hash Standard (Draft FIPS PUB 180-4) can be found at:
6bc89f92 773
65484cb9 774L<http://csrc.nist.gov/publications/drafts/fips180-4/Draft-FIPS180-4_Feb2011.pdf>
6bc89f92
SP
775
776The Keyed-Hash Message Authentication Code (HMAC):
777
778L<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
786The author is particularly grateful to
787
788 Gisle Aas
03c6205f 789 H. Merijn Brand
0a178734 790 Sean Burke
6bc89f92 791 Chris Carey
670096db 792 Alexandr Ciornii
f4f12f2f 793 Chris David
747da336 794 Jim Doble
a0780036 795 Thomas Drugeon
6bc89f92
SP
796 Julius Duque
797 Jeffrey Friedl
798 Robert Gilmour
799 Brian Gladman
03c6205f 800 Jarkko Hietaniemi
c7e5c266 801 Adam Kennedy
207902b1 802 Mark Lawrence
6bc89f92
SP
803 Andy Lester
804 Alex Muntada
77d2a621 805 Steve Peters
6bc89f92
SP
806 Chris Skiscim
807 Martin Thurn
808 Gunnar Wolf
809 Adam Woodbury
810
65484cb9
CBW
811"who by trained skill rescued life from such great billows and such thick
812darkness and moored it in so perfect a calm and in so brilliant a light"
813- Lucretius
6bc89f92
SP
814
815=head1 COPYRIGHT AND LICENSE
816
f4f12f2f 817Copyright (C) 2003-2017 Mark Shelor
6bc89f92
SP
818
819This library is free software; you can redistribute it and/or modify
820it under the same terms as Perl itself.
821
822L<perlartistic>
823
824=cut