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