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