MAN page from Old RedHat 6.X Digest-MD5-2.07-1.i386.rpm

lib::Digest

Section: User Contributed Perl Documentation (3)
Updated: perl 5.005, patch 03
Index

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 message. The digest is some smallfixed size string. The actual size depend of the algorithm used. Themessage is simply a sequence of arbitrary bytes.

An important property of the digest algorithms is that the digest islikely to change if the message change in some way. Anotherproperty is that digest functions are one-way functions, i.e. itshould be hard to find a message that correspond to some givendigest. Algorithms differ in how ``likely'' and how ``hard'', as well ashow efficient they are to compute.

All Digest:: modules provide the same programming interface. Afunctional interface for simple use, as well as an object orientedinterface that can handle messages of arbitrary length and which canread files directly.

The digest can be delivered in three formats:

binary: This is the most compact form, but it is not well suited for printingor 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 encodedrepresentation of the digest with any trailing padding removed. Thestring will be about 30% longer than the binary version. Thethe MIME::Base64 manpage tells you more about this encoding.

The functional interface is simply importable functions with the samename as the algorithm. The functions take the message as argument andreturn 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 themessage-digest algorithm. You can add data to the object and finallyask for the digest. The ``XXX'' should of course be replaced by the propername of the digest algorithm you want to use.

The two first forms are simply syntactic sugar which automaticallyload the right module on first use. The second form allow you to usealgorithm names which contains letters which are not legal perlidentifiers, e.g. ``SHA-1''.

If new() is called as a instance method (i.e. $ctx->new) it will justreset the state the object to the state of a newly created object. Nonew object is created in this case.

$ctx->reset

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

$ctx->add($data,...)

The $data provided as argument are appended to the message wecalculate 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 themessage we calculate the digest for. The return value is the $ctxobject 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 isautomatically reset and can be used to calculate another digestvalue.

$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 encodedstring.

AUTHOR

Gisle Aas <gisleAATTaas.no>

The Digest:: interface is based on the interface originallydeveloped by Neil Winton for his MD5 module.

This document was created byman2html,using the manual pages.