1package Digest; 2 3use strict; 4use vars qw($VERSION %MMAP $AUTOLOAD); 5 6$VERSION = "1.06"; 7 8%MMAP = ( 9 "SHA-1" => ["Digest::SHA1", ["Digest::SHA", 1], ["Digest::SHA2", 1]], 10 "SHA-256" => [["Digest::SHA", 256], ["Digest::SHA2", 256]], 11 "SHA-384" => [["Digest::SHA", 384], ["Digest::SHA2", 384]], 12 "SHA-512" => [["Digest::SHA", 512], ["Digest::SHA2", 512]], 13 "HMAC-MD5" => "Digest::HMAC_MD5", 14 "HMAC-SHA-1" => "Digest::HMAC_SHA1", 15); 16 17sub new 18{ 19 shift; # class ignored 20 my $algorithm = shift; 21 my $impl = $MMAP{$algorithm} || do { 22 $algorithm =~ s/\W+//; 23 "Digest::$algorithm"; 24 }; 25 $impl = [$impl] unless ref($impl); 26 my $err; 27 for (@$impl) { 28 my $class = $_; 29 my @args; 30 ($class, @args) = @$class if ref($class); 31 no strict 'refs'; 32 unless (exists ${"$class\::"}{"VERSION"}) { 33 eval "require $class"; 34 if ($@) { 35 $err ||= $@; 36 next; 37 } 38 } 39 return $class->new(@args, @_); 40 } 41 die $err; 42} 43 44sub AUTOLOAD 45{ 46 my $class = shift; 47 my $algorithm = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2); 48 $class->new($algorithm, @_); 49} 50 511; 52 53__END__ 54 55=head1 NAME 56 57Digest - Modules that calculate message digests 58 59=head1 SYNOPSIS 60 61 $md5 = Digest->new("MD5"); 62 $sha1 = Digest->new("SHA-1"); 63 $sha256 = Digest->new("SHA-256"); 64 $sha384 = Digest->new("SHA-384"); 65 $sha512 = Digest->new("SHA-512"); 66 67 $hmac = Digest->HMAC_MD5($key); 68 69=head1 DESCRIPTION 70 71The C<Digest::> modules calculate digests, also called "fingerprints" 72or "hashes", of some data, called a message. The digest is (usually) 73some small/fixed size string. The actual size of the digest depend of 74the algorithm used. The message is simply a sequence of arbitrary 75bytes or bits. 76 77An important property of the digest algorithms is that the digest is 78I<likely> to change if the message change in some way. Another 79property is that digest functions are one-way functions, i.e. it 80should be I<hard> to find a message that correspond to some given 81digest. Algorithms differ in how "likely" and how "hard", as well as 82how efficient they are to compute. 83 84All C<Digest::> modules provide the same programming interface. A 85functional interface for simple use, as well as an object oriented 86interface that can handle messages of arbitrary length and which can 87read files directly. 88 89The digest can be delivered in three formats: 90 91=over 8 92 93=item I<binary> 94 95This is the most compact form, but it is not well suited for printing 96or embedding in places that can't handle arbitrary data. 97 98=item I<hex> 99 100A twice as long string of lowercase hexadecimal digits. 101 102=item I<base64> 103 104A string of portable printable characters. This is the base64 encoded 105representation of the digest with any trailing padding removed. The 106string will be about 30% longer than the binary version. 107L<MIME::Base64> tells you more about this encoding. 108 109=back 110 111 112The functional interface is simply importable functions with the same 113name as the algorithm. The functions take the message as argument and 114return the digest. Example: 115 116 use Digest::MD5 qw(md5); 117 $digest = md5($message); 118 119There are also versions of the functions with "_hex" or "_base64" 120appended to the name, which returns the digest in the indicated form. 121 122=head1 OO INTERFACE 123 124The following methods are available for all C<Digest::> modules: 125 126=over 4 127 128=item $ctx = Digest->XXX($arg,...) 129 130=item $ctx = Digest->new(XXX => $arg,...) 131 132=item $ctx = Digest::XXX->new($arg,...) 133 134The constructor returns some object that encapsulate the state of the 135message-digest algorithm. You can add data to the object and finally 136ask for the digest. The "XXX" should of course be replaced by the proper 137name of the digest algorithm you want to use. 138 139The two first forms are simply syntactic sugar which automatically 140load the right module on first use. The second form allow you to use 141algorithm names which contains letters which are not legal perl 142identifiers, e.g. "SHA-1". If no implementation for the given algorithm 143can be found, then an exception is raised. 144 145If new() is called as an instance method (i.e. $ctx->new) it will just 146reset the state the object to the state of a newly created object. No 147new object is created in this case, and the return value is the 148reference to the object (i.e. $ctx). 149 150=item $other_ctx = $ctx->clone 151 152The clone method creates a copy of the digest state object and returns 153a reference to the copy. 154 155=item $ctx->reset 156 157This is just an alias for $ctx->new. 158 159=item $ctx->add( $data, ... ) 160 161The $data provided as argument are appended to the message we 162calculate the digest for. The return value is the $ctx object itself. 163 164=item $ctx->addfile( $io_handle ) 165 166The $io_handle is read until EOF and the content is appended to the 167message we calculate the digest for. The return value is the $ctx 168object itself. 169 170=item $ctx->add_bits( $data, $nbits ) 171 172=item $ctx->add_bits( $bitstring ) 173 174The bits provided are appended to the message we calculate the digest 175for. The return value is the $ctx object itself. 176 177The two argument form of add_bits() will add the first $nbits bits 178from data. For the last potentially partial byte only the high order 179C<< $nbits % 8 >> bits are used. If $nbits is greater than C<< 180length($data) * 8 >>, then this method would do the same as C<< 181$ctx->add($data) >>, i.e. $nbits is silently ignored. 182 183The one argument form of add_bits() takes a $bitstring of "1" and "0" 184chars as argument. It's a shorthand for C<< $ctx->add_bits(pack("B*", 185$bitstring), length($bitstring)) >>. 186 187This example shows two calls that should have the same effect: 188 189 $ctx->add_bits("111100001010"); 190 $ctx->add_bits("\xF0\xA0", 12); 191 192Most digest algorithms are byte based. For those it is not possible 193to add bits that are not a multiple of 8, and the add_bits() method 194will croak if you try. 195 196=item $ctx->digest 197 198Return the binary digest for the message. 199 200Note that the C<digest> operation is effectively a destructive, 201read-once operation. Once it has been performed, the $ctx object is 202automatically C<reset> and can be used to calculate another digest 203value. Call $ctx->clone->digest if you want to calculate the digest 204without reseting the digest state. 205 206=item $ctx->hexdigest 207 208Same as $ctx->digest, but will return the digest in hexadecimal form. 209 210=item $ctx->b64digest 211 212Same as $ctx->digest, but will return the digest as a base64 encoded 213string. 214 215=back 216 217=head1 Digest speed 218 219This table should give some indication on the relative speed of 220different algorithms. It is sorted by throughput based on a benchmark 221done with of some implementations of this API: 222 223 Algorithm Size Implementation MB/s 224 225 MD4 128 Digest::MD4 v1.1 24.9 226 MD5 128 Digest::MD5 v2.30 18.7 227 Haval-256 256 Digest::Haval256 v1.0.4 17.0 228 SHA-1 160 Digest::SHA1 v2.06 15.3 229 SHA-1 160 Digest::SHA v4.0.0 10.1 230 SHA-256 256 Digest::SHA2 v1.0.0 7.6 231 SHA-256 256 Digest::SHA v4.0.0 6.5 232 SHA-384 384 Digest::SHA2 v1.0.0 2.7 233 SHA-384 384 Digest::SHA v4.0.0 2.7 234 SHA-512 512 Digest::SHA2 v1.0.0 2.7 235 SHA-512 512 Digest::SHA v4.0.0 2.7 236 Whirlpool 512 Digest::Whirlpool v1.0.2 1.4 237 MD2 128 Digest::MD2 v2.03 1.1 238 239 Adler-32 32 Digest::Adler32 v0.03 0.2 240 MD5 128 Digest::Perl::MD5 v1.5 0.1 241 242These numbers was achieved Nov 2003 with ActivePerl-5.8.1 running 243under Linux on a P-II 350 MHz CPU. The last 2 entries differ by being 244pure perl implementations of the algorithms, which explains why they 245are so slow. 246 247=head1 SEE ALSO 248 249L<Digest::Adler32>, L<Digest::Haval256>, L<Digest::HMAC>, L<Digest::MD2>, L<Digest::MD4>, L<Digest::MD5>, L<Digest::SHA>, L<Digest::SHA1>, L<Digest::SHA2>, L<Digest::Whirlpool> 250 251New digest implementations should consider subclassing from L<Digest::base>. 252 253L<MIME::Base64> 254 255=head1 AUTHOR 256 257Gisle Aas <gisle@aas.no> 258 259The C<Digest::> interface is based on the interface originally 260developed by Neil Winton for his C<MD5> module. 261 262This library is free software; you can redistribute it and/or 263modify it under the same terms as Perl itself. 264 265 Copyright 1998-2001,2003-2004 Gisle Aas. 266 Copyright 1995-1996 Neil Winton. 267 268=cut 269