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