Digest::SHA - Perl extension for Bitwise SHA-1/256/384/512
# Direct computation use Digest::SHA qw(sha1hex sha1base64 sha256hex sha256base64 sha384hex sha384base64 sha512hex sha512base64); $digest = sha1hex($data, $data_length_in_bits); $digest = sha1base64($data, $data_length_in_bits); # Iterative computation use Digest::SHA qw(shaopen shawrite shafinish shaclose shahex shabase64 shadup); $state = shaopen($alg); # $alg = 1, 256, 384, or 512 shawrite($data, $data_length_in_bits, $state); shawrite($moredata, $moredata_length_in_bits, $state); shawrite($evenmoredata, $evenmoredata_length_in_bits, $state); shafinish($state); $digest = shahex($state); $digest = shabase64($state); shaclose($state);
Digest::SHA provides a Perl interface to all algorithms defined in the NIST Secure Hash Standard (FIPS PUB 180-2). 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.
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 iteratively 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 = ("hello", " ", "world"); my $all_at_once = sha256hex($data, 8*length($data)); my $state = shaopen(256); for (@frags) { shawrite($_, 8*length($_), $state); } shafinish($state); my $in_stages = shahex($state); print $all_at_once eq $in_stages ? "whew!\n" : "career in aluminum siding\n";
Note that the second argument of "shahex()" and "sha256hex()" is multiplied by 8. This is because the second argument reflects a bit count, not a byte count.
Calculating the digest value of a bit-string is equally straightforward. 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);
None by default.
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 have access to the SHA-384 and SHA-512 routines, which require 64-bit operations.
Direct Functions
sha1hex($data, $data_length_in_bits)
Returns the SHA-1 digest of $data, encoded as a 40-character hexadecimal string.
sha1base64($data, $data_length_in_bits)
Returns the SHA-1 digest of $data, encoded as a Base64 string.
sha256hex($data, $data_length_in_bits)
Returns the SHA-256 digest of $data, encoded as a 64-character hexadecimal string.
sha256base64($data, $data_length_in_bits)
Returns the SHA-256 digest of $data, encoded as a Base64 string.
sha384hex($data, $data_length_in_bits)
Returns the SHA-384 digest of $data, encoded as a 96-character hexadecimal string. This function will be undefined if your C compiler lacks support for 64-bit integral types.
sha384base64($data, $data_length_in_bits)
Returns the SHA-384 digest of $data, encoded as a Base64 string. This function will be undefined if your C compiler lacks support for 64-bit integral types.
sha512hex($data, $data_length_in_bits)
Returns the SHA-512 digest of $data, encoded as a 128-character hexadecimal string. This function will be undefined if your C compiler lacks support for 64-bit integral types.
sha512base64($data, $data_length_in_bits)
Returns the SHA-512 digest of $data, encoded as a Base64 string. This function will be undefined if your C compiler lacks support for 64-bit integral types.
Iterative Functions
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, $data_length_in_bits, $state)
Updates the SHA state by feeding in $data. This function is called repeatedly until all data has been processed. The value of $data_length_in_bits 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)
Makes a copy of the current state, and returns a handle to that copy. This is useful in speeding up SHA calculations for data sets that share identical headers. See the "gillogly.hard" script in the "t/" subdirectory for an example of how "shadup()" can improve performance for such data sets.
shaclose($state)
Frees all memory associated the SHA calculation initiated with the corresponding "shaopen()" call.
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
Mark Shelor, <mshelor@comcast.net>
Copyright (C) 2003 by Mark Shelor
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
2 POD Errors
The following errors were encountered while parsing the POD:
You can't have =items (as at line 143) unless the first thing after the =over is an =item
You forgot a '=back' before '=head1'
To install Digest::SHA, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Digest::SHA
CPAN shell
perl -MCPAN -e shell install Digest::SHA
For more information on module installation, please visit the detailed CPAN module installation guide.