NAME
Crypt::Sodium::XS::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::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
CONSTRUCTOR
The constructor is called with the Crypt::Sodium::XS->generichash method.
my $gh = Crypt::Sodium::XS->generichash;
my $gh = Crypt::Sodium::XS->generichash(primitive => 'blake2b');Returns a new generichash object.
Implementation detail: the returned object is blessed into Crypt::Sodium::XS::OO::generichash.
ATTRIBUTES
primitive
my $primitive = $gh->primitive;
$gh->primitive('chacha20poly1305');Gets or sets the primitive used for all operations by this object. It must be one of the primitives listed in "PRIMITIVES", including default.
METHODS
primitives
my @primitives = $gh->primitives;
my @primitives = Crypt::Sodium::XS::generichash->primitives;Returns a list of all supported primitive names, including default.
Can be called as a class method.
PRIMITIVE
my $primitive = $gh->PRIMITIVE;Returns the primitive used for all operations by this object. Note this will never be default but would instead be the primitive it represents.
generichash
my $hash = $gh->generichash($message, $hash_size, $key);
my $hash = $gh->generichash($message, $hash_size);
my $hash = $gh->generichash($message);
my $hash = $gh->generichash($message, undef, $key);$message is the message to hash. It may be a Crypt::Sodium::XS::MemVault.
$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 "BYTES" will be used. It must be in the range of "BYTES_MIN" to "BYTES_MAX", inclusive.
$key is optional. It must be "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 length.
init
my $multipart = $gh->init($hash_size, $key, $flags);$hash_size is optional. It is the desired length of the hashed output. If it is omitted or numifies to zero (undef, 0, ""), the default hash length "BYTES" will be used. It must be in the range of "BYTES_MIN" to "BYTES_MAX", inclusive.
$key is optional. It must be "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".
keygen
my $key = $gh->keygen($key_size, $flags);$key_size is optional. It is the desired length of the generated key. If it is omitted or numifies to zero (undef, 0, ""), the default key length "KEYBYTES" will be used. It must be in the range of "KEYBYTES_MIN" to "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.
BYTES
my $hash_default_size = $gh->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.
BYTES_MIN
my $hash_min_size = $gh->BYTES_MIN;Returns the minimum size, in bytes, of hash output.
BYTES_MAX
my $hash_max_size = $gh->BYTES_MAX;Returns the maximum size, in bytes, of hash output.
KEYBYTES
my $key_default_size = $gh->KEYBYTES;Returns the recommended size, in bytes, of secret keys.
KEYBYTES_MIN
my $key_min_size = $gh->KEYBYTES_MIN;Returns the minimum size, in bytes, of secret keys.
KEYBYTES_MAX
my $key_max_size = $gh->KEYBYTES_MAX;Returns the maximum size, in bytes, of secret keys.
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;Returns the final hash for all data added with "update". The output hash size will be the original $hash_size given to "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.
blake2b METHODS
The following methods are available only when explicitly using the blake2b primitive and fatal otherwise.
Warning: For these methods, $salt and $personal must be at least "SALTBYTES" and "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.
PERSONALBYTES
my $personalbytes_len = $gh->PERSONALBYTES;The size, in bytes, of personalization strings.
SALTBYTES
my $salt_len = $gh->SALTBYTES;The size, in bytes, of salts.
salt_personal
my $hash = $gh->salt_personal($message, $salt, $personal, $hash_size, $key);$salt is an arbitrary string which is at least "SALTBYTES" bytes (see warnings above).
$personal as an arbitrary string which is at least "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 "BYTES" will be used. It must be in the range of "BYTES_MIN" to "BYTES_MAX", inclusive.
$key is optional. It must be "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.
init_salt_personal
my $multipart = $gh->init_salt_personal($salt, $personal, $hash_size, $key);$salt as an arbitrary string which is at least "SALTBYTES" bytes (see warnings above).
$personal as an arbitrary string which is at least "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 "BYTES" will be used. It must be in the range of "BYTES_MIN" to "BYTES_MAX", inclusive.
$key is optional. It must be "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".
PRIMITIVES
blake2b (default)
FUNCTIONS
The object API above is the recommended way to use this module. The functions and constants documented below can be imported instead or in addition.
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 (function)
generichash_<primitive>
my $hash = generichash($message, $hash_size, $key);Same as "generichash" (method).
generichash_init
generichash_<primitive>_init
my $multipart = generichash_init($hash_size, $key, $flags);Same as "init".
generichash_keygen
generichash_<primitive>_keygen
my $key = generichash_keygen($key_size, $flags);Same as "keygen".
blake2b FUNCTIONS
See notes under "blake2b METHODS".
generichash_blake2b_salt_personal
my $hash = generichash_blake2b_salt_personal(
$message,
$salt,
$personal,
$hash_size,
$key
);Same as "salt_personal".
generichash_blake2b_init_salt_personal
my $multipart = generichash_blake2b_init_salt_personal(
$salt,
$personal,
$hash_size,
$key
);Same as "init_salt_personal".
CONSTANTS
generichash_PRIMITIVE
my $default_primitive = generichash_PRIMITIVE();Returns the name of the default primitive.
generichash_BYTES
generichash_<primitive>_BYTES
my $hash_default_size = generichash_BYTES();Same as "BYTES".
generichash_BYTES_MIN
generichash_<primitive>_BYTES_MIN
my $hash_min_size = generichash_BYTES_MIN();Same as "BYTES_MIN".
generichash_BYTES_MAX
generichash_<primitive>_BYTES_MAX
my $hash_max_size = generichash_BYTES_MAX();Same as "BYTES_MAX".
generichash_KEYBYTES
generichash_<primitive>_KEYBYTES
my $key_default_size = generichash_KEYBYTES();Same as "KEYBYTES".
generichash_KEYBYTES_MIN
generichash_<primitive>_KEYBYTES_MIN
my $key_min_size = generichash_KEYBYTES_MIN();Same as "KEYBYTES_MIN".
generichash_KEYBYTES_MAX
generichash_<primitive>_KEYBYTES_MAX
my $key_max_size = generichash_KEYBYTES_MAX();Same as "KEYBYTES_MAX".
blake2b CONSTANTS
Crypt::Sodium::XS::generichash has the following constants available only in their primitive-specific form.
generichash_blake2b_PERSONALBYTES
Same as "PERSONALBYTES".
generichash_blake2b_SALTBYTES
Same as "SALTBYTES".
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.