view release on metacpan or  search on metacpan

lib/Crypt/NaCl/Sodium/hash.pod  view on Meta::CPAN

=head1 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();
    }

=head1 DESCRIPTION

The I<SHA-256> and I<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
I<SHA-2>, using L<Crypt::NaCl::Sodium::generichash> might be a
better choice.

=head1 METHODS

=head2 sha256

    my $hash256 = $crypto_hash->sha256($msg);

Generates I<SHA-256> hash of the given C<$msg>.

The length of the C<$sha256> equals L</SHA256_BYTES>.

Returns L<Data::BytesLocker> object.

=head3 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();

=head4 sha256_init

    my $ctx256 = $crypto_hash->sha256_init();

Creates a context for multi-part computation.

Returns C<Crypt::NaCl::Sodium::hash::sha256stream> object which encapsulates
the computation state of the I<SHA-256> algorithm.

=head4 clone

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

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

=head4 update

    $ctx256->update( $msgX, ... );

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

Returns the C<$ctx256> object itself.

=head4 final

    my $mac256 = $ctx256->final();