NAME

Crypt::SHAVS - Interface to NIST SHA Validation System

SYNOPSIS

        # Check SHA-256 implementation in Digest::SHA (BYTE mode):

        use Crypt::SHAVS;
        use Digest::SHA qw(sha256);

        $shavs = Crypt::SHAVS->new(\&sha256);
        for $file (glob('SHA256*.rsp')) {
                $shavs->check($file);
        }

ABSTRACT

Crypt::SHAVS automates the checking of any SHA implementation by comparing its behavior against the detailed test vectors of NIST's SHA Validation System (SHAVS). The capability extends to the testing of upcoming SHA-3 implementations as well, assuming the continued use of SHAVS by NIST.

DESCRIPTION

Crypt::SHAVS is designed for ease of use rather than power. The user doesn't need to understand the details of SHAVS test vectors or the algorithms used in processing short, long, and pseudorandomly-generated test messages.

Rather, as the SYNOPSIS illustrates, the user simply passes a reference to the SHA function under test, and indicates which test vectors are to be examined. Crypt::SHAVS reports the value computed by the function for each vector, and whether that value matches (OK) or doesn't match (FAILED) the expected result.

Most SHA implementations are BYTE oriented, meaning that they allow input data only in units of whole bytes. Crypt::SHAVS has the ability to handle BIT implementations as well. To use the latter, simply pass a second argument to the constructor with a true value, and supply a reference to a 2-argument function that calls the appropriate BIT implementation. Here's how it's done with Perl's Digest::SHA module, this time using SHA-1:

        use Crypt::SHAVS;
        use Digest::SHA;

        $sha1BIT = sub {Digest::SHA->new()->add_bits($_[0], $_[1])->digest};

        $shavs = Crypt::SHAVS->new($sha1BIT, 1);
        for $file (glob('SHA1*.rsp')) {
                $shavs->check($file);
        }

Note that in this case, the rsp files must be taken from NIST's repository of SHA bit-oriented messages (ref. "SEE ALSO"), whereas in the SYNOPSIS they're taken from among the byte-oriented messages.

OBJECT-ORIENTED INTERFACE

In keeping with the theme of simplicity, the Crypt::SHAVS object supplies only two methods:

new($sha, $BIT)

Returns a new Crypt::SHAVS object. The first argument, $sha, is a reference to the SHA function being tested. The optional second argument is set only for testing BIT-oriented messages.

In the more usual case of BYTE-oriented messages, the $sha function being referenced takes a single argument consisting of the binary message whose binary digest is to be calculated. The $sha function is allowed to accept more than one argument, like the various sha...() functions of Digest::SHA and Digest::SHA1, but no more than one argument is ever supplied internally by Crypt::SHAVS for byte-oriented messages.

For BIT-oriented messages, the $sha function takes a second argument designating the number of bits in the message. The above example illustrates the appropriate construction of a bit-oriented function for Digest::SHA.

check($file)

This method accepts the name of a particular file from either of the two NIST test vector repositories (ref. "SEE ALSO"). Those file names adhere to the following pattern:

        $file = "SHA" . $alg . $type . ".rsp"

where $alg can take values from (1, 224, 256, 384, 512), and $type is selected from qw(ShortMsg LongMsg Monte).

For each vector, check() will print the value computed by the $sha function passed previously to new(), and then compare that value to the expected value and print "OK" if the values match, and "FAILED" if they don't.

EXPORT

None

EXPORTABLE FUNCTIONS

None

SEE ALSO

Digest, Digest::SHA, Digest::SHA1, Digest::SHA::PurePerl

NIST SHAVS - Test Vectors for Bit-Oriented and Byte-Oriented Messages:

http://csrc.nist.gov/groups/STM/cavp/index.html#03

The Secure Hash Standard (Draft FIPS PUB 180-3):

http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf

AUTHOR

        Mark Shelor     <mshelor@cpan.org>

ACKNOWLEDGMENTS

The author is grateful to

        Gisle Aas

for ideas and suggestions beneficial to the construction of this module.

COPYRIGHT AND LICENSE

Copyright (C) 2011 Mark Shelor

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

perlartistic

cpanm Crypt::SHAVS

perl -MCPAN -e shell
install Crypt::SHAVS