Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | package Digest::MD5; |
2 | ||
3 | use strict; | |
4 | use vars qw($VERSION @ISA @EXPORT_OK); | |
5 | ||
6 | $VERSION = '2.20'; # $Date: 2002/05/06 05:15:09 $ | |
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 { | |
16 | Digest::MD5->bootstrap($VERSION); | |
17 | }; | |
18 | if ($@) { | |
19 | my $olderr = $@; | |
20 | eval { | |
21 | # Try to load the pure perl version | |
22 | require Digest::Perl::MD5; | |
23 | ||
24 | Digest::Perl::MD5->import(qw(md5 md5_hex md5_base64)); | |
25 | push(@ISA, "Digest::Perl::MD5"); # make OO interface work | |
26 | }; | |
27 | if ($@) { | |
28 | # restore the original error | |
29 | die $olderr; | |
30 | } | |
31 | } | |
32 | else { | |
33 | *reset = \&new; | |
34 | } | |
35 | ||
36 | 1; | |
37 | __END__ | |
38 | ||
39 | =head1 NAME | |
40 | ||
41 | Digest::MD5 - Perl interface to the MD5 Algorithm | |
42 | ||
43 | =head1 SYNOPSIS | |
44 | ||
45 | # Functional style | |
46 | use Digest::MD5 qw(md5 md5_hex md5_base64); | |
47 | ||
48 | $digest = md5($data); | |
49 | $digest = md5_hex($data); | |
50 | $digest = md5_base64($data); | |
51 | ||
52 | # OO style | |
53 | use Digest::MD5; | |
54 | ||
55 | $ctx = Digest::MD5->new; | |
56 | ||
57 | $ctx->add($data); | |
58 | $ctx->addfile(*FILE); | |
59 | ||
60 | $digest = $ctx->digest; | |
61 | $digest = $ctx->hexdigest; | |
62 | $digest = $ctx->b64digest; | |
63 | ||
64 | =head1 DESCRIPTION | |
65 | ||
66 | The C<Digest::MD5> module allows you to use the RSA Data Security | |
67 | Inc. MD5 Message Digest algorithm from within Perl programs. The | |
68 | algorithm takes as input a message of arbitrary length and produces as | |
69 | output a 128-bit "fingerprint" or "message digest" of the input. | |
70 | ||
71 | The C<Digest::MD5> module provide a procedural interface for simple | |
72 | use, as well as an object oriented interface that can handle messages | |
73 | of arbitrary length and which can read files directly. | |
74 | ||
75 | A binary digest will be 16 bytes long. A hex digest will be 32 | |
76 | characters long. A base64 digest will be 22 characters long. | |
77 | ||
78 | =head1 FUNCTIONS | |
79 | ||
80 | The following functions can be exported from the C<Digest::MD5> | |
81 | module. No functions are exported by default. | |
82 | ||
83 | =over 4 | |
84 | ||
85 | =item md5($data,...) | |
86 | ||
87 | This function will concatenate all arguments, calculate the MD5 digest | |
88 | of this "message", and return it in binary form. | |
89 | ||
90 | =item md5_hex($data,...) | |
91 | ||
92 | Same as md5(), but will return the digest in hexadecimal form. | |
93 | ||
94 | =item md5_base64($data,...) | |
95 | ||
96 | Same as md5(), but will return the digest as a base64 encoded string. | |
97 | ||
98 | The base64 encoded string returned is not padded to be a multiple of 4 | |
99 | bytes long. If you want interoperability with other base64 encoded | |
100 | md5 digests you might want to append the string "==" to the result. | |
101 | ||
102 | =back | |
103 | ||
104 | =head1 METHODS | |
105 | ||
106 | The following methods are available: | |
107 | ||
108 | =over 4 | |
109 | ||
110 | =item $md5 = Digest::MD5->new | |
111 | ||
112 | The constructor returns a new C<Digest::MD5> object which encapsulate | |
113 | the state of the MD5 message-digest algorithm. You can add data to | |
114 | the object and finally ask for the digest. | |
115 | ||
116 | If called as an instance method (i.e. $md5->new) it will just reset the | |
117 | state the object to the state of a newly created object. No new | |
118 | object is created in this case. | |
119 | ||
120 | =item $md5->reset | |
121 | ||
122 | This is just an alias for $md5->new. | |
123 | ||
124 | =item $md5->add($data,...) | |
125 | ||
126 | The $data provided as argument are appended to the message we | |
127 | calculate the digest for. The return value is the $md5 object itself. | |
128 | ||
129 | =item $md5->addfile($io_handle) | |
130 | ||
131 | The $io_handle is read until EOF and the content is appended to the | |
132 | message we calculate the digest for. The return value is the $md5 | |
133 | object itself. | |
134 | ||
135 | In most cases you want to make sure that the $io_handle is set up to | |
136 | be in binmode(). | |
137 | ||
138 | =item $md5->digest | |
139 | ||
140 | Return the binary digest for the message. | |
141 | ||
142 | Note that the C<digest> operation is effectively a destructive, | |
143 | read-once operation. Once it has been performed, the C<Digest::MD5> | |
144 | object is automatically C<reset> and can be used to calculate another | |
145 | digest value. | |
146 | ||
147 | =item $md5->hexdigest | |
148 | ||
149 | Same as $md5->digest, but will return the digest in hexadecimal form. | |
150 | ||
151 | =item $md5->b64digest | |
152 | ||
153 | Same as $md5->digest, but will return the digest as a base64 encoded | |
154 | string. | |
155 | ||
156 | The base64 encoded string returned is not padded to be a multiple of 4 | |
157 | bytes long. If you want interoperability with other base64 encoded | |
158 | md5 digests you might want to append the string "==" to the result. | |
159 | ||
160 | =back | |
161 | ||
162 | ||
163 | =head1 EXAMPLES | |
164 | ||
165 | The simplest way to use this library is to import the md5_hex() | |
166 | function (or one of its cousins): | |
167 | ||
168 | use Digest::MD5 qw(md5_hex); | |
169 | print "Digest is ", md5_hex("foobarbaz"), "\n"; | |
170 | ||
171 | The above example would print out the message | |
172 | ||
173 | Digest is 6df23dc03f9b54cc38a0fc1483df6e21 | |
174 | ||
175 | provided that the implementation is working correctly. The same | |
176 | checksum can also be calculated in OO style: | |
177 | ||
178 | use Digest::MD5; | |
179 | ||
180 | $md5 = Digest::MD5->new; | |
181 | $md5->add('foo', 'bar'); | |
182 | $md5->add('baz'); | |
183 | $digest = $md5->hexdigest; | |
184 | ||
185 | print "Digest is $digest\n"; | |
186 | ||
187 | With OO style you can break the message arbitrary. This means that we | |
188 | are no longer limited to have space for the whole message in memory, i.e. | |
189 | we can handle messages of any size. | |
190 | ||
191 | This is useful when calculating checksum for files: | |
192 | ||
193 | use Digest::MD5; | |
194 | ||
195 | my $file = shift || "/etc/passwd"; | |
196 | open(FILE, $file) or die "Can't open '$file': $!"; | |
197 | binmode(FILE); | |
198 | ||
199 | $md5 = Digest::MD5->new; | |
200 | while (<FILE>) { | |
201 | $md5->add($_); | |
202 | } | |
203 | close(FILE); | |
204 | print $md5->b64digest, " $file\n"; | |
205 | ||
206 | Or we can use the builtin addfile method for more efficient reading of | |
207 | the file: | |
208 | ||
209 | use Digest::MD5; | |
210 | ||
211 | my $file = shift || "/etc/passwd"; | |
212 | open(FILE, $file) or die "Can't open '$file': $!"; | |
213 | binmode(FILE); | |
214 | ||
215 | print Digest::MD5->new->addfile(*FILE)->hexdigest, " $file\n"; | |
216 | ||
217 | =head1 SEE ALSO | |
218 | ||
219 | L<Digest>, | |
220 | L<Digest::MD2>, | |
221 | L<Digest::SHA1>, | |
222 | L<Digest::HMAC> | |
223 | ||
224 | L<md5sum(1)> | |
225 | ||
226 | RFC 1321 | |
227 | ||
228 | =head1 COPYRIGHT | |
229 | ||
230 | This library is free software; you can redistribute it and/or | |
231 | modify it under the same terms as Perl itself. | |
232 | ||
233 | Copyright 1998-2002 Gisle Aas. | |
234 | Copyright 1995-1996 Neil Winton. | |
235 | Copyright 1991-1992 RSA Data Security, Inc. | |
236 | ||
237 | The MD5 algorithm is defined in RFC 1321. The basic C code | |
238 | implementing the algorithm is derived from that in the RFC and is | |
239 | covered by the following copyright: | |
240 | ||
241 | =over 4 | |
242 | ||
243 | =item | |
244 | ||
245 | Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All | |
246 | rights reserved. | |
247 | ||
248 | License to copy and use this software is granted provided that it | |
249 | is identified as the "RSA Data Security, Inc. MD5 Message-Digest | |
250 | Algorithm" in all material mentioning or referencing this software | |
251 | or this function. | |
252 | ||
253 | License is also granted to make and use derivative works provided | |
254 | that such works are identified as "derived from the RSA Data | |
255 | Security, Inc. MD5 Message-Digest Algorithm" in all material | |
256 | mentioning or referencing the derived work. | |
257 | ||
258 | RSA Data Security, Inc. makes no representations concerning either | |
259 | the merchantability of this software or the suitability of this | |
260 | software for any particular purpose. It is provided "as is" | |
261 | without express or implied warranty of any kind. | |
262 | ||
263 | These notices must be retained in any copies of any part of this | |
264 | documentation and/or software. | |
265 | ||
266 | =back | |
267 | ||
268 | This copyright does not prohibit distribution of any version of Perl | |
269 | containing this extension under the terms of the GNU or Artistic | |
270 | licenses. | |
271 | ||
272 | =head1 AUTHORS | |
273 | ||
274 | The original MD5 interface was written by Neil Winton | |
275 | (C<N.Winton@axion.bt.co.uk>). | |
276 | ||
277 | This release was made by Gisle Aas <gisle@ActiveState.com> | |
278 | ||
279 | =cut |