=head1 NAME

SHA - Perl interface to the NIST Secure Hash Algorithm

=head1 SYNOPSIS

    use Crypt::SHA;
    
    $context = new SHA;
    $context->reset();
    
    $context->add(LIST);
    $context->addfile(HANDLE);
    
    $digest = $context->digest();
    $string = $context->hexdigest();

=head1 DESCRIPTION

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

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 16-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.

Two 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
hexdecimal digits in eight-digit groups.

=head1 EXAMPLE AND VALIDATION

    $sha = new SHA;

    print "EXPECT:   0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880\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";

The above example will produce the output

    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

provided that the implementation is working correctly.

=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>
following the MD5 interface written by Neil Winton
(C<N.Winton@axion.bt.co.uk>).
