NAME
Crypt::NaCl::Sodium::hash - SHA-2 hash functions (SHA-256, SHA-512)
VERSION
version 1.0.8.0
SYNOPSIS
use Crypt::NaCl::Sodium qw( :utils );
my $crypto_hash = Crypt::NaCl::Sodium->hash();
# list of files for which we are computing the checksums
my @files = ...;
## SHA-256
########
for my $file ( @files ) {
# file name checksum
my $filename_hash = $crypto_hash->sha256($file);
# using multi-part API
my $stream = $crypto_hash->sha256_init();
open(my $fh, $file) or die;
while ( sysread($fh, my $buf, 4096) ) {
# add the chunk of data
$stream->update( $buf );
}
close($fh);
# calculate the final checksum
my $checksum = $stream->final();
}
## SHA-512
########
for my $file ( @files ) {
# file name checksum
my $filename_hash = $crypto_hash->sha512($file);
# using multi-part API
my $stream = $crypto_hash->sha512_init();
open(my $fh, $file) or die;
while ( sysread($fh, my $buf, 4096) ) {
# add the chunk of data
$stream->update( $buf );
}
close($fh);
# calculate the final checksum
my $checksum = $stream->final();
}DESCRIPTION
The SHA-256 and SHA-512 functions are provided for interoperability with other applications.
These functions are not keyed and are thus deterministic. In addition, they are vulnerable to length extension attacks.
A message can be hashed in a single pass, but a streaming API is also available to process a message as a sequence of multiple chunks.
If you are looking for a generic hash function and not specifically SHA-2, using Crypt::NaCl::Sodium::generichash might be a better choice.
METHODS
sha256
my $hash256 = $crypto_hash->sha256($msg);Generates SHA-256 hash of the given $msg.
The length of the $sha256 equals "SHA256_BYTES".
Returns Data::BytesLocker object.
Multi-part API
Multi-part computation is also supported.
my $ctx256 = $crypto_hash->sha256_init();
$ctx256->update( $msgX );
$ctx256->update( $msgY )->update( $msgZ, ... );
my $mac256 = $ctx256->final();sha256_init
my $ctx256 = $crypto_hash->sha256_init();Creates a context for multi-part computation.
Returns Crypt::NaCl::Sodium::hash::sha256stream object which encapsulates the computation state of the SHA-256 algorithm.
clone
while ( <> ) {
$ctx256->update( $_ );
print "Line: $.: ", $ctx256->clone->final->to_hex, "\n";
}Returns a copy of $ctx object, that contains the current computation state.
update
$ctx256->update( $msgX, ... );Appends its arguments to the message for which the MAC is being calculated.
Returns the $ctx256 object itself.
final
my $mac256 = $ctx256->final();Computes the final MAC of the input data.
Returns Data::BytesLocker object.
sha512
my $hash512 = $crypto_hash->sha512($msg);Generates SHA-512 hash of the given $msg.
The length of the $sha512 equals "SHA512_BYTES".
Returns Data::BytesLocker object.
Multi-part API
Multi-part computation is also supported.
my $ctx512 = $crypto_hash->sha512_init();
$ctx512->update( $msgX );
$ctx512->update( $msgY )->update( $msgZ, ... );
my $mac512 = $ctx512->final();sha512_init
my $ctx512 = $crypto_hash->sha512_init();Creates a context for multi-part computation.
Returns Crypt::NaCl::Sodium::hash::sha512stream object which encapsulates the computation state of the SHA-512 algorithm.
clone
while ( <> ) {
$ctx512->update( $_ );
print "Line: $.: ", $ctx512->clone->final->to_hex, "\n";
}Returns a copy of $ctx object, that contains the current computation state.
update
$ctx512->update( $msgX, ... );Appends its arguments to the message for which the MAC is being calculated.
Returns the $ctx512 object itself.
final
my $mac512 = $ctx512->final();Computes the final MAC of the input data.
Returns Data::BytesLocker object.
CONSTANTS
SHA256_BYTES
my $sha256_length = $crypto_hash->SHA256_BYTES;Returns the length of SHA-256 hash.
SHA512_BYTES
my $sha512_length = $crypto_hash->SHA512_BYTES;Returns the length of SHA-512 hash.
SECURITY MODEL
Although the existing attacks against SHA-2 are not yet practical, there are various attacks against its implementations. The recommended ways of message authentication are provided by Crypt::NaCl::Sodium::generichash and Crypt::NaCl::Sodium::auth.
SEE ALSO
Data::BytesLocker - guarded data storage
AUTHOR
Alex J. G. Burzyński <ajgb@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Alex J. G. Burzyński <ajgb@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.