NAME

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

VERSION

version 1.0.8.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

• Data::BytesLocker - guarded data storage

• BLAKE2 - fast secure hashing

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.

cpanm Crypt::NaCl::Sodium

perl -MCPAN -e shell
install Crypt::NaCl::Sodium