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

package Digest::SHA;

require 5.006000;

use strict;
use warnings;
use integer;

our $VERSION = '5.43';

require Exporter;
our @ISA = qw(Exporter);

our @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;
}

require XSLoader;
XSLoader::load('Digest::SHA', $VERSION);

# Preloaded methods go here.

# 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;

	open(my $fh, "<$file")			## no critic
		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;          	# Apple/MacOS 9
		$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);
}

1;
__END__

=head1 NAME

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

=head1 SYNOPSIS (SHA)

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 BASE64 DIGESTS

By convention, CPAN Digest modules do not pad their Base64 output.
This means that Base64 digests contain no trailing "=" characters.
Unfortunately, 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, the rule for accomplishing it is straightforward: if the
length of a Base64-encoded digest isn't a multiple of 4, simply append
1 or more "=" 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</"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</"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</"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
	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-2006 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
c7e5c266	3	require 5.006000;
c7e5c266	4
6bc89f92	5	use strict;
	6	use warnings;
	7	use integer;
	8
44e8b72c	9	our $VERSION = '5.43';
6bc89f92	10
	11	require Exporter;
	12	our @ISA = qw(Exporter);
	13
	14	our @EXPORT_OK = qw(
	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
	40	require XSLoader;
	41	XSLoader::load('Digest::SHA', $VERSION);
	42
	43	# Preloaded methods go here.
	44
	45	# The following routines aren't time-critical, so they can be left in Perl
	46
	47	sub new {
	48	my($class, $alg) = @_;
	49	$alg =~ s/\D+//g if defined $alg;
	50	if (ref($class)) { # instance method
	51	unless (defined($alg) && ($alg != $class->algorithm)) {
	52	sharewind($$class);
	53	return($class);
	54	}
	55	shaclose($$class) if $$class;
	56	$$class = shaopen($alg) \|\| return;
	57	return($class);
	58	}
	59	$alg = 1 unless defined $alg;
	60	my $state = shaopen($alg) \|\| return;
	61	my $self = \$state;
	62	bless($self, $class);
	63	return($self);
	64	}
	65
	66	sub DESTROY {
	67	my $self = shift;
	68	shaclose($$self) if $$self;
	69	}
	70
	71	sub clone {
	72	my $self = shift;
	73	my $state = shadup($$self) \|\| return;
	74	my $copy = \$state;
	75	bless($copy, ref($self));
	76	return($copy);
	77	}
	78
	79	*reset = \&new;
	80
	81	sub add_bits {
	82	my($self, $data, $nbits) = @_;
	83	unless (defined $nbits) {
	84	$nbits = length($data);
	85	$data = pack("B*", $data);
	86	}
	87	shawrite($data, $nbits, $$self);
	88	return($self);
	89	}
	90
c7e5c266	91	sub _bail {
	92	my $msg = shift;
	93
	94	require Carp;
	95	Carp::croak("$msg: $!");
	96	}
6bc89f92	97
c7e5c266	98	sub _addfile { # this is "addfile" from Digest::base 1.00
6bc89f92	99	my ($self, $handle) = @_;
	100
	101	my $n;
	102	my $buf = "";
	103
	104	while (($n = read($handle, $buf, 4096))) {
c7e5c266	105	$self->add($buf);
6bc89f92	106	}
c7e5c266	107	_bail("Read failed") unless defined $n;
6bc89f92	108
	109	$self;
	110	}
	111
c7e5c266	112	sub Addfile {
	113	my ($self, $file, $mode) = @_;
	114
84c0b84e	115	return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR';
c7e5c266	116
	117	$mode = defined($mode) ? $mode : "";
	118	my ($binary, $portable) = map { $_ eq $mode } ("b", "p");
	119	my $text = -T $file;
	120
44e8b72c	121	open(my $fh, "<$file") ## no critic
44e8b72c	122	or _bail("Open failed");
cccd5831	123	binmode($fh) if $binary \|\| $portable;
c7e5c266	124
c7e5c266	125	unless ($portable && $text) {
cccd5831	126	$self->_addfile($fh);
cccd5831	127	close($fh);
c7e5c266	128	return($self);
	129	}
	130
	131	my ($n1, $n2);
	132	my ($buf1, $buf2) = ("", "");
	133
cccd5831	134	while (($n1 = read($fh, $buf1, 4096))) {
c7e5c266	135	while (substr($buf1, -1) eq "\015") {
cccd5831	136	$n2 = read($fh, $buf2, 4096);
c7e5c266	137	_bail("Read failed") unless defined $n2;
	138	last unless $n2;
	139	$buf1 .= $buf2;
	140	}
84c0b84e	141	$buf1 =~ s/\015?\015\012/\012/g; # DOS/Windows
84c0b84e	142	$buf1 =~ s/\015/\012/g; # Apple/MacOS 9
c7e5c266	143	$self->add($buf1);
	144	}
	145	_bail("Read failed") unless defined $n1;
cccd5831	146	close($fh);
c7e5c266	147
	148	$self;
	149	}
	150
6bc89f92	151	sub dump {
	152	my $self = shift;
	153	my $file = shift \|\| "";
	154
	155	shadump($file, $$self) \|\| return;
	156	return($self);
	157	}
	158
	159	sub load {
	160	my $class = shift;
	161	my $file = shift \|\| "";
	162	if (ref($class)) { # instance method
	163	shaclose($$class) if $$class;
	164	$$class = shaload($file) \|\| return;
	165	return($class);
	166	}
	167	my $state = shaload($file) \|\| return;
	168	my $self = \$state;
	169	bless($self, $class);
	170	return($self);
	171	}
	172
	173	1;
	174	__END__
	175
	176	=head1 NAME
	177
	178	Digest::SHA - Perl extension for SHA-1/224/256/384/512
	179
	180	=head1 SYNOPSIS (SHA)
	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
cccd5831	326	=head1 BASE64 DIGESTS
	327
	328	By convention, CPAN Digest modules do not pad their Base64 output.
	329	This means that Base64 digests contain no trailing "=" characters.
	330	Unfortunately, problems can occur when feeding such digests to other
	331	software that expects properly padded Base64 encodings.
	332
	333	For the time being, any necessary padding must be done by the user.
	334	Fortunately, the rule for accomplishing it is straightforward: if the
	335	length of a Base64-encoded digest isn't a multiple of 4, simply append
	336	1 or more "=" characters to the end of the digest until it is:
	337
	338	while (length($b64_digest) % 4) {
	339	$b64_digest .= '=';
	340	}
	341
	342	To illustrate, I<sha256_base64("abc")> is computed to be
	343
	344	ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
	345
	346	which has a length of 43. So, the properly padded version is
	347
	348	ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
	349
6bc89f92	350	=head1 EXPORT
	351
	352	None by default.
	353
	354	=head1 EXPORTABLE FUNCTIONS
	355
	356	Provided your C compiler supports a 64-bit type (e.g. the I<long
	357	long> of C99, or I<__int64> used by Microsoft C/C++), all of these
	358	functions will be available for use. Otherwise, you won't be able
	359	to perform the SHA-384 and SHA-512 transforms, both of which require
	360	64-bit operations.
	361
	362	I<Functional style>
	363
	364	=over 4
	365
	366	=item B<sha1($data, ...)>
	367
	368	=item B<sha224($data, ...)>
	369
	370	=item B<sha256($data, ...)>
	371
	372	=item B<sha384($data, ...)>
	373
	374	=item B<sha512($data, ...)>
	375
	376	Logically joins the arguments into a single string, and returns
	377	its SHA-1/224/256/384/512 digest encoded as a binary string.
	378
	379	=item B<sha1_hex($data, ...)>
	380
	381	=item B<sha224_hex($data, ...)>
	382
	383	=item B<sha256_hex($data, ...)>
	384
	385	=item B<sha384_hex($data, ...)>
	386
	387	=item B<sha512_hex($data, ...)>
	388
	389	Logically joins the arguments into a single string, and returns
	390	its SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
	391
	392	=item B<sha1_base64($data, ...)>
	393
	394	=item B<sha224_base64($data, ...)>
	395
	396	=item B<sha256_base64($data, ...)>
	397
	398	=item B<sha384_base64($data, ...)>
	399
	400	=item B<sha512_base64($data, ...)>
	401
	402	Logically joins the arguments into a single string, and returns
	403	its SHA-1/224/256/384/512 digest encoded as a Base64 string.
	404
cccd5831	405	It's important to note that the resulting string does B<not> contain
	406	the padding characters typical of Base64 encodings. This omission is
	407	deliberate, and is done to maintain compatibility with the family of
	408	CPAN Digest modules. See L</"BASE64 DIGESTS"> for details.
	409
6bc89f92	410	=back
	411
	412	I<OOP style>
	413
	414	=over 4
	415
	416	=item B<new($alg)>
	417
	418	Returns a new Digest::SHA object. Allowed values for I<$alg> are
	419	1, 224, 256, 384, or 512. It's also possible to use common string
	420	representations of the algorithm (e.g. "sha256", "SHA-384"). If
	421	the argument is missing, SHA-1 will be used by default.
	422
	423	Invoking I<new> as an instance method will not create a new object;
	424	instead, it will simply reset the object to the initial state
	425	associated with I<$alg>. If the argument is missing, the object
	426	will continue using the same algorithm that was selected at creation.
	427
	428	=item B<reset($alg)>
	429
	430	This method has exactly the same effect as I<new($alg)>. In fact,
	431	I<reset> is just an alias for I<new>.
	432
	433	=item B<hashsize>
	434
	435	Returns the number of digest bits for this object. The values are
	436	160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384,
	437	and SHA-512, respectively.
	438
	439	=item B<algorithm>
	440
	441	Returns the digest algorithm for this object. The values are 1,
	442	224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and
	443	SHA-512, respectively.
	444
	445	=item B<clone>
	446
	447	Returns a duplicate copy of the object.
	448
	449	=item B<add($data, ...)>
	450
	451	Logically joins the arguments into a single string, and uses it to
	452	update the current digest state. In other words, the following
	453	statements have the same effect:
	454
	455	$sha->add("a"); $sha->add("b"); $sha->add("c");
	456	$sha->add("a")->add("b")->add("c");
	457	$sha->add("a", "b", "c");
	458	$sha->add("abc");
	459
	460	The return value is the updated object itself.
	461
	462	=item B<add_bits($data, $nbits)>
	463
	464	=item B<add_bits($bits)>
	465
	466	Updates the current digest state by appending bits to it. The
	467	return value is the updated object itself.
	468
	469	The first form causes the most-significant I<$nbits> of I<$data>
	470	to be appended to the stream. The I<$data> argument is in the
	471	customary binary format used for Perl strings.
	472
	473	The second form takes an ASCII string of "0" and "1" characters as
474	its argument. It's equivalent to
475
476	$sha->add_bits(pack("B*", $bits), length($bits));
477
478	So, the following two statements do the same thing:
479
480	$sha->add_bits("111100001010");
481	$sha->add_bits("\xF0\xA0", 12);
482
483	=item B<addfile(*FILE)>
484
485	Reads from I<FILE> until EOF, and appends that data to the current
486	state. The return value is the updated object itself.
487
c7e5c266	488	=item B<addfile($filename [, $mode])>
	489
	490	Reads the contents of I<$filename>, and appends that data to the current
	491	state. The return value is the updated object itself.
	492
	493	By default, I<$filename> is simply opened and read; no special modes
	494	or I/O disciplines are used. To change this, set the optional I<$mode>
	495	argument to one of the following values:
	496
84c0b84e	497	"b" read file in binary mode
c7e5c266	498
84c0b84e	499	"p" use portable mode
c7e5c266	500
	501	The "p" mode is handy since it ensures that the digest value of
	502	I<$filename> will be the same when computed on different operating
	503	systems. It accomplishes this by internally translating all newlines
	504	in text files to UNIX format before calculating the digest; on the other
	505	hand, binary files are read in raw mode with no translation whatsoever.
	506
	507	For a fuller discussion of newline formats, refer to CPAN module
	508	L<File::LocalizeNewlines>. Its "universal line separator" regex forms
	509	the basis of I<addfile>'s portable mode processing.
6bc89f92	510
	511	=item B<dump($filename)>
	512
	513	Provides persistent storage of intermediate SHA states by writing
	514	a portable, human-readable representation of the current state to
	515	I<$filename>. If the argument is missing, or equal to the empty
	516	string, the state information will be written to STDOUT.
	517
	518	=item B<load($filename)>
	519
	520	Returns a Digest::SHA object representing the intermediate SHA
	521	state that was previously dumped to I<$filename>. If called as a
	522	class method, a new object is created; if called as an instance
	523	method, the object is reset to the state contained in I<$filename>.
	524	If the argument is missing, or equal to the empty string, the state
	525	information will be read from STDIN.
	526
	527	=item B<digest>
	528
	529	Returns the digest encoded as a binary string.
	530
	531	Note that the I<digest> method is a read-once operation. Once it
	532	has been performed, the Digest::SHA object is automatically reset
	533	in preparation for calculating another digest value. Call
	534	I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
	535	original digest state.
	536
	537	=item B<hexdigest>
	538
	539	Returns the digest encoded as a hexadecimal string.
	540
	541	Like I<digest>, this method is a read-once operation. Call
	542	I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve
	543	the original digest state.
	544
	545	This method is inherited if L<Digest::base> is installed on your
	546	system. Otherwise, a functionally equivalent substitute is used.
	547
	548	=item B<b64digest>
	549
	550	Returns the digest encoded as a Base64 string.
	551
	552	Like I<digest>, this method is a read-once operation. Call
	553	I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve
	554	the original digest state.
	555
	556	This method is inherited if L<Digest::base> is installed on your
	557	system. Otherwise, a functionally equivalent substitute is used.
	558
cccd5831	559	It's important to note that the resulting string does B<not> contain
	560	the padding characters typical of Base64 encodings. This omission is
	561	deliberate, and is done to maintain compatibility with the family of
	562	CPAN Digest modules. See L</"BASE64 DIGESTS"> for details.
	563
6bc89f92	564	=back
	565
	566	I<HMAC-SHA-1/224/256/384/512>
	567
	568	=over 4
	569
	570	=item B<hmac_sha1($data, $key)>
	571
	572	=item B<hmac_sha224($data, $key)>
	573
	574	=item B<hmac_sha256($data, $key)>
	575
	576	=item B<hmac_sha384($data, $key)>
	577
	578	=item B<hmac_sha512($data, $key)>
	579
	580	Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
	581	with the result encoded as a binary string. Multiple I<$data>
	582	arguments are allowed, provided that I<$key> is the last argument
	583	in the list.
	584
	585	=item B<hmac_sha1_hex($data, $key)>
	586
	587	=item B<hmac_sha224_hex($data, $key)>
	588
	589	=item B<hmac_sha256_hex($data, $key)>
	590
	591	=item B<hmac_sha384_hex($data, $key)>
	592
	593	=item B<hmac_sha512_hex($data, $key)>
	594
	595	Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
	596	with the result encoded as a hexadecimal string. Multiple I<$data>
	597	arguments are allowed, provided that I<$key> is the last argument
	598	in the list.
	599
	600	=item B<hmac_sha1_base64($data, $key)>
	601
	602	=item B<hmac_sha224_base64($data, $key)>
	603
	604	=item B<hmac_sha256_base64($data, $key)>
	605
	606	=item B<hmac_sha384_base64($data, $key)>
	607
	608	=item B<hmac_sha512_base64($data, $key)>
	609
	610	Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
	611	with the result encoded as a Base64 string. Multiple I<$data>
	612	arguments are allowed, provided that I<$key> is the last argument
	613	in the list.
	614
cccd5831	615	It's important to note that the resulting string does B<not> contain
	616	the padding characters typical of Base64 encodings. This omission is
	617	deliberate, and is done to maintain compatibility with the family of
	618	CPAN Digest modules. See L</"BASE64 DIGESTS"> for details.
	619
6bc89f92	620	=back
	621
	622	=head1 SEE ALSO
	623
	624	L<Digest>, L<Digest::SHA::PurePerl>
	625
	626	The Secure Hash Standard (FIPS PUB 180-2) can be found at:
	627
	628	L<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>
	629
	630	The Keyed-Hash Message Authentication Code (HMAC):
	631
	632	L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
	633
	634	=head1 AUTHOR
	635
	636	Mark Shelor <mshelor@cpan.org>
	637
	638	=head1 ACKNOWLEDGMENTS
	639
	640	The author is particularly grateful to
	641
	642	Gisle Aas
	643	Chris Carey
	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
77d2a621	661	Copyright (C) 2003-2006 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