[p5sagit/p5-mst-13.2.git] / ext / Digest / SHA / SHA.pm

package Digest::SHA;

require 5.003000;

use strict;
use integer;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);

$VERSION = '5.46';

require Exporter;
require DynaLoader;
@ISA = qw(Exporter DynaLoader);
@EXPORT_OK = qw(
	hmac_sha1	hmac_sha1_base64	hmac_sha1_hex
	hmac_sha224	hmac_sha224_base64	hmac_sha224_hex
	hmac_sha256	hmac_sha256_base64	hmac_sha256_hex
	hmac_sha384	hmac_sha384_base64	hmac_sha384_hex
	hmac_sha512	hmac_sha512_base64	hmac_sha512_hex
	sha1		sha1_base64		sha1_hex
	sha224		sha224_base64		sha224_hex
	sha256		sha256_base64		sha256_hex
	sha384		sha384_base64		sha384_hex
	sha512		sha512_base64		sha512_hex);

# If possible, inherit from Digest::base (which depends on MIME::Base64)

*addfile = \&Addfile;

eval {
	require MIME::Base64;
	require Digest::base;
	push(@ISA, 'Digest::base');
};
if ($@) {
	*hexdigest = \&Hexdigest;
	*b64digest = \&B64digest;
}

# The following routines aren't time-critical, so they can be left in Perl

sub new {
	my($class, $alg) = @_;
	$alg =~ s/\D+//g if defined $alg;
	if (ref($class)) {	# instance method
		unless (defined($alg) && ($alg != $class->algorithm)) {
			sharewind($$class);
			return($class);
		}
		shaclose($$class) if $$class;
		$$class = shaopen($alg) || return;
		return($class);
	}
	$alg = 1 unless defined $alg;
	my $state = shaopen($alg) || return;
	my $self = \$state;
	bless($self, $class);
	return($self);
}

sub DESTROY {
	my $self = shift;
	shaclose($$self) if $$self;
}

sub clone {
	my $self = shift;
	my $state = shadup($$self) || return;
	my $copy = \$state;
	bless($copy, ref($self));
	return($copy);
}

*reset = \&new;

sub add_bits {
	my($self, $data, $nbits) = @_;
	unless (defined $nbits) {
		$nbits = length($data);
		$data = pack("B*", $data);
	}
	shawrite($data, $nbits, $$self);
	return($self);
}

sub _bail {
	my $msg = shift;

        require Carp;
        Carp::croak("$msg: $!");
}

sub _addfile {  # this is "addfile" from Digest::base 1.00
    my ($self, $handle) = @_;

    my $n;
    my $buf = "";

    while (($n = read($handle, $buf, 4096))) {
        $self->add($buf);
    }
    _bail("Read failed") unless defined $n;

    $self;
}

sub Addfile {
	my ($self, $file, $mode) = @_;

	return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR';

	$mode = defined($mode) ? $mode : "";
	my ($binary, $portable) = map { $_ eq $mode } ("b", "p");
	my $text = -T $file;

	local *FH;
		# protect any leading or trailing whitespace in $file;
		# otherwise, 2-arg "open" will ignore them
	$file =~ s#^(\s)#./$1#;
	open(FH, "< $file\0") or _bail("Open failed");
	binmode(FH) if $binary || $portable;

	unless ($portable && $text) {
		$self->_addfile(*FH);
		close(FH);
		return($self);
	}

	my ($n1, $n2);
	my ($buf1, $buf2) = ("", "");

	while (($n1 = read(FH, $buf1, 4096))) {
		while (substr($buf1, -1) eq "\015") {
			$n2 = read(FH, $buf2, 4096);
			_bail("Read failed") unless defined $n2;
			last unless $n2;
			$buf1 .= $buf2;
		}
		$buf1 =~ s/\015?\015\012/\012/g; 	# DOS/Windows
		$buf1 =~ s/\015/\012/g;          	# early MacOS
		$self->add($buf1);
	}
	_bail("Read failed") unless defined $n1;
	close(FH);

	$self;
}

sub dump {
	my $self = shift;
	my $file = shift || "";

	shadump($file, $$self) || return;
	return($self);
}

sub load {
	my $class = shift;
	my $file = shift || "";
	if (ref($class)) {	# instance method
		shaclose($$class) if $$class;
		$$class = shaload($file) || return;
		return($class);
	}
	my $state = shaload($file) || return;
	my $self = \$state;
	bless($self, $class);
	return($self);
}

Digest::SHA->bootstrap($VERSION);

1;
__END__

=head1 NAME

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

=head1 SYNOPSIS

In programs:

		# Functional interface

	use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);

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

	$digest = sha256($data);
	$digest = sha384_hex($data);
	$digest = sha512_base64($data);

		# Object-oriented

	use Digest::SHA;

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

	$sha->add($data);		# feed data into stream

	$sha->addfile(*F);
	$sha->addfile($filename);

	$sha->add_bits($bits);
	$sha->add_bits($data, $nbits);

	$sha_copy = $sha->clone;	# if needed, make copy of
	$sha->dump($file);		#	current digest state,
	$sha->load($file);		#	or save it on disk

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

From the command line:

	$ shasum files

	$ shasum --help

=head1 SYNOPSIS (HMAC-SHA)

		# Functional interface only

	use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);

	$digest = hmac_sha1($data, $key);
	$digest = hmac_sha224_hex($data, $key);
	$digest = hmac_sha256_base64($data, $key);

=head1 ABSTRACT

Digest::SHA is a complete implementation of the NIST Secure Hash
Standard.  It gives Perl programmers a convenient way to calculate
SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 message digests.
The module can handle all types of input, including partial-byte
data.

=head1 DESCRIPTION

Digest::SHA is written in C for speed.  If your platform lacks a
C compiler, you can install the functionally equivalent (but much
slower) L<Digest::SHA::PurePerl> module.

The programming interface is easy to use: it's the same one found
in CPAN's L<Digest> module.  So, if your applications currently
use L<Digest::MD5> and you'd prefer the stronger security of SHA,
it's a simple matter to convert them.

The interface provides two ways to calculate digests:  all-at-once,
or in stages.  To illustrate, the following short program computes
the SHA-256 digest of "hello world" using each approach:

	use Digest::SHA qw(sha256_hex);

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

	# all-at-once (Functional style)
	$digest1 = sha256_hex($data);

	# in-stages (OOP style)
	$state = Digest::SHA->new(256);
	for (@frags) { $state->add($_) }
	$digest2 = $state->hexdigest;

	print $digest1 eq $digest2 ?
		"whew!\n" : "oops!\n";

To calculate the digest of an n-bit message where I<n> is not a
multiple of 8, use the I<add_bits()> method.  For example, consider
the 446-bit message consisting of the bit-string "110" repeated
148 times, followed by "11".  Here's how to display its SHA-1
digest:

	use Digest::SHA;
	$bits = "110" x 148 . "11";
	$sha = Digest::SHA->new(1)->add_bits($bits);
	print $sha->hexdigest, "\n";

Note that for larger bit-strings, it's more efficient to use the
two-argument version I<add_bits($data, $nbits)>, where I<$data> is
in the customary packed binary format used for Perl strings.

The module also lets you save intermediate SHA states to disk, or
display them on standard output.  The I<dump()> method generates
portable, human-readable text describing the current state of
computation.  You can subsequently retrieve the file with I<load()>
to resume where the calculation left off.

To see what a state description looks like, just run the following:

	use Digest::SHA;
	Digest::SHA->new->add("Shaw" x 1962)->dump;

As an added convenience, the Digest::SHA module offers routines to
calculate keyed hashes using the HMAC-SHA-1/224/256/384/512
algorithms.  These services exist in functional form only, and
mimic the style and behavior of the I<sha()>, I<sha_hex()>, and
I<sha_base64()> functions.

	# Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt

	use Digest::SHA qw(hmac_sha256_hex);
	print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";

=head1 NIST STATEMENT ON SHA-1

I<NIST was recently informed that researchers had discovered a way
to "break" the current Federal Information Processing Standard SHA-1
algorithm, which has been in effect since 1994. The researchers
have not yet published their complete results, so NIST has not
confirmed these findings. However, the researchers are a reputable
research team with expertise in this area.>

I<Due to advances in computing power, NIST already planned to phase
out SHA-1 in favor of the larger and stronger hash functions (SHA-224,
SHA-256, SHA-384 and SHA-512) by 2010. New developments should use
the larger and stronger hash functions.>

ref. L<http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20Statement/Burr_Mar2005.html>

=head1 PADDING OF BASE64 DIGESTS

By convention, CPAN Digest modules do B<not> pad their Base64 output.
Problems can occur when feeding such digests to other software that
expects properly padded Base64 encodings.

For the time being, any necessary padding must be done by the user.
Fortunately, this is a simple operation: if the length of a Base64-encoded
digest isn't a multiple of 4, simply append "=" characters to the end
of the digest until it is:

	while (length($b64_digest) % 4) {
		$b64_digest .= '=';
	}

To illustrate, I<sha256_base64("abc")> is computed to be

	ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0

which has a length of 43.  So, the properly padded version is

	ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

=head1 EXPORT

None by default.

=head1 EXPORTABLE FUNCTIONS

Provided your C compiler supports a 64-bit type (e.g. the I<long
long> of C99, or I<__int64> used by Microsoft C/C++), all of these
functions will be available for use.  Otherwise, you won't be able
to perform the SHA-384 and SHA-512 transforms, both of which require
64-bit operations.

I<Functional style>

=over 4

=item B<sha1($data, ...)>

=item B<sha224($data, ...)>

=item B<sha256($data, ...)>

=item B<sha384($data, ...)>

=item B<sha512($data, ...)>

Logically joins the arguments into a single string, and returns
its SHA-1/224/256/384/512 digest encoded as a binary string.

=item B<sha1_hex($data, ...)>

=item B<sha224_hex($data, ...)>

=item B<sha256_hex($data, ...)>

=item B<sha384_hex($data, ...)>

=item B<sha512_hex($data, ...)>

Logically joins the arguments into a single string, and returns
its SHA-1/224/256/384/512 digest encoded as a hexadecimal string.

=item B<sha1_base64($data, ...)>

=item B<sha224_base64($data, ...)>

=item B<sha256_base64($data, ...)>

=item B<sha384_base64($data, ...)>

=item B<sha512_base64($data, ...)>

Logically joins the arguments into a single string, and returns
its SHA-1/224/256/384/512 digest encoded as a Base64 string.

It's important to note that the resulting string does B<not> contain
the padding characters typical of Base64 encodings.  This omission is
deliberate, and is done to maintain compatibility with the family of
CPAN Digest modules.  See L</"PADDING OF BASE64 DIGESTS"> for details.

=back

I<OOP style>

=over 4

=item B<new($alg)>

Returns a new Digest::SHA object.  Allowed values for I<$alg> are
1, 224, 256, 384, or 512.  It's also possible to use common string
representations of the algorithm (e.g. "sha256", "SHA-384").  If
the argument is missing, SHA-1 will be used by default.

Invoking I<new> as an instance method will not create a new object;
instead, it will simply reset the object to the initial state
associated with I<$alg>.  If the argument is missing, the object
will continue using the same algorithm that was selected at creation.

=item B<reset($alg)>

This method has exactly the same effect as I<new($alg)>.  In fact,
I<reset> is just an alias for I<new>.

=item B<hashsize>

Returns the number of digest bits for this object.  The values are
160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384,
and SHA-512, respectively.

=item B<algorithm>

Returns the digest algorithm for this object.  The values are 1,
224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and
SHA-512, respectively.

=item B<clone>

Returns a duplicate copy of the object.

=item B<add($data, ...)>

Logically joins the arguments into a single string, and uses it to
update the current 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");

The return value is the updated object itself.

=item B<add_bits($data, $nbits)>

=item B<add_bits($bits)>

Updates the current digest state by appending bits to it.  The
return value is the updated object itself.

The first form causes the most-significant I<$nbits> of I<$data>
to be appended to the stream.  The I<$data> argument is in the
customary binary format used for Perl strings.

The second form takes an ASCII string of "0" and "1" characters as
its argument.  It's equivalent to

	$sha->add_bits(pack("B*", $bits), length($bits));

So, the following two statements do the same thing:

	$sha->add_bits("111100001010");
	$sha->add_bits("\xF0\xA0", 12);

=item B<addfile(*FILE)>

Reads from I<FILE> until EOF, and appends that data to the current
state.  The return value is the updated object itself.

=item B<addfile($filename [, $mode])>

Reads the contents of I<$filename>, and appends that data to the current
state.  The return value is the updated object itself.

By default, I<$filename> is simply opened and read; no special modes
or I/O disciplines are used.  To change this, set the optional I<$mode>
argument to one of the following values:

	"b"	read file in binary mode

	"p"	use portable mode

The "p" mode is handy since it ensures that the digest value of
I<$filename> will be the same when computed on different operating
systems.  It accomplishes this by internally translating all newlines
in text files to UNIX format before calculating the digest; on the other
hand, binary files are read in raw mode with no translation whatsoever.

For a fuller discussion of newline formats, refer to CPAN module
L<File::LocalizeNewlines>.  Its "universal line separator" regex forms
the basis of I<addfile>'s portable mode processing.

=item B<dump($filename)>

Provides persistent storage of intermediate SHA states by writing
a portable, human-readable representation of the current state to
I<$filename>.  If the argument is missing, or equal to the empty
string, the state information will be written to STDOUT.

=item B<load($filename)>

Returns a Digest::SHA object representing the intermediate SHA
state that was previously dumped to I<$filename>.  If called as a
class method, a new object is created; if called as an instance
method, the object is reset to the state contained in I<$filename>.
If the argument is missing, or equal to the empty string, the state
information will be read from STDIN.

=item B<digest>

Returns the digest encoded as a binary string.

Note that the I<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
I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
original digest state.

=item B<hexdigest>

Returns the digest encoded as a hexadecimal string.

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

This method is inherited if L<Digest::base> is installed on your
system.  Otherwise, a functionally equivalent substitute is used.

=item B<b64digest>

Returns the digest encoded as a Base64 string.

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

This method is inherited if L<Digest::base> is installed on your
system.  Otherwise, a functionally equivalent substitute is used.

It's important to note that the resulting string does B<not> contain
the padding characters typical of Base64 encodings.  This omission is
deliberate, and is done to maintain compatibility with the family of
CPAN Digest modules.  See L</"PADDING OF BASE64 DIGESTS"> for details.

=back

I<HMAC-SHA-1/224/256/384/512>

=over 4

=item B<hmac_sha1($data, $key)>

=item B<hmac_sha224($data, $key)>

=item B<hmac_sha256($data, $key)>

=item B<hmac_sha384($data, $key)>

=item B<hmac_sha512($data, $key)>

Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
with the result encoded as a binary string.  Multiple I<$data>
arguments are allowed, provided that I<$key> is the last argument
in the list.

=item B<hmac_sha1_hex($data, $key)>

=item B<hmac_sha224_hex($data, $key)>

=item B<hmac_sha256_hex($data, $key)>

=item B<hmac_sha384_hex($data, $key)>

=item B<hmac_sha512_hex($data, $key)>

Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
with the result encoded as a hexadecimal string.  Multiple I<$data>
arguments are allowed, provided that I<$key> is the last argument
in the list.

=item B<hmac_sha1_base64($data, $key)>

=item B<hmac_sha224_base64($data, $key)>

=item B<hmac_sha256_base64($data, $key)>

=item B<hmac_sha384_base64($data, $key)>

=item B<hmac_sha512_base64($data, $key)>

Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
with the result encoded as a Base64 string.  Multiple I<$data>
arguments are allowed, provided that I<$key> is the last argument
in the list.

It's important to note that the resulting string does B<not> contain
the padding characters typical of Base64 encodings.  This omission is
deliberate, and is done to maintain compatibility with the family of
CPAN Digest modules.  See L</"PADDING OF BASE64 DIGESTS"> for details.

=back

=head1 SEE ALSO

L<Digest>, L<Digest::SHA::PurePerl>

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

L<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>

The Keyed-Hash Message Authentication Code (HMAC):

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

=head1 AUTHOR

	Mark Shelor	<mshelor@cpan.org>

=head1 ACKNOWLEDGMENTS

The author is particularly grateful to

	Gisle Aas
	Chris Carey
	Jim Doble
	Julius Duque
	Jeffrey Friedl
	Robert Gilmour
	Brian Gladman
	Adam Kennedy
	Andy Lester
	Alex Muntada
	Steve Peters
	Chris Skiscim
	Martin Thurn
	Gunnar Wolf
	Adam Woodbury

for their valuable comments and suggestions.

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2003-2008 Mark Shelor

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

L<perlartistic>

=cut
Commit	Line	Data
6bc89f92	1	package Digest::SHA;
6bc89f92	2
747da336	3	require 5.003000;
c7e5c266	4
6bc89f92	5	use strict;
6bc89f92	6	use integer;
747da336	7	use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
6bc89f92	8
0bc2b4f8	9	$VERSION = '5.46';
6bc89f92	10
6bc89f92	11	require Exporter;
747da336	12	require DynaLoader;
	13	@ISA = qw(Exporter DynaLoader);
	14	@EXPORT_OK = qw(
6bc89f92	15	hmac_sha1 hmac_sha1_base64 hmac_sha1_hex
	16	hmac_sha224 hmac_sha224_base64 hmac_sha224_hex
	17	hmac_sha256 hmac_sha256_base64 hmac_sha256_hex
	18	hmac_sha384 hmac_sha384_base64 hmac_sha384_hex
	19	hmac_sha512 hmac_sha512_base64 hmac_sha512_hex
	20	sha1 sha1_base64 sha1_hex
	21	sha224 sha224_base64 sha224_hex
	22	sha256 sha256_base64 sha256_hex
	23	sha384 sha384_base64 sha384_hex
	24	sha512 sha512_base64 sha512_hex);
	25
	26	# If possible, inherit from Digest::base (which depends on MIME::Base64)
	27
c7e5c266	28	*addfile = \&Addfile;
c7e5c266	29
6bc89f92	30	eval {
	31	require MIME::Base64;
	32	require Digest::base;
	33	push(@ISA, 'Digest::base');
	34	};
	35	if ($@) {
6bc89f92	36	*hexdigest = \&Hexdigest;
	37	*b64digest = \&B64digest;
	38	}
	39
6bc89f92	40	# The following routines aren't time-critical, so they can be left in Perl
	41
	42	sub new {
	43	my($class, $alg) = @_;
	44	$alg =~ s/\D+//g if defined $alg;
	45	if (ref($class)) { # instance method
	46	unless (defined($alg) && ($alg != $class->algorithm)) {
	47	sharewind($$class);
	48	return($class);
	49	}
	50	shaclose($$class) if $$class;
	51	$$class = shaopen($alg) \|\| return;
	52	return($class);
	53	}
	54	$alg = 1 unless defined $alg;
	55	my $state = shaopen($alg) \|\| return;
	56	my $self = \$state;
	57	bless($self, $class);
	58	return($self);
	59	}
	60
	61	sub DESTROY {
	62	my $self = shift;
	63	shaclose($$self) if $$self;
	64	}
	65
	66	sub clone {
	67	my $self = shift;
	68	my $state = shadup($$self) \|\| return;
	69	my $copy = \$state;
	70	bless($copy, ref($self));
	71	return($copy);
	72	}
	73
	74	*reset = \&new;
	75
	76	sub add_bits {
	77	my($self, $data, $nbits) = @_;
	78	unless (defined $nbits) {
	79	$nbits = length($data);
	80	$data = pack("B*", $data);
	81	}
	82	shawrite($data, $nbits, $$self);
	83	return($self);
	84	}
	85
c7e5c266	86	sub _bail {
	87	my $msg = shift;
	88
	89	require Carp;
	90	Carp::croak("$msg: $!");
	91	}
6bc89f92	92
c7e5c266	93	sub _addfile { # this is "addfile" from Digest::base 1.00
6bc89f92	94	my ($self, $handle) = @_;
	95
	96	my $n;
	97	my $buf = "";
	98
	99	while (($n = read($handle, $buf, 4096))) {
c7e5c266	100	$self->add($buf);
6bc89f92	101	}
c7e5c266	102	_bail("Read failed") unless defined $n;
6bc89f92	103
	104	$self;
	105	}
	106
c7e5c266	107	sub Addfile {
	108	my ($self, $file, $mode) = @_;
	109
84c0b84e	110	return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR';
c7e5c266	111
	112	$mode = defined($mode) ? $mode : "";
	113	my ($binary, $portable) = map { $_ eq $mode } ("b", "p");
	114	my $text = -T $file;
	115
747da336	116	local *FH;
0bc2b4f8	117	# protect any leading or trailing whitespace in $file;
	118	# otherwise, 2-arg "open" will ignore them
	119	$file =~ s#^(\s)#./$1#;
	120	open(FH, "< $file\0") or _bail("Open failed");
747da336	121	binmode(FH) if $binary \|\| $portable;
c7e5c266	122
c7e5c266	123	unless ($portable && $text) {
747da336	124	$self->_addfile(*FH);
747da336	125	close(FH);
c7e5c266	126	return($self);
	127	}
	128
	129	my ($n1, $n2);
	130	my ($buf1, $buf2) = ("", "");
	131
747da336	132	while (($n1 = read(FH, $buf1, 4096))) {
c7e5c266	133	while (substr($buf1, -1) eq "\015") {
747da336	134	$n2 = read(FH, $buf2, 4096);
c7e5c266	135	_bail("Read failed") unless defined $n2;
	136	last unless $n2;
	137	$buf1 .= $buf2;
	138	}
84c0b84e	139	$buf1 =~ s/\015?\015\012/\012/g; # DOS/Windows
747da336	140	$buf1 =~ s/\015/\012/g; # early MacOS
c7e5c266	141	$self->add($buf1);
	142	}
	143	_bail("Read failed") unless defined $n1;
747da336	144	close(FH);
c7e5c266	145
	146	$self;
	147	}
	148
6bc89f92	149	sub dump {
	150	my $self = shift;
	151	my $file = shift \|\| "";
	152
	153	shadump($file, $$self) \|\| return;
	154	return($self);
	155	}
	156
	157	sub load {
	158	my $class = shift;
	159	my $file = shift \|\| "";
	160	if (ref($class)) { # instance method
	161	shaclose($$class) if $$class;
	162	$$class = shaload($file) \|\| return;
	163	return($class);
	164	}
	165	my $state = shaload($file) \|\| return;
	166	my $self = \$state;
	167	bless($self, $class);
	168	return($self);
	169	}
	170
747da336	171	Digest::SHA->bootstrap($VERSION);
747da336	172
6bc89f92	173	1;
	174	__END__
	175
	176	=head1 NAME
	177
	178	Digest::SHA - Perl extension for SHA-1/224/256/384/512
	179
747da336	180	=head1 SYNOPSIS
6bc89f92	181
	182	In programs:
	183
	184	# Functional interface
	185
	186	use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
	187
	188	$digest = sha1($data);
	189	$digest = sha1_hex($data);
	190	$digest = sha1_base64($data);
	191
	192	$digest = sha256($data);
	193	$digest = sha384_hex($data);
	194	$digest = sha512_base64($data);
	195
	196	# Object-oriented
	197
	198	use Digest::SHA;
	199
	200	$sha = Digest::SHA->new($alg);
	201
	202	$sha->add($data); # feed data into stream
c7e5c266	203
6bc89f92	204	$sha->addfile(*F);
c7e5c266	205	$sha->addfile($filename);
c7e5c266	206
6bc89f92	207	$sha->add_bits($bits);
	208	$sha->add_bits($data, $nbits);
	209
	210	$sha_copy = $sha->clone; # if needed, make copy of
	211	$sha->dump($file); # current digest state,
	212	$sha->load($file); # or save it on disk
	213
	214	$digest = $sha->digest; # compute digest
	215	$digest = $sha->hexdigest;
	216	$digest = $sha->b64digest;
	217
	218	From the command line:
	219
	220	$ shasum files
	221
	222	$ shasum --help
	223
	224	=head1 SYNOPSIS (HMAC-SHA)
	225
	226	# Functional interface only
	227
	228	use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
	229
	230	$digest = hmac_sha1($data, $key);
	231	$digest = hmac_sha224_hex($data, $key);
	232	$digest = hmac_sha256_base64($data, $key);
	233
	234	=head1 ABSTRACT
	235
	236	Digest::SHA is a complete implementation of the NIST Secure Hash
	237	Standard. It gives Perl programmers a convenient way to calculate
	238	SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 message digests.
	239	The module can handle all types of input, including partial-byte
	240	data.
	241
	242	=head1 DESCRIPTION
	243
	244	Digest::SHA is written in C for speed. If your platform lacks a
	245	C compiler, you can install the functionally equivalent (but much
	246	slower) L<Digest::SHA::PurePerl> module.
	247
	248	The programming interface is easy to use: it's the same one found
	249	in CPAN's L<Digest> module. So, if your applications currently
	250	use L<Digest::MD5> and you'd prefer the stronger security of SHA,
	251	it's a simple matter to convert them.
	252
	253	The interface provides two ways to calculate digests: all-at-once,
	254	or in stages. To illustrate, the following short program computes
	255	the SHA-256 digest of "hello world" using each approach:
	256
	257	use Digest::SHA qw(sha256_hex);
	258
	259	$data = "hello world";
	260	@frags = split(//, $data);
	261
	262	# all-at-once (Functional style)
	263	$digest1 = sha256_hex($data);
	264
	265	# in-stages (OOP style)
	266	$state = Digest::SHA->new(256);
	267	for (@frags) { $state->add($_) }
	268	$digest2 = $state->hexdigest;
	269
	270	print $digest1 eq $digest2 ?
271	"whew!\n" : "oops!\n";
272
273	To calculate the digest of an n-bit message where I<n> is not a
274	multiple of 8, use the I<add_bits()> method. For example, consider
275	the 446-bit message consisting of the bit-string "110" repeated
276	148 times, followed by "11". Here's how to display its SHA-1
277	digest:
278
279	use Digest::SHA;
280	$bits = "110" x 148 . "11";
281	$sha = Digest::SHA->new(1)->add_bits($bits);
282	print $sha->hexdigest, "\n";
283
284	Note that for larger bit-strings, it's more efficient to use the
285	two-argument version I<add_bits($data, $nbits)>, where I<$data> is
286	in the customary packed binary format used for Perl strings.
287
288	The module also lets you save intermediate SHA states to disk, or
289	display them on standard output. The I<dump()> method generates
290	portable, human-readable text describing the current state of
291	computation. You can subsequently retrieve the file with I<load()>
292	to resume where the calculation left off.
293
294	To see what a state description looks like, just run the following:
295
296	use Digest::SHA;
297	Digest::SHA->new->add("Shaw" x 1962)->dump;
298
299	As an added convenience, the Digest::SHA module offers routines to
300	calculate keyed hashes using the HMAC-SHA-1/224/256/384/512
301	algorithms. These services exist in functional form only, and
302	mimic the style and behavior of the I<sha()>, I<sha_hex()>, and
303	I<sha_base64()> functions.
304
305	# Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt
306
307	use Digest::SHA qw(hmac_sha256_hex);
308	print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
309
310	=head1 NIST STATEMENT ON SHA-1
311
312	I<NIST was recently informed that researchers had discovered a way
313	to "break" the current Federal Information Processing Standard SHA-1
314	algorithm, which has been in effect since 1994. The researchers
315	have not yet published their complete results, so NIST has not
316	confirmed these findings. However, the researchers are a reputable
317	research team with expertise in this area.>
318
319	I<Due to advances in computing power, NIST already planned to phase
320	out SHA-1 in favor of the larger and stronger hash functions (SHA-224,
321	SHA-256, SHA-384 and SHA-512) by 2010. New developments should use
322	the larger and stronger hash functions.>
323
324	ref. L<http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20Statement/Burr_Mar2005.html>
325
1bd6a86e	326	=head1 PADDING OF BASE64 DIGESTS
cccd5831	327
1bd6a86e	328	By convention, CPAN Digest modules do B<not> pad their Base64 output.
	329	Problems can occur when feeding such digests to other software that
	330	expects properly padded Base64 encodings.
cccd5831	331
cccd5831	332	For the time being, any necessary padding must be done by the user.
1bd6a86e	333	Fortunately, this is a simple operation: if the length of a Base64-encoded
	334	digest isn't a multiple of 4, simply append "=" characters to the end
	335	of the digest until it is:
cccd5831	336
	337	while (length($b64_digest) % 4) {
	338	$b64_digest .= '=';
	339	}
	340
	341	To illustrate, I<sha256_base64("abc")> is computed to be
	342
	343	ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
	344
	345	which has a length of 43. So, the properly padded version is
	346
	347	ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
	348
6bc89f92	349	=head1 EXPORT
	350
	351	None by default.
	352
	353	=head1 EXPORTABLE FUNCTIONS
	354
	355	Provided your C compiler supports a 64-bit type (e.g. the I<long
	356	long> of C99, or I<__int64> used by Microsoft C/C++), all of these
	357	functions will be available for use. Otherwise, you won't be able
	358	to perform the SHA-384 and SHA-512 transforms, both of which require
	359	64-bit operations.
	360
	361	I<Functional style>
	362
	363	=over 4
	364
	365	=item B<sha1($data, ...)>
	366
	367	=item B<sha224($data, ...)>
	368
	369	=item B<sha256($data, ...)>
	370
	371	=item B<sha384($data, ...)>
	372
	373	=item B<sha512($data, ...)>
	374
	375	Logically joins the arguments into a single string, and returns
	376	its SHA-1/224/256/384/512 digest encoded as a binary string.
	377
	378	=item B<sha1_hex($data, ...)>
	379
	380	=item B<sha224_hex($data, ...)>
	381
	382	=item B<sha256_hex($data, ...)>
	383
	384	=item B<sha384_hex($data, ...)>
	385
	386	=item B<sha512_hex($data, ...)>
	387
	388	Logically joins the arguments into a single string, and returns
	389	its SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
	390
	391	=item B<sha1_base64($data, ...)>
	392
	393	=item B<sha224_base64($data, ...)>
	394
	395	=item B<sha256_base64($data, ...)>
	396
	397	=item B<sha384_base64($data, ...)>
	398
	399	=item B<sha512_base64($data, ...)>
	400
	401	Logically joins the arguments into a single string, and returns
	402	its SHA-1/224/256/384/512 digest encoded as a Base64 string.
	403
cccd5831	404	It's important to note that the resulting string does B<not> contain
	405	the padding characters typical of Base64 encodings. This omission is
	406	deliberate, and is done to maintain compatibility with the family of
747da336	407	CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details.
cccd5831	408
6bc89f92	409	=back
	410
	411	I<OOP style>
	412
	413	=over 4
	414
	415	=item B<new($alg)>
	416
	417	Returns a new Digest::SHA object. Allowed values for I<$alg> are
	418	1, 224, 256, 384, or 512. It's also possible to use common string
	419	representations of the algorithm (e.g. "sha256", "SHA-384"). If
	420	the argument is missing, SHA-1 will be used by default.
	421
	422	Invoking I<new> as an instance method will not create a new object;
	423	instead, it will simply reset the object to the initial state
	424	associated with I<$alg>. If the argument is missing, the object
	425	will continue using the same algorithm that was selected at creation.
	426
	427	=item B<reset($alg)>
	428
	429	This method has exactly the same effect as I<new($alg)>. In fact,
	430	I<reset> is just an alias for I<new>.
	431
	432	=item B<hashsize>
	433
	434	Returns the number of digest bits for this object. The values are
	435	160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384,
	436	and SHA-512, respectively.
	437
	438	=item B<algorithm>
	439
	440	Returns the digest algorithm for this object. The values are 1,
	441	224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and
	442	SHA-512, respectively.
	443
	444	=item B<clone>
	445
	446	Returns a duplicate copy of the object.
	447
	448	=item B<add($data, ...)>
	449
	450	Logically joins the arguments into a single string, and uses it to
	451	update the current digest state. In other words, the following
	452	statements have the same effect:
	453
	454	$sha->add("a"); $sha->add("b"); $sha->add("c");
	455	$sha->add("a")->add("b")->add("c");
	456	$sha->add("a", "b", "c");
	457	$sha->add("abc");
	458
	459	The return value is the updated object itself.
	460
	461	=item B<add_bits($data, $nbits)>
	462
	463	=item B<add_bits($bits)>
	464
	465	Updates the current digest state by appending bits to it. The
	466	return value is the updated object itself.
	467
	468	The first form causes the most-significant I<$nbits> of I<$data>
	469	to be appended to the stream. The I<$data> argument is in the
	470	customary binary format used for Perl strings.
	471
	472	The second form takes an ASCII string of "0" and "1" characters as
473	its argument. It's equivalent to
474
475	$sha->add_bits(pack("B*", $bits), length($bits));
476
477	So, the following two statements do the same thing:
478
479	$sha->add_bits("111100001010");
480	$sha->add_bits("\xF0\xA0", 12);
481
482	=item B<addfile(*FILE)>
483
484	Reads from I<FILE> until EOF, and appends that data to the current
485	state. The return value is the updated object itself.
486
c7e5c266	487	=item B<addfile($filename [, $mode])>
	488
	489	Reads the contents of I<$filename>, and appends that data to the current
	490	state. The return value is the updated object itself.
	491
	492	By default, I<$filename> is simply opened and read; no special modes
	493	or I/O disciplines are used. To change this, set the optional I<$mode>
	494	argument to one of the following values:
	495
84c0b84e	496	"b" read file in binary mode
c7e5c266	497
84c0b84e	498	"p" use portable mode
c7e5c266	499
	500	The "p" mode is handy since it ensures that the digest value of
	501	I<$filename> will be the same when computed on different operating
	502	systems. It accomplishes this by internally translating all newlines
	503	in text files to UNIX format before calculating the digest; on the other
	504	hand, binary files are read in raw mode with no translation whatsoever.
	505
	506	For a fuller discussion of newline formats, refer to CPAN module
	507	L<File::LocalizeNewlines>. Its "universal line separator" regex forms
	508	the basis of I<addfile>'s portable mode processing.
6bc89f92	509
	510	=item B<dump($filename)>
	511
	512	Provides persistent storage of intermediate SHA states by writing
	513	a portable, human-readable representation of the current state to
	514	I<$filename>. If the argument is missing, or equal to the empty
	515	string, the state information will be written to STDOUT.
	516
	517	=item B<load($filename)>
	518
	519	Returns a Digest::SHA object representing the intermediate SHA
	520	state that was previously dumped to I<$filename>. If called as a
	521	class method, a new object is created; if called as an instance
	522	method, the object is reset to the state contained in I<$filename>.
	523	If the argument is missing, or equal to the empty string, the state
	524	information will be read from STDIN.
	525
	526	=item B<digest>
	527
	528	Returns the digest encoded as a binary string.
	529
	530	Note that the I<digest> method is a read-once operation. Once it
	531	has been performed, the Digest::SHA object is automatically reset
	532	in preparation for calculating another digest value. Call
	533	I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
	534	original digest state.
	535
	536	=item B<hexdigest>
	537
	538	Returns the digest encoded as a hexadecimal string.
	539
	540	Like I<digest>, this method is a read-once operation. Call
	541	I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve
	542	the original digest state.
	543
	544	This method is inherited if L<Digest::base> is installed on your
	545	system. Otherwise, a functionally equivalent substitute is used.
	546
	547	=item B<b64digest>
	548
	549	Returns the digest encoded as a Base64 string.
	550
	551	Like I<digest>, this method is a read-once operation. Call
	552	I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve
	553	the original digest state.
	554
	555	This method is inherited if L<Digest::base> is installed on your
	556	system. Otherwise, a functionally equivalent substitute is used.
	557
cccd5831	558	It's important to note that the resulting string does B<not> contain
	559	the padding characters typical of Base64 encodings. This omission is
	560	deliberate, and is done to maintain compatibility with the family of
747da336	561	CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details.
cccd5831	562
6bc89f92	563	=back
	564
	565	I<HMAC-SHA-1/224/256/384/512>
	566
	567	=over 4
	568
	569	=item B<hmac_sha1($data, $key)>
	570
	571	=item B<hmac_sha224($data, $key)>
	572
	573	=item B<hmac_sha256($data, $key)>
	574
	575	=item B<hmac_sha384($data, $key)>
	576
	577	=item B<hmac_sha512($data, $key)>
	578
	579	Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
	580	with the result encoded as a binary string. Multiple I<$data>
	581	arguments are allowed, provided that I<$key> is the last argument
	582	in the list.
	583
	584	=item B<hmac_sha1_hex($data, $key)>
	585
	586	=item B<hmac_sha224_hex($data, $key)>
	587
	588	=item B<hmac_sha256_hex($data, $key)>
	589
	590	=item B<hmac_sha384_hex($data, $key)>
	591
	592	=item B<hmac_sha512_hex($data, $key)>
	593
	594	Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
	595	with the result encoded as a hexadecimal string. Multiple I<$data>
	596	arguments are allowed, provided that I<$key> is the last argument
	597	in the list.
	598
	599	=item B<hmac_sha1_base64($data, $key)>
	600
	601	=item B<hmac_sha224_base64($data, $key)>
	602
	603	=item B<hmac_sha256_base64($data, $key)>
	604
	605	=item B<hmac_sha384_base64($data, $key)>
	606
	607	=item B<hmac_sha512_base64($data, $key)>
	608
	609	Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
	610	with the result encoded as a Base64 string. Multiple I<$data>
	611	arguments are allowed, provided that I<$key> is the last argument
	612	in the list.
	613
cccd5831	614	It's important to note that the resulting string does B<not> contain
	615	the padding characters typical of Base64 encodings. This omission is
	616	deliberate, and is done to maintain compatibility with the family of
747da336	617	CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details.
cccd5831	618
6bc89f92	619	=back
	620
	621	=head1 SEE ALSO
	622
	623	L<Digest>, L<Digest::SHA::PurePerl>
	624
	625	The Secure Hash Standard (FIPS PUB 180-2) can be found at:
	626
	627	L<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>
	628
	629	The Keyed-Hash Message Authentication Code (HMAC):
	630
	631	L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
	632
	633	=head1 AUTHOR
	634
	635	Mark Shelor <mshelor@cpan.org>
	636
	637	=head1 ACKNOWLEDGMENTS
	638
	639	The author is particularly grateful to
	640
	641	Gisle Aas
	642	Chris Carey
747da336	643	Jim Doble
6bc89f92	644	Julius Duque
	645	Jeffrey Friedl
	646	Robert Gilmour
	647	Brian Gladman
c7e5c266	648	Adam Kennedy
6bc89f92	649	Andy Lester
6bc89f92	650	Alex Muntada
77d2a621	651	Steve Peters
6bc89f92	652	Chris Skiscim
	653	Martin Thurn
	654	Gunnar Wolf
	655	Adam Woodbury
	656
	657	for their valuable comments and suggestions.
	658
	659	=head1 COPYRIGHT AND LICENSE
	660
0bc2b4f8	661	Copyright (C) 2003-2008 Mark Shelor
6bc89f92	662
	663	This library is free software; you can redistribute it and/or modify
	664	it under the same terms as Perl itself.
	665
	666	L<perlartistic>
	667
	668	=cut