


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


NAME
       Digest:: - Modules that calculate message digests

SYNOPSIS
         $md2 = Digest->MD2;
         $md5 = Digest->MD5;

         $sha1 = Digest->SHA1;
         $sha1 = Digest->new("SHA-1");

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

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

       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, i.e. 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.

       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
       arbitrary 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 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 message as argument and return the digest.  Example:

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



perl v5.8.2                 2002-11-06                          1





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


       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
           contains letters which are not legal perl identifiers,
           e.g. "SHA-1".

           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 ref-
           erence 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
           message we calculate the digest for.  The return value
           is the $ctx object itself.

       $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->digest
           Return the binary digest for the message.

           Note that the "digest" operation is effectively a
           destructive, read-once operation. Once it has been
           performed, 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



perl v5.8.2                 2002-11-06                          2





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


           digest without reseting the digest state.

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

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

SEE ALSO
       Digest::MD5, Digest::SHA1, Digest::HMAC, Digest::MD2

       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.





































perl v5.8.2                 2002-11-06                          3


