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