Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10) |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sp \" Vertical space (when we can't use .PP) |
6 | .if t .sp .5v |
7 | .if n .sp |
8 | .. |
9 | .de Vb \" Begin verbatim text |
10 | .ft CW |
11 | .nf |
12 | .ne \\$1 |
13 | .. |
14 | .de Ve \" End verbatim text |
15 | .ft R |
16 | .fi |
17 | .. |
18 | .\" Set up some character translations and predefined strings. \*(-- will |
19 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
20 | .\" double quote, and \*(R" will give a right double quote. \*(C+ will |
21 | .\" give a nicer C++. Capital omega is used to do unbreakable dashes and |
22 | .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, |
23 | .\" nothing in troff, for use with C<>. |
24 | .tr \(*W- |
25 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
26 | .ie n \{\ |
27 | . ds -- \(*W- |
28 | . ds PI pi |
29 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
30 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
31 | . ds L" "" |
32 | . ds R" "" |
33 | . ds C` "" |
34 | . ds C' "" |
35 | 'br\} |
36 | .el\{\ |
37 | . ds -- \|\(em\| |
38 | . ds PI \(*p |
39 | . ds L" `` |
40 | . ds R" '' |
41 | 'br\} |
42 | .\" |
43 | .\" Escape single quotes in literal strings from groff's Unicode transform. |
44 | .ie \n(.g .ds Aq \(aq |
45 | .el .ds Aq ' |
46 | .\" |
47 | .\" If the F register is turned on, we'll generate index entries on stderr for |
48 | .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
49 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
50 | .\" output yourself in some meaningful fashion. |
51 | .ie \nF \{\ |
52 | . de IX |
53 | . tm Index:\\$1\t\\n%\t"\\$2" |
54 | .. |
55 | . nr % 0 |
56 | . rr F |
57 | .\} |
58 | .el \{\ |
59 | . de IX |
60 | .. |
61 | .\} |
62 | .\" |
63 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
64 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
65 | . \" fudge factors for nroff and troff |
66 | .if n \{\ |
67 | . ds #H 0 |
68 | . ds #V .8m |
69 | . ds #F .3m |
70 | . ds #[ \f1 |
71 | . ds #] \fP |
72 | .\} |
73 | .if t \{\ |
74 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
75 | . ds #V .6m |
76 | . ds #F 0 |
77 | . ds #[ \& |
78 | . ds #] \& |
79 | .\} |
80 | . \" simple accents for nroff and troff |
81 | .if n \{\ |
82 | . ds ' \& |
83 | . ds ` \& |
84 | . ds ^ \& |
85 | . ds , \& |
86 | . ds ~ ~ |
87 | . ds / |
88 | .\} |
89 | .if t \{\ |
90 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
91 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
92 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
93 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
94 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
95 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
96 | .\} |
97 | . \" troff and (daisy-wheel) nroff accents |
98 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
99 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
100 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
101 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
102 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
103 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
104 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
105 | .ds ae a\h'-(\w'a'u*4/10)'e |
106 | .ds Ae A\h'-(\w'A'u*4/10)'E |
107 | . \" corrections for vroff |
108 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
109 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
110 | . \" for low resolution devices (crt and lpr) |
111 | .if \n(.H>23 .if \n(.V>19 \ |
112 | \{\ |
113 | . ds : e |
114 | . ds 8 ss |
115 | . ds o a |
116 | . ds d- d\h'-1'\(ga |
117 | . ds D- D\h'-1'\(hy |
118 | . ds th \o'bp' |
119 | . ds Th \o'LP' |
120 | . ds ae ae |
121 | . ds Ae AE |
122 | .\} |
123 | .rm #[ #] #H #V #F C |
124 | .\" ======================================================================== |
125 | .\" |
126 | .IX Title "MD5 3" |
127 | .TH MD5 3 "2009-06-09" "perl v5.8.7" "User Contributed Perl Documentation" |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
129 | .\" way too many mistakes in technical documents. |
130 | .if n .ad l |
131 | .nh |
132 | .SH "NAME" |
133 | Digest::MD5 \- Perl interface to the MD5 Algorithm |
134 | .SH "SYNOPSIS" |
135 | .IX Header "SYNOPSIS" |
136 | .Vb 2 |
137 | \& # Functional style |
138 | \& use Digest::MD5 qw(md5 md5_hex md5_base64); |
139 | \& |
140 | \& $digest = md5($data); |
141 | \& $digest = md5_hex($data); |
142 | \& $digest = md5_base64($data); |
143 | \& |
144 | \& # OO style |
145 | \& use Digest::MD5; |
146 | \& |
147 | \& $ctx = Digest::MD5\->new; |
148 | \& |
149 | \& $ctx\->add($data); |
150 | \& $ctx\->addfile(*FILE); |
151 | \& |
152 | \& $digest = $ctx\->digest; |
153 | \& $digest = $ctx\->hexdigest; |
154 | \& $digest = $ctx\->b64digest; |
155 | .Ve |
156 | .SH "DESCRIPTION" |
157 | .IX Header "DESCRIPTION" |
158 | The \f(CW\*(C`Digest::MD5\*(C'\fR module allows you to use the \s-1RSA\s0 Data Security |
159 | Inc. \s-1MD5\s0 Message Digest algorithm from within Perl programs. The |
160 | algorithm takes as input a message of arbitrary length and produces as |
161 | output a 128\-bit \*(L"fingerprint\*(R" or \*(L"message digest\*(R" of the input. |
162 | .PP |
163 | Note that the \s-1MD5\s0 algorithm is not as strong as it used to be. It has |
164 | since 2005 been easy to generate different messages that produce the |
165 | same \s-1MD5\s0 digest. It still seems hard to generate messages that |
166 | produce a given digest, but it is probably wise to move to stronger |
167 | algorithms for applications that depend on the digest to uniquely identify |
168 | a message. |
169 | .PP |
170 | The \f(CW\*(C`Digest::MD5\*(C'\fR module provide a procedural interface for simple |
171 | use, as well as an object oriented interface that can handle messages |
172 | of arbitrary length and which can read files directly. |
173 | .SH "FUNCTIONS" |
174 | .IX Header "FUNCTIONS" |
175 | The following functions are provided by the \f(CW\*(C`Digest::MD5\*(C'\fR module. |
176 | None of these functions are exported by default. |
177 | .IP "md5($data,...)" 4 |
178 | .IX Item "md5($data,...)" |
179 | This function will concatenate all arguments, calculate the \s-1MD5\s0 digest |
180 | of this \*(L"message\*(R", and return it in binary form. The returned string |
181 | will be 16 bytes long. |
182 | .Sp |
183 | The result of md5(\*(L"a\*(R", \*(L"b\*(R", \*(L"c\*(R") will be exactly the same as the |
184 | result of md5(\*(L"abc\*(R"). |
185 | .IP "md5_hex($data,...)" 4 |
186 | .IX Item "md5_hex($data,...)" |
187 | Same as \fImd5()\fR, but will return the digest in hexadecimal form. The |
188 | length of the returned string will be 32 and it will only contain |
189 | characters from this set: '0'..'9' and 'a'..'f'. |
190 | .IP "md5_base64($data,...)" 4 |
191 | .IX Item "md5_base64($data,...)" |
192 | Same as \fImd5()\fR, but will return the digest as a base64 encoded string. |
193 | The length of the returned string will be 22 and it will only contain |
194 | characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and |
195 | \&'/'. |
196 | .Sp |
197 | Note that the base64 encoded string returned is not padded to be a |
198 | multiple of 4 bytes long. If you want interoperability with other |
199 | base64 encoded md5 digests you might want to append the redundant |
200 | string \*(L"==\*(R" to the result. |
201 | .SH "METHODS" |
202 | .IX Header "METHODS" |
203 | The object oriented interface to \f(CW\*(C`Digest::MD5\*(C'\fR is described in this |
204 | section. After a \f(CW\*(C`Digest::MD5\*(C'\fR object has been created, you will add |
205 | data to it and finally ask for the digest in a suitable format. A |
206 | single object can be used to calculate multiple digests. |
207 | .PP |
208 | The following methods are provided: |
209 | .ie n .IP "$md5 = Digest::MD5\->new" 4 |
210 | .el .IP "\f(CW$md5\fR = Digest::MD5\->new" 4 |
211 | .IX Item "$md5 = Digest::MD5->new" |
212 | The constructor returns a new \f(CW\*(C`Digest::MD5\*(C'\fR object which encapsulate |
213 | the state of the \s-1MD5\s0 message-digest algorithm. |
214 | .Sp |
215 | If called as an instance method (i.e. \f(CW$md5\fR\->new) it will just reset the |
216 | state the object to the state of a newly created object. No new |
217 | object is created in this case. |
218 | .ie n .IP "$md5\->reset" 4 |
219 | .el .IP "\f(CW$md5\fR\->reset" 4 |
220 | .IX Item "$md5->reset" |
221 | This is just an alias for \f(CW$md5\fR\->new. |
222 | .ie n .IP "$md5\->clone" 4 |
223 | .el .IP "\f(CW$md5\fR\->clone" 4 |
224 | .IX Item "$md5->clone" |
225 | This a copy of the \f(CW$md5\fR object. It is useful when you do not want to |
226 | destroy the digests state, but need an intermediate value of the |
227 | digest, e.g. when calculating digests iteratively on a continuous data |
228 | stream. Example: |
229 | .Sp |
230 | .Vb 5 |
231 | \& my $md5 = Digest::MD5\->new; |
232 | \& while (<>) { |
233 | \& $md5\->add($_); |
234 | \& print "Line $.: ", $md5\->clone\->hexdigest, "\en"; |
235 | \& } |
236 | .Ve |
237 | .ie n .IP "$md5\->add($data,...)" 4 |
238 | .el .IP "\f(CW$md5\fR\->add($data,...)" 4 |
239 | .IX Item "$md5->add($data,...)" |
240 | The \f(CW$data\fR provided as argument are appended to the message we |
241 | calculate the digest for. The return value is the \f(CW$md5\fR object itself. |
242 | .Sp |
243 | All these lines will have the same effect on the state of the \f(CW$md5\fR |
244 | object: |
245 | .Sp |
246 | .Vb 4 |
247 | \& $md5\->add("a"); $md5\->add("b"); $md5\->add("c"); |
248 | \& $md5\->add("a")\->add("b")\->add("c"); |
249 | \& $md5\->add("a", "b", "c"); |
250 | \& $md5\->add("abc"); |
251 | .Ve |
252 | .ie n .IP "$md5\->addfile($io_handle)" 4 |
253 | .el .IP "\f(CW$md5\fR\->addfile($io_handle)" 4 |
254 | .IX Item "$md5->addfile($io_handle)" |
255 | The \f(CW$io_handle\fR will be read until \s-1EOF\s0 and its content appended to the |
256 | message we calculate the digest for. The return value is the \f(CW$md5\fR |
257 | object itself. |
258 | .Sp |
259 | The \fIaddfile()\fR method will \fIcroak()\fR if it fails reading data for some |
260 | reason. If it croaks it is unpredictable what the state of the \f(CW$md5\fR |
261 | object will be in. The \fIaddfile()\fR method might have been able to read |
262 | the file partially before it failed. It is probably wise to discard |
263 | or reset the \f(CW$md5\fR object if this occurs. |
264 | .Sp |
265 | In most cases you want to make sure that the \f(CW$io_handle\fR is in |
266 | \&\f(CW\*(C`binmode\*(C'\fR before you pass it as argument to the \fIaddfile()\fR method. |
267 | .ie n .IP "$md5\->add_bits($data, $nbits)" 4 |
268 | .el .IP "\f(CW$md5\fR\->add_bits($data, \f(CW$nbits\fR)" 4 |
269 | .IX Item "$md5->add_bits($data, $nbits)" |
270 | .PD 0 |
271 | .ie n .IP "$md5\->add_bits($bitstring)" 4 |
272 | .el .IP "\f(CW$md5\fR\->add_bits($bitstring)" 4 |
273 | .IX Item "$md5->add_bits($bitstring)" |
274 | .PD |
275 | Since the \s-1MD5\s0 algorithm is byte oriented you might only add bits as |
276 | multiples of 8, so you probably want to just use \fIadd()\fR instead. The |
277 | \&\fIadd_bits()\fR method is provided for compatibility with other digest |
278 | implementations. See Digest for description of the arguments |
279 | that \fIadd_bits()\fR take. |
280 | .ie n .IP "$md5\->digest" 4 |
281 | .el .IP "\f(CW$md5\fR\->digest" 4 |
282 | .IX Item "$md5->digest" |
283 | Return the binary digest for the message. The returned string will be |
284 | 16 bytes long. |
285 | .Sp |
286 | Note that the \f(CW\*(C`digest\*(C'\fR operation is effectively a destructive, |
287 | read-once operation. Once it has been performed, the \f(CW\*(C`Digest::MD5\*(C'\fR |
288 | object is automatically \f(CW\*(C`reset\*(C'\fR and can be used to calculate another |
289 | digest value. Call \f(CW$md5\fR\->clone\->digest if you want to calculate the |
290 | digest without resetting the digest state. |
291 | .ie n .IP "$md5\->hexdigest" 4 |
292 | .el .IP "\f(CW$md5\fR\->hexdigest" 4 |
293 | .IX Item "$md5->hexdigest" |
294 | Same as \f(CW$md5\fR\->digest, but will return the digest in hexadecimal |
295 | form. The length of the returned string will be 32 and it will only |
296 | contain characters from this set: '0'..'9' and 'a'..'f'. |
297 | .ie n .IP "$md5\->b64digest" 4 |
298 | .el .IP "\f(CW$md5\fR\->b64digest" 4 |
299 | .IX Item "$md5->b64digest" |
300 | Same as \f(CW$md5\fR\->digest, but will return the digest as a base64 encoded |
301 | string. The length of the returned string will be 22 and it will only |
302 | contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' |
303 | and '/'. |
304 | .Sp |
305 | The base64 encoded string returned is not padded to be a multiple of 4 |
306 | bytes long. If you want interoperability with other base64 encoded |
307 | md5 digests you might want to append the string \*(L"==\*(R" to the result. |
308 | .SH "EXAMPLES" |
309 | .IX Header "EXAMPLES" |
310 | The simplest way to use this library is to import the \fImd5_hex()\fR |
311 | function (or one of its cousins): |
312 | .PP |
313 | .Vb 2 |
314 | \& use Digest::MD5 qw(md5_hex); |
315 | \& print "Digest is ", md5_hex("foobarbaz"), "\en"; |
316 | .Ve |
317 | .PP |
318 | The above example would print out the message: |
319 | .PP |
320 | .Vb 1 |
321 | \& Digest is 6df23dc03f9b54cc38a0fc1483df6e21 |
322 | .Ve |
323 | .PP |
324 | The same checksum can also be calculated in \s-1OO\s0 style: |
325 | .PP |
326 | .Vb 1 |
327 | \& use Digest::MD5; |
328 | \& |
329 | \& $md5 = Digest::MD5\->new; |
330 | \& $md5\->add(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq); |
331 | \& $md5\->add(\*(Aqbaz\*(Aq); |
332 | \& $digest = $md5\->hexdigest; |
333 | \& |
334 | \& print "Digest is $digest\en"; |
335 | .Ve |
336 | .PP |
337 | With \s-1OO\s0 style you can break the message arbitrary. This means that we |
338 | are no longer limited to have space for the whole message in memory, i.e. |
339 | we can handle messages of any size. |
340 | .PP |
341 | This is useful when calculating checksum for files: |
342 | .PP |
343 | .Vb 1 |
344 | \& use Digest::MD5; |
345 | \& |
346 | \& my $file = shift || "/etc/passwd"; |
347 | \& open(FILE, $file) or die "Can\*(Aqt open \*(Aq$file\*(Aq: $!"; |
348 | \& binmode(FILE); |
349 | \& |
350 | \& $md5 = Digest::MD5\->new; |
351 | \& while (<FILE>) { |
352 | \& $md5\->add($_); |
353 | \& } |
354 | \& close(FILE); |
355 | \& print $md5\->b64digest, " $file\en"; |
356 | .Ve |
357 | .PP |
358 | Or we can use the addfile method for more efficient reading of |
359 | the file: |
360 | .PP |
361 | .Vb 1 |
362 | \& use Digest::MD5; |
363 | \& |
364 | \& my $file = shift || "/etc/passwd"; |
365 | \& open(FILE, $file) or die "Can\*(Aqt open \*(Aq$file\*(Aq: $!"; |
366 | \& binmode(FILE); |
367 | \& |
368 | \& print Digest::MD5\->new\->addfile(*FILE)\->hexdigest, " $file\en"; |
369 | .Ve |
370 | .PP |
371 | Perl 5.8 support Unicode characters in strings. Since the \s-1MD5\s0 |
372 | algorithm is only defined for strings of bytes, it can not be used on |
373 | strings that contains chars with ordinal number above 255. The \s-1MD5\s0 |
374 | functions and methods will croak if you try to feed them such input |
375 | data: |
376 | .PP |
377 | .Vb 1 |
378 | \& use Digest::MD5 qw(md5_hex); |
379 | \& |
380 | \& my $str = "abc\ex{300}"; |
381 | \& print md5_hex($str), "\en"; # croaks |
382 | \& # Wide character in subroutine entry |
383 | .Ve |
384 | .PP |
385 | What you can do is calculate the \s-1MD5\s0 checksum of the \s-1UTF\-8\s0 |
386 | representation of such strings. This is achieved by filtering the |
387 | string through \fIencode_utf8()\fR function: |
388 | .PP |
389 | .Vb 2 |
390 | \& use Digest::MD5 qw(md5_hex); |
391 | \& use Encode qw(encode_utf8); |
392 | \& |
393 | \& my $str = "abc\ex{300}"; |
394 | \& print md5_hex(encode_utf8($str)), "\en"; |
395 | \& # 8c2d46911f3f5a326455f0ed7a8ed3b3 |
396 | .Ve |
397 | .SH "SEE ALSO" |
398 | .IX Header "SEE ALSO" |
399 | Digest, |
400 | Digest::MD2, |
401 | Digest::SHA, |
402 | Digest::HMAC |
403 | .PP |
404 | \&\fImd5sum\fR\|(1) |
405 | .PP |
406 | \&\s-1RFC\s0 1321 |
407 | .PP |
408 | http://en.wikipedia.org/wiki/MD5 |
409 | .PP |
410 | The paper \*(L"How to Break \s-1MD5\s0 and Other Hash Functions\*(R" by Xiaoyun Wang |
411 | and Hongbo Yu. |
412 | .SH "COPYRIGHT" |
413 | .IX Header "COPYRIGHT" |
414 | This library is free software; you can redistribute it and/or |
415 | modify it under the same terms as Perl itself. |
416 | .PP |
417 | .Vb 3 |
418 | \& Copyright 1998\-2003 Gisle Aas. |
419 | \& Copyright 1995\-1996 Neil Winton. |
420 | \& Copyright 1991\-1992 RSA Data Security, Inc. |
421 | .Ve |
422 | .PP |
423 | The \s-1MD5\s0 algorithm is defined in \s-1RFC\s0 1321. This implementation is |
424 | derived from the reference C code in \s-1RFC\s0 1321 which is covered by |
425 | the following copyright statement: |
426 | .IP "\(bu" 4 |
427 | Copyright (C) 1991\-2, \s-1RSA\s0 Data Security, Inc. Created 1991. All |
428 | rights reserved. |
429 | .Sp |
430 | License to copy and use this software is granted provided that it |
431 | is identified as the \*(L"\s-1RSA\s0 Data Security, Inc. \s-1MD5\s0 Message-Digest |
432 | Algorithm\*(R" in all material mentioning or referencing this software |
433 | or this function. |
434 | .Sp |
435 | License is also granted to make and use derivative works provided |
436 | that such works are identified as \*(L"derived from the \s-1RSA\s0 Data |
437 | Security, Inc. \s-1MD5\s0 Message-Digest Algorithm\*(R" in all material |
438 | mentioning or referencing the derived work. |
439 | .Sp |
440 | \&\s-1RSA\s0 Data Security, Inc. makes no representations concerning either |
441 | the merchantability of this software or the suitability of this |
442 | software for any particular purpose. It is provided \*(L"as is\*(R" |
443 | without express or implied warranty of any kind. |
444 | .Sp |
445 | These notices must be retained in any copies of any part of this |
446 | documentation and/or software. |
447 | .PP |
448 | This copyright does not prohibit distribution of any version of Perl |
449 | containing this extension under the terms of the \s-1GNU\s0 or Artistic |
450 | licenses. |
451 | .SH "AUTHORS" |
452 | .IX Header "AUTHORS" |
453 | The original \f(CW\*(C`MD5\*(C'\fR interface was written by Neil Winton |
454 | (\f(CW\*(C`N.Winton@axion.bt.co.uk\*(C'\fR). |
455 | .PP |
456 | The \f(CW\*(C`Digest::MD5\*(C'\fR module is written by Gisle Aas <gisle@ActiveState.com>. |