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