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