This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Assimilate Cwd 2.12 from CPAN. Cwd wasn't in Maintainers, so change
[perl5.git] / lib / Digest.pm
CommitLineData
3357b1b1
JH
1package Digest;
2
3use strict;
4use vars qw($VERSION %MMAP $AUTOLOAD);
5
b12d758c 6$VERSION = "1.03";
3357b1b1
JH
7
8%MMAP = (
b12d758c
NC
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]],
3357b1b1
JH
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;
b12d758c
NC
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, @_);
3357b1b1 40 }
b12d758c 41 die $err;
3357b1b1
JH
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 $md2 = Digest->MD2;
62 $md5 = Digest->MD5;
63
64 $sha1 = Digest->SHA1;
65 $sha1 = Digest->new("SHA-1");
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
b12d758c 75bytes or bits.
3357b1b1
JH
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".
143
67859229 144If new() is called as an instance method (i.e. $ctx->new) it will just
3357b1b1
JH
145reset the state the object to the state of a newly created object. No
146new object is created in this case, and the return value is the
147reference to the object (i.e. $ctx).
148
70ee4409
JH
149=item $other_ctx = $ctx->clone
150
151The clone method creates a copy of the digest state object and returns
152a reference to the copy.
153
3357b1b1
JH
154=item $ctx->reset
155
156This is just an alias for $ctx->new.
157
158=item $ctx->add($data,...)
159
160The $data provided as argument are appended to the message we
161calculate the digest for. The return value is the $ctx object itself.
162
163=item $ctx->addfile($io_handle)
164
165The $io_handle is read until EOF and the content is appended to the
166message we calculate the digest for. The return value is the $ctx
167object itself.
168
b12d758c
NC
169=item $ctx->add_bits($data, $nbits)
170
171=item $ctx->add_bits($bitstring)
172
173The bits provided are appended to the message we calculate the digest
174for. The return value is the $ctx object itself.
175
176The two argument form of add_bits() will add the first $nbits bits
177from data. For the last potentially partial byte only the high order
178C<< $nbits % 8 >> bits are used. If $nbits is greater than C<<
179length($data) * 8 >>, then this method would do the same as C<<
180$ctx->add($data) >>, i.e. $nbits is silently ignored.
181
182The one argument form of add_bits() takes a $bitstring of "1" and "0"
183chars as argument. It's a shorthand for C<< $ctx->add_bits(pack("B*",
184$bitstring), length($bitstring)) >>.
185
186This example shows two calls that should have the same effect:
187
188 $ctx->add_bits("111100001010");
189 $ctx->add_bits("\xF0\xA0", 12);
190
191Most digest algorithms are byte based. For those it is not possible
192to add bits that are not a multiple of 8, and the add_bits() method
193will croak if you try.
194
3357b1b1
JH
195=item $ctx->digest
196
197Return the binary digest for the message.
198
199Note that the C<digest> operation is effectively a destructive,
200read-once operation. Once it has been performed, the $ctx object is
201automatically C<reset> and can be used to calculate another digest
70ee4409
JH
202value. Call $ctx->clone->digest if you want to calculate the digest
203without reseting the digest state.
3357b1b1
JH
204
205=item $ctx->hexdigest
206
207Same as $ctx->digest, but will return the digest in hexadecimal form.
208
209=item $ctx->b64digest
210
211Same as $ctx->digest, but will return the digest as a base64 encoded
212string.
213
214=back
215
216=head1 SEE ALSO
217
218L<Digest::MD5>, L<Digest::SHA1>, L<Digest::HMAC>, L<Digest::MD2>
219
220L<MIME::Base64>
221
222=head1 AUTHOR
223
224Gisle Aas <gisle@aas.no>
225
226The C<Digest::> interface is based on the interface originally
227developed by Neil Winton for his C<MD5> module.
228
229=cut