4 use vars qw($VERSION %MMAP $AUTOLOAD);
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",
19 shift; # class ignored
20 my $algorithm = shift;
21 my $impl = $MMAP{$algorithm} || do {
22 $algorithm =~ s/\W+//;
25 $impl = [$impl] unless ref($impl);
30 ($class, @args) = @$class if ref($class);
32 unless (exists ${"$class\::"}{"VERSION"}) {
33 eval "require $class";
39 return $class->new(@args, @_);
47 my $algorithm = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2);
48 $class->new($algorithm, @_);
57 Digest:: - Modules that calculate message digests
65 $sha1 = Digest->new("SHA-1");
67 $hmac = Digest->HMAC_MD5($key);
71 The C<Digest::> modules calculate digests, also called "fingerprints"
72 or "hashes", of some data, called a message. The digest is (usually)
73 some small/fixed size string. The actual size of the digest depend of
74 the algorithm used. The message is simply a sequence of arbitrary
77 An important property of the digest algorithms is that the digest is
78 I<likely> to change if the message change in some way. Another
79 property is that digest functions are one-way functions, i.e. it
80 should be I<hard> to find a message that correspond to some given
81 digest. Algorithms differ in how "likely" and how "hard", as well as
82 how efficient they are to compute.
84 All C<Digest::> modules provide the same programming interface. A
85 functional interface for simple use, as well as an object oriented
86 interface that can handle messages of arbitrary length and which can
89 The digest can be delivered in three formats:
95 This is the most compact form, but it is not well suited for printing
96 or embedding in places that can't handle arbitrary data.
100 A twice as long string of (lowercase) hexadecimal digits.
104 A string of portable printable characters. This is the base64 encoded
105 representation of the digest with any trailing padding removed. The
106 string will be about 30% longer than the binary version.
107 L<MIME::Base64> tells you more about this encoding.
112 The functional interface is simply importable functions with the same
113 name as the algorithm. The functions take the message as argument and
114 return the digest. Example:
116 use Digest::MD5 qw(md5);
117 $digest = md5($message);
119 There are also versions of the functions with "_hex" or "_base64"
120 appended to the name, which returns the digest in the indicated form.
124 The following methods are available for all C<Digest::> modules:
128 =item $ctx = Digest->XXX($arg,...)
130 =item $ctx = Digest->new(XXX => $arg,...)
132 =item $ctx = Digest::XXX->new($arg,...)
134 The constructor returns some object that encapsulate the state of the
135 message-digest algorithm. You can add data to the object and finally
136 ask for the digest. The "XXX" should of course be replaced by the proper
137 name of the digest algorithm you want to use.
139 The two first forms are simply syntactic sugar which automatically
140 load the right module on first use. The second form allow you to use
141 algorithm names which contains letters which are not legal perl
142 identifiers, e.g. "SHA-1".
144 If new() is called as an instance method (i.e. $ctx->new) it will just
145 reset the state the object to the state of a newly created object. No
146 new object is created in this case, and the return value is the
147 reference to the object (i.e. $ctx).
149 =item $other_ctx = $ctx->clone
151 The clone method creates a copy of the digest state object and returns
152 a reference to the copy.
156 This is just an alias for $ctx->new.
158 =item $ctx->add($data,...)
160 The $data provided as argument are appended to the message we
161 calculate the digest for. The return value is the $ctx object itself.
163 =item $ctx->addfile($io_handle)
165 The $io_handle is read until EOF and the content is appended to the
166 message we calculate the digest for. The return value is the $ctx
169 =item $ctx->add_bits($data, $nbits)
171 =item $ctx->add_bits($bitstring)
173 The bits provided are appended to the message we calculate the digest
174 for. The return value is the $ctx object itself.
176 The two argument form of add_bits() will add the first $nbits bits
177 from data. For the last potentially partial byte only the high order
178 C<< $nbits % 8 >> bits are used. If $nbits is greater than C<<
179 length($data) * 8 >>, then this method would do the same as C<<
180 $ctx->add($data) >>, i.e. $nbits is silently ignored.
182 The one argument form of add_bits() takes a $bitstring of "1" and "0"
183 chars as argument. It's a shorthand for C<< $ctx->add_bits(pack("B*",
184 $bitstring), length($bitstring)) >>.
186 This example shows two calls that should have the same effect:
188 $ctx->add_bits("111100001010");
189 $ctx->add_bits("\xF0\xA0", 12);
191 Most digest algorithms are byte based. For those it is not possible
192 to add bits that are not a multiple of 8, and the add_bits() method
193 will croak if you try.
197 Return the binary digest for the message.
199 Note that the C<digest> operation is effectively a destructive,
200 read-once operation. Once it has been performed, the $ctx object is
201 automatically C<reset> and can be used to calculate another digest
202 value. Call $ctx->clone->digest if you want to calculate the digest
203 without reseting the digest state.
205 =item $ctx->hexdigest
207 Same as $ctx->digest, but will return the digest in hexadecimal form.
209 =item $ctx->b64digest
211 Same as $ctx->digest, but will return the digest as a base64 encoded
218 L<Digest::MD5>, L<Digest::SHA1>, L<Digest::HMAC>, L<Digest::MD2>
224 Gisle Aas <gisle@aas.no>
226 The C<Digest::> interface is based on the interface originally
227 developed by Neil Winton for his C<MD5> module.