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