Blame Digest.pm

Packit eb1bc2
package Digest;
Packit eb1bc2
Packit eb1bc2
use strict;
Packit eb1bc2
use vars qw($VERSION %MMAP $AUTOLOAD);
Packit eb1bc2
Packit eb1bc2
$VERSION = "1.17";
Packit eb1bc2
Packit eb1bc2
%MMAP = (
Packit eb1bc2
  "SHA-1"      => [["Digest::SHA", 1], "Digest::SHA1", ["Digest::SHA2", 1]],
Packit eb1bc2
  "SHA-224"    => [["Digest::SHA", 224]],
Packit eb1bc2
  "SHA-256"    => [["Digest::SHA", 256], ["Digest::SHA2", 256]],
Packit eb1bc2
  "SHA-384"    => [["Digest::SHA", 384], ["Digest::SHA2", 384]],
Packit eb1bc2
  "SHA-512"    => [["Digest::SHA", 512], ["Digest::SHA2", 512]],
Packit eb1bc2
  "HMAC-MD5"   => "Digest::HMAC_MD5",
Packit eb1bc2
  "HMAC-SHA-1" => "Digest::HMAC_SHA1",
Packit eb1bc2
  "CRC-16"     => [["Digest::CRC", type => "crc16"]],
Packit eb1bc2
  "CRC-32"     => [["Digest::CRC", type => "crc32"]],
Packit eb1bc2
  "CRC-CCITT"  => [["Digest::CRC", type => "crcccitt"]],
Packit eb1bc2
  "RIPEMD-160" => "Crypt::RIPEMD160",
Packit eb1bc2
);
Packit eb1bc2
Packit eb1bc2
sub new
Packit eb1bc2
{
Packit eb1bc2
    shift;  # class ignored
Packit eb1bc2
    my $algorithm = shift;
Packit eb1bc2
    my $impl = $MMAP{$algorithm} || do {
Packit eb1bc2
        $algorithm =~ s/\W+//g;
Packit eb1bc2
        "Digest::$algorithm";
Packit eb1bc2
    };
Packit eb1bc2
    $impl = [$impl] unless ref($impl);
Packit eb1bc2
    local $@;  # don't clobber it for our caller
Packit eb1bc2
    my $err;
Packit eb1bc2
    for  (@$impl) {
Packit eb1bc2
        my $class = $_;
Packit eb1bc2
        my @args;
Packit eb1bc2
        ($class, @args) = @$class if ref($class);
Packit eb1bc2
        no strict 'refs';
Packit eb1bc2
        unless (exists ${"$class\::"}{"VERSION"}) {
Packit eb1bc2
            my $pm_file = $class . ".pm";
Packit eb1bc2
            $pm_file =~ s{::}{/}g;
Packit Service cc4a2b
            eval {
Packit Service cc4a2b
                local @INC = @INC;
Packit Service cc4a2b
                pop @INC if $INC[-1] eq '.';
Packit Service cc4a2b
                require $pm_file;
Packit Service cc4a2b
            };
Packit eb1bc2
            if ($@) {
Packit eb1bc2
                $err ||= $@;
Packit eb1bc2
                next;
Packit eb1bc2
            }
Packit eb1bc2
        }
Packit eb1bc2
        return $class->new(@args, @_);
Packit eb1bc2
    }
Packit eb1bc2
    die $err;
Packit eb1bc2
}
Packit eb1bc2
Packit eb1bc2
sub AUTOLOAD
Packit eb1bc2
{
Packit eb1bc2
    my $class = shift;
Packit eb1bc2
    my $algorithm = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2);
Packit eb1bc2
    $class->new($algorithm, @_);
Packit eb1bc2
}
Packit eb1bc2
Packit eb1bc2
1;
Packit eb1bc2
Packit eb1bc2
__END__
Packit eb1bc2
Packit eb1bc2
=head1 NAME
Packit eb1bc2
Packit eb1bc2
Digest - Modules that calculate message digests
Packit eb1bc2
Packit eb1bc2
=head1 SYNOPSIS
Packit eb1bc2
Packit eb1bc2
  $md5  = Digest->new("MD5");
Packit eb1bc2
  $sha1 = Digest->new("SHA-1");
Packit eb1bc2
  $sha256 = Digest->new("SHA-256");
Packit eb1bc2
  $sha384 = Digest->new("SHA-384");
Packit eb1bc2
  $sha512 = Digest->new("SHA-512");
Packit eb1bc2
Packit eb1bc2
  $hmac = Digest->HMAC_MD5($key);
Packit eb1bc2
Packit eb1bc2
=head1 DESCRIPTION
Packit eb1bc2
Packit eb1bc2
The C<Digest::> modules calculate digests, also called "fingerprints"
Packit eb1bc2
or "hashes", of some data, called a message.  The digest is (usually)
Packit eb1bc2
some small/fixed size string.  The actual size of the digest depend of
Packit eb1bc2
the algorithm used.  The message is simply a sequence of arbitrary
Packit eb1bc2
bytes or bits.
Packit eb1bc2
Packit eb1bc2
An important property of the digest algorithms is that the digest is
Packit eb1bc2
I<likely> to change if the message change in some way.  Another
Packit eb1bc2
property is that digest functions are one-way functions, that is it
Packit eb1bc2
should be I<hard> to find a message that correspond to some given
Packit eb1bc2
digest.  Algorithms differ in how "likely" and how "hard", as well as
Packit eb1bc2
how efficient they are to compute.
Packit eb1bc2
Packit eb1bc2
Note that the properties of the algorithms change over time, as the
Packit eb1bc2
algorithms are analyzed and machines grow faster.  If your application
Packit eb1bc2
for instance depends on it being "impossible" to generate the same
Packit eb1bc2
digest for a different message it is wise to make it easy to plug in
Packit eb1bc2
stronger algorithms as the one used grow weaker.  Using the interface
Packit eb1bc2
documented here should make it easy to change algorithms later.
Packit eb1bc2
Packit eb1bc2
All C<Digest::> modules provide the same programming interface.  A
Packit eb1bc2
functional interface for simple use, as well as an object oriented
Packit eb1bc2
interface that can handle messages of arbitrary length and which can
Packit eb1bc2
read files directly.
Packit eb1bc2
Packit eb1bc2
The digest can be delivered in three formats:
Packit eb1bc2
Packit eb1bc2
=over 8
Packit eb1bc2
Packit eb1bc2
=item I<binary>
Packit eb1bc2
Packit eb1bc2
This is the most compact form, but it is not well suited for printing
Packit eb1bc2
or embedding in places that can't handle arbitrary data.
Packit eb1bc2
Packit eb1bc2
=item I<hex>
Packit eb1bc2
Packit eb1bc2
A twice as long string of lowercase hexadecimal digits.
Packit eb1bc2
Packit eb1bc2
=item I<base64>
Packit eb1bc2
Packit eb1bc2
A string of portable printable characters.  This is the base64 encoded
Packit eb1bc2
representation of the digest with any trailing padding removed.  The
Packit eb1bc2
string will be about 30% longer than the binary version.
Packit eb1bc2
L<MIME::Base64> tells you more about this encoding.
Packit eb1bc2
Packit eb1bc2
=back
Packit eb1bc2
Packit eb1bc2
Packit eb1bc2
The functional interface is simply importable functions with the same
Packit eb1bc2
name as the algorithm.  The functions take the message as argument and
Packit eb1bc2
return the digest.  Example:
Packit eb1bc2
Packit eb1bc2
  use Digest::MD5 qw(md5);
Packit eb1bc2
  $digest = md5($message);
Packit eb1bc2
Packit eb1bc2
There are also versions of the functions with "_hex" or "_base64"
Packit eb1bc2
appended to the name, which returns the digest in the indicated form.
Packit eb1bc2
Packit eb1bc2
=head1 OO INTERFACE
Packit eb1bc2
Packit eb1bc2
The following methods are available for all C<Digest::> modules:
Packit eb1bc2
Packit eb1bc2
=over 4
Packit eb1bc2
Packit eb1bc2
=item $ctx = Digest->XXX($arg,...)
Packit eb1bc2
Packit eb1bc2
=item $ctx = Digest->new(XXX => $arg,...)
Packit eb1bc2
Packit eb1bc2
=item $ctx = Digest::XXX->new($arg,...)
Packit eb1bc2
Packit eb1bc2
The constructor returns some object that encapsulate the state of the
Packit eb1bc2
message-digest algorithm.  You can add data to the object and finally
Packit eb1bc2
ask for the digest.  The "XXX" should of course be replaced by the proper
Packit eb1bc2
name of the digest algorithm you want to use.
Packit eb1bc2
Packit eb1bc2
The two first forms are simply syntactic sugar which automatically
Packit eb1bc2
load the right module on first use.  The second form allow you to use
Packit eb1bc2
algorithm names which contains letters which are not legal perl
Packit eb1bc2
identifiers, e.g. "SHA-1".  If no implementation for the given algorithm
Packit eb1bc2
can be found, then an exception is raised.
Packit eb1bc2
Packit eb1bc2
If new() is called as an instance method (i.e. $ctx->new) it will just
Packit eb1bc2
reset the state the object to the state of a newly created object.  No
Packit eb1bc2
new object is created in this case, and the return value is the
Packit eb1bc2
reference to the object (i.e. $ctx).
Packit eb1bc2
Packit eb1bc2
=item $other_ctx = $ctx->clone
Packit eb1bc2
Packit eb1bc2
The clone method creates a copy of the digest state object and returns
Packit eb1bc2
a reference to the copy.
Packit eb1bc2
Packit eb1bc2
=item $ctx->reset
Packit eb1bc2
Packit eb1bc2
This is just an alias for $ctx->new.
Packit eb1bc2
Packit eb1bc2
=item $ctx->add( $data )
Packit eb1bc2
Packit eb1bc2
=item $ctx->add( $chunk1, $chunk2, ... )
Packit eb1bc2
Packit eb1bc2
The string value of the $data provided as argument is appended to the
Packit eb1bc2
message we calculate the digest for.  The return value is the $ctx
Packit eb1bc2
object itself.
Packit eb1bc2
Packit eb1bc2
If more arguments are provided then they are all appended to the
Packit eb1bc2
message, thus all these lines will have the same effect on the state
Packit eb1bc2
of the $ctx object:
Packit eb1bc2
Packit eb1bc2
  $ctx->add("a"); $ctx->add("b"); $ctx->add("c");
Packit eb1bc2
  $ctx->add("a")->add("b")->add("c");
Packit eb1bc2
  $ctx->add("a", "b", "c");
Packit eb1bc2
  $ctx->add("abc");
Packit eb1bc2
Packit eb1bc2
Most algorithms are only defined for strings of bytes and this method
Packit eb1bc2
might therefore croak if the provided arguments contain chars with
Packit eb1bc2
ordinal number above 255.
Packit eb1bc2
Packit eb1bc2
=item $ctx->addfile( $io_handle )
Packit eb1bc2
Packit eb1bc2
The $io_handle is read until EOF and the content is appended to the
Packit eb1bc2
message we calculate the digest for.  The return value is the $ctx
Packit eb1bc2
object itself.
Packit eb1bc2
Packit eb1bc2
The addfile() method will croak() if it fails reading data for some
Packit eb1bc2
reason.  If it croaks it is unpredictable what the state of the $ctx
Packit eb1bc2
object will be in. The addfile() method might have been able to read
Packit eb1bc2
the file partially before it failed.  It is probably wise to discard
Packit eb1bc2
or reset the $ctx object if this occurs.
Packit eb1bc2
Packit eb1bc2
In most cases you want to make sure that the $io_handle is in
Packit eb1bc2
"binmode" before you pass it as argument to the addfile() method.
Packit eb1bc2
Packit eb1bc2
=item $ctx->add_bits( $data, $nbits )
Packit eb1bc2
Packit eb1bc2
=item $ctx->add_bits( $bitstring )
Packit eb1bc2
Packit eb1bc2
The add_bits() method is an alternative to add() that allow partial
Packit eb1bc2
bytes to be appended to the message.  Most users should just ignore
Packit eb1bc2
this method as partial bytes is very unlikely to be of any practical
Packit eb1bc2
use.
Packit eb1bc2
Packit eb1bc2
The two argument form of add_bits() will add the first $nbits bits
Packit eb1bc2
from $data.  For the last potentially partial byte only the high order
Packit eb1bc2
C<< $nbits % 8 >> bits are used.  If $nbits is greater than C<<
Packit eb1bc2
length($data) * 8 >>, then this method would do the same as C<<
Packit eb1bc2
$ctx->add($data) >>.
Packit eb1bc2
Packit eb1bc2
The one argument form of add_bits() takes a $bitstring of "1" and "0"
Packit eb1bc2
chars as argument.  It's a shorthand for C<< $ctx->add_bits(pack("B*",
Packit eb1bc2
$bitstring), length($bitstring)) >>.
Packit eb1bc2
Packit eb1bc2
The return value is the $ctx object itself.
Packit eb1bc2
Packit eb1bc2
This example shows two calls that should have the same effect:
Packit eb1bc2
Packit eb1bc2
   $ctx->add_bits("111100001010");
Packit eb1bc2
   $ctx->add_bits("\xF0\xA0", 12);
Packit eb1bc2
Packit eb1bc2
Most digest algorithms are byte based and for these it is not possible
Packit eb1bc2
to add bits that are not a multiple of 8, and the add_bits() method
Packit eb1bc2
will croak if you try.
Packit eb1bc2
Packit eb1bc2
=item $ctx->digest
Packit eb1bc2
Packit eb1bc2
Return the binary digest for the message.
Packit eb1bc2
Packit eb1bc2
Note that the C<digest> operation is effectively a destructive,
Packit eb1bc2
read-once operation. Once it has been performed, the $ctx object is
Packit eb1bc2
automatically C<reset> and can be used to calculate another digest
Packit eb1bc2
value.  Call $ctx->clone->digest if you want to calculate the digest
Packit eb1bc2
without resetting the digest state.
Packit eb1bc2
Packit eb1bc2
=item $ctx->hexdigest
Packit eb1bc2
Packit eb1bc2
Same as $ctx->digest, but will return the digest in hexadecimal form.
Packit eb1bc2
Packit eb1bc2
=item $ctx->b64digest
Packit eb1bc2
Packit eb1bc2
Same as $ctx->digest, but will return the digest as a base64 encoded
Packit eb1bc2
string.
Packit eb1bc2
Packit eb1bc2
=back
Packit eb1bc2
Packit eb1bc2
=head1 Digest speed
Packit eb1bc2
Packit eb1bc2
This table should give some indication on the relative speed of
Packit eb1bc2
different algorithms.  It is sorted by throughput based on a benchmark
Packit eb1bc2
done with of some implementations of this API:
Packit eb1bc2
Packit eb1bc2
 Algorithm      Size    Implementation                  MB/s
Packit eb1bc2
Packit eb1bc2
 MD4            128     Digest::MD4 v1.3               165.0
Packit eb1bc2
 MD5            128     Digest::MD5 v2.33               98.8
Packit eb1bc2
 SHA-256        256     Digest::SHA2 v1.1.0             66.7
Packit eb1bc2
 SHA-1          160     Digest::SHA v4.3.1              58.9
Packit eb1bc2
 SHA-1          160     Digest::SHA1 v2.10              48.8
Packit eb1bc2
 SHA-256        256     Digest::SHA v4.3.1              41.3
Packit eb1bc2
 Haval-256      256     Digest::Haval256 v1.0.4         39.8
Packit eb1bc2
 SHA-384        384     Digest::SHA2 v1.1.0             19.6
Packit eb1bc2
 SHA-512        512     Digest::SHA2 v1.1.0             19.3
Packit eb1bc2
 SHA-384        384     Digest::SHA v4.3.1              19.2
Packit eb1bc2
 SHA-512        512     Digest::SHA v4.3.1              19.2
Packit eb1bc2
 Whirlpool      512     Digest::Whirlpool v1.0.2        13.0
Packit eb1bc2
 MD2            128     Digest::MD2 v2.03                9.5
Packit eb1bc2
Packit eb1bc2
 Adler-32        32     Digest::Adler32 v0.03            1.3
Packit eb1bc2
 CRC-16          16     Digest::CRC v0.05                1.1
Packit eb1bc2
 CRC-32          32     Digest::CRC v0.05                1.1
Packit eb1bc2
 MD5            128     Digest::Perl::MD5 v1.5           1.0
Packit eb1bc2
 CRC-CCITT       16     Digest::CRC v0.05                0.8
Packit eb1bc2
Packit eb1bc2
These numbers was achieved Apr 2004 with ActivePerl-5.8.3 running
Packit eb1bc2
under Linux on a P4 2.8 GHz CPU.  The last 5 entries differ by being
Packit eb1bc2
pure perl implementations of the algorithms, which explains why they
Packit eb1bc2
are so slow.
Packit eb1bc2
Packit eb1bc2
=head1 SEE ALSO
Packit eb1bc2
Packit eb1bc2
L<Digest::Adler32>, L<Digest::CRC>, L<Digest::Haval256>,
Packit eb1bc2
L<Digest::HMAC>, L<Digest::MD2>, L<Digest::MD4>, L<Digest::MD5>,
Packit eb1bc2
L<Digest::SHA>, L<Digest::SHA1>, L<Digest::SHA2>, L<Digest::Whirlpool>
Packit eb1bc2
Packit eb1bc2
New digest implementations should consider subclassing from L<Digest::base>.
Packit eb1bc2
Packit eb1bc2
L<MIME::Base64>
Packit eb1bc2
Packit eb1bc2
http://en.wikipedia.org/wiki/Cryptographic_hash_function
Packit eb1bc2
Packit eb1bc2
=head1 AUTHOR
Packit eb1bc2
Packit eb1bc2
Gisle Aas <gisle@aas.no>
Packit eb1bc2
Packit eb1bc2
The C<Digest::> interface is based on the interface originally
Packit eb1bc2
developed by Neil Winton for his C<MD5> module.
Packit eb1bc2
Packit eb1bc2
This library is free software; you can redistribute it and/or
Packit eb1bc2
modify it under the same terms as Perl itself.
Packit eb1bc2
Packit eb1bc2
    Copyright 1998-2006 Gisle Aas.
Packit eb1bc2
    Copyright 1995,1996 Neil Winton.
Packit eb1bc2
Packit eb1bc2
=cut