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