This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate Digest-1.00 and Digest-MD5-2.13, from Gisle Aas.
[perl5.git] / lib / Digest.pm
CommitLineData
3357b1b1
JH
1package Digest;
2
3use strict;
4use vars qw($VERSION %MMAP $AUTOLOAD);
5
6$VERSION = "1.00";
7
8%MMAP = (
9 "SHA-1" => "Digest::SHA1",
10 "HMAC-MD5" => "Digest::HMAC_MD5",
11 "HMAC-SHA-1" => "Digest::HMAC_SHA1",
12);
13
14sub new
15{
16 shift; # class ignored
17 my $algorithm = shift;
18 my $class = $MMAP{$algorithm} || "Digest::$algorithm";
19 no strict 'refs';
20 unless (exists ${"$class\::"}{"VERSION"}) {
21 eval "require $class";
22 die $@ if $@;
23 }
24 $class->new(@_);
25}
26
27sub AUTOLOAD
28{
29 my $class = shift;
30 my $algorithm = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2);
31 $class->new($algorithm, @_);
32}
33
341;
35
36__END__
37
38=head1 NAME
39
40Digest:: - Modules that calculate message digests
41
42=head1 SYNOPSIS
43
44 $md2 = Digest->MD2;
45 $md5 = Digest->MD5;
46
47 $sha1 = Digest->SHA1;
48 $sha1 = Digest->new("SHA-1");
49
50 $hmac = Digest->HMAC_MD5($key);
51
52=head1 DESCRIPTION
53
54The C<Digest::> modules calculate digests, also called "fingerprints"
55or "hashes", of some data, called a message. The digest is (usually)
56some small/fixed size string. The actual size of the digest depend of
57the algorithm used. The message is simply a sequence of arbitrary
58bytes.
59
60An important property of the digest algorithms is that the digest is
61I<likely> to change if the message change in some way. Another
62property is that digest functions are one-way functions, i.e. it
63should be I<hard> to find a message that correspond to some given
64digest. Algorithms differ in how "likely" and how "hard", as well as
65how efficient they are to compute.
66
67All C<Digest::> modules provide the same programming interface. A
68functional interface for simple use, as well as an object oriented
69interface that can handle messages of arbitrary length and which can
70read files directly.
71
72The digest can be delivered in three formats:
73
74=over 8
75
76=item I<binary>
77
78This is the most compact form, but it is not well suited for printing
79or embedding in places that can't handle arbitrary data.
80
81=item I<hex>
82
83A twice as long string of (lowercase) hexadecimal digits.
84
85=item I<base64>
86
87A string of portable printable characters. This is the base64 encoded
88representation of the digest with any trailing padding removed. The
89string will be about 30% longer than the binary version.
90L<MIME::Base64> tells you more about this encoding.
91
92=back
93
94
95The functional interface is simply importable functions with the same
96name as the algorithm. The functions take the message as argument and
97return the digest. Example:
98
99 use Digest::MD5 qw(md5);
100 $digest = md5($message);
101
102There are also versions of the functions with "_hex" or "_base64"
103appended to the name, which returns the digest in the indicated form.
104
105=head1 OO INTERFACE
106
107The following methods are available for all C<Digest::> modules:
108
109=over 4
110
111=item $ctx = Digest->XXX($arg,...)
112
113=item $ctx = Digest->new(XXX => $arg,...)
114
115=item $ctx = Digest::XXX->new($arg,...)
116
117The constructor returns some object that encapsulate the state of the
118message-digest algorithm. You can add data to the object and finally
119ask for the digest. The "XXX" should of course be replaced by the proper
120name of the digest algorithm you want to use.
121
122The two first forms are simply syntactic sugar which automatically
123load the right module on first use. The second form allow you to use
124algorithm names which contains letters which are not legal perl
125identifiers, e.g. "SHA-1".
126
127If new() is called as a instance method (i.e. $ctx->new) it will just
128reset the state the object to the state of a newly created object. No
129new object is created in this case, and the return value is the
130reference to the object (i.e. $ctx).
131
132=item $ctx->reset
133
134This is just an alias for $ctx->new.
135
136=item $ctx->add($data,...)
137
138The $data provided as argument are appended to the message we
139calculate the digest for. The return value is the $ctx object itself.
140
141=item $ctx->addfile($io_handle)
142
143The $io_handle is read until EOF and the content is appended to the
144message we calculate the digest for. The return value is the $ctx
145object itself.
146
147=item $ctx->digest
148
149Return the binary digest for the message.
150
151Note that the C<digest> operation is effectively a destructive,
152read-once operation. Once it has been performed, the $ctx object is
153automatically C<reset> and can be used to calculate another digest
154value.
155
156=item $ctx->hexdigest
157
158Same as $ctx->digest, but will return the digest in hexadecimal form.
159
160=item $ctx->b64digest
161
162Same as $ctx->digest, but will return the digest as a base64 encoded
163string.
164
165=back
166
167=head1 SEE ALSO
168
169L<Digest::MD5>, L<Digest::SHA1>, L<Digest::HMAC>, L<Digest::MD2>
170
171L<MIME::Base64>
172
173=head1 AUTHOR
174
175Gisle Aas <gisle@aas.no>
176
177The C<Digest::> interface is based on the interface originally
178developed by Neil Winton for his C<MD5> module.
179
180=cut