++ed by:
1 non-PAUSE user
Author image Alex J. G. Burzyński

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

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.