ext/Digest/MD5/MD5.pm

   1 package Digest::MD5;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA @EXPORT_OK);
   5
   6 $VERSION = '2.13';
   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