cpan/Digest/Digest.pm

   1 package Digest;
   2
   3 use strict;
   4 use vars qw($VERSION %MMAP $AUTOLOAD);
   5
   6 $VERSION = "1.17";
   7
   8 %MMAP = (
   9   "SHA-1"      => [["Digest::SHA", 1], "Digest::SHA1", ["Digest::SHA2", 1]],
  10   "SHA-224"    => [["Digest::SHA", 224]],
  11   "SHA-256"    => [["Digest::SHA", 256], ["Digest::SHA2", 256]],
  12   "SHA-384"    => [["Digest::SHA", 384], ["Digest::SHA2", 384]],
  13   "SHA-512"    => [["Digest::SHA", 512], ["Digest::SHA2", 512]],
  14   "HMAC-MD5"   => "Digest::HMAC_MD5",
  15   "HMAC-SHA-1" => "Digest::HMAC_SHA1",
  16   "CRC-16"     => [["Digest::CRC", type => "crc16"]],
  17   "CRC-32"     => [["Digest::CRC", type => "crc32"]],
  18   "CRC-CCITT"  => [["Digest::CRC", type => "crcccitt"]],
  19   "RIPEMD-160" => "Crypt::RIPEMD160",
  20 );
  21
  22 sub new
  23 {
  24     shift;  # class ignored
  25     my $algorithm = shift;
  26     my $impl = $MMAP{$algorithm} || do {
  27         $algorithm =~ s/\W+//g;
  28         "Digest::$algorithm";
  29     };
  30     $impl = [$impl] unless ref($impl);
  31     local $@;  # don't clobber it for our caller
  32     my $err;
  33     for  (@$impl) {
  34         my $class = $_;
  35         my @args;
  36         ($class, @args) = @$class if ref($class);
  37         no strict 'refs';
  38         unless (exists ${"$class\::"}{"VERSION"}) {
  39             my $pm_file = $class . ".pm";
  40             $pm_file =~ s{::}{/}g;
  41             eval { require $pm_file };
  42             if ($@) {
  43                 $err ||= $@;
  44                 next;
  45             }
  46         }
  47         return $class->new(@args, @_);
  48     }
  49     die $err;
  50 }
  51
  52 sub AUTOLOAD
  53 {
  54     my $class = shift;
  55     my $algorithm = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2);
  56     $class->new($algorithm, @_);
  57 }
  58
  59 1;
  60
  61 __END__
  62
  63 =head1 NAME
  64
  65 Digest - Modules that calculate message digests
  66
  67 =head1 SYNOPSIS
  68
  69   $md5  = Digest->new("MD5");
  70   $sha1 = Digest->new("SHA-1");
  71   $sha256 = Digest->new("SHA-256");
  72   $sha384 = Digest->new("SHA-384");
  73   $sha512 = Digest->new("SHA-512");
  74
  75   $hmac = Digest->HMAC_MD5($key);
  76
  77 =head1 DESCRIPTION
  78
  79 The C<Digest::> modules calculate digests, also called "fingerprints"
  80 or "hashes", of some data, called a message.  The digest is (usually)
  81 some small/fixed size string.  The actual size of the digest depend of
  82 the algorithm used.  The message is simply a sequence of arbitrary
  83 bytes or bits.
  84
  85 An important property of the digest algorithms is that the digest is
  86 I<likely> to change if the message change in some way.  Another
  87 property is that digest functions are one-way functions, that is it
  88 should be I<hard> to find a message that correspond to some given
  89 digest.  Algorithms differ in how "likely" and how "hard", as well as
  90 how efficient they are to compute.
  91
  92 Note that the properties of the algorithms change over time, as the
  93 algorithms are analyzed and machines grow faster.  If your application
  94 for instance depends on it being "impossible" to generate the same
  95 digest for a different message it is wise to make it easy to plug in
  96 stronger algorithms as the one used grow weaker.  Using the interface
  97 documented here should make it easy to change algorithms later.
  98
  99 All C<Digest::> modules provide the same programming interface.  A
 100 functional interface for simple use, as well as an object oriented
 101 interface that can handle messages of arbitrary length and which can
 102 read files directly.
 103
 104 The digest can be delivered in three formats:
 105
 106 =over 8
 107
 108 =item I<binary>
 109
 110 This is the most compact form, but it is not well suited for printing
 111 or embedding in places that can't handle arbitrary data.
 112
 113 =item I<hex>
 114
 115 A twice as long string of lowercase hexadecimal digits.
 116
 117 =item I<base64>
 118
 119 A string of portable printable characters.  This is the base64 encoded
 120 representation of the digest with any trailing padding removed.  The
 121 string will be about 30% longer than the binary version.
 122 L<MIME::Base64> tells you more about this encoding.
 123
 124 =back
 125
 126
 127 The functional interface is simply importable functions with the same
 128 name as the algorithm.  The functions take the message as argument and
 129 return the digest.  Example:
 130
 131   use Digest::MD5 qw(md5);
 132   $digest = md5($message);
 133
 134 There are also versions of the functions with "_hex" or "_base64"
 135 appended to the name, which returns the digest in the indicated form.
 136
 137 =head1 OO INTERFACE
 138
 139 The following methods are available for all C<Digest::> modules:
 140
 141 =over 4
 142
 143 =item $ctx = Digest->XXX($arg,...)
 144
 145 =item $ctx = Digest->new(XXX => $arg,...)
 146
 147 =item $ctx = Digest::XXX->new($arg,...)
 148
 149 The constructor returns some object that encapsulate the state of the
 150 message-digest algorithm.  You can add data to the object and finally
 151 ask for the digest.  The "XXX" should of course be replaced by the proper
 152 name of the digest algorithm you want to use.
 153
 154 The two first forms are simply syntactic sugar which automatically
 155 load the right module on first use.  The second form allow you to use
 156 algorithm names which contains letters which are not legal perl
 157 identifiers, e.g. "SHA-1".  If no implementation for the given algorithm
 158 can be found, then an exception is raised.
 159
 160 If new() is called as an instance method (i.e. $ctx->new) it will just
 161 reset the state the object to the state of a newly created object.  No
 162 new object is created in this case, and the return value is the
 163 reference to the object (i.e. $ctx).
 164
 165 =item $other_ctx = $ctx->clone
 166
 167 The clone method creates a copy of the digest state object and returns
 168 a reference to the copy.
 169
 170 =item $ctx->reset
 171
 172 This is just an alias for $ctx->new.
 173
 174 =item $ctx->add( $data )
 175
 176 =item $ctx->add( $chunk1, $chunk2, ... )
 177
 178 The string value of the $data provided as argument is appended to the
 179 message we calculate the digest for.  The return value is the $ctx
 180 object itself.
 181
 182 If more arguments are provided then they are all appended to the
 183 message, thus all these lines will have the same effect on the state
 184 of the $ctx object:
 185
 186   $ctx->add("a"); $ctx->add("b"); $ctx->add("c");
 187   $ctx->add("a")->add("b")->add("c");
 188   $ctx->add("a", "b", "c");
 189   $ctx->add("abc");
 190
 191 Most algorithms are only defined for strings of bytes and this method
 192 might therefore croak if the provided arguments contain chars with
 193 ordinal number above 255.
 194
 195 =item $ctx->addfile( $io_handle )
 196
 197 The $io_handle is read until EOF and the content is appended to the
 198 message we calculate the digest for.  The return value is the $ctx
 199 object itself.
 200
 201 The addfile() method will croak() if it fails reading data for some
 202 reason.  If it croaks it is unpredictable what the state of the $ctx
 203 object will be in. The addfile() method might have been able to read
 204 the file partially before it failed.  It is probably wise to discard
 205 or reset the $ctx object if this occurs.
 206
 207 In most cases you want to make sure that the $io_handle is in
 208 "binmode" before you pass it as argument to the addfile() method.
 209
 210 =item $ctx->add_bits( $data, $nbits )
 211
 212 =item $ctx->add_bits( $bitstring )
 213
 214 The add_bits() method is an alternative to add() that allow partial
 215 bytes to be appended to the message.  Most users should just ignore
 216 this method as partial bytes is very unlikely to be of any practical
 217 use.
 218
 219 The two argument form of add_bits() will add the first $nbits bits
 220 from $data.  For the last potentially partial byte only the high order
 221 C<< $nbits % 8 >> bits are used.  If $nbits is greater than C<<
 222 length($data) * 8 >>, then this method would do the same as C<<
 223 $ctx->add($data) >>.
 224
 225 The one argument form of add_bits() takes a $bitstring of "1" and "0"
 226 chars as argument.  It's a shorthand for C<< $ctx->add_bits(pack("B*",
 227 $bitstring), length($bitstring)) >>.
 228
 229 The return value is the $ctx object itself.
 230
 231 This example shows two calls that should have the same effect:
 232
 233    $ctx->add_bits("111100001010");
 234    $ctx->add_bits("\xF0\xA0", 12);
 235
 236 Most digest algorithms are byte based and for these it is not possible
 237 to add bits that are not a multiple of 8, and the add_bits() method
 238 will croak if you try.
 239
 240 =item $ctx->digest
 241
 242 Return the binary digest for the message.
 243
 244 Note that the C<digest> operation is effectively a destructive,
 245 read-once operation. Once it has been performed, the $ctx object is
 246 automatically C<reset> and can be used to calculate another digest
 247 value.  Call $ctx->clone->digest if you want to calculate the digest
 248 without resetting the digest state.
 249
 250 =item $ctx->hexdigest
 251
 252 Same as $ctx->digest, but will return the digest in hexadecimal form.
 253
 254 =item $ctx->b64digest
 255
 256 Same as $ctx->digest, but will return the digest as a base64 encoded
 257 string.
 258
 259 =back
 260
 261 =head1 Digest speed
 262
 263 This table should give some indication on the relative speed of
 264 different algorithms.  It is sorted by throughput based on a benchmark
 265 done with of some implementations of this API:
 266
 267  Algorithm      Size    Implementation                  MB/s
 268
 269  MD4            128     Digest::MD4 v1.3               165.0
 270  MD5            128     Digest::MD5 v2.33               98.8
 271  SHA-256        256     Digest::SHA2 v1.1.0             66.7
 272  SHA-1          160     Digest::SHA v4.3.1              58.9
 273  SHA-1          160     Digest::SHA1 v2.10              48.8
 274  SHA-256        256     Digest::SHA v4.3.1              41.3
 275  Haval-256      256     Digest::Haval256 v1.0.4         39.8
 276  SHA-384        384     Digest::SHA2 v1.1.0             19.6
 277  SHA-512        512     Digest::SHA2 v1.1.0             19.3
 278  SHA-384        384     Digest::SHA v4.3.1              19.2
 279  SHA-512        512     Digest::SHA v4.3.1              19.2
 280  Whirlpool      512     Digest::Whirlpool v1.0.2        13.0
 281  MD2            128     Digest::MD2 v2.03                9.5
 282
 283  Adler-32        32     Digest::Adler32 v0.03            1.3
 284  CRC-16          16     Digest::CRC v0.05                1.1
 285  CRC-32          32     Digest::CRC v0.05                1.1
 286  MD5            128     Digest::Perl::MD5 v1.5           1.0
 287  CRC-CCITT       16     Digest::CRC v0.05                0.8
 288
 289 These numbers was achieved Apr 2004 with ActivePerl-5.8.3 running
 290 under Linux on a P4 2.8 GHz CPU.  The last 5 entries differ by being
 291 pure perl implementations of the algorithms, which explains why they
 292 are so slow.
 293
 294 =head1 SEE ALSO
 295
 296 L<Digest::Adler32>, L<Digest::CRC>, L<Digest::Haval256>,
 297 L<Digest::HMAC>, L<Digest::MD2>, L<Digest::MD4>, L<Digest::MD5>,
 298 L<Digest::SHA>, L<Digest::SHA1>, L<Digest::SHA2>, L<Digest::Whirlpool>
 299
 300 New digest implementations should consider subclassing from L<Digest::base>.
 301
 302 L<MIME::Base64>
 303
 304 http://en.wikipedia.org/wiki/Cryptographic_hash_function
 305
 306 =head1 AUTHOR
 307
 308 Gisle Aas <gisle@aas.no>
 309
 310 The C<Digest::> interface is based on the interface originally
 311 developed by Neil Winton for his C<MD5> module.
 312
 313 This library is free software; you can redistribute it and/or
 314 modify it under the same terms as Perl itself.
 315
 316     Copyright 1998-2006 Gisle Aas.
 317     Copyright 1995,1996 Neil Winton.
 318
 319 =cut