[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.42_01';

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, q{<}, $file) 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
57303e6c	9	our $VERSION = '5.42_01';
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
cccd5831	121	open(my $fh, q{<}, $file) or _bail("Open failed");
cccd5831	122	binmode($fh) if $binary \|\| $portable;
c7e5c266	123
c7e5c266	124	unless ($portable && $text) {
cccd5831	125	$self->_addfile($fh);
cccd5831	126	close($fh);
c7e5c266	127	return($self);
	128	}
	129
	130	my ($n1, $n2);
	131	my ($buf1, $buf2) = ("", "");
	132
cccd5831	133	while (($n1 = read($fh, $buf1, 4096))) {
c7e5c266	134	while (substr($buf1, -1) eq "\015") {
cccd5831	135	$n2 = read($fh, $buf2, 4096);
c7e5c266	136	_bail("Read failed") unless defined $n2;
	137	last unless $n2;
	138	$buf1 .= $buf2;
	139	}
84c0b84e	140	$buf1 =~ s/\015?\015\012/\012/g; # DOS/Windows
84c0b84e	141	$buf1 =~ s/\015/\012/g; # Apple/MacOS 9
c7e5c266	142	$self->add($buf1);
	143	}
	144	_bail("Read failed") unless defined $n1;
cccd5831	145	close($fh);
c7e5c266	146
	147	$self;
	148	}
	149
6bc89f92	150	sub dump {
	151	my $self = shift;
	152	my $file = shift \|\| "";
	153
	154	shadump($file, $$self) \|\| return;
	155	return($self);
	156	}
	157
	158	sub load {
	159	my $class = shift;
	160	my $file = shift \|\| "";
	161	if (ref($class)) { # instance method
	162	shaclose($$class) if $$class;
	163	$$class = shaload($file) \|\| return;
	164	return($class);
	165	}
	166	my $state = shaload($file) \|\| return;
	167	my $self = \$state;
	168	bless($self, $class);
	169	return($self);
	170	}
	171
	172	1;
	173	__END__
	174
	175	=head1 NAME
	176
	177	Digest::SHA - Perl extension for SHA-1/224/256/384/512
	178
	179	=head1 SYNOPSIS (SHA)
	180
	181	In programs:
	182
	183	# Functional interface
	184
	185	use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
	186
	187	$digest = sha1($data);
	188	$digest = sha1_hex($data);
	189	$digest = sha1_base64($data);
	190
	191	$digest = sha256($data);
	192	$digest = sha384_hex($data);
	193	$digest = sha512_base64($data);
	194
	195	# Object-oriented
	196
	197	use Digest::SHA;
	198
	199	$sha = Digest::SHA->new($alg);
	200
	201	$sha->add($data); # feed data into stream
c7e5c266	202
6bc89f92	203	$sha->addfile(*F);
c7e5c266	204	$sha->addfile($filename);
c7e5c266	205
6bc89f92	206	$sha->add_bits($bits);
	207	$sha->add_bits($data, $nbits);
	208
	209	$sha_copy = $sha->clone; # if needed, make copy of
	210	$sha->dump($file); # current digest state,
	211	$sha->load($file); # or save it on disk
	212
	213	$digest = $sha->digest; # compute digest
	214	$digest = $sha->hexdigest;
	215	$digest = $sha->b64digest;
	216
	217	From the command line:
	218
	219	$ shasum files
	220
	221	$ shasum --help
	222
	223	=head1 SYNOPSIS (HMAC-SHA)
	224
	225	# Functional interface only
	226
	227	use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
	228
	229	$digest = hmac_sha1($data, $key);
	230	$digest = hmac_sha224_hex($data, $key);
	231	$digest = hmac_sha256_base64($data, $key);
	232
	233	=head1 ABSTRACT
	234
	235	Digest::SHA is a complete implementation of the NIST Secure Hash
	236	Standard. It gives Perl programmers a convenient way to calculate
	237	SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 message digests.
	238	The module can handle all types of input, including partial-byte
	239	data.
	240
	241	=head1 DESCRIPTION
	242
	243	Digest::SHA is written in C for speed. If your platform lacks a
	244	C compiler, you can install the functionally equivalent (but much
	245	slower) L<Digest::SHA::PurePerl> module.
	246
	247	The programming interface is easy to use: it's the same one found
	248	in CPAN's L<Digest> module. So, if your applications currently
	249	use L<Digest::MD5> and you'd prefer the stronger security of SHA,
	250	it's a simple matter to convert them.
	251
	252	The interface provides two ways to calculate digests: all-at-once,
	253	or in stages. To illustrate, the following short program computes
	254	the SHA-256 digest of "hello world" using each approach:
	255
	256	use Digest::SHA qw(sha256_hex);
	257
	258	$data = "hello world";
	259	@frags = split(//, $data);
	260
	261	# all-at-once (Functional style)
	262	$digest1 = sha256_hex($data);
	263
	264	# in-stages (OOP style)
	265	$state = Digest::SHA->new(256);
	266	for (@frags) { $state->add($_) }
	267	$digest2 = $state->hexdigest;
	268
	269	print $digest1 eq $digest2 ?
270	"whew!\n" : "oops!\n";
271
272	To calculate the digest of an n-bit message where I<n> is not a
273	multiple of 8, use the I<add_bits()> method. For example, consider
274	the 446-bit message consisting of the bit-string "110" repeated
275	148 times, followed by "11". Here's how to display its SHA-1
276	digest:
277
278	use Digest::SHA;
279	$bits = "110" x 148 . "11";
280	$sha = Digest::SHA->new(1)->add_bits($bits);
281	print $sha->hexdigest, "\n";
282
283	Note that for larger bit-strings, it's more efficient to use the
284	two-argument version I<add_bits($data, $nbits)>, where I<$data> is
285	in the customary packed binary format used for Perl strings.
286
287	The module also lets you save intermediate SHA states to disk, or
288	display them on standard output. The I<dump()> method generates
289	portable, human-readable text describing the current state of
290	computation. You can subsequently retrieve the file with I<load()>
291	to resume where the calculation left off.
292
293	To see what a state description looks like, just run the following:
294
295	use Digest::SHA;
296	Digest::SHA->new->add("Shaw" x 1962)->dump;
297
298	As an added convenience, the Digest::SHA module offers routines to
299	calculate keyed hashes using the HMAC-SHA-1/224/256/384/512
300	algorithms. These services exist in functional form only, and
301	mimic the style and behavior of the I<sha()>, I<sha_hex()>, and
302	I<sha_base64()> functions.
303
304	# Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt
305
306	use Digest::SHA qw(hmac_sha256_hex);
307	print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
308
309	=head1 NIST STATEMENT ON SHA-1
310
311	I<NIST was recently informed that researchers had discovered a way
312	to "break" the current Federal Information Processing Standard SHA-1
313	algorithm, which has been in effect since 1994. The researchers
314	have not yet published their complete results, so NIST has not
315	confirmed these findings. However, the researchers are a reputable
316	research team with expertise in this area.>
317
318	I<Due to advances in computing power, NIST already planned to phase
319	out SHA-1 in favor of the larger and stronger hash functions (SHA-224,
320	SHA-256, SHA-384 and SHA-512) by 2010. New developments should use
321	the larger and stronger hash functions.>
322
323	ref. L<http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20Statement/Burr_Mar2005.html>
324
cccd5831	325	=head1 BASE64 DIGESTS
	326
	327	By convention, CPAN Digest modules do not pad their Base64 output.
	328	This means that Base64 digests contain no trailing "=" characters.
	329	Unfortunately, problems can occur when feeding such digests to other
	330	software that expects properly padded Base64 encodings.
	331
	332	For the time being, any necessary padding must be done by the user.
	333	Fortunately, the rule for accomplishing it is straightforward: if the
	334	length of a Base64-encoded digest isn't a multiple of 4, simply append
	335	1 or more "=" characters to the end of the digest until it is:
	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
	407	CPAN Digest modules. See L</"BASE64 DIGESTS"> for details.
	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
	561	CPAN Digest modules. See L</"BASE64 DIGESTS"> for details.
	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
	617	CPAN Digest modules. See L</"BASE64 DIGESTS"> for details.
	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
	643	Julius Duque
	644	Jeffrey Friedl
	645	Robert Gilmour
	646	Brian Gladman
c7e5c266	647	Adam Kennedy
6bc89f92	648	Andy Lester
6bc89f92	649	Alex Muntada
77d2a621	650	Steve Peters
6bc89f92	651	Chris Skiscim
	652	Martin Thurn
	653	Gunnar Wolf
	654	Adam Woodbury
	655
	656	for their valuable comments and suggestions.
	657
	658	=head1 COPYRIGHT AND LICENSE
	659
77d2a621	660	Copyright (C) 2003-2006 Mark Shelor
6bc89f92	661
	662	This library is free software; you can redistribute it and/or modify
	663	it under the same terms as Perl itself.
	664
	665	L<perlartistic>
	666
	667	=cut