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

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-size fingerprint for an arbitrary long message.

Sample use cases:

  • File integrity checking

  • Creating unique identifiers to index arbitrary long data

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.

ATTRIBUTES

primitive

my $primitive = $gh->primitive;
$gh->primitive('chacha20poly1305');

Gets or sets the primitive used for all operations by this object. Note this can be default.

METHODS

primitives

my @primitives = Crypt::Sodium::XS::generichash->primitives;
my @primitives = $gh->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".

SEE ALSO

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

FEEDBACK

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

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.