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-size 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 documented below. A separate :<primitive> import tag is provided for each of the primitives listed in "PRIMITIVES". These tags import the generichash_<primitive>_* functions and constants for that primitive. A :all tag imports everything.
generichash
my $hash = generichash($message, $hash_size, $key);$message is the message to hash. It may be a Crypt::Sodium::XS::MemVault.
$hash_size is optional. It is the desired size, in bytes, of the hashed output. If it is omitted or numifies to zero (undef, 0, ""), the default hash size "generichash_BYTES" will be used. It must be in the range of "generichash_BYTES_MIN" to "generichash_BYTES_MAX", inclusive.
$key is optional. It must be "generichash_KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault. Note that if a key is not provided, the same message will always produce the same hash output.
Returns hash output of the requested size.
generichash_init
my $multipart = generichash_init($hash_size, $key, $flags);$hash_size is optional. It is the desired size, in bytes, of the hashed output. If it is omitted or numifies to zero (undef, 0, ""), the default hash size "generichash_BYTES" will be used. It must be in the range of "generichash_BYTES_MIN" to "generichash_BYTES_MAX", inclusive.
$key is optional. It must be "generichash_KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault. Note that if a key is not provided, the same message will always produce the same hash output.
$flags is optional. It is the flags used for the multipart protected memory object. See Crypt::Sodium::XS::ProtMem.
Returns an opaque protected memory object: a multipart hashing object. See "MULTI-PART INTERFACE".
generichash_keygen
my $key = generichash_keygen($key_size, $flags);$key_size is optional. It is the desired size, in bytes, of the generated key. If it is omitted or numifies to zero (undef, 0, ""), the default key size "generichash_KEYBYTES" will be used. It must be in the range of "generichash_KEYBYTES_MIN" to "generichash_KEYBYTES_MAX", inclusive.
$flags is optional. It is the flags used for the $key Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.
Returns a Crypt::Sodium::XS::MemVault: a secret key of $key_size bytes.
blake2b FUNCTIONS
Crypt::Sodium::XS::generichash has the following functions available only in their primitive-specific form.
Warning: For these functions $salt and $personal must be at least "generichash_blake2b_SALTBYTES" and "generichash_blake2b_PERSONALBYTES" in bytes, respectively. If they are longer than the required size, only the initial bytes of the required size 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_salt_personal
my $hash = generichash_blake2b_salt_personal(
$message,
$salt,
$personal,
$hash_size,
$key
);$salt is an arbitrary string which is at least "generichash_blake2b_SALTBYTES" bytes (see warnings above).
$personal as an arbitrary string which is at least "generichash_blake2b_PERSONALBYTES" bytes (see warnings above).
$hash_size is optional. It is the desired size of the hashed output. If it is omitted or numifies to zero (undef, 0, ""), the default hash size "generichash_blake2b_BYTES" will be used. It must be in the range of "generichash_BYTES_MIN" to "generichash_BYTES_MAX", inclusive.
$key is optional. It must be "generichash_blake2b_KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault. Note that if a key is not provided, the same message will always produce the same hash output.
generichash_blake2b_init_salt_personal
my $multipart = generichash_blake2b_init_salt_personal(
$salt,
$personal,
$hash_size,
$key
);$salt as an arbitrary string which is at least generichash_blake2b_SALTBYTES bytes(see warnings above).
$personal as an arbitrary string which is at least generichash_blake2b_PERSONALBYTES bytes (see warnings above).
$hash_size is optional. It is the desired size of the hashed output. If it is omitted or numifies to zero (undef, 0, ""), the default hash size "generichash_blake2b_BYTES" will be used. It must be in the range of "generichash_BYTES_MIN" to "generichash_BYTES_MAX", inclusive.
$key is optional. It must be "generichash_blake2b_KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault. Note that if a key is not provided, the same message will always produce the same hash output.
Returns a multipart hashing object. See "MULTI-PART INTERFACE".
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;Returns a cloned copy of the multipart hashing object, duplicating its internal state.
final
my $hash = $multipart->final;Returns the final hash for all data added with "update". The output hash size will be the original $hash_size given to "generichash_init".
Once final has been called, the hashing object must not be used further.
update
$multipart->update(@messages);Adds all given arguments (stringified) to hashed data. Any argument may be a Crypt::Sodium::XS::MemVault.
CONSTANTS
generichash_PRIMITIVE
my $default_primitive = generichash_PRIMITIVE();Returns the name of the default primitive.
generichash_BYTES
my $hash_default_size = generichash_BYTES();Returns the recommended minimum size, in bytes, of hash output. This size makes it practically impossible for two messages to produce the same fingerprint.
generichash_BYTES_MIN
my $hash_min_size = generichash_BYTES_MIN();Returns the minimum size, in bytes, of hash output.
generichash_BYTES_MAX
my $hash_max_size = generichash_BYTES_MAX();Returns the maximum size, in bytes, of hash output.
generichash_KEYBYTES
my $key_default_size = generichash_KEYBYTES();Returns the recommended size, in bytes, of secret keys.
generichash_KEYBYTES_MIN
my $key_min_size = generichash_KEYBYTES_MIN();Returns the minimum size, in bytes, of secret keys.
generichash_KEYBYTES_MAX
my $key_max_size = generichash_KEYBYTES_MAX();Returns the maximum size, in bytes, of secret keys.
blake2b CONSTANTS
Crypt::Sodium::XS::generichash has the following constants available only in their primitive-specific form.
generichash_blake2b_PERSONALBYTES
The size, in bytes, of personalization strings.
generichash_blake2b_SALTBYTES
The size, in bytes, of salts.
PRIMITIVES
All constants (except _PRIMITIVE) and functions have generichash_<primitive<gt>-prefixed counterparts (e.g. generichash_blake2b, generichash_blake2b_BYTES).
blake2b (default)
SEE ALSO
FEEDBACK
For reporting bugs, giving feedback, submitting patches, etc. please use the following:
RT queue at https://rt.cpan.org/Dist/Display.html?Name=Crypt-Sodium-XS
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.