Blame lib/Digest/SHA.pm

Packit fa4fcc
package Digest::SHA;
Packit fa4fcc
Packit fa4fcc
require 5.003000;
Packit fa4fcc
Packit fa4fcc
use strict;
Packit fa4fcc
use warnings;
Packit fa4fcc
use vars qw($VERSION @ISA @EXPORT_OK $errmsg);
Packit fa4fcc
use Fcntl qw(O_RDONLY O_RDWR);
Packit fa4fcc
use integer;
Packit fa4fcc
Packit fa4fcc
$VERSION = '6.02';
Packit fa4fcc
Packit fa4fcc
require Exporter;
Packit fa4fcc
@ISA = qw(Exporter);
Packit fa4fcc
@EXPORT_OK = qw(
Packit fa4fcc
	$errmsg
Packit fa4fcc
	hmac_sha1	hmac_sha1_base64	hmac_sha1_hex
Packit fa4fcc
	hmac_sha224	hmac_sha224_base64	hmac_sha224_hex
Packit fa4fcc
	hmac_sha256	hmac_sha256_base64	hmac_sha256_hex
Packit fa4fcc
	hmac_sha384	hmac_sha384_base64	hmac_sha384_hex
Packit fa4fcc
	hmac_sha512	hmac_sha512_base64	hmac_sha512_hex
Packit fa4fcc
	hmac_sha512224	hmac_sha512224_base64	hmac_sha512224_hex
Packit fa4fcc
	hmac_sha512256	hmac_sha512256_base64	hmac_sha512256_hex
Packit fa4fcc
	sha1		sha1_base64		sha1_hex
Packit fa4fcc
	sha224		sha224_base64		sha224_hex
Packit fa4fcc
	sha256		sha256_base64		sha256_hex
Packit fa4fcc
	sha384		sha384_base64		sha384_hex
Packit fa4fcc
	sha512		sha512_base64		sha512_hex
Packit fa4fcc
	sha512224	sha512224_base64	sha512224_hex
Packit fa4fcc
	sha512256	sha512256_base64	sha512256_hex);
Packit fa4fcc
Packit fa4fcc
# Inherit from Digest::base if possible
Packit fa4fcc
Packit fa4fcc
eval {
Packit fa4fcc
	require Digest::base;
Packit fa4fcc
	push(@ISA, 'Digest::base');
Packit fa4fcc
};
Packit fa4fcc
Packit fa4fcc
# The following routines aren't time-critical, so they can be left in Perl
Packit fa4fcc
Packit fa4fcc
sub new {
Packit fa4fcc
	my($class, $alg) = @_;
Packit fa4fcc
	$alg =~ s/\D+//g if defined $alg;
Packit fa4fcc
	if (ref($class)) {	# instance method
Packit fa4fcc
		if (!defined($alg) || ($alg == $class->algorithm)) {
Packit fa4fcc
			sharewind($class);
Packit fa4fcc
			return($class);
Packit fa4fcc
		}
Packit fa4fcc
		return shainit($class, $alg) ? $class : undef;
Packit fa4fcc
	}
Packit fa4fcc
	$alg = 1 unless defined $alg;
Packit fa4fcc
	return $class->newSHA($alg);
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
BEGIN { *reset = \&new }
Packit fa4fcc
Packit fa4fcc
sub add_bits {
Packit fa4fcc
	my($self, $data, $nbits) = @_;
Packit fa4fcc
	unless (defined $nbits) {
Packit fa4fcc
		$nbits = length($data);
Packit fa4fcc
		$data = pack("B*", $data);
Packit fa4fcc
	}
Packit fa4fcc
	$nbits = length($data) * 8 if $nbits > length($data) * 8;
Packit fa4fcc
	shawrite($data, $nbits, $self);
Packit fa4fcc
	return($self);
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
sub _bail {
Packit fa4fcc
	my $msg = shift;
Packit fa4fcc
Packit fa4fcc
	$errmsg = $!;
Packit fa4fcc
	$msg .= ": $!";
Packit fa4fcc
	require Carp;
Packit fa4fcc
	Carp::croak($msg);
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
{
Packit fa4fcc
	my $_can_T_filehandle;
Packit fa4fcc
Packit fa4fcc
	sub _istext {
Packit fa4fcc
		local *FH = shift;
Packit fa4fcc
		my $file = shift;
Packit fa4fcc
Packit fa4fcc
		if (! defined $_can_T_filehandle) {
Packit fa4fcc
			local $^W = 0;
Packit fa4fcc
			my $istext = eval { -T FH };
Packit fa4fcc
			$_can_T_filehandle = $@ ? 0 : 1;
Packit fa4fcc
			return $_can_T_filehandle ? $istext : -T $file;
Packit fa4fcc
		}
Packit fa4fcc
		return $_can_T_filehandle ? -T FH : -T $file;
Packit fa4fcc
	}
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
sub _addfile {
Packit fa4fcc
	my ($self, $handle) = @_;
Packit fa4fcc
Packit fa4fcc
	my $n;
Packit fa4fcc
	my $buf = "";
Packit fa4fcc
Packit fa4fcc
	while (($n = read($handle, $buf, 4096))) {
Packit fa4fcc
		$self->add($buf);
Packit fa4fcc
	}
Packit fa4fcc
	_bail("Read failed") unless defined $n;
Packit fa4fcc
Packit fa4fcc
	$self;
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
sub addfile {
Packit fa4fcc
	my ($self, $file, $mode) = @_;
Packit fa4fcc
Packit fa4fcc
	return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR';
Packit fa4fcc
Packit fa4fcc
	$mode = defined($mode) ? $mode : "";
Packit fa4fcc
	my ($binary, $UNIVERSAL, $BITS) =
Packit fa4fcc
		map { $_ eq $mode } ("b", "U", "0");
Packit fa4fcc
Packit fa4fcc
		## Always interpret "-" to mean STDIN; otherwise use
Packit fa4fcc
		##	sysopen to handle full range of POSIX file names.
Packit fa4fcc
		## If $file is a directory, force an EISDIR error
Packit fa4fcc
		##	by attempting to open with mode O_RDWR
Packit fa4fcc
Packit fa4fcc
	local *FH;
Packit fa4fcc
	$file eq '-' and open(FH, '< -')
Packit fa4fcc
		or sysopen(FH, $file, -d $file ? O_RDWR : O_RDONLY)
Packit fa4fcc
			or _bail('Open failed');
Packit fa4fcc
Packit fa4fcc
	if ($BITS) {
Packit fa4fcc
		my ($n, $buf) = (0, "");
Packit fa4fcc
		while (($n = read(FH, $buf, 4096))) {
Packit fa4fcc
			$buf =~ tr/01//cd;
Packit fa4fcc
			$self->add_bits($buf);
Packit fa4fcc
		}
Packit fa4fcc
		_bail("Read failed") unless defined $n;
Packit fa4fcc
		close(FH);
Packit fa4fcc
		return($self);
Packit fa4fcc
	}
Packit fa4fcc
Packit fa4fcc
	binmode(FH) if $binary || $UNIVERSAL;
Packit fa4fcc
	if ($UNIVERSAL && _istext(*FH, $file)) {
Packit fa4fcc
		$self->_addfileuniv(*FH);
Packit fa4fcc
	}
Packit fa4fcc
	else { $self->_addfilebin(*FH) }
Packit fa4fcc
	close(FH);
Packit fa4fcc
Packit fa4fcc
	$self;
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
sub getstate {
Packit fa4fcc
	my $self = shift;
Packit fa4fcc
Packit fa4fcc
	my $alg = $self->algorithm or return;
Packit fa4fcc
	my $state = $self->_getstate or return;
Packit fa4fcc
	my $nD = $alg <= 256 ?  8 :  16;
Packit fa4fcc
	my $nH = $alg <= 256 ? 32 :  64;
Packit fa4fcc
	my $nB = $alg <= 256 ? 64 : 128;
Packit fa4fcc
	my($H, $block, $blockcnt, $lenhh, $lenhl, $lenlh, $lenll) =
Packit fa4fcc
		$state =~ /^(.{$nH})(.{$nB})(.{4})(.{4})(.{4})(.{4})(.{4})$/s;
Packit fa4fcc
	for ($alg, $H, $block, $blockcnt, $lenhh, $lenhl, $lenlh, $lenll) {
Packit fa4fcc
		return unless defined $_;
Packit fa4fcc
	}
Packit fa4fcc
Packit fa4fcc
	my @s = ();
Packit fa4fcc
	push(@s, "alg:" . $alg);
Packit fa4fcc
	push(@s, "H:" . join(":", unpack("H*", $H) =~ /.{$nD}/g));
Packit fa4fcc
	push(@s, "block:" . join(":", unpack("H*", $block) =~ /.{2}/g));
Packit fa4fcc
	push(@s, "blockcnt:" . unpack("N", $blockcnt));
Packit fa4fcc
	push(@s, "lenhh:" . unpack("N", $lenhh));
Packit fa4fcc
	push(@s, "lenhl:" . unpack("N", $lenhl));
Packit fa4fcc
	push(@s, "lenlh:" . unpack("N", $lenlh));
Packit fa4fcc
	push(@s, "lenll:" . unpack("N", $lenll));
Packit fa4fcc
	join("\n", @s) . "\n";
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
sub putstate {
Packit fa4fcc
	my($class, $state) = @_;
Packit fa4fcc
Packit fa4fcc
	my %s = ();
Packit fa4fcc
	for (split(/\n/, $state)) {
Packit fa4fcc
		s/^\s+//;
Packit fa4fcc
		s/\s+$//;
Packit fa4fcc
		next if (/^(#|$)/);
Packit fa4fcc
		my @f = split(/[:\s]+/);
Packit fa4fcc
		my $tag = shift(@f);
Packit fa4fcc
		$s{$tag} = join('', @f);
Packit fa4fcc
	}
Packit fa4fcc
Packit fa4fcc
	# H and block may contain arbitrary values, but check everything else
Packit fa4fcc
	grep { $_ == $s{'alg'} } (1,224,256,384,512,512224,512256) or return;
Packit fa4fcc
	length($s{'H'}) == ($s{'alg'} <= 256 ? 64 : 128) or return;
Packit fa4fcc
	length($s{'block'}) == ($s{'alg'} <= 256 ? 128 : 256) or return;
Packit fa4fcc
	{
Packit fa4fcc
		no integer;
Packit fa4fcc
		for (qw(blockcnt lenhh lenhl lenlh lenll)) {
Packit fa4fcc
			0 <= $s{$_} or return;
Packit fa4fcc
			$s{$_} <= 4294967295 or return;
Packit fa4fcc
		}
Packit fa4fcc
		$s{'blockcnt'} < ($s{'alg'} <= 256 ? 512 : 1024) or return;
Packit fa4fcc
	}
Packit fa4fcc
Packit fa4fcc
	my $packed_state = (
Packit fa4fcc
		pack("H*", $s{'H'}) .
Packit fa4fcc
		pack("H*", $s{'block'}) .
Packit fa4fcc
		pack("N",  $s{'blockcnt'}) .
Packit fa4fcc
		pack("N",  $s{'lenhh'}) .
Packit fa4fcc
		pack("N",  $s{'lenhl'}) .
Packit fa4fcc
		pack("N",  $s{'lenlh'}) .
Packit fa4fcc
		pack("N",  $s{'lenll'})
Packit fa4fcc
	);
Packit fa4fcc
Packit fa4fcc
	return $class->new($s{'alg'})->_putstate($packed_state);
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
sub dump {
Packit fa4fcc
	my $self = shift;
Packit fa4fcc
	my $file = shift;
Packit fa4fcc
Packit fa4fcc
	my $state = $self->getstate or return;
Packit fa4fcc
	$file = "-" if (!defined($file) || $file eq "");
Packit fa4fcc
Packit fa4fcc
	local *FH;
Packit fa4fcc
	open(FH, "> $file") or return;
Packit fa4fcc
	print FH $state;
Packit fa4fcc
	close(FH);
Packit fa4fcc
Packit fa4fcc
	return($self);
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
sub load {
Packit fa4fcc
	my $class = shift;
Packit fa4fcc
	my $file = shift;
Packit fa4fcc
Packit fa4fcc
	$file = "-" if (!defined($file) || $file eq "");
Packit fa4fcc
Packit fa4fcc
	local *FH;
Packit fa4fcc
	open(FH, "< $file") or return;
Packit fa4fcc
	my $str = join('', <FH>);
Packit fa4fcc
	close(FH);
Packit fa4fcc
Packit fa4fcc
	$class->putstate($str);
Packit fa4fcc
}
Packit fa4fcc
Packit fa4fcc
eval {
Packit fa4fcc
	require XSLoader;
Packit fa4fcc
	XSLoader::load('Digest::SHA', $VERSION);
Packit fa4fcc
	1;
Packit fa4fcc
} or do {
Packit fa4fcc
	require DynaLoader;
Packit fa4fcc
	push @ISA, 'DynaLoader';
Packit fa4fcc
	Digest::SHA->bootstrap($VERSION);
Packit fa4fcc
};
Packit fa4fcc
Packit fa4fcc
1;
Packit fa4fcc
__END__
Packit fa4fcc
Packit fa4fcc
=head1 NAME
Packit fa4fcc
Packit fa4fcc
Digest::SHA - Perl extension for SHA-1/224/256/384/512
Packit fa4fcc
Packit fa4fcc
=head1 SYNOPSIS
Packit fa4fcc
Packit fa4fcc
In programs:
Packit fa4fcc
Packit fa4fcc
		# Functional interface
Packit fa4fcc
Packit fa4fcc
	use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
Packit fa4fcc
Packit fa4fcc
	$digest = sha1($data);
Packit fa4fcc
	$digest = sha1_hex($data);
Packit fa4fcc
	$digest = sha1_base64($data);
Packit fa4fcc
Packit fa4fcc
	$digest = sha256($data);
Packit fa4fcc
	$digest = sha384_hex($data);
Packit fa4fcc
	$digest = sha512_base64($data);
Packit fa4fcc
Packit fa4fcc
		# Object-oriented
Packit fa4fcc
Packit fa4fcc
	use Digest::SHA;
Packit fa4fcc
Packit fa4fcc
	$sha = Digest::SHA->new($alg);
Packit fa4fcc
Packit fa4fcc
	$sha->add($data);		# feed data into stream
Packit fa4fcc
Packit fa4fcc
	$sha->addfile(*F);
Packit fa4fcc
	$sha->addfile($filename);
Packit fa4fcc
Packit fa4fcc
	$sha->add_bits($bits);
Packit fa4fcc
	$sha->add_bits($data, $nbits);
Packit fa4fcc
Packit fa4fcc
	$sha_copy = $sha->clone;	# make copy of digest object
Packit fa4fcc
	$state = $sha->getstate;	# save current state to string
Packit fa4fcc
	$sha->putstate($state);		# restore previous $state
Packit fa4fcc
Packit fa4fcc
	$digest = $sha->digest;		# compute digest
Packit fa4fcc
	$digest = $sha->hexdigest;
Packit fa4fcc
	$digest = $sha->b64digest;
Packit fa4fcc
Packit fa4fcc
From the command line:
Packit fa4fcc
Packit fa4fcc
	$ shasum files
Packit fa4fcc
Packit fa4fcc
	$ shasum --help
Packit fa4fcc
Packit fa4fcc
=head1 SYNOPSIS (HMAC-SHA)
Packit fa4fcc
Packit fa4fcc
		# Functional interface only
Packit fa4fcc
Packit fa4fcc
	use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
Packit fa4fcc
Packit fa4fcc
	$digest = hmac_sha1($data, $key);
Packit fa4fcc
	$digest = hmac_sha224_hex($data, $key);
Packit fa4fcc
	$digest = hmac_sha256_base64($data, $key);
Packit fa4fcc
Packit fa4fcc
=head1 ABSTRACT
Packit fa4fcc
Packit fa4fcc
Digest::SHA is a complete implementation of the NIST Secure Hash Standard.
Packit fa4fcc
It gives Perl programmers a convenient way to calculate SHA-1, SHA-224,
Packit fa4fcc
SHA-256, SHA-384, SHA-512, SHA-512/224, and SHA-512/256 message digests.
Packit fa4fcc
The module can handle all types of input, including partial-byte data.
Packit fa4fcc
Packit fa4fcc
=head1 DESCRIPTION
Packit fa4fcc
Packit fa4fcc
Digest::SHA is written in C for speed.  If your platform lacks a
Packit fa4fcc
C compiler, you can install the functionally equivalent (but much
Packit fa4fcc
slower) L<Digest::SHA::PurePerl> module.
Packit fa4fcc
Packit fa4fcc
The programming interface is easy to use: it's the same one found
Packit fa4fcc
in CPAN's L<Digest> module.  So, if your applications currently
Packit fa4fcc
use L<Digest::MD5> and you'd prefer the stronger security of SHA,
Packit fa4fcc
it's a simple matter to convert them.
Packit fa4fcc
Packit fa4fcc
The interface provides two ways to calculate digests:  all-at-once,
Packit fa4fcc
or in stages.  To illustrate, the following short program computes
Packit fa4fcc
the SHA-256 digest of "hello world" using each approach:
Packit fa4fcc
Packit fa4fcc
	use Digest::SHA qw(sha256_hex);
Packit fa4fcc
Packit fa4fcc
	$data = "hello world";
Packit fa4fcc
	@frags = split(//, $data);
Packit fa4fcc
Packit fa4fcc
	# all-at-once (Functional style)
Packit fa4fcc
	$digest1 = sha256_hex($data);
Packit fa4fcc
Packit fa4fcc
	# in-stages (OOP style)
Packit fa4fcc
	$state = Digest::SHA->new(256);
Packit fa4fcc
	for (@frags) { $state->add($_) }
Packit fa4fcc
	$digest2 = $state->hexdigest;
Packit fa4fcc
Packit fa4fcc
	print $digest1 eq $digest2 ?
Packit fa4fcc
		"whew!\n" : "oops!\n";
Packit fa4fcc
Packit fa4fcc
To calculate the digest of an n-bit message where I<n> is not a
Packit fa4fcc
multiple of 8, use the I<add_bits()> method.  For example, consider
Packit fa4fcc
the 446-bit message consisting of the bit-string "110" repeated
Packit fa4fcc
148 times, followed by "11".  Here's how to display its SHA-1
Packit fa4fcc
digest:
Packit fa4fcc
Packit fa4fcc
	use Digest::SHA;
Packit fa4fcc
	$bits = "110" x 148 . "11";
Packit fa4fcc
	$sha = Digest::SHA->new(1)->add_bits($bits);
Packit fa4fcc
	print $sha->hexdigest, "\n";
Packit fa4fcc
Packit fa4fcc
Note that for larger bit-strings, it's more efficient to use the
Packit fa4fcc
two-argument version I<add_bits($data, $nbits)>, where I<$data> is
Packit fa4fcc
in the customary packed binary format used for Perl strings.
Packit fa4fcc
Packit fa4fcc
The module also lets you save intermediate SHA states to a string.  The
Packit fa4fcc
I<getstate()> method generates portable, human-readable text describing
Packit fa4fcc
the current state of computation.  You can subsequently restore that
Packit fa4fcc
state with I<putstate()> to resume where the calculation left off.
Packit fa4fcc
Packit fa4fcc
To see what a state description looks like, just run the following:
Packit fa4fcc
Packit fa4fcc
	use Digest::SHA;
Packit fa4fcc
	print Digest::SHA->new->add("Shaw" x 1962)->getstate;
Packit fa4fcc
Packit fa4fcc
As an added convenience, the Digest::SHA module offers routines to
Packit fa4fcc
calculate keyed hashes using the HMAC-SHA-1/224/256/384/512
Packit fa4fcc
algorithms.  These services exist in functional form only, and
Packit fa4fcc
mimic the style and behavior of the I<sha()>, I<sha_hex()>, and
Packit fa4fcc
I<sha_base64()> functions.
Packit fa4fcc
Packit fa4fcc
	# Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt
Packit fa4fcc
Packit fa4fcc
	use Digest::SHA qw(hmac_sha256_hex);
Packit fa4fcc
	print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
Packit fa4fcc
Packit fa4fcc
=head1 UNICODE AND SIDE EFFECTS
Packit fa4fcc
Packit fa4fcc
Perl supports Unicode strings as of version 5.6.  Such strings may
Packit fa4fcc
contain wide characters, namely, characters whose ordinal values are
Packit fa4fcc
greater than 255.  This can cause problems for digest algorithms such
Packit fa4fcc
as SHA that are specified to operate on sequences of bytes.
Packit fa4fcc
Packit fa4fcc
The rule by which Digest::SHA handles a Unicode string is easy
Packit fa4fcc
to state, but potentially confusing to grasp: the string is interpreted
Packit fa4fcc
as a sequence of byte values, where each byte value is equal to the
Packit fa4fcc
ordinal value (viz. code point) of its corresponding Unicode character.
Packit fa4fcc
That way, the Unicode string 'abc' has exactly the same digest value as
Packit fa4fcc
the ordinary string 'abc'.
Packit fa4fcc
Packit fa4fcc
Since a wide character does not fit into a byte, the Digest::SHA
Packit fa4fcc
routines croak if they encounter one.  Whereas if a Unicode string
Packit fa4fcc
contains no wide characters, the module accepts it quite happily.
Packit fa4fcc
The following code illustrates the two cases:
Packit fa4fcc
Packit fa4fcc
	$str1 = pack('U*', (0..255));
Packit fa4fcc
	print sha1_hex($str1);		# ok
Packit fa4fcc
Packit fa4fcc
	$str2 = pack('U*', (0..256));
Packit fa4fcc
	print sha1_hex($str2);		# croaks
Packit fa4fcc
Packit fa4fcc
Be aware that the digest routines silently convert UTF-8 input into its
Packit fa4fcc
equivalent byte sequence in the native encoding (cf. utf8::downgrade).
Packit fa4fcc
This side effect influences only the way Perl stores the data internally,
Packit fa4fcc
but otherwise leaves the actual value of the data intact.
Packit fa4fcc
Packit fa4fcc
=head1 NIST STATEMENT ON SHA-1
Packit fa4fcc
Packit fa4fcc
NIST acknowledges that the work of Prof. Xiaoyun Wang constitutes a
Packit fa4fcc
practical collision attack on SHA-1.  Therefore, NIST encourages the
Packit fa4fcc
rapid adoption of the SHA-2 hash functions (e.g. SHA-256) for applications
Packit fa4fcc
requiring strong collision resistance, such as digital signatures.
Packit fa4fcc
Packit fa4fcc
ref. L<http://csrc.nist.gov/groups/ST/hash/statement.html>
Packit fa4fcc
Packit fa4fcc
=head1 PADDING OF BASE64 DIGESTS
Packit fa4fcc
Packit fa4fcc
By convention, CPAN Digest modules do B<not> pad their Base64 output.
Packit fa4fcc
Problems can occur when feeding such digests to other software that
Packit fa4fcc
expects properly padded Base64 encodings.
Packit fa4fcc
Packit fa4fcc
For the time being, any necessary padding must be done by the user.
Packit fa4fcc
Fortunately, this is a simple operation: if the length of a Base64-encoded
Packit fa4fcc
digest isn't a multiple of 4, simply append "=" characters to the end
Packit fa4fcc
of the digest until it is:
Packit fa4fcc
Packit fa4fcc
	while (length($b64_digest) % 4) {
Packit fa4fcc
		$b64_digest .= '=';
Packit fa4fcc
	}
Packit fa4fcc
Packit fa4fcc
To illustrate, I<sha256_base64("abc")> is computed to be
Packit fa4fcc
Packit fa4fcc
	ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
Packit fa4fcc
Packit fa4fcc
which has a length of 43.  So, the properly padded version is
Packit fa4fcc
Packit fa4fcc
	ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
Packit fa4fcc
Packit fa4fcc
=head1 EXPORT
Packit fa4fcc
Packit fa4fcc
None by default.
Packit fa4fcc
Packit fa4fcc
=head1 EXPORTABLE FUNCTIONS
Packit fa4fcc
Packit fa4fcc
Provided your C compiler supports a 64-bit type (e.g. the I
Packit fa4fcc
long> of C99, or I<__int64> used by Microsoft C/C++), all of these
Packit fa4fcc
functions will be available for use.  Otherwise, you won't be able
Packit fa4fcc
to perform the SHA-384 and SHA-512 transforms, both of which require
Packit fa4fcc
64-bit operations.
Packit fa4fcc
Packit fa4fcc
I<Functional style>
Packit fa4fcc
Packit fa4fcc
=over 4
Packit fa4fcc
Packit fa4fcc
=item B<sha1($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha224($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha256($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha384($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha512($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha512224($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha512256($data, ...)>
Packit fa4fcc
Packit fa4fcc
Logically joins the arguments into a single string, and returns
Packit fa4fcc
its SHA-1/224/256/384/512 digest encoded as a binary string.
Packit fa4fcc
Packit fa4fcc
=item B<sha1_hex($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha224_hex($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha256_hex($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha384_hex($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha512_hex($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha512224_hex($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha512256_hex($data, ...)>
Packit fa4fcc
Packit fa4fcc
Logically joins the arguments into a single string, and returns
Packit fa4fcc
its SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
Packit fa4fcc
Packit fa4fcc
=item B<sha1_base64($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha224_base64($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha256_base64($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha384_base64($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha512_base64($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha512224_base64($data, ...)>
Packit fa4fcc
Packit fa4fcc
=item B<sha512256_base64($data, ...)>
Packit fa4fcc
Packit fa4fcc
Logically joins the arguments into a single string, and returns
Packit fa4fcc
its SHA-1/224/256/384/512 digest encoded as a Base64 string.
Packit fa4fcc
Packit fa4fcc
It's important to note that the resulting string does B<not> contain
Packit fa4fcc
the padding characters typical of Base64 encodings.  This omission is
Packit fa4fcc
deliberate, and is done to maintain compatibility with the family of
Packit fa4fcc
CPAN Digest modules.  See L</"PADDING OF BASE64 DIGESTS"> for details.
Packit fa4fcc
Packit fa4fcc
=back
Packit fa4fcc
Packit fa4fcc
I<OOP style>
Packit fa4fcc
Packit fa4fcc
=over 4
Packit fa4fcc
Packit fa4fcc
=item B<new($alg)>
Packit fa4fcc
Packit fa4fcc
Returns a new Digest::SHA object.  Allowed values for I<$alg> are 1,
Packit fa4fcc
224, 256, 384, 512, 512224, or 512256.  It's also possible to use
Packit fa4fcc
common string representations of the algorithm (e.g. "sha256",
Packit fa4fcc
"SHA-384").  If the argument is missing, SHA-1 will be used by
Packit fa4fcc
default.
Packit fa4fcc
Packit fa4fcc
Invoking I<new> as an instance method will reset the object to the
Packit fa4fcc
initial state associated with I<$alg>.  If the argument is missing,
Packit fa4fcc
the object will continue using the same algorithm that was selected
Packit fa4fcc
at creation.
Packit fa4fcc
Packit fa4fcc
=item B<reset($alg)>
Packit fa4fcc
Packit fa4fcc
This method has exactly the same effect as I<new($alg)>.  In fact,
Packit fa4fcc
I<reset> is just an alias for I<new>.
Packit fa4fcc
Packit fa4fcc
=item B<hashsize>
Packit fa4fcc
Packit fa4fcc
Returns the number of digest bits for this object.  The values are
Packit fa4fcc
160, 224, 256, 384, 512, 224, and 256 for SHA-1, SHA-224, SHA-256,
Packit fa4fcc
SHA-384, SHA-512, SHA-512/224 and SHA-512/256, respectively.
Packit fa4fcc
Packit fa4fcc
=item B<algorithm>
Packit fa4fcc
Packit fa4fcc
Returns the digest algorithm for this object.  The values are 1,
Packit fa4fcc
224, 256, 384, 512, 512224, and 512256 for SHA-1, SHA-224, SHA-256,
Packit fa4fcc
SHA-384, SHA-512, SHA-512/224, and SHA-512/256, respectively.
Packit fa4fcc
Packit fa4fcc
=item B<clone>
Packit fa4fcc
Packit fa4fcc
Returns a duplicate copy of the object.
Packit fa4fcc
Packit fa4fcc
=item B<add($data, ...)>
Packit fa4fcc
Packit fa4fcc
Logically joins the arguments into a single string, and uses it to
Packit fa4fcc
update the current digest state.  In other words, the following
Packit fa4fcc
statements have the same effect:
Packit fa4fcc
Packit fa4fcc
	$sha->add("a"); $sha->add("b"); $sha->add("c");
Packit fa4fcc
	$sha->add("a")->add("b")->add("c");
Packit fa4fcc
	$sha->add("a", "b", "c");
Packit fa4fcc
	$sha->add("abc");
Packit fa4fcc
Packit fa4fcc
The return value is the updated object itself.
Packit fa4fcc
Packit fa4fcc
=item B<add_bits($data, $nbits)>
Packit fa4fcc
Packit fa4fcc
=item B<add_bits($bits)>
Packit fa4fcc
Packit fa4fcc
Updates the current digest state by appending bits to it.  The
Packit fa4fcc
return value is the updated object itself.
Packit fa4fcc
Packit fa4fcc
The first form causes the most-significant I<$nbits> of I<$data>
Packit fa4fcc
to be appended to the stream.  The I<$data> argument is in the
Packit fa4fcc
customary binary format used for Perl strings.
Packit fa4fcc
Packit fa4fcc
The second form takes an ASCII string of "0" and "1" characters as
Packit fa4fcc
its argument.  It's equivalent to
Packit fa4fcc
Packit fa4fcc
	$sha->add_bits(pack("B*", $bits), length($bits));
Packit fa4fcc
Packit fa4fcc
So, the following two statements do the same thing:
Packit fa4fcc
Packit fa4fcc
	$sha->add_bits("111100001010");
Packit fa4fcc
	$sha->add_bits("\xF0\xA0", 12);
Packit fa4fcc
Packit fa4fcc
Note that SHA-1 and SHA-2 use I<most-significant-bit ordering>
Packit fa4fcc
for their internal state.  This means that
Packit fa4fcc
Packit fa4fcc
	$sha3->add_bits("110");
Packit fa4fcc
Packit fa4fcc
is equivalent to
Packit fa4fcc
Packit fa4fcc
	$sha3->add_bits("1")->add_bits("1")->add_bits("0");
Packit fa4fcc
Packit fa4fcc
=item B<addfile(*FILE)>
Packit fa4fcc
Packit fa4fcc
Reads from I<FILE> until EOF, and appends that data to the current
Packit fa4fcc
state.  The return value is the updated object itself.
Packit fa4fcc
Packit fa4fcc
=item B<addfile($filename [, $mode])>
Packit fa4fcc
Packit fa4fcc
Reads the contents of I<$filename>, and appends that data to the current
Packit fa4fcc
state.  The return value is the updated object itself.
Packit fa4fcc
Packit fa4fcc
By default, I<$filename> is simply opened and read; no special modes
Packit fa4fcc
or I/O disciplines are used.  To change this, set the optional I<$mode>
Packit fa4fcc
argument to one of the following values:
Packit fa4fcc
Packit fa4fcc
	"b"	read file in binary mode
Packit fa4fcc
Packit fa4fcc
	"U"	use universal newlines
Packit fa4fcc
Packit fa4fcc
	"0"	use BITS mode
Packit fa4fcc
Packit fa4fcc
The "U" mode is modeled on Python's "Universal Newlines" concept, whereby
Packit fa4fcc
DOS and Mac OS line terminators are converted internally to UNIX newlines
Packit fa4fcc
before processing.  This ensures consistent digest values when working
Packit fa4fcc
simultaneously across multiple file systems.  B
Packit fa4fcc
only text files>, namely those passing Perl's I<-T> test; binary files
Packit fa4fcc
are processed with no translation whatsoever.
Packit fa4fcc
Packit fa4fcc
The BITS mode ("0") interprets the contents of I<$filename> as a logical
Packit fa4fcc
stream of bits, where each ASCII '0' or '1' character represents a 0 or
Packit fa4fcc
1 bit, respectively.  All other characters are ignored.  This provides
Packit fa4fcc
a convenient way to calculate the digest values of partial-byte data
Packit fa4fcc
by using files, rather than having to write separate programs employing
Packit fa4fcc
the I<add_bits> method.
Packit fa4fcc
Packit fa4fcc
=item B<getstate>
Packit fa4fcc
Packit fa4fcc
Returns a string containing a portable, human-readable representation
Packit fa4fcc
of the current SHA state.
Packit fa4fcc
Packit fa4fcc
=item B<putstate($str)>
Packit fa4fcc
Packit fa4fcc
Returns a Digest::SHA object representing the SHA state contained
Packit fa4fcc
in I<$str>.  The format of I<$str> matches the format of the output
Packit fa4fcc
produced by method I<getstate>.  If called as a class method, a new
Packit fa4fcc
object is created; if called as an instance method, the object is reset
Packit fa4fcc
to the state contained in I<$str>.
Packit fa4fcc
Packit fa4fcc
=item B<dump($filename)>
Packit fa4fcc
Packit fa4fcc
Writes the output of I<getstate> to I<$filename>.  If the argument is
Packit fa4fcc
missing, or equal to the empty string, the state information will be
Packit fa4fcc
written to STDOUT.
Packit fa4fcc
Packit fa4fcc
=item B<load($filename)>
Packit fa4fcc
Packit fa4fcc
Returns a Digest::SHA object that results from calling I<putstate> on
Packit fa4fcc
the contents of I<$filename>.  If the argument is missing, or equal to
Packit fa4fcc
the empty string, the state information will be read from STDIN.
Packit fa4fcc
Packit fa4fcc
=item B<digest>
Packit fa4fcc
Packit fa4fcc
Returns the digest encoded as a binary string.
Packit fa4fcc
Packit fa4fcc
Note that the I<digest> method is a read-once operation. Once it
Packit fa4fcc
has been performed, the Digest::SHA object is automatically reset
Packit fa4fcc
in preparation for calculating another digest value.  Call
Packit fa4fcc
I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
Packit fa4fcc
original digest state.
Packit fa4fcc
Packit fa4fcc
=item B<hexdigest>
Packit fa4fcc
Packit fa4fcc
Returns the digest encoded as a hexadecimal string.
Packit fa4fcc
Packit fa4fcc
Like I<digest>, this method is a read-once operation.  Call
Packit fa4fcc
I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve
Packit fa4fcc
the original digest state.
Packit fa4fcc
Packit fa4fcc
=item B<b64digest>
Packit fa4fcc
Packit fa4fcc
Returns the digest encoded as a Base64 string.
Packit fa4fcc
Packit fa4fcc
Like I<digest>, this method is a read-once operation.  Call
Packit fa4fcc
I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve
Packit fa4fcc
the original digest state.
Packit fa4fcc
Packit fa4fcc
It's important to note that the resulting string does B<not> contain
Packit fa4fcc
the padding characters typical of Base64 encodings.  This omission is
Packit fa4fcc
deliberate, and is done to maintain compatibility with the family of
Packit fa4fcc
CPAN Digest modules.  See L</"PADDING OF BASE64 DIGESTS"> for details.
Packit fa4fcc
Packit fa4fcc
=back
Packit fa4fcc
Packit fa4fcc
I<HMAC-SHA-1/224/256/384/512>
Packit fa4fcc
Packit fa4fcc
=over 4
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha1($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha224($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha256($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha384($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha512($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha512224($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha512256($data, $key)>
Packit fa4fcc
Packit fa4fcc
Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
Packit fa4fcc
with the result encoded as a binary string.  Multiple I<$data>
Packit fa4fcc
arguments are allowed, provided that I<$key> is the last argument
Packit fa4fcc
in the list.
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha1_hex($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha224_hex($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha256_hex($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha384_hex($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha512_hex($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha512224_hex($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha512256_hex($data, $key)>
Packit fa4fcc
Packit fa4fcc
Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
Packit fa4fcc
with the result encoded as a hexadecimal string.  Multiple I<$data>
Packit fa4fcc
arguments are allowed, provided that I<$key> is the last argument
Packit fa4fcc
in the list.
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha1_base64($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha224_base64($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha256_base64($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha384_base64($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha512_base64($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha512224_base64($data, $key)>
Packit fa4fcc
Packit fa4fcc
=item B<hmac_sha512256_base64($data, $key)>
Packit fa4fcc
Packit fa4fcc
Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
Packit fa4fcc
with the result encoded as a Base64 string.  Multiple I<$data>
Packit fa4fcc
arguments are allowed, provided that I<$key> is the last argument
Packit fa4fcc
in the list.
Packit fa4fcc
Packit fa4fcc
It's important to note that the resulting string does B<not> contain
Packit fa4fcc
the padding characters typical of Base64 encodings.  This omission is
Packit fa4fcc
deliberate, and is done to maintain compatibility with the family of
Packit fa4fcc
CPAN Digest modules.  See L</"PADDING OF BASE64 DIGESTS"> for details.
Packit fa4fcc
Packit fa4fcc
=back
Packit fa4fcc
Packit fa4fcc
=head1 SEE ALSO
Packit fa4fcc
Packit fa4fcc
L<Digest>, L<Digest::SHA::PurePerl>
Packit fa4fcc
Packit fa4fcc
The Secure Hash Standard (Draft FIPS PUB 180-4) can be found at:
Packit fa4fcc
Packit fa4fcc
L<http://csrc.nist.gov/publications/drafts/fips180-4/Draft-FIPS180-4_Feb2011.pdf>
Packit fa4fcc
Packit fa4fcc
The Keyed-Hash Message Authentication Code (HMAC):
Packit fa4fcc
Packit fa4fcc
L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
Packit fa4fcc
Packit fa4fcc
=head1 AUTHOR
Packit fa4fcc
Packit fa4fcc
	Mark Shelor	<mshelor@cpan.org>
Packit fa4fcc
Packit fa4fcc
=head1 ACKNOWLEDGMENTS
Packit fa4fcc
Packit fa4fcc
The author is particularly grateful to
Packit fa4fcc
Packit fa4fcc
	Gisle Aas
Packit fa4fcc
	H. Merijn Brand
Packit fa4fcc
	Sean Burke
Packit fa4fcc
	Chris Carey
Packit fa4fcc
	Alexandr Ciornii
Packit fa4fcc
	Chris David
Packit fa4fcc
	Jim Doble
Packit fa4fcc
	Thomas Drugeon
Packit fa4fcc
	Julius Duque
Packit fa4fcc
	Jeffrey Friedl
Packit fa4fcc
	Robert Gilmour
Packit fa4fcc
	Brian Gladman
Packit fa4fcc
	Jarkko Hietaniemi
Packit fa4fcc
	Adam Kennedy
Packit fa4fcc
	Mark Lawrence
Packit fa4fcc
	Andy Lester
Packit fa4fcc
	Alex Muntada
Packit fa4fcc
	Steve Peters
Packit fa4fcc
	Chris Skiscim
Packit fa4fcc
	Martin Thurn
Packit fa4fcc
	Gunnar Wolf
Packit fa4fcc
	Adam Woodbury
Packit fa4fcc
Packit fa4fcc
"who by trained skill rescued life from such great billows and such thick
Packit fa4fcc
darkness and moored it in so perfect a calm and in so brilliant a light"
Packit fa4fcc
- Lucretius
Packit fa4fcc
Packit fa4fcc
=head1 COPYRIGHT AND LICENSE
Packit fa4fcc
Packit fa4fcc
Copyright (C) 2003-2018 Mark Shelor
Packit fa4fcc
Packit fa4fcc
This library is free software; you can redistribute it and/or modify
Packit fa4fcc
it under the same terms as Perl itself.
Packit fa4fcc
Packit fa4fcc
L<perlartistic>
Packit fa4fcc
Packit fa4fcc
=cut