MirOS Manual: Digest(3p)


Digest(3p)      Perl Programmers Reference Guide       Digest(3p)

NAME

     Digest - Modules that calculate message digests

SYNOPSIS

       $md5  = Digest->new("MD5");
       $sha1 = Digest->new("SHA-1");
       $sha256 = Digest->new("SHA-256");
       $sha384 = Digest->new("SHA-384");
       $sha512 = Digest->new("SHA-512");

       $hmac = Digest->HMAC_MD5($key);

DESCRIPTION

     The "Digest::" modules calculate digests, also called
     "fingerprints" or "hashes", of some data, called a message.
     The digest is (usually) some small/fixed size string.  The
     actual size of the digest depend of the algorithm used.  The
     message is simply a sequence of arbitrary bytes or bits.

     An important property of the digest algorithms is that the
     digest is likely to change if the message change in some
     way.  Another property is that digest functions are one-way
     functions, that is it should be hard to find a message that
     correspond to some given digest.  Algorithms differ in how
     "likely" and how "hard", as well as how efficient they are
     to compute.

     Note that the properties of the algorithms change over time,
     as the algorithms are analyzed and machines grow faster.  If
     your application for instance depends on it being "impossi-
     ble" to generate the same digest for a different message it
     is wise to make it easy to plug in stronger algorithms as
     the one used grow weaker.  Using the interface documented
     here should make it easy to change algorithms later.

     All "Digest::" modules provide the same programming inter-
     face.  A functional interface for simple use, as well as an
     object oriented interface that can handle messages of arbi-
     trary length and which can read files directly.

     The digest can be delivered in three formats:

     binary  This is the most compact form, but it is not well
             suited for printing or embedding in places that
             can't handle arbitrary data.

     hex     A twice as long string of lowercase hexadecimal
             digits.

     base64  A string of portable printable characters.  This is
             the base64 encoded representation of the digest with
             any trailing padding removed.  The string will be

perl v5.8.8                2005-02-05                           1

Digest(3p)      Perl Programmers Reference Guide       Digest(3p)

             about 30% longer than the binary version.
             MIME::Base64 tells you more about this encoding.

     The functional interface is simply importable functions with
     the same name as the algorithm.  The functions take the mes-
     sage as argument and return the digest.  Example:

       use Digest::MD5 qw(md5);
       $digest = md5($message);

     There are also versions of the functions with "_hex" or
     "_base64" appended to the name, which returns the digest in
     the indicated form.

OO INTERFACE

     The following methods are available for all "Digest::"
     modules:

     $ctx = Digest->XXX($arg,...)
     $ctx = Digest->new(XXX => $arg,...)
     $ctx = Digest::XXX->new($arg,...)
         The constructor returns some object that encapsulate the
         state of the message-digest algorithm.  You can add data
         to the object and finally ask for the digest.  The "XXX"
         should of course be replaced by the proper name of the
         digest algorithm you want to use.

         The two first forms are simply syntactic sugar which
         automatically load the right module on first use.  The
         second form allow you to use algorithm names which con-
         tains letters which are not legal perl identifiers, e.g.
         "SHA-1".  If no implementation for the given algorithm
         can be found, then an exception is raised.

         If new() is called as an instance method (i.e.
         $ctx->new) it will just reset the state the object to
         the state of a newly created object.  No new object is
         created in this case, and the return value is the refer-
         ence to the object (i.e. $ctx).

     $other_ctx = $ctx->clone
         The clone method creates a copy of the digest state
         object and returns a reference to the copy.

     $ctx->reset
         This is just an alias for $ctx->new.

     $ctx->add( $data, ... )
         The $data provided as argument are appended to the mes-
         sage we calculate the digest for.  The return value is
         the $ctx object itself.

perl v5.8.8                2005-02-05                           2

Digest(3p)      Perl Programmers Reference Guide       Digest(3p)

     $ctx->addfile( $io_handle )
         The $io_handle is read until EOF and the content is
         appended to the message we calculate the digest for.
         The return value is the $ctx object itself.

     $ctx->add_bits( $data, $nbits )
     $ctx->add_bits( $bitstring )
         The bits provided are appended to the message we calcu-
         late the digest for.  The return value is the $ctx
         object itself.

         The two argument form of add_bits() will add the first
         $nbits bits from data.  For the last potentially partial
         byte only the high order "$nbits % 8" bits are used.  If
         $nbits is greater than "length($data) * 8", then this
         method would do the same as "$ctx->add($data)", that is
         $nbits is silently ignored.

         The one argument form of add_bits() takes a $bitstring
         of "1" and "0" chars as argument.  It's a shorthand for
         "$ctx->add_bits(pack("B*", $bitstring),
         length($bitstring))".

         This example shows two calls that should have the same
         effect:

            $ctx->add_bits("111100001010");
            $ctx->add_bits("\xF0\xA0", 12);

         Most digest algorithms are byte based.  For those it is
         not possible to add bits that are not a multiple of 8,
         and the add_bits() method will croak if you try.

     $ctx->digest
         Return the binary digest for the message.

         Note that the "digest" operation is effectively a des-
         tructive, read-once operation. Once it has been per-
         formed, the $ctx object is automatically "reset" and can
         be used to calculate another digest value.  Call
         $ctx->clone->digest if you want to calculate the digest
         without reseting the digest state.

     $ctx->hexdigest
         Same as $ctx->digest, but will return the digest in hex-
         adecimal form.

     $ctx->b64digest
         Same as $ctx->digest, but will return the digest as a
         base64 encoded string.

perl v5.8.8                2005-02-05                           3

Digest(3p)      Perl Programmers Reference Guide       Digest(3p)

Digest speed

     This table should give some indication on the relative speed
     of different algorithms.  It is sorted by throughput based
     on a benchmark done with of some implementations of this
     API:

      Algorithm      Size    Implementation                  MB/s

      MD4            128     Digest::MD4 v1.3               165.0
      MD5            128     Digest::MD5 v2.33               98.8
      SHA-256        256     Digest::SHA2 v1.1.0             66.7
      SHA-1          160     Digest::SHA v4.3.1              58.9
      SHA-1          160     Digest::SHA1 v2.10              48.8
      SHA-256        256     Digest::SHA v4.3.1              41.3
      Haval-256      256     Digest::Haval256 v1.0.4         39.8
      SHA-384        384     Digest::SHA2 v1.1.0             19.6
      SHA-512        512     Digest::SHA2 v1.1.0             19.3
      SHA-384        384     Digest::SHA v4.3.1              19.2
      SHA-512        512     Digest::SHA v4.3.1              19.2
      Whirlpool      512     Digest::Whirlpool v1.0.2        13.0
      MD2            128     Digest::MD2 v2.03                9.5

      Adler-32        32     Digest::Adler32 v0.03            1.3
      CRC-16          16     Digest::CRC v0.05                1.1
      CRC-32          32     Digest::CRC v0.05                1.1
      MD5            128     Digest::Perl::MD5 v1.5           1.0
      CRC-CCITT       16     Digest::CRC v0.05                0.8

     These numbers was achieved Apr 2004 with ActivePerl-5.8.3
     running under Linux on a P4 2.8 GHz CPU.  The last 5 entries
     differ by being pure perl implementations of the algorithms,
     which explains why they are so slow.

SEE ALSO

     Digest::Adler32, Digest::CRC, Digest::Haval256,
     Digest::HMAC, Digest::MD2, Digest::MD4, Digest::MD5,
     Digest::SHA, Digest::SHA1, Digest::SHA2, Digest::Whirlpool

     New digest implementations should consider subclassing from
     Digest::base.

     MIME::Base64

AUTHOR

     Gisle Aas <gisle@aas.no>

     The "Digest::" interface is based on the interface origi-
     nally developed by Neil Winton for his "MD5" module.

     This library is free software; you can redistribute it
     and/or modify it under the same terms as Perl itself.

perl v5.8.8                2005-02-05                           4

Digest(3p)      Perl Programmers Reference Guide       Digest(3p)

         Copyright 1998-2001,2003-2004 Gisle Aas.
         Copyright 1995-1996 Neil Winton.

perl v5.8.8                2005-02-05                           5

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.