/ 
Crypt-NaCl-Sodium-1.0.7.0
River stage one • 1 direct dependent • 2 total dependents
/ Crypt::NaCl::Sodium::generichash

NAME

Crypt::NaCl::Sodium::generichash - Generic hashing (Blake2b)

VERSION

version 1.0.7.0

SYNOPSIS

use Crypt::NaCl::Sodium qw( :utils );

my $crypto_generichash = Crypt::NaCl::Sodium->generichash();

# generate secret key
my $key = $crypto_generichash->keygen();

# list of files for which we are computing the checksums
my @files = ...;

for my $file ( @files ) {
    # file name checksum
    my $filename_hash = $crypto_generichash->mac($file, key => $key, bytes => 32 );

    # using multi-part API
    my $stream = $crypto_generichash->init( key => $key, bytes => 64 );

    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

Compute a fixed-length fingerprint for an arbitrary long message. crypto_generichash supports multi-part API and the use of keys of variable length.

A message will always have the same fingerprint for a given key, but different keys used to hash the same message are very likely to produce distinct fingerprints.

If the key is used it should remain secret.

The crypto_generichash provides better and faster alternative to other hashing functions like MD5 and SHA-1/2/3.

METHODS

keygen

my $key = $crypto_generichash->keygen( $keybytes );

Helper method to generate a random key to be used by $crypto_generichash.

The value of the $keybytes argument can by any value between "KEYBYTES_MIN" (included) and "KEYBYTES_MAX" (included).

The default value of $keybytes is "KEYBYTES".

The length of the $key equals the value of $keybytes.

NOTE: keep the key confidential.

Returns Data::BytesLocker object.

mac

my $mac = $crypto_generichash->mac( $msg, key => $key, bytes => $bytes );

Computes the MAC of the $msg using (optional) $key. The value of optional $bytes argument specifies the length of the computed $mac.

The value of the $bytes argument can by any value between "BYTES_MIN" (included) and "BYTES_MAX" (included).

The default value of $bytes is "BYTES".

The length of the $mac equals the value of $bytes.

Returns Data::BytesLocker object.

Multi-part API

Multi-part computation is also supported.

my $ctx = $crypto_generichash->init( key => $key, bytes => $bytes );

$ctx->update( $msgX );
$ctx->update( $msgY )->update( $msgZ, ... );

my $mac = $ctx->final( bytes => $bytes );

init

my $ctx = $crypto_generichash->mac( key => $key, bytes => $bytes );

Creates a context for multi-part computation using (optional) $key. The value of optional $bytes argument specifies the length of the final hash.

The value of the $bytes argument can by any value between "BYTES_MIN" (included) and "BYTES_MAX" (included).

The default value of $bytes is "BYTES".

Returns Crypt::NaCl::Sodium::generichash::stream object which encapsulates the computation state of the algorithm.

clone

while ( <> ) {
    $ctx->update( $_ );
    print "Line: $.: ", $ctx->clone->final->to_hex, "\n";
}

Returns a copy of $ctx object, that contains the current computation state.

update

$ctx->update( $msg, ... );

Appends its arguments to the message for which the MAC is being calculated.

Returns the $ctx object itself.

final

my $mac = $ctx->final( bytes => $bytes );

Computes the final MAC of the input data. The value of optional $bytes argument specifies the output length of the final output.

The value of the $bytes argument can by any value between "BYTES_MIN" (included) and "BYTES_MAX" (included).

The default value of $bytes equals to the value of $bytes of the "init" parameter.

Returns Data::BytesLocker object.

CONSTANTS

KEYBYTES

my $key_length = $crypto_generichash->KEYBYTES;

Returns the default length of key.

KEYBYTES_MIN

my $key_min_length = $crypto_generichash->KEYBYTES_MIN;

Returns the minimum length of key.

KEYBYTES_MAX

my $key_max_length = $crypto_generichash->KEYBYTES_MAX;

Returns the maximum length of key.

BYTES

my $mac_length = $crypto_generichash->BYTES;

Returns the default length of MAC.

BYTES_MIN

my $mac_min_length = $crypto_generichash->BYTES_MIN;

Returns the minimum length of MAC.

BYTES_MAX

my $mac_max_length = $crypto_generichash->BYTES_MAX;

Returns the maximum length of MAC.

SECURITY MODEL

crypto_generichash uses Blake2b hash function which is an improved version of SHA-3 finalist BLAKE. Like SHA-3, Blake2b offers highest security, yet is fast as MD5 on 64-bit platforms and requires 33% less RAM then SHA-2 or SHA-3 on low-end systems. The core algorithm of Blake2b is derived from ChaCha stream cipher.

SEE ALSO

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.