NAME
Crypt::Sodium::XS::OO::generichash - Cryptographic hashing
SYNOPSIS
use Crypt::Sodium::XS;
my $gh = Crypt::Sodium::XS->generichash;
my $msg = "hello, world!";
my $hash = $gh->generichash($msg);
my $output_len = 64;
my $key = $gh->keygen;
$hash = $gh->generichash($msg, $output_len, $key);
my $hasher = $gh->init;
$hasher->update($msg);
$hash = $hasher->final;DESCRIPTION
Crypt::Sodium::XS::OO::generichash computes a fixed-length fingerprint for an arbitrary long message.
CONSTRUCTOR
new
my $gh = Crypt::Sodium::XS::OO::generichash->new;
my $gh = Crypt::Sodium::XS::OO::generichash->new(primitive => 'blake2b');
my $gh = Crypt::Sodium::XS->generichash;Returns a new generichash object for the given primitive. If not given, the default primitive is default.
METHODS
PRIMITIVE
my $gh = Crypt::Sodium::XS::OO::generichash->new(primitive => 'default');
my $default_primitive = $gh->PRIMITIVE;BYTES
my $hash_default_length = $gh->BYTES;BYTES_MIN
my $hash_min_length = $gh->BYTES_MIN;BYTES_MAX
my $hash_max_length = $gh->BYTES_MAX;KEYBYTES
my $key_default_length = $gh->KEYBYTES;KEYBYTES_MIN
my $key_min_length = $gh->KEYBYTES_MIN;KEYBYTES_MAX
my $key_max_length = $gh->KEYBYTES_MAX;primitives
my @primitives = $gh->primitives;Returns a list of all supported primitive names (including 'default').
generichash
my $hash = $gh->generichash($message, $hash_length, $key);
my $hash = $gh->generichash($message, $hash_length);
my $hash = $gh->generichash($message);
my $hash = $gh->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 ("BYTES") will be used.
$key is optional.
init
my $multipart = $gh->init($hash_length, $key);
my $multipart = $gh->init($hash_length);
my $multipart = $gh->init(undef, $key);Returns a multipart hashing object. See "MULTI-PART INTERFACE".
$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 ("BYTES") will be used.
$key is optional. If provided, it must be "KEYBYTES" in length.
keygen
my $key = $gh->keygen;
my $key = $gh->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 ("KEYBYTES") will be used. The length of $key_length, if given, must be from "KEYBYTES_MIN" to "KEYBYTES_MAX", inclusive.
MULTI-PART INTERFACE
A multipart hashing object is created by calling the "init" method. 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;Returns a cloned copy of the multipart hashing object, duplicating its internal state.
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 "init".
Retruns the final hash for all data added with "update".
Once final has been called, the hashing object must not be used further.
update
$multipart->update($message);
$multipart->update(@messages);Adds all given arguments (stringified) to hashed data.
blake2b METHODS
The following methods are available only when explicitly using the blake2b primitive and fatal otherwise.
PERSONALBYTES
my $personalbytes_len = $gh->PERSONALBYTES;SALTBYTES
my $salt_len = $gh->SALTBYTES;salt_personal
my $hash = $gh->salt_personal($message, $salt, $personal, $hash_length, $key);
my $hash = $gh->salt_personal($message, $salt, $personal, $hash_length);
my $hash = $gh->salt_personal($message, $salt, $personal);
my $hash = $gh->salt_personal($message, $salt, $personal, undef, $key);$salt as an arbitrary string which is at least SALTBYTES in length (see warnings below).
$personal as an arbitrary string which is at least 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 (BYTES) will be used.
$key is optional.
WARNING: $salt and $personal must be at least SALTBYTES and 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.
init_salt_personal
my $multipart = $gh->init_salt_personal($hash_length, $key);
my $multipart = $gh->init_salt_personal($hash_length);
my $multipart = $gh->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 (BYTES) will be used.
$key is optional. If provided, it must be KEYBYTES in length.
SEE ALSO
FEEDBACK
For reporting bugs, giving feedback, submitting patches, etc. please use the following:
IRC channel
#sodiumonirc.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.