[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.38_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) = @_;

	if (ref(\$file) eq 'GLOB') { return(_addfile($self, $file)) }

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

	local *F;
	_bail("Open failed") unless open(F, "<$file");
	binmode(F) if $binary || $portable;

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

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

	while (($n1 = read(F, $buf1, 4096))) {
		while (substr($buf1, -1) eq "\015") {
			$n2 = read(F, $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(F);

	$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 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.

=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:

=over 4

=item B<"b">	read file in binary mode

=item B<"p">	use portable mode

=back

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.

=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.

=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
c7e5c266	9	our $VERSION = '5.38_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
	115	if (ref(\$file) eq 'GLOB') { return(_addfile($self, $file)) }
	116
	117	$mode = defined($mode) ? $mode : "";
	118	my ($binary, $portable) = map { $_ eq $mode } ("b", "p");
	119	my $text = -T $file;
	120
	121	local *F;
	122	_bail("Open failed") unless open(F, "<$file");
	123	binmode(F) if $binary \|\| $portable;
	124
	125	unless ($portable && $text) {
	126	$self->_addfile(*F);
	127	close(F);
	128	return($self);
	129	}
	130
	131	my ($n1, $n2);
	132	my ($buf1, $buf2) = ("", "");
	133
	134	while (($n1 = read(F, $buf1, 4096))) {
	135	while (substr($buf1, -1) eq "\015") {
	136	$n2 = read(F, $buf2, 4096);
	137	_bail("Read failed") unless defined $n2;
	138	last unless $n2;
	139	$buf1 .= $buf2;
	140	}
	141	$buf1 =~ s/\015?\015\012/\012/g; # DOS/Windows
	142	$buf1 =~ s/\015/\012/g; # Apple/MacOS 9
	143	$self->add($buf1);
	144	}
	145	_bail("Read failed") unless defined $n1;
	146	close(F);
	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
326	=head1 EXPORT
327
328	None by default.
329
330	=head1 EXPORTABLE FUNCTIONS
331
332	Provided your C compiler supports a 64-bit type (e.g. the I<long
333	long> of C99, or I<__int64> used by Microsoft C/C++), all of these
334	functions will be available for use. Otherwise, you won't be able
335	to perform the SHA-384 and SHA-512 transforms, both of which require
336	64-bit operations.
337
338	I<Functional style>
339
340	=over 4
341
342	=item B<sha1($data, ...)>
343
344	=item B<sha224($data, ...)>
345
346	=item B<sha256($data, ...)>
347
348	=item B<sha384($data, ...)>
349
350	=item B<sha512($data, ...)>
351
352	Logically joins the arguments into a single string, and returns
353	its SHA-1/224/256/384/512 digest encoded as a binary string.
354
355	=item B<sha1_hex($data, ...)>
356
357	=item B<sha224_hex($data, ...)>
358
359	=item B<sha256_hex($data, ...)>
360
361	=item B<sha384_hex($data, ...)>
362
363	=item B<sha512_hex($data, ...)>
364
365	Logically joins the arguments into a single string, and returns
366	its SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
367
368	=item B<sha1_base64($data, ...)>
369
370	=item B<sha224_base64($data, ...)>
371
372	=item B<sha256_base64($data, ...)>
373
374	=item B<sha384_base64($data, ...)>
375
376	=item B<sha512_base64($data, ...)>
377
378	Logically joins the arguments into a single string, and returns
379	its SHA-1/224/256/384/512 digest encoded as a Base64 string.
380
381	=back
382
383	I<OOP style>
384
385	=over 4
386
387	=item B<new($alg)>
388
389	Returns a new Digest::SHA object. Allowed values for I<$alg> are
390	1, 224, 256, 384, or 512. It's also possible to use common string
391	representations of the algorithm (e.g. "sha256", "SHA-384"). If
392	the argument is missing, SHA-1 will be used by default.
393
394	Invoking I<new> as an instance method will not create a new object;
395	instead, it will simply reset the object to the initial state
396	associated with I<$alg>. If the argument is missing, the object
397	will continue using the same algorithm that was selected at creation.
398
399	=item B<reset($alg)>
400
401	This method has exactly the same effect as I<new($alg)>. In fact,
402	I<reset> is just an alias for I<new>.
403
404	=item B<hashsize>
405
406	Returns the number of digest bits for this object. The values are
407	160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384,
408	and SHA-512, respectively.
409
410	=item B<algorithm>
411
412	Returns the digest algorithm for this object. The values are 1,
413	224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and
414	SHA-512, respectively.
415
416	=item B<clone>
417
418	Returns a duplicate copy of the object.
419
420	=item B<add($data, ...)>
421
422	Logically joins the arguments into a single string, and uses it to
423	update the current digest state. In other words, the following
424	statements have the same effect:
425
426	$sha->add("a"); $sha->add("b"); $sha->add("c");
427	$sha->add("a")->add("b")->add("c");
428	$sha->add("a", "b", "c");
429	$sha->add("abc");
430
431	The return value is the updated object itself.
432
433	=item B<add_bits($data, $nbits)>
434
435	=item B<add_bits($bits)>
436
437	Updates the current digest state by appending bits to it. The
438	return value is the updated object itself.
439
440	The first form causes the most-significant I<$nbits> of I<$data>
441	to be appended to the stream. The I<$data> argument is in the
442	customary binary format used for Perl strings.
443
444	The second form takes an ASCII string of "0" and "1" characters as
445	its argument. It's equivalent to
446
447	$sha->add_bits(pack("B*", $bits), length($bits));
448
449	So, the following two statements do the same thing:
450
451	$sha->add_bits("111100001010");
452	$sha->add_bits("\xF0\xA0", 12);
453
454	=item B<addfile(*FILE)>
455
456	Reads from I<FILE> until EOF, and appends that data to the current
457	state. The return value is the updated object itself.
458
c7e5c266	459	=item B<addfile($filename [, $mode])>
	460
	461	Reads the contents of I<$filename>, and appends that data to the current
	462	state. The return value is the updated object itself.
	463
	464	By default, I<$filename> is simply opened and read; no special modes
	465	or I/O disciplines are used. To change this, set the optional I<$mode>
	466	argument to one of the following values:
	467
	468	=over 4
	469
	470	=item B<"b"> read file in binary mode
	471
	472	=item B<"p"> use portable mode
	473
	474	=back
	475
	476	The "p" mode is handy since it ensures that the digest value of
	477	I<$filename> will be the same when computed on different operating
	478	systems. It accomplishes this by internally translating all newlines
	479	in text files to UNIX format before calculating the digest; on the other
	480	hand, binary files are read in raw mode with no translation whatsoever.
	481
	482	For a fuller discussion of newline formats, refer to CPAN module
	483	L<File::LocalizeNewlines>. Its "universal line separator" regex forms
	484	the basis of I<addfile>'s portable mode processing.
6bc89f92	485
	486	=item B<dump($filename)>
	487
	488	Provides persistent storage of intermediate SHA states by writing
	489	a portable, human-readable representation of the current state to
	490	I<$filename>. If the argument is missing, or equal to the empty
	491	string, the state information will be written to STDOUT.
	492
	493	=item B<load($filename)>
	494
	495	Returns a Digest::SHA object representing the intermediate SHA
	496	state that was previously dumped to I<$filename>. If called as a
	497	class method, a new object is created; if called as an instance
	498	method, the object is reset to the state contained in I<$filename>.
	499	If the argument is missing, or equal to the empty string, the state
	500	information will be read from STDIN.
	501
	502	=item B<digest>
	503
	504	Returns the digest encoded as a binary string.
	505
	506	Note that the I<digest> method is a read-once operation. Once it
	507	has been performed, the Digest::SHA object is automatically reset
	508	in preparation for calculating another digest value. Call
	509	I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
	510	original digest state.
	511
	512	=item B<hexdigest>
	513
	514	Returns the digest encoded as a hexadecimal string.
	515
	516	Like I<digest>, this method is a read-once operation. Call
	517	I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve
	518	the original digest state.
	519
	520	This method is inherited if L<Digest::base> is installed on your
	521	system. Otherwise, a functionally equivalent substitute is used.
	522
	523	=item B<b64digest>
	524
	525	Returns the digest encoded as a Base64 string.
	526
	527	Like I<digest>, this method is a read-once operation. Call
	528	I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve
	529	the original digest state.
	530
	531	This method is inherited if L<Digest::base> is installed on your
	532	system. Otherwise, a functionally equivalent substitute is used.
	533
	534	=back
	535
	536	I<HMAC-SHA-1/224/256/384/512>
	537
	538	=over 4
	539
	540	=item B<hmac_sha1($data, $key)>
	541
	542	=item B<hmac_sha224($data, $key)>
	543
	544	=item B<hmac_sha256($data, $key)>
	545
	546	=item B<hmac_sha384($data, $key)>
	547
	548	=item B<hmac_sha512($data, $key)>
549
550	Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
551	with the result encoded as a binary string. Multiple I<$data>
552	arguments are allowed, provided that I<$key> is the last argument
553	in the list.
554
555	=item B<hmac_sha1_hex($data, $key)>
556
557	=item B<hmac_sha224_hex($data, $key)>
558
559	=item B<hmac_sha256_hex($data, $key)>
560
561	=item B<hmac_sha384_hex($data, $key)>
562
563	=item B<hmac_sha512_hex($data, $key)>
564
565	Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
566	with the result encoded as a hexadecimal string. Multiple I<$data>
567	arguments are allowed, provided that I<$key> is the last argument
568	in the list.
569
570	=item B<hmac_sha1_base64($data, $key)>
571
572	=item B<hmac_sha224_base64($data, $key)>
573
574	=item B<hmac_sha256_base64($data, $key)>
575
576	=item B<hmac_sha384_base64($data, $key)>
577
578	=item B<hmac_sha512_base64($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 Base64 string. Multiple I<$data>
582	arguments are allowed, provided that I<$key> is the last argument
583	in the list.
584
585	=back
586
587	=head1 SEE ALSO
588
589	L<Digest>, L<Digest::SHA::PurePerl>
590
591	The Secure Hash Standard (FIPS PUB 180-2) can be found at:
592
593	L<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>
594
595	The Keyed-Hash Message Authentication Code (HMAC):
596
597	L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
598
599	=head1 AUTHOR
600
601	Mark Shelor <mshelor@cpan.org>
602
603	=head1 ACKNOWLEDGMENTS
604
605	The author is particularly grateful to
606
607	Gisle Aas
608	Chris Carey
609	Julius Duque
610	Jeffrey Friedl
611	Robert Gilmour
612	Brian Gladman
c7e5c266	613	Adam Kennedy
6bc89f92	614	Andy Lester
6bc89f92	615	Alex Muntada
77d2a621	616	Steve Peters
6bc89f92	617	Chris Skiscim
	618	Martin Thurn
	619	Gunnar Wolf
	620	Adam Woodbury
	621
	622	for their valuable comments and suggestions.
	623
	624	=head1 COPYRIGHT AND LICENSE
	625
77d2a621	626	Copyright (C) 2003-2006 Mark Shelor
6bc89f92	627
	628	This library is free software; you can redistribute it and/or modify
	629	it under the same terms as Perl itself.
	630
	631	L<perlartistic>
	632
	633	=cut