Digest::SHA2 - A variable-length one-way hash function

NAME
DEPRECATED
ABSTRACT
DESCRIPTION
SYNOPSIS
METHODS
EXAMPLE 1
EXAMPLE 2
MORE EXAMPLES
DIGEST SPEED
ACKNOWLEDGEMENT
COPYRIGHT AND LICENSE

NAME

Digest::SHA2 - A variable-length one-way hash function (deprecated in favor of the Digest::SHA manpage)

DEPRECATED

This module has numerious known bugs, is not compatable with the Digest interface and its functionality is a subset of the functionality of the Digest::SHA manpage (which is in perl core as of 5.9.3).

Please use the Digest::SHA manpage instead of this module in new and old code.

ABSTRACT

Digest::SHA2 - A Perl interface for SHA-256, SHA-384 and SHA-512, collectively known as SHA-2

DESCRIPTION

SHA-2 is the collective name of one-way hash functions developed by the NIST. SHA-256, SHA-384, and SHA-512 pertain to hashes whose outputs are 256 bits, 384 bits and 512 bits, respectively.

This Perl implementation is meant to be a replacement for the older SHA256 by Rafael R. Sevilla. His module has a bug in the SHA-256 implementation.

This new implementation uses the C source of Aaron Gifford.

SYNOPSIS

    use Digest::SHA2;

    $sha2obj = new Digest::SHA2 [$hashlength];
    $sha2obj->add(LIST);
    $sha2obj->addfile(*HANDLE);
    $sha2obj->reset();

    $sha_clone = $sha2obj->clone();
    $digest = $sha2obj->digest();
    $digest = $sha2obj->hexdigest();
    $digest = $sha2obj->b64digest();
    $digest = $sha2obj->base64digest();  # deprecated

    $digest = $sha2obj->hashsize();
    $digest = $sha2obj->rounds();

METHODS

SHA-2 supports the following functions:

new [$hashlength]

Creates a SHA-2 object, where $hashlength represents the hash output length; valid values for $hashlength are 256, 384, and 512 only. If $hashlength is omitted, the output defaults to 256 bits.

For example, to specify SHA-512, use

        $sha2obj = new Digest::SHA2 512;

To specify SHA-256, use

        $sha2obj = new Digest::SHA2 256;

or just simply

        $sha2obj = new Digest::SHA2;

hashsize()

Returns the digest size (in bits) of the hash output used; valid sizes are 256, 384, and 512 only.

rounds()

Returns the number of rounds (1, in this case) used to generate the hash output; this is included only so that Digest::SHA2 is consistent with other one-way hash functions that have variable number of rounds, like Haval and Tiger.

Haval can uses 3, 4, or 5 rounds, with 5 different output lengths: 128, 160, 192, 224, and 256 bits, thereby, having 15 variants. Tiger, on the other hand, outputs 192 bits of digest, using 3 rounds; but for added security, can also use 4 rounds.

add(LIST)

Hashes a string or a list of strings

For example,

        $sha2obj->add($string1);
        $sha2obj->add($string2, $string3, $string4);

addfile(*HANDLE)

Hashes a file whose file handle is HANDLE

reset()

Re-initializes the hash state of the SHA-2 object. Before calculating another digest, reset() refreshes the hash state, and is, therefore, functionally equivalent to the new() method, except that no SHA-2 object is created.

digest()

Generates the hash output as a binary string

hexdigest()

Generates a hexadecimal representation of the hash output

base64digest() (deprecated)

This will be removed in future releases; use b64digest() instead.

b64digest()

Generates a base64 representation of the hash output

clone()

Returns a copy of the SHA-2 object; useful when you want to preserve an intermediate value of the digest

For example,

        my $clone = $sha2obj->clone();   # clone SHA-2 object

        my $sig = $sha2obj->clone->hexdigest;
        print "partial digest: $sig\n";

EXAMPLE 1

    #!/usr/local/bin/perl

    use diagnostics;
    use strict;
    use warnings;
    use Digest::SHA2;

    my $string1 = "This is a string.";
    my $string2 = "This is another string.";
    my $string3 = "This is a string.This is another string.";

    my $sha2obj = new Digest::SHA2 512;
    print "hash size = ", $sha2obj->hashsize, " bits\n";

    $sha2obj->add($string1);
    my $digest = $sha2obj->hexdigest();
    print "Hash string1 only\n";
    print "$digest\n\n";

    $sha2obj->reset();
    $sha2obj->add($string1, $string2);
    my $digest2 = $sha2obj->hexdigest();
    print "Hash string1 and then hash string2\n";
    print "$digest2\n\n";

    $sha2obj->reset();
    $sha2obj->add($string1);
    $sha2obj->add($string2);
    my $digest3 = $sha2obj->hexdigest();
    print "Hash string1 and then hash string2\n";
    print "$digest3\n\n";

    $sha2obj->reset();
    $sha2obj->add($string3);
    print "Hash the two concatenated strings\n";
    my $digest4 = $sha2obj->hexdigest();
    print "$digest4\n";

EXAMPLE 2

    #!/usr/local/bin/perl

    use diagnostics;
    use strict;
    use warnings;
    use MIME::Base64;
    use Digest::SHA2;

    my $file = "strings";
    open INFILE, $file or die "$file not found";

    my $sha2obj = new Digest::SHA2;  # defaults to 256-bit output
    $sha2obj->addfile(*INFILE);
    my $hex_output = $sha2obj->hexdigest();
    my $base64_output = $sha2obj->b64digest();
    close INFILE;
    print "$file\n";
    print "$hex_output\n";
    print "$base64_output\n";

MORE EXAMPLES

See the ``examples'' and ``t'' directories for more examples.

DIGEST SPEED

Please consult the file, COMPARISON, for comparison of various one-way hash functions with digest lengths of 256, 384, and 512 bits.

ACKNOWLEDGEMENT

I used the C source of Aaron Gifford as backend for this Perl implementation.

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as the GNU General Public License.

Digest::SHA2 - A variable-length one-way hash function