Commit | Line | Data |
3357b1b1 |
1 | package Digest::MD5; |
2 | |
3 | use strict; |
4 | use vars qw($VERSION @ISA @EXPORT_OK); |
5 | |
ee7ea0b1 |
6 | $VERSION = '2.33'; # $Date: 2003/12/07 08:40:18 $ |
3357b1b1 |
7 | |
8 | require Exporter; |
9 | *import = \&Exporter::import; |
10 | @EXPORT_OK = qw(md5 md5_hex md5_base64); |
11 | |
12 | require DynaLoader; |
13 | @ISA=qw(DynaLoader); |
14 | |
15 | eval { |
49953a3f |
16 | require Digest::base; |
17 | push(@ISA, 'Digest::base'); |
18 | }; |
19 | if ($@) { |
20 | my $err = $@; |
21 | *add_bits = sub { die $err }; |
22 | } |
23 | |
24 | |
25 | eval { |
3357b1b1 |
26 | Digest::MD5->bootstrap($VERSION); |
27 | }; |
28 | if ($@) { |
db2a39d5 |
29 | my $olderr = $@; |
30 | eval { |
31 | # Try to load the pure perl version |
32 | require Digest::Perl::MD5; |
33 | |
34 | Digest::Perl::MD5->import(qw(md5 md5_hex md5_base64)); |
35 | push(@ISA, "Digest::Perl::MD5"); # make OO interface work |
36 | }; |
37 | if ($@) { |
38 | # restore the original error |
39 | die $olderr; |
40 | } |
3357b1b1 |
41 | } |
42 | else { |
43 | *reset = \&new; |
44 | } |
45 | |
46 | 1; |
47 | __END__ |
48 | |
49 | =head1 NAME |
50 | |
51 | Digest::MD5 - Perl interface to the MD5 Algorithm |
52 | |
53 | =head1 SYNOPSIS |
54 | |
55 | # Functional style |
ac70dec1 |
56 | use Digest::MD5 qw(md5 md5_hex md5_base64); |
3357b1b1 |
57 | |
58 | $digest = md5($data); |
59 | $digest = md5_hex($data); |
60 | $digest = md5_base64($data); |
61 | |
62 | # OO style |
63 | use Digest::MD5; |
64 | |
65 | $ctx = Digest::MD5->new; |
66 | |
67 | $ctx->add($data); |
68 | $ctx->addfile(*FILE); |
69 | |
70 | $digest = $ctx->digest; |
71 | $digest = $ctx->hexdigest; |
72 | $digest = $ctx->b64digest; |
73 | |
74 | =head1 DESCRIPTION |
75 | |
76 | The C<Digest::MD5> module allows you to use the RSA Data Security |
77 | Inc. MD5 Message Digest algorithm from within Perl programs. The |
78 | algorithm takes as input a message of arbitrary length and produces as |
79 | output a 128-bit "fingerprint" or "message digest" of the input. |
80 | |
81 | The C<Digest::MD5> module provide a procedural interface for simple |
82 | use, as well as an object oriented interface that can handle messages |
83 | of arbitrary length and which can read files directly. |
84 | |
3357b1b1 |
85 | =head1 FUNCTIONS |
86 | |
ac70dec1 |
87 | The following functions are provided by the C<Digest::MD5> module. |
88 | None of these functions are exported by default. |
3357b1b1 |
89 | |
90 | =over 4 |
91 | |
92 | =item md5($data,...) |
93 | |
94 | This function will concatenate all arguments, calculate the MD5 digest |
ac70dec1 |
95 | of this "message", and return it in binary form. The returned string |
96 | will be 16 bytes long. |
97 | |
98 | The result of md5("a", "b", "c") will be exactly the same as the |
99 | result of md5("abc"). |
3357b1b1 |
100 | |
101 | =item md5_hex($data,...) |
102 | |
ac70dec1 |
103 | Same as md5(), but will return the digest in hexadecimal form. The |
104 | length of the returned string will be 32 and it will only contain |
105 | characters from this set: '0'..'9' and 'a'..'f'. |
3357b1b1 |
106 | |
107 | =item md5_base64($data,...) |
108 | |
109 | Same as md5(), but will return the digest as a base64 encoded string. |
ac70dec1 |
110 | The length of the returned string will be 22 and it will only contain |
111 | characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and |
112 | '/'. |
3357b1b1 |
113 | |
ac70dec1 |
114 | Note that the base64 encoded string returned is not padded to be a |
115 | multiple of 4 bytes long. If you want interoperability with other |
116 | base64 encoded md5 digests you might want to append the redundant |
8be5f608 |
117 | string "==" to the result. |
db2a39d5 |
118 | |
3357b1b1 |
119 | =back |
120 | |
121 | =head1 METHODS |
122 | |
ac70dec1 |
123 | The object oriented interface to C<Digest::MD5> is described in this |
124 | section. After a C<Digest::MD5> object has been created, you will add |
125 | data to it and finally ask for the digest in a suitable format. A |
126 | single object can be used to calculate multiple digests. |
127 | |
128 | The following methods are provided: |
3357b1b1 |
129 | |
130 | =over 4 |
131 | |
132 | =item $md5 = Digest::MD5->new |
133 | |
134 | The constructor returns a new C<Digest::MD5> object which encapsulate |
ac70dec1 |
135 | the state of the MD5 message-digest algorithm. |
3357b1b1 |
136 | |
d1be9408 |
137 | If called as an instance method (i.e. $md5->new) it will just reset the |
3357b1b1 |
138 | state the object to the state of a newly created object. No new |
139 | object is created in this case. |
140 | |
141 | =item $md5->reset |
142 | |
143 | This is just an alias for $md5->new. |
144 | |
ac70dec1 |
145 | =item $md5->clone |
146 | |
147 | This a copy of the $md5 object. It is useful when you do not want to |
148 | destroy the digests state, but need an intermediate value of the |
149 | digest, e.g. when calculating digests iteratively on a continuous data |
150 | stream. Example: |
151 | |
152 | my $md5 = Digest::MD5->new; |
153 | while (<>) { |
154 | $md5->add($_); |
155 | print "Line $.: ", $md5->clone->hexdigest, "\n"; |
156 | } |
157 | |
3357b1b1 |
158 | =item $md5->add($data,...) |
159 | |
160 | The $data provided as argument are appended to the message we |
161 | calculate the digest for. The return value is the $md5 object itself. |
162 | |
ac70dec1 |
163 | All these lines will have the same effect on the state of the $md5 |
164 | object: |
165 | |
166 | $md5->add("a"); $md5->add("b"); $md5->add("c"); |
167 | $md5->add("a")->add("b")->add("c"); |
168 | $md5->add("a", "b", "c"); |
169 | $md5->add("abc"); |
170 | |
3357b1b1 |
171 | =item $md5->addfile($io_handle) |
172 | |
ac70dec1 |
173 | The $io_handle will be read until EOF and its content appended to the |
3357b1b1 |
174 | message we calculate the digest for. The return value is the $md5 |
175 | object itself. |
176 | |
ac70dec1 |
177 | The addfile() method will croak() if it fails reading data for some |
178 | reason. If it croaks it is unpredictable what the state of the $md5 |
179 | object will be in. The addfile() method might have been able to read |
180 | the file partially before it failed. It is probably wise to discard |
181 | or reset the $md5 object if this occurs. |
182 | |
183 | In most cases you want to make sure that the $io_handle is in |
184 | C<binmode> before you pass it as argument to the addfile() method. |
3357b1b1 |
185 | |
49953a3f |
186 | =item $md5->add_bits($data, $nbits) |
187 | |
188 | =item $md5->add_bits($bitstring) |
189 | |
190 | Since the MD5 algorithm is byte oriented you might only add bits as |
191 | multiples of 8, so you probably want to just use add() instead. The |
192 | add_bits() method is provided for compatibility with other digest |
ee7ea0b1 |
193 | implementations. See L<Digest> for description of the arguments |
194 | that add_bits() take. |
49953a3f |
195 | |
3357b1b1 |
196 | =item $md5->digest |
197 | |
ac70dec1 |
198 | Return the binary digest for the message. The returned string will be |
199 | 16 bytes long. |
3357b1b1 |
200 | |
201 | Note that the C<digest> operation is effectively a destructive, |
202 | read-once operation. Once it has been performed, the C<Digest::MD5> |
203 | object is automatically C<reset> and can be used to calculate another |
f62a1bde |
204 | digest value. Call $md5->clone->digest if you want to calculate the |
205 | digest without reseting the digest state. |
3357b1b1 |
206 | |
207 | =item $md5->hexdigest |
208 | |
ac70dec1 |
209 | Same as $md5->digest, but will return the digest in hexadecimal |
210 | form. The length of the returned string will be 32 and it will only |
211 | contain characters from this set: '0'..'9' and 'a'..'f'. |
3357b1b1 |
212 | |
213 | =item $md5->b64digest |
214 | |
215 | Same as $md5->digest, but will return the digest as a base64 encoded |
ac70dec1 |
216 | string. The length of the returned string will be 22 and it will only |
217 | contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' |
218 | and '/'. |
219 | |
3357b1b1 |
220 | |
db2a39d5 |
221 | The base64 encoded string returned is not padded to be a multiple of 4 |
222 | bytes long. If you want interoperability with other base64 encoded |
223 | md5 digests you might want to append the string "==" to the result. |
224 | |
3357b1b1 |
225 | =back |
226 | |
227 | |
228 | =head1 EXAMPLES |
229 | |
230 | The simplest way to use this library is to import the md5_hex() |
231 | function (or one of its cousins): |
232 | |
233 | use Digest::MD5 qw(md5_hex); |
234 | print "Digest is ", md5_hex("foobarbaz"), "\n"; |
235 | |
ac70dec1 |
236 | The above example would print out the message: |
3357b1b1 |
237 | |
238 | Digest is 6df23dc03f9b54cc38a0fc1483df6e21 |
239 | |
ac70dec1 |
240 | The same checksum can also be calculated in OO style: |
3357b1b1 |
241 | |
242 | use Digest::MD5; |
243 | |
244 | $md5 = Digest::MD5->new; |
245 | $md5->add('foo', 'bar'); |
246 | $md5->add('baz'); |
247 | $digest = $md5->hexdigest; |
248 | |
249 | print "Digest is $digest\n"; |
250 | |
251 | With OO style you can break the message arbitrary. This means that we |
252 | are no longer limited to have space for the whole message in memory, i.e. |
253 | we can handle messages of any size. |
254 | |
255 | This is useful when calculating checksum for files: |
256 | |
257 | use Digest::MD5; |
258 | |
259 | my $file = shift || "/etc/passwd"; |
260 | open(FILE, $file) or die "Can't open '$file': $!"; |
261 | binmode(FILE); |
262 | |
263 | $md5 = Digest::MD5->new; |
264 | while (<FILE>) { |
265 | $md5->add($_); |
266 | } |
267 | close(FILE); |
268 | print $md5->b64digest, " $file\n"; |
269 | |
8be5f608 |
270 | Or we can use the addfile method for more efficient reading of |
3357b1b1 |
271 | the file: |
272 | |
273 | use Digest::MD5; |
274 | |
275 | my $file = shift || "/etc/passwd"; |
276 | open(FILE, $file) or die "Can't open '$file': $!"; |
277 | binmode(FILE); |
278 | |
279 | print Digest::MD5->new->addfile(*FILE)->hexdigest, " $file\n"; |
280 | |
9a03235d |
281 | Perl 5.8 support Unicode characters in strings. Since the MD5 |
282 | algorithm is only defined for strings of bytes, it can not be used on |
283 | strings that contains chars with ordinal number above 255. The MD5 |
284 | functions and methods will croak if you try to feed them such input |
285 | data: |
286 | |
287 | use Digest::MD5 qw(md5_hex); |
288 | |
289 | my $str = "abc\x{300}"; |
290 | print md5_hex($str), "\n"; # croaks |
291 | # Wide character in subroutine entry |
292 | |
293 | What you can do is calculate the MD5 checksum of the UTF-8 |
294 | representation of such strings. This is achieved by filtering the |
295 | string through encode_utf8() function: |
296 | |
297 | use Digest::MD5 qw(md5_hex); |
298 | use Encode qw(encode_utf8); |
299 | |
300 | my $str = "abc\x{300}"; |
301 | print md5_hex(encode_utf8($str)), "\n"; |
302 | # 8c2d46911f3f5a326455f0ed7a8ed3b3 |
303 | |
3357b1b1 |
304 | =head1 SEE ALSO |
305 | |
306 | L<Digest>, |
307 | L<Digest::MD2>, |
308 | L<Digest::SHA1>, |
309 | L<Digest::HMAC> |
310 | |
311 | L<md5sum(1)> |
312 | |
313 | RFC 1321 |
314 | |
315 | =head1 COPYRIGHT |
316 | |
317 | This library is free software; you can redistribute it and/or |
318 | modify it under the same terms as Perl itself. |
319 | |
f62a1bde |
320 | Copyright 1998-2003 Gisle Aas. |
3357b1b1 |
321 | Copyright 1995-1996 Neil Winton. |
322 | Copyright 1991-1992 RSA Data Security, Inc. |
323 | |
ac70dec1 |
324 | The MD5 algorithm is defined in RFC 1321. This implementation is |
325 | derived from the reference C code in RFC 1321 which is covered by |
326 | the following copyright statement: |
3357b1b1 |
327 | |
328 | =over 4 |
329 | |
330 | =item |
331 | |
332 | Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All |
333 | rights reserved. |
334 | |
335 | License to copy and use this software is granted provided that it |
336 | is identified as the "RSA Data Security, Inc. MD5 Message-Digest |
337 | Algorithm" in all material mentioning or referencing this software |
338 | or this function. |
339 | |
340 | License is also granted to make and use derivative works provided |
341 | that such works are identified as "derived from the RSA Data |
342 | Security, Inc. MD5 Message-Digest Algorithm" in all material |
343 | mentioning or referencing the derived work. |
344 | |
345 | RSA Data Security, Inc. makes no representations concerning either |
346 | the merchantability of this software or the suitability of this |
347 | software for any particular purpose. It is provided "as is" |
348 | without express or implied warranty of any kind. |
349 | |
350 | These notices must be retained in any copies of any part of this |
351 | documentation and/or software. |
352 | |
353 | =back |
354 | |
355 | This copyright does not prohibit distribution of any version of Perl |
356 | containing this extension under the terms of the GNU or Artistic |
357 | licenses. |
358 | |
359 | =head1 AUTHORS |
360 | |
ac70dec1 |
361 | The original C<MD5> interface was written by Neil Winton |
3357b1b1 |
362 | (C<N.Winton@axion.bt.co.uk>). |
363 | |
ac70dec1 |
364 | The C<Digest::MD5> module is written by Gisle Aas <gisle@ActiveState.com>. |
3357b1b1 |
365 | |
366 | =cut |