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