NAME

Digest::combined — Calculate multiple message digests simultaneously

SYNOPSIS

  my $combined
    = Digest::combined->new ("Algo-1", [ $algo_2, @args_2 ], ...);
  my $debian_digests
    = Digest::combined->new (qw (SHA-256 SHA-1 MD5));

DESCRIPTION

Certain catalogues and protocols out there allow (or require) one to list several digests for a single file (or, rather, an octet sequence), provided that these are of different “kinds.” Consider, e. g., the magnet: URI schema, or Debian's “Packages” database:

    Package: beep
    ...
    Filename: pool/main/b/beep/beep_1.2.2-22_amd64.deb
    Size: 24036
    MD5sum: dec6eb5a0eb38f4ac85e24d653c01916
    SHA1: 15df36acc29d696c91cf432986e3bbd99761eada
    SHA256: 869fc8d7d8e3d0cba191ea430e8a32426cc29efeb54e0b55af49c3fea90cddf0

The Digest::combined module is intended to provide a simple and convenient interface for such a task.

INTERFACE

my $ctx = Digest::combined->new ($algo_1, ...);

Construct and return an object encapsulating the state of all the message digest algorithms requested.

Each of the algorithms ($algo_1, etc.) is specified either as scalar, which is passed unaltered to Digest-new ()>, or as a reference to the list of arguments to be passed to Digest-new ()>.

Please note that thanks to the magic of the latter, the following contexts are essentially equivalent:

    my $c_1
        = Digest::combined->new (qw (SHA-256 SHA-1 MD5))
        or die ();

    my $c_2
        = Digest::combined->new (["SHA", 256], ["SHA", 1], "MD5")
        or die ();

Note also that the current implementation makes this constructor “safe” in that it either succeeds or raises an exception (i. e., dies.) However, the later versions of the code may choose to return undef in the case of failure instead.

$ctx->add ($data);

$ctx->add ($chunk_1, $chunk_2, ...);

$ctx->clone ();

my $digest = $ctx->digest ();

my $digest = $ctx->digest ($delimiter);

$ctx->reset ();

These method behave just like their counterparts for individual message digests. Namely, they append to the message the digest is calculated for, create a copy of the message digest algorithms' state, return (destructively) the concatenated calculated binary digest for the message, and reset the state of all the message digest algorithms combined within the context, respectively. (Please refer to the Digest module documentation for the details.)

The add, digest, and reset methods assume that the respective methods for all the algorithms combined within the context always succeed, and always succeed in turn.

Note that the current implementation makes the clone method “safe” in that it either succeeds or raises an exception (i. e., dies.) However, the later versions of the code may choose to return undef in the case of failure instead.

my @digests = $ctx->digests ();

Return (destructively) the individual calculated binary digests for the message.

This method assumes that the digest method for all the algorithms combined within the context always succeed, and always succeeds in turn.

SEE ALSO

Digest

http://en.wikipedia.org/wiki/Cryptographic_hash_function

AUTHOR

Ivan Shmakov <oneingray@gmail.com>

Based on the code suggested by Gisle Aas <gisle@aas.no> (CPAN RT ticket #76044.)

The Digest::combined code is in the public domain.