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