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