4 use vars qw($VERSION %MMAP $AUTOLOAD);
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",
24 shift; # class ignored
25 my $algorithm = shift;
26 my $impl = $MMAP{$algorithm} || do {
27 $algorithm =~ s/\W+//g;
30 $impl = [$impl] unless ref($impl);
31 local $@; # don't clobber it for our caller
36 ($class, @args) = @$class if ref($class);
38 unless (exists ${"$class\::"}{"VERSION"}) {
39 my $pm_file = $class . ".pm";
40 $pm_file =~ s{::}{/}g;
41 eval { require $pm_file };
47 return $class->new(@args, @_);
55 my $algorithm = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2);
56 $class->new($algorithm, @_);
65 Digest - Modules that calculate message digests
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");
75 $hmac = Digest->HMAC_MD5($key);
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
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.
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.
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
104 The digest can be delivered in three formats:
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.
115 A twice as long string of lowercase hexadecimal digits.
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.
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:
131 use Digest::MD5 qw(md5);
132 $digest = md5($message);
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.
139 The following methods are available for all C<Digest::> modules:
143 =item $ctx = Digest->XXX($arg,...)
145 =item $ctx = Digest->new(XXX => $arg,...)
147 =item $ctx = Digest::XXX->new($arg,...)
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.
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.
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).
165 =item $other_ctx = $ctx->clone
167 The clone method creates a copy of the digest state object and returns
168 a reference to the copy.
172 This is just an alias for $ctx->new.
174 =item $ctx->add( $data )
176 =item $ctx->add( $chunk1, $chunk2, ... )
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
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
186 $ctx->add("a"); $ctx->add("b"); $ctx->add("c");
187 $ctx->add("a")->add("b")->add("c");
188 $ctx->add("a", "b", "c");
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.
195 =item $ctx->addfile( $io_handle )
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
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.
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.
210 =item $ctx->add_bits( $data, $nbits )
212 =item $ctx->add_bits( $bitstring )
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
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<<
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)) >>.
229 The return value is the $ctx object itself.
231 This example shows two calls that should have the same effect:
233 $ctx->add_bits("111100001010");
234 $ctx->add_bits("\xF0\xA0", 12);
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.
242 Return the binary digest for the message.
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.
250 =item $ctx->hexdigest
252 Same as $ctx->digest, but will return the digest in hexadecimal form.
254 =item $ctx->b64digest
256 Same as $ctx->digest, but will return the digest as a base64 encoded
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:
267 Algorithm Size Implementation MB/s
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
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
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
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>
300 New digest implementations should consider subclassing from L<Digest::base>.
304 http://en.wikipedia.org/wiki/Cryptographic_hash_function
308 Gisle Aas <gisle@aas.no>
310 The C<Digest::> interface is based on the interface originally
311 developed by Neil Winton for his C<MD5> module.
313 This library is free software; you can redistribute it and/or
314 modify it under the same terms as Perl itself.
316 Copyright 1998-2006 Gisle Aas.
317 Copyright 1995,1996 Neil Winton.