ext/Digest/SHA/SHA.pm

   1 package Digest::SHA;
   2
   3 use strict;
   4 use warnings;
   5 use integer;
   6
   7 our $VERSION = '5.34_01';
   8
   9 require Exporter;
  10 our @ISA = qw(Exporter);
  11
  12 our @EXPORT_OK = qw(
  13         hmac_sha1       hmac_sha1_base64        hmac_sha1_hex
  14         hmac_sha224     hmac_sha224_base64      hmac_sha224_hex
  15         hmac_sha256     hmac_sha256_base64      hmac_sha256_hex
  16         hmac_sha384     hmac_sha384_base64      hmac_sha384_hex
  17         hmac_sha512     hmac_sha512_base64      hmac_sha512_hex
  18         sha1            sha1_base64             sha1_hex
  19         sha224          sha224_base64           sha224_hex
  20         sha256          sha256_base64           sha256_hex
  21         sha384          sha384_base64           sha384_hex
  22         sha512          sha512_base64           sha512_hex);
  23
  24 # If possible, inherit from Digest::base (which depends on MIME::Base64)
  25
  26 eval {
  27         require MIME::Base64;
  28         require Digest::base;
  29         push(@ISA, 'Digest::base');
  30 };
  31 if ($@) {
  32         *addfile = \&Addfile;
  33         *hexdigest = \&Hexdigest;
  34         *b64digest = \&B64digest;
  35 }
  36
  37 require XSLoader;
  38 XSLoader::load('Digest::SHA', $VERSION);
  39
  40 # Preloaded methods go here.
  41
  42 # The following routines aren't time-critical, so they can be left in Perl
  43
  44 sub 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                 shaclose($$class) if $$class;
  53                 $$class = shaopen($alg) || return;
  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
  63 sub DESTROY {
  64         my $self = shift;
  65         shaclose($$self) if $$self;
  66 }
  67
  68 sub 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
  78 sub add_bits {
  79         my($self, $data, $nbits) = @_;
  80         unless (defined $nbits) {
  81                 $nbits = length($data);
  82                 $data = pack("B*", $data);
  83         }
  84         shawrite($data, $nbits, $$self);
  85         return($self);
  86 }
  87
  88 # local copy of "addfile" in case Digest::base not installed
  89
  90 sub Addfile {   # this is "addfile" from Digest::base 1.00
  91     my ($self, $handle) = @_;
  92
  93     my $n;
  94     my $buf = "";
  95
  96     while (($n = read($handle, $buf, 4096))) {
  97         $self->add($buf);
  98     }
  99     unless (defined $n) {
 100         require Carp;
 101         Carp::croak("Read failed: $!");
 102     }
 103
 104     $self;
 105 }
 106
 107 sub dump {
 108         my $self = shift;
 109         my $file = shift || "";
 110
 111         shadump($file, $$self) || return;
 112         return($self);
 113 }
 114
 115 sub load {
 116         my $class = shift;
 117         my $file = shift || "";
 118         if (ref($class)) {      # instance method
 119                 shaclose($$class) if $$class;
 120                 $$class = shaload($file) || return;
 121                 return($class);
 122         }
 123         my $state = shaload($file) || return;
 124         my $self = \$state;
 125         bless($self, $class);
 126         return($self);
 127 }
 128
 129 1;
 130 __END__
 131
 132 =head1 NAME
 133
 134 Digest::SHA - Perl extension for SHA-1/224/256/384/512
 135
 136 =head1 SYNOPSIS (SHA)
 137
 138 In programs:
 139
 140                 # Functional interface
 141
 142         use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
 143
 144         $digest = sha1($data);
 145         $digest = sha1_hex($data);
 146         $digest = sha1_base64($data);
 147
 148         $digest = sha256($data);
 149         $digest = sha384_hex($data);
 150         $digest = sha512_base64($data);
 151
 152                 # Object-oriented
 153
 154         use Digest::SHA;
 155
 156         $sha = Digest::SHA->new($alg);
 157
 158         $sha->add($data);               # feed data into stream
 159         $sha->addfile(*F);
 160         $sha->add_bits($bits);
 161         $sha->add_bits($data, $nbits);
 162
 163         $sha_copy = $sha->clone;        # if needed, make copy of
 164         $sha->dump($file);              #       current digest state,
 165         $sha->load($file);              #       or save it on disk
 166
 167         $digest = $sha->digest;         # compute digest
 168         $digest = $sha->hexdigest;
 169         $digest = $sha->b64digest;
 170
 171 From the command line:
 172
 173         $ shasum files
 174
 175         $ shasum --help
 176
 177 =head1 SYNOPSIS (HMAC-SHA)
 178
 179                 # Functional interface only
 180
 181         use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
 182
 183         $digest = hmac_sha1($data, $key);
 184         $digest = hmac_sha224_hex($data, $key);
 185         $digest = hmac_sha256_base64($data, $key);
 186
 187 =head1 ABSTRACT
 188
 189 Digest::SHA is a complete implementation of the NIST Secure Hash
 190 Standard.  It gives Perl programmers a convenient way to calculate
 191 SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 message digests.
 192 The module can handle all types of input, including partial-byte
 193 data.
 194
 195 =head1 DESCRIPTION
 196
 197 Digest::SHA is written in C for speed.  If your platform lacks a
 198 C compiler, you can install the functionally equivalent (but much
 199 slower) L<Digest::SHA::PurePerl> module.
 200
 201 The programming interface is easy to use: it's the same one found
 202 in CPAN's L<Digest> module.  So, if your applications currently
 203 use L<Digest::MD5> and you'd prefer the stronger security of SHA,
 204 it's a simple matter to convert them.
 205
 206 The interface provides two ways to calculate digests:  all-at-once,
 207 or in stages.  To illustrate, the following short program computes
 208 the SHA-256 digest of "hello world" using each approach:
 209
 210         use Digest::SHA qw(sha256_hex);
 211
 212         $data = "hello world";
 213         @frags = split(//, $data);
 214
 215         # all-at-once (Functional style)
 216         $digest1 = sha256_hex($data);
 217
 218         # in-stages (OOP style)
 219         $state = Digest::SHA->new(256);
 220         for (@frags) { $state->add($_) }
 221         $digest2 = $state->hexdigest;
 222
 223         print $digest1 eq $digest2 ?
 224                 "whew!\n" : "oops!\n";
 225
 226 To calculate the digest of an n-bit message where I<n> is not a
 227 multiple of 8, use the I<add_bits()> method.  For example, consider
 228 the 446-bit message consisting of the bit-string "110" repeated
 229 148 times, followed by "11".  Here's how to display its SHA-1
 230 digest:
 231
 232         use Digest::SHA;
 233         $bits = "110" x 148 . "11";
 234         $sha = Digest::SHA->new(1)->add_bits($bits);
 235         print $sha->hexdigest, "\n";
 236
 237 Note that for larger bit-strings, it's more efficient to use the
 238 two-argument version I<add_bits($data, $nbits)>, where I<$data> is
 239 in the customary packed binary format used for Perl strings.
 240
 241 The module also lets you save intermediate SHA states to disk, or
 242 display them on standard output.  The I<dump()> method generates
 243 portable, human-readable text describing the current state of
 244 computation.  You can subsequently retrieve the file with I<load()>
 245 to resume where the calculation left off.
 246
 247 To see what a state description looks like, just run the following:
 248
 249         use Digest::SHA;
 250         Digest::SHA->new->add("Shaw" x 1962)->dump;
 251
 252 As an added convenience, the Digest::SHA module offers routines to
 253 calculate keyed hashes using the HMAC-SHA-1/224/256/384/512
 254 algorithms.  These services exist in functional form only, and
 255 mimic the style and behavior of the I<sha()>, I<sha_hex()>, and
 256 I<sha_base64()> functions.
 257
 258         # Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt
 259
 260         use Digest::SHA qw(hmac_sha256_hex);
 261         print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
 262
 263 =head1 NIST STATEMENT ON SHA-1
 264
 265 I<NIST was recently informed that researchers had discovered a way
 266 to "break" the current Federal Information Processing Standard SHA-1
 267 algorithm, which has been in effect since 1994. The researchers
 268 have not yet published their complete results, so NIST has not
 269 confirmed these findings. However, the researchers are a reputable
 270 research team with expertise in this area.>
 271
 272 I<Due to advances in computing power, NIST already planned to phase
 273 out SHA-1 in favor of the larger and stronger hash functions (SHA-224,
 274 SHA-256, SHA-384 and SHA-512) by 2010. New developments should use
 275 the larger and stronger hash functions.>
 276
 277 ref. L<http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20Statement/Burr_Mar2005.html>
 278
 279 =head1 EXPORT
 280
 281 None by default.
 282
 283 =head1 EXPORTABLE FUNCTIONS
 284
 285 Provided your C compiler supports a 64-bit type (e.g. the I<long
 286 long> of C99, or I<__int64> used by Microsoft C/C++), all of these
 287 functions will be available for use.  Otherwise, you won't be able
 288 to perform the SHA-384 and SHA-512 transforms, both of which require
 289 64-bit operations.
 290
 291 I<Functional style>
 292
 293 =over 4
 294
 295 =item B<sha1($data, ...)>
 296
 297 =item B<sha224($data, ...)>
 298
 299 =item B<sha256($data, ...)>
 300
 301 =item B<sha384($data, ...)>
 302
 303 =item B<sha512($data, ...)>
 304
 305 Logically joins the arguments into a single string, and returns
 306 its SHA-1/224/256/384/512 digest encoded as a binary string.
 307
 308 =item B<sha1_hex($data, ...)>
 309
 310 =item B<sha224_hex($data, ...)>
 311
 312 =item B<sha256_hex($data, ...)>
 313
 314 =item B<sha384_hex($data, ...)>
 315
 316 =item B<sha512_hex($data, ...)>
 317
 318 Logically joins the arguments into a single string, and returns
 319 its SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
 320
 321 =item B<sha1_base64($data, ...)>
 322
 323 =item B<sha224_base64($data, ...)>
 324
 325 =item B<sha256_base64($data, ...)>
 326
 327 =item B<sha384_base64($data, ...)>
 328
 329 =item B<sha512_base64($data, ...)>
 330
 331 Logically joins the arguments into a single string, and returns
 332 its SHA-1/224/256/384/512 digest encoded as a Base64 string.
 333
 334 =back
 335
 336 I<OOP style>
 337
 338 =over 4
 339
 340 =item B<new($alg)>
 341
 342 Returns a new Digest::SHA object.  Allowed values for I<$alg> are
 343 1, 224, 256, 384, or 512.  It's also possible to use common string
 344 representations of the algorithm (e.g. "sha256", "SHA-384").  If
 345 the argument is missing, SHA-1 will be used by default.
 346
 347 Invoking I<new> as an instance method will not create a new object;
 348 instead, it will simply reset the object to the initial state
 349 associated with I<$alg>.  If the argument is missing, the object
 350 will continue using the same algorithm that was selected at creation.
 351
 352 =item B<reset($alg)>
 353
 354 This method has exactly the same effect as I<new($alg)>.  In fact,
 355 I<reset> is just an alias for I<new>.
 356
 357 =item B<hashsize>
 358
 359 Returns the number of digest bits for this object.  The values are
 360 160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384,
 361 and SHA-512, respectively.
 362
 363 =item B<algorithm>
 364
 365 Returns the digest algorithm for this object.  The values are 1,
 366 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and
 367 SHA-512, respectively.
 368
 369 =item B<clone>
 370
 371 Returns a duplicate copy of the object.
 372
 373 =item B<add($data, ...)>
 374
 375 Logically joins the arguments into a single string, and uses it to
 376 update the current digest state.  In other words, the following
 377 statements have the same effect:
 378
 379         $sha->add("a"); $sha->add("b"); $sha->add("c");
 380         $sha->add("a")->add("b")->add("c");
 381         $sha->add("a", "b", "c");
 382         $sha->add("abc");
 383
 384 The return value is the updated object itself.
 385
 386 =item B<add_bits($data, $nbits)>
 387
 388 =item B<add_bits($bits)>
 389
 390 Updates the current digest state by appending bits to it.  The
 391 return value is the updated object itself.
 392
 393 The first form causes the most-significant I<$nbits> of I<$data>
 394 to be appended to the stream.  The I<$data> argument is in the
 395 customary binary format used for Perl strings.
 396
 397 The second form takes an ASCII string of "0" and "1" characters as
 398 its argument.  It's equivalent to
 399
 400         $sha->add_bits(pack("B*", $bits), length($bits));
 401
 402 So, the following two statements do the same thing:
 403
 404         $sha->add_bits("111100001010");
 405         $sha->add_bits("\xF0\xA0", 12);
 406
 407 =item B<addfile(*FILE)>
 408
 409 Reads from I<FILE> until EOF, and appends that data to the current
 410 state.  The return value is the updated object itself.
 411
 412 This method is inherited if L<Digest::base> is installed on your
 413 system.  Otherwise, a functionally equivalent substitute is used.
 414
 415 =item B<dump($filename)>
 416
 417 Provides persistent storage of intermediate SHA states by writing
 418 a portable, human-readable representation of the current state to
 419 I<$filename>.  If the argument is missing, or equal to the empty
 420 string, the state information will be written to STDOUT.
 421
 422 =item B<load($filename)>
 423
 424 Returns a Digest::SHA object representing the intermediate SHA
 425 state that was previously dumped to I<$filename>.  If called as a
 426 class method, a new object is created; if called as an instance
 427 method, the object is reset to the state contained in I<$filename>.
 428 If the argument is missing, or equal to the empty string, the state
 429 information will be read from STDIN.
 430
 431 =item B<digest>
 432
 433 Returns the digest encoded as a binary string.
 434
 435 Note that the I<digest> method is a read-once operation. Once it
 436 has been performed, the Digest::SHA object is automatically reset
 437 in preparation for calculating another digest value.  Call
 438 I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
 439 original digest state.
 440
 441 =item B<hexdigest>
 442
 443 Returns the digest encoded as a hexadecimal string.
 444
 445 Like I<digest>, this method is a read-once operation.  Call
 446 I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve
 447 the original digest state.
 448
 449 This method is inherited if L<Digest::base> is installed on your
 450 system.  Otherwise, a functionally equivalent substitute is used.
 451
 452 =item B<b64digest>
 453
 454 Returns the digest encoded as a Base64 string.
 455
 456 Like I<digest>, this method is a read-once operation.  Call
 457 I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve
 458 the original digest state.
 459
 460 This method is inherited if L<Digest::base> is installed on your
 461 system.  Otherwise, a functionally equivalent substitute is used.
 462
 463 =back
 464
 465 I<HMAC-SHA-1/224/256/384/512>
 466
 467 =over 4
 468
 469 =item B<hmac_sha1($data, $key)>
 470
 471 =item B<hmac_sha224($data, $key)>
 472
 473 =item B<hmac_sha256($data, $key)>
 474
 475 =item B<hmac_sha384($data, $key)>
 476
 477 =item B<hmac_sha512($data, $key)>
 478
 479 Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
 480 with the result encoded as a binary string.  Multiple I<$data>
 481 arguments are allowed, provided that I<$key> is the last argument
 482 in the list.
 483
 484 =item B<hmac_sha1_hex($data, $key)>
 485
 486 =item B<hmac_sha224_hex($data, $key)>
 487
 488 =item B<hmac_sha256_hex($data, $key)>
 489
 490 =item B<hmac_sha384_hex($data, $key)>
 491
 492 =item B<hmac_sha512_hex($data, $key)>
 493
 494 Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
 495 with the result encoded as a hexadecimal string.  Multiple I<$data>
 496 arguments are allowed, provided that I<$key> is the last argument
 497 in the list.
 498
 499 =item B<hmac_sha1_base64($data, $key)>
 500
 501 =item B<hmac_sha224_base64($data, $key)>
 502
 503 =item B<hmac_sha256_base64($data, $key)>
 504
 505 =item B<hmac_sha384_base64($data, $key)>
 506
 507 =item B<hmac_sha512_base64($data, $key)>
 508
 509 Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
 510 with the result encoded as a Base64 string.  Multiple I<$data>
 511 arguments are allowed, provided that I<$key> is the last argument
 512 in the list.
 513
 514 =back
 515
 516 =head1 SEE ALSO
 517
 518 L<Digest>, L<Digest::SHA::PurePerl>
 519
 520 The Secure Hash Standard (FIPS PUB 180-2) can be found at:
 521
 522 L<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>
 523
 524 The Keyed-Hash Message Authentication Code (HMAC):
 525
 526 L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
 527
 528 =head1 AUTHOR
 529
 530         Mark Shelor     <mshelor@cpan.org>
 531
 532 =head1 ACKNOWLEDGMENTS
 533
 534 The author is particularly grateful to
 535
 536         Gisle Aas
 537         Chris Carey
 538         Julius Duque
 539         Jeffrey Friedl
 540         Robert Gilmour
 541         Brian Gladman
 542         Andy Lester
 543         Alex Muntada
 544         Steve Peters
 545         Chris Skiscim
 546         Martin Thurn
 547         Gunnar Wolf
 548         Adam Woodbury
 549
 550 for their valuable comments and suggestions.
 551
 552 =head1 COPYRIGHT AND LICENSE
 553
 554 Copyright (C) 2003-2006 Mark Shelor
 555
 556 This library is free software; you can redistribute it and/or modify
 557 it under the same terms as Perl itself.
 558
 559 L<perlartistic>
 560
 561 =cut