NAME

Digest::SHA - Perl extension for SHA-1/256/384/512 and HMAC-SHA

SYNOPSIS

# Functional style
use Digest::SHA qw(sha1 sha1_hex sha1_base64 sha256 sha256_hex ... );

$digest = sha1($data);
$digest = sha1_hex($data);
$digest = sha1_base64($data);


# OO style
use Digest::SHA ':all';

$sha = Digest::SHA->new($alg);	# alg = 1, 256, 384, 512

$sha->add($data);
$sha->addfile(*FILE);

$sha_copy = $sha->clone;

$digest = $sha->digest;
$digest = $sha->hexdigest;
$digest = $sha->b64digest;

The simple interface above follows the guidelines and conventions described in the Digest:: module, and is sufficient to handle the majority of applications requiring SHA digest computations. Unfortunately, that interface alone cannot accommodate the full range of inputs outlined in the NIST SHA specification (FIPS PUB 180-2). Specifically, the routines are unable to handle general bit-string inputs (i.e. data streams that are not aligned on byte boundaries).

For that reason, the Digest::SHA module includes additional functions to process such streams. Also included are functions that perform useful services such as calculating keyed SHA hashes using the HMAC algorithm, and capturing and retrieving intermediate SHA states to and from persistent storage (see the "EXPORTABLE FUNCTIONS" section for a complete description). A brief synopsis of the interface follows:

# Direct computation
use Digest::SHA qw(sha1hex sha1base64 sha256hex sha256base64 ... );

$digest = sha1hex($data);			# byte-oriented data
$digest = sha1hex($data, $numbits);		# bit-oriented

$digest = sha384base64($data);
$digest = sha512base64($data, $numbits);
...

# Iterative computation
use Digest::SHA qw(shaopen shawrite shafinish shaclose shahex ... );

$state = shaopen($alg);		# $alg = 1, 256, 384, or 512

shawrite($data, [ $numbits, ] $state);
shawrite($moredata, [ $numbits, ] $state);

shafinish($state);

$digest = shahex($state);
$digest = shabase64($state);

shaclose($state);

# HMAC-SHA keyed hash
use Digest::SHA qw(hmac1hex hmac1base64 hmac256hex ... );

$digest = hmac1hex($data, [ $numbits, ] $key);
$digest = hmac1base64($data, [ $numbits, ] $key);
...

ABSTRACT

Digest::SHA provides a Perl interface to all algorithms defined in the NIST Secure Hash Standard (FIPS PUB 180-2). The module also includes support for computing keyed SHA hashes using the HMAC algorithm described in FIPS PUB 198. The routines are general-purpose, allowing digests to be calculated for bit-strings as well as byte-strings. The underlying code is written in C.

DESCRIPTION

Digest::SHA endeavors to provide a complete and portable implementation of the NIST Secure Hash Standard. It differs from the majority of existing SHA packages which usually omit support for bit-string inputs, and often don't include the entire range of transforms specified by NIST.

The module attempts to be as fast and efficient as possible, with the goal of combining Perl's ease-of-use with C's performance advantages. For added convenience, the package includes the Perl script shasum to perform myriad SHA operations through the command line. Just go to the utils/ directory and type perl shasum --help for details.

Digest::SHA offers two ways to calculate digests: all-at-once, or in stages. The first is simpler, and often requires only one line of Perl. The second is more general, allowing input to be processed in chunks.

To illustrate the difference, the following program calculates the SHA-256 digest of hello world using the two different methods:

use Digest::SHA ':all';

my $data = "hello world";
my @frags = split(//, $data);

my $method1 = sha256hex($data);

my $state = shaopen(256);
for (@frags) {
	shawrite($_, $state);
}
shafinish($state);
my $method2 = shahex($state);

print $method1 eq $method2 ?
	"whew!\n" : "career in aluminum siding\n";

PLEASE NOTE: the optional $numbits argument of sha256hex() and shawrite() is omitted in the above example since the input data is byte-oriented.

Computing the digest value of a bit-string is also easy. Let's say the input string is 446 bits, consisting of the fragment 110 repeated 148 times, followed by the fragment 11. Here's how to calculate its SHA-1 digest:

$digest = sha1hex(pack("B*", ("110"x148)."11"), 446);

When calculating keyed-hashes using the HMAC-SHA functions, it's important to note that the optional data length argument is in bits. If omitted, the corresponding data is assumed to be byte-oriented.

So, to compute the HMAC-SHA-1 digest of burpleson using a suitable key, the code would go something like this:

$data = "burpleson";
$key = "poe";
$digest = hmac1hex($data, $key);

or, if you're paid by the character:

$digest = hmac1hex($data, 8 * length($data), $key);

EXPORT

None by default.

EXPORTABLE FUNCTIONS

Provided your C compiler supports 64-bit types (i.e. long long), all of these functions will be available for use. If it doesn't, you won't be able to perform SHA-384 and SHA-512 transforms, both of which require 64-bit operations.

Functional style

sha1($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-1 digest encoded as a binary string.

sha1_hex($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-1 digest encoded as a hexadecimal string.

sha1_base64($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-1 digest encoded as a Base64 string.

sha256($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-256 digest encoded as a binary string.

sha256_hex($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-256 digest encoded as a hexadecimal string.

sha256_base64($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-256 digest encoded as a Base64 string.

sha384($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-384 digest encoded as a binary string.

sha384_hex($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-384 digest encoded as a hexadecimal string.

sha384_base64($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-384 digest encoded as a Base64 string.

sha512($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-512 digest encoded as a binary string.

sha512_hex($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-512 digest encoded as a hexadecimal string.

sha512_base64($data, ...)

Concatenates the $data, ... arguments into a single stream, and returns its SHA-512 digest encoded as a Base64 string.

OO style

$sha = Digest::SHA->new($alg)

Returns a new Digest::SHA object. Possible values for $alg are 1, 256, 384, and 512, which correspond to the SHA-1, SHA-256, SHA-384, and SHA-512 transforms, respectively. If $alg is missing, the SHA-1 transform will be used by default.

Invoking new($alg) as an instance method will not cause a new object to be created, but rather will simply reset the digest state to the initial value associated with $alg. If $alg is missing, the object will continue using the same transform that was selected at creation.

$sha->reset($alg)

This method has exactly the same effect as $sha->new($alg).

$sha->clone

Returns a duplicate copy of the $sha object.

$sha->add($data, ...)

Concatenates the $data, ... arguments into a single stream, and uses it to update the current $sha digest state. In other words, the following statements have the same effect:

$sha->add("a"); $sha->add("b"); $sha->add("c");
$sha->add("a")->add("b")->add("c");
$sha->add("a", "b", "c");
$sha->add("abc");

$sha->addfile(*FILE)

Reads the file-handle until EOF, and uses that data to update the current $sha state. The return value is the $sha object itself.

$sha->digest

Returns the digest encoded as a binary string.

Note that the digest method is a read-once operation. Once it has been performed, the Digest::SHA object is automatically reset in preparation for calculating another digest value. Call $sha->clone->digest if it's necessary to preserve the original digest state.

$sha->hexdigest

Returns the digest encoded as a hexadecimal string.

Like digest, the hexdigest method is a read-once operation. Call $sha->clone->hexdigest if it's necessary to preserve the original digest state.

$sha->b64digest

Returns the digest encoded as a Base64 string.

Like digest, the b64digest method is a read-once operation. Call $sha->clone->b64digest if it's necessary to preserve the original digest state.

Direct Functions (Bit- and Byte-Oriented Data)

sha1hex($data [ , $numbits ] )

Returns the SHA-1 digest of $data, encoded as a 40-character hexadecimal string.

sha1base64($data [ , $numbits ] )

Returns the SHA-1 digest of $data, encoded as a Base64 string.

sha256hex($data [ , $numbits ] )

Returns the SHA-256 digest of $data, encoded as a 64-character hexadecimal string.

sha256base64($data [ , $numbits ] )

Returns the SHA-256 digest of $data, encoded as a Base64 string.

sha384hex($data [ , $numbits ] )

Returns the SHA-384 digest of $data, encoded as a 96-character hexadecimal string. This function will return a null value if your C compiler lacks support for 64-bit integral types.

sha384base64($data [ , $numbits ] )

Returns the SHA-384 digest of $data, encoded as a Base64 string. This function will return a null value if your C compiler lacks support for 64-bit integral types.

sha512hex($data [ , $numbits ] )

Returns the SHA-512 digest of $data, encoded as a 128-character hexadecimal string. This function will return a null value if your C compiler lacks support for 64-bit integral types.

sha512base64($data [ , $numbits ] )

Returns the SHA-512 digest of $data, encoded as a Base64 string. This function will return a null value if your C compiler lacks support for 64-bit integral types.

Iterative Functions (Bit- and Byte-Oriented Data)

shaopen($alg)

Begins the iterative calculation of a SHA digest, returning a state variable for use by subsequent iterative sha...() functions. The $alg argument determines which SHA transform will be used (e.g. $alg = 256 corresponds to SHA-256). This function will return a null value for $alg = 384 or $alg = 512 if your C compiler lacks support for 64-bit integral types.

shawrite($data, [ $numbits, ] $state)

Updates the SHA state by feeding in $data. The caller invokes this function repeatedly until all data has been processed. The value of $numbits must not exceed 2^32-1 for each individual call of shawrite(). However, per the NIST standard, the total accumulated length of the data stream may be as large as 2^64-1 for SHA-1 and SHA-256, or 2^128-1 for SHA-384 and SHA-512.

shafinish($state)

Finalizes the SHA calculation by padding and transforming the final block(s), and updating the state. It is necessary to call this function before attempting to access the final digest value through shahex() or shabase64(). However, calling them beforehand may be useful to folks who are interested in examining SHA's internal state at various stages of the digest computation.

shahex($state)

Returns the digest value, encoded as a hexadecimal string.

shabase64($state)

Returns the digest value, encoded as a Base64 string.

shadup($state)

Returns a duplicate copy of the current state.

shadump( [ $filename, ] $state)

Provides persistent storage of intermediate SHA states by writing the contents of the $state structure to disk. If $filename is missing, or equal to the empty string, the state information will be written to stdout. In combination with shaload() and shadup(), this routine can help to speed up SHA calculations for data sets that share identical headers. See the gillogly-hard script in the t/ subdirectory for a simple illustration.

shaload( [ $filename ] )

Retrieves the contents of an intermediate SHA state that was previously stored to disk by shadump(). If $filename is missing, or equal to the empty string, the state information will be read from stdin. The shaload() routine returns a fresh copy of this state, so it's not necessary to create or initialize it beforehand by calling shaopen().

shaclose($state)

Frees all memory allocated during the previous shaopen(), shadup(), or shaload() call.

HMAC-SHA Functions

hmac1hex($data, [ $numbits, ] $key)

Returns the HMAC-SHA-1 digest of $data/$key, encoded as a 40-character hexadecimal string.

hmac1base64($data, [ $numbits, ] $key)

Returns the HMAC-SHA-1 digest of $data/$key, encoded as a Base64 string.

hmac256hex($data, [ $numbits, ] $key)

Returns the HMAC-SHA-256 digest of $data/$key, encoded as a 64-character hexadecimal string.

hmac256base64($data, [ $numbits, ] $key)

Returns the HMAC-SHA-256 digest of $data/$key, encoded as a Base64 string.

hmac384hex($data, [ $numbits, ] $key)

Returns the HMAC-SHA-384 digest of $data/$key, encoded as a 96-character hexadecimal string. This function will return a null value if your C compiler lacks support for 64-bit integral types.

hmac384base64($data, [ $numbits, ] $key)

Returns the HMAC-SHA-384 digest of $data/$key, encoded as a Base64 string. This function will return a null value if your C compiler lacks support for 64-bit integral types.

hmac512hex($data, [ $numbits, ] $key)

Returns the HMAC-SHA-512 digest of $data/$key, encoded as a 128-character hexadecimal string. This function will return a null value if your C compiler lacks support for 64-bit integral types.

hmac512base64($data, [ $numbits, ] $key)

Returns the HMAC-SHA-512 digest of $data/$key, encoded as a Base64 string. This function will return a null value if your C compiler lacks support for 64-bit integral types.

SEE ALSO

Digest::, Digest::SHA1

The Secure Hash Standard (FIPS PUB 180-2) can be found at:

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

The Keyed-Hash Message Authentication Code (HMAC):

http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf

AUTHOR

Mark Shelor, <mshelor@comcast.net>

The author extends special thanks to Jeffrey Friedl and Chris Skiscim for their valuable comments and suggestions.

COPYRIGHT AND LICENSE

Copyright (C) 2003 by Mark Shelor, Julius C. Duque

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

cpanm Digest::SHA

perl -MCPAN -e shell
install Digest::SHA