NAME

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

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();

    $digest = $sha2obj->digest();
    $digest = $sha2obj->hexdigest();
    $digest = $sha2obj->base64digest();
    
    $digest = $sha2obj->hashsize();

DESCRIPTION

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 the default SHA-256, just use

        $sha2obj = new Digest::SHA2;

hashsize()

Returns the digest size (in bits) of the hash output used

add(LIST)

Hashes a string or a list of strings

addfile(*HANDLE)

Hashes a file

reset()

Re-initializes the hash state. Before calculating another digest, the hash state must be refreshed.

digest()

Generates the hash output as a binary string

hexdigest()

Generates a hexadecimal representation of the hash output

base64digest()

Generates a base64 representation of the hash output. MIME::Base64 must be installed first for this function to work.

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, "\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.pl";
    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->base64digest();
    close INFILE;
    print "$file\n";
    print "$hex_output\n";
    print "$base64_output\n";

MORE EXAMPLES

See the "examples" and "t" directories for more examples.

COPYRIGHT AND LICENSE

Copyright (C) 2003 Julius C. Duque. Please read contact.html that comes with this distribution for details on how to contact the author.

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

ACKNOWLEDGEMENT

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