=head1 NAME

SHA - Perl interface to the NIST Secure Hash Algorithm

=head1 SYNOPSIS

    use SHA;

    $version = &SHA::sha_version;

    $context = new SHA;
    $context->reset();

    $context->add(LIST);
    $context->addfile(HANDLE);

    $digest = $context->digest();
    $string = $context->hexdigest();

    $digest = $context->hash($string);
    $string = $context->hexhash($string);

=head1 DESCRIPTION

The B<SHA> module allows you to use the NIST SHA message digest algorithm
from within Perl programs.

The sha_version routine returns the version of the algorithm which is being
used: either "SHA" for the original algorithm or "SHA-1" for the updated
algorithm.

A new SHA context object is created with the B<new> operation.
Multiple simultaneous digest contexts can be maintained, if desired.
The context is updated with the B<add> operation which adds the
strings contained in the I<LIST> parameter. Adding two strings
separately is equivalent to adding their concatenation:
C<add('foo', 'bar')> produces the same effect as C<add('foo')>,
C<add('bar')>, which in turn produces the same effect as C<add('foobar')>.

The final message digest value is returned by the B<digest> operation
as a 20-byte binary string. This operation delivers the result of
operations since the last B<new> or B<reset> operation. Once the
operation has been performed, the context must be B<reset> before
being used to calculate another digest value.

Several convenience functions are also provided. The B<addfile>
operation takes an open file-handle and reads it until end-of file in
8192-byte blocks adding the contents to the context. The B<hexdigest>
operation calls B<digest> and returns the result as a printable string
of hexadecimal digits in eight-digit groups. The B<hash> operation
performs the complete series of steps: B<reset>, B<add>, B<digest> on
the supplied scalar value, and returns the result as a 20-byte binary
string. The B<hexhash> operation does the same thing, but returns the
result in the format of the B<hexdigest> operation.

=head1 EXAMPLE AND VALIDATION

    use SHA 1.2;

    $ver = &SHA::sha_version;
    $sha = new SHA;

    if ($ver eq 'SHA') {
	print "EXPECT:   0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880\n";
    } elsif ($ver eq 'SHA-1') {
	print "EXPECT:   a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d\n";
    } else {
	die "panic! unrecognized output '$ver' from sha_version\n";
    }

    $sha->reset();
    $sha->add("abc");
    print "RESULT 1: " . $sha->hexdigest() . "\n";

    $sha->reset();
    $sha->add("a", "bc");
    print "RESULT 2: " . $sha->hexdigest() . "\n";

    $sha->reset();
    $sha->add("ab", "c");
    print "RESULT 3: " . $sha->hexdigest() . "\n";

    $sha->reset();
    $sha->add("a", "b", "c");
    print "RESULT 4: " . $sha->hexdigest() . "\n";

    $sha->reset();
    $sha->add("ab");
    $sha->add("c");
    print "RESULT 5: " . $sha->hexdigest() . "\n";

    $sha->reset();
    $sha->add("a");
    $sha->add("bc");
    print "RESULT 6: " . $sha->hexdigest() . "\n";

    $sha->reset();
    $sha->add("a");
    $sha->add("b");
    $sha->add("c");
    print "RESULT 7: " . $sha->hexdigest() . "\n";

    print "RESULT 8: " . $sha->hexhash("abc") . "\n";

    $sha->reset();
    $sha->add("ab", "c");
    print "result a: " . unpack("H*", ($sha->digest())) . "\n";

    print "result b: " . unpack("H*", ($sha->hash("abc"))) . "\n";

The above example will produce one of two outputs. If the original SHA
algorithm is being used, the output will be:

    EXPECT:   0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
    RESULT 1: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
    RESULT 2: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
    RESULT 3: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
    RESULT 4: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
    RESULT 5: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
    RESULT 6: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
    RESULT 7: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
    RESULT 8: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
    result a: 0164b8a914cd2a5e74c4f7ff082c4d97f1edf880
    result b: 0164b8a914cd2a5e74c4f7ff082c4d97f1edf880

If the new SHA-1 algorithm is being used, the output will be

    EXPECT:   a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
    RESULT 1: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
    RESULT 2: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
    RESULT 3: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
    RESULT 4: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
    RESULT 5: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
    RESULT 6: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
    RESULT 7: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
    RESULT 8: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
    result a: a9993e364706816aba3e25717850c26c9cd0d89d
    result b: a9993e364706816aba3e25717850c26c9cd0d89d

provided that the implementation is working correctly.

=head1 FURTHER EXAMPLES AND VALIDATION

The file sha_driver.pl contains further validation data and examples of
how to use the SHA module. It may be invoked with the B<-h> flag, which gives
further usage instructions; the B<-x> flag runs a few more tests.

=head1 NOTE

The SHA extension may be redistributed under the same terms as Perl.
The SHA code is in the public domain. It was heavily modified by
Uwe Hollerbach following the implementation by Peter Gutmann.

=head1 AUTHOR

The SHA interface was written by Uwe Hollerbach C<uh@alumni.caltech.edu>,
shamelessly stealing from the MD5 interface written by Neil Winton
(C<N.Winton@axion.bt.co.uk>).