/ 
Crypt-Sodium-XS-0.000020
River stage zero No dependents
/ Crypt::Sodium::XS::generichash

NAME

Crypt::Sodium::XS::generichash - Cryptographic hashing

SYNOPSIS

use Crypt::Sodium::XS::generichash ":default";

my $msg = "hello, world!";
my $hash = generichash($msg);

my $output_len = 64;
my $key = generichash_keygen;
$hash = generichash($msg, $output_len, $key);

my $multipart = generichash_init;
$multipart->update($msg);
$hash = $multipart->final;

DESCRIPTION

Crypt::Sodium::XS::generichash computes a fixed-length fingerprint for an arbitrary long message.

Sample use cases:

  • File integrity checking

  • Creating unique identifiers to index arbitrary long data

FUNCTIONS

Nothing is exported by default. A :default tag imports the functions and constants as documented below. A separate import tag is provided for each of the primitives listed in "PRIMITIVES". For example, :blake2b imports generichash_blake2b. You should use at least one import tag.

generichash

my $hash = generichash($message, $hash_length, $key);
my $hash = generichash($message, $hash_length);
my $hash = generichash($message);
my $hash = generichash($message, undef, $key);

$hash_length is the desired length of the hashed output. It is optional. If $hash_length is omitted or numifies to zero (undef, 0, ""), the default hash length ("generichash_BYTES") will be used.

$key is optional.

generichash_init

my $multipart = generichash_init($hash_length, $key);
my $multipart = generichash_init($hash_length);
my $multipart = generichash_init(undef, $key);

$hash_length is the desired length of the hashed output. It is optional. If it is omitted or numifies to zero (undef, 0, ""), the default hash length ("generichash_BYTES") will be used.

$key is optional. If provided, it must be "generichash_KEYBYTES" in length.

See "MULTI-PART INTERFACE".

generichash_keygen()

my $key = generichash_keygen();
my $key = generichash_keygen($key_length);

$key_length is the desired length of the generated key. It is optional. If it is omitted or numifies to zero (undef, 0, ""), the default key length ("generichash_KEYBYTES") will be used. The length of $key_length, if given, must be from "generichash_KEYBYTES_MIN" to "generichash_KEYBYTES_MAX", inclusive.

generichash_keygen

my $key = generichash_keygen();
my $key = generichash_keygen($key_length);

MULTI-PART INTERFACE

A multipart hashing object is created by calling the "generichash_init" function. Data to be hashed is added by calling the "update" method of that object as many times as desired. An output hash is generated by calling its "final" method. Do not use the object after calling "final".

The multipart hashing object is an opaque object which provides the following methods:

clone

my $multipart_copy = $multipart->clone;

final

my $hash = $multipart->final;

Note there is a difference to the sodium API. Finalizing the hash does not require, nor accept, a new output length. The output hash length will be the original $hash_length given to "generichash_init".

Once final has been called, the hashing object must not be used further.

update

$multipart->update($message);
$multipart->update(@messages);

CONSTANTS

generichash_PRIMITIVE

my $default_primitive = generichash_PRIMITIVE();

generichash_BYTES

my $hash_default_length = generichash_BYTES();

generichash_BYTES_MIN

my $hash_min_length = generichash_BYTES_MIN();

generichash_BYTES_MAX

my $hash_max_length = generichash_BYTES_MAX();

generichash_KEYBYTES

my $key_default_length = generichash_KEYBYTES();

generichash_KEYBYTES_MIN

my $key_min_length = generichash_KEYBYTES_MIN();

generichash_KEYBYTES_MAX

my $key_max_length = generichash_KEYBYTES_MAX();

PRIMITIVES

All constants (except _PRIMITIVE) and functions have generichash_<primitive<gt>-prefixed counterparts (e.g. generichash_blake2b, generichash_blake2b_BYTES).

  • blake2b

blake2b FUNCTIONS

Crypt::Sodium::XS::generichash has the following functions available only in their primitive-specific form.

generichash_blake2b_salt_personal

my $hash = generichash_blake2b_salt_personal($message, $salt, $personal, $hash_length, $key);
my $hash = generichash_blake2b_salt_personal($message, $salt, $personal, $hash_length);
my $hash = generichash_blake2b_salt_personal($message, $salt, $personal);
my $hash = generichash_blake2b_salt_personal($message, $salt, $personal, undef, $key);

$salt as an arbitrary string which is at least generichash_blake2b_SALTBYTES in length (see warnings below).

$personal as an arbitrary string which is at least generichash_blake2b_PERSONALBYTES in length (see warnings below).

$hash_length is the desired length of the hashed output. It is optional. If $hash_length is omitted or numifies to zero (undef, 0, ""), the default hash length (generichash_blake2b_BYTES) will be used.

$key is optional.

WARNING: $salt and $personal must be at least generichash_blake2b_SALTBYTES and generichash_blake2b_PERSONALBYTES in length, respectively. If they are longer than the required length, only the required length of initial bytes will be used. If these values are not being randomly chosen, it is recommended to use an arbitrary-length string as the input to a hash function (e.g., "generichash" in Crypt::Sodium::XS::generichash or "shorthash" in Crypt::Sodium::XS::shorthash) and use the hash output rather than the strings.

generichash_blake2b_init_salt_personal

my $multipart = generichash_blake2b_init_salt_personal($hash_length, $key);
my $multipart = generichash_blake2b_init_salt_personal($hash_length);
my $multipart = generichash_blake2b_init_salt_personal($hash_length, $key);

$hash_length is the desired length of the hashed output. It is optional. If it is omitted or numifies to zero (undef, 0, ""), the default hash length (generichash_blake2b_BYTES) will be used.

$key is optional. If provided, it must be generichash_blake2b_KEYBYTES in length.

blake2b CONSTANTS

Crypt::Sodium::XS::generichash has the following constants available only in their primitive-specific form.

generichash_blake2b_PERSONALBYTES

generichash_blake2b_SALTBYTES

SEE ALSO

Crypt::Sodium::XS
https://doc.libsodium.org/hashing/generic_hashing

FEEDBACK

For reporting bugs, giving feedback, submitting patches, etc. please use the following:

  • IRC channel #sodium on irc.perl.org.

  • Email the author directly.

AUTHOR

Brad Barden <perlmodules@5c30.org>

COPYRIGHT & LICENSE

Copyright (c) 2022 Brad Barden. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.