/ 
Crypt-Sodium-XS-0.002000
/ Crypt::Sodium::XS::hash

NAME

Crypt::Sodium::XS::hash - SHA2 cryptographic hashing

SYNOPSIS

use Crypt::Sodium::XS;
my $xs_hash = Crypt::Sodium::XS->hash;

my $hash = $xs_hash->hash("arbitrary input data");

my $multipart = $xs_hash->init;
$multipart->update("arbitrary");
$multipart->update("input", " data");
$hash = $multipart->final;

DESCRIPTION

The SHA-2 (SHA-256 and SHA-512) and SHA-3 (SHA3-256 and SHA3-512) functions are provided for interoperability with other applications. If you are looking for a generic hash function and not specifically SHA-2 or SHA-3, using Crypt::Sodium::XS::generichash (BLAKE2b) might be a better choice.

These functions are also not suitable for hashing passwords or deriving keys from passwords. Use Crypt::Sodium::XS::pwhash instead.

These functions are not keyed and are thus deterministic. In addition, the untruncated versions are vulnerable to length extension attacks.

A message can be hashed in a single pass, but a multi-part API is also available to process a message as a sequence of multiple chunks.

CONSTRUCTOR

The constructor is called with the Crypt::Sodium::XS->hash method.

my $xs_hash = Crypt::Sodium::XS->hash;
my $xs_hash = Crypt::Sodium::XS->hash(primitive => 'sha256');

Returns a new hash object.

Implementation detail: the returned object is blessed into Crypt::Sodium::XS::OO::hash.

ATTRIBUTES

primitive

my $primitive = $xs_hash->primitive;
$xs_hash->primitive('sha256');

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

sha3_available

my $has_sha3 = $xs_hash->sha3_available;
my $has_sha3 = Crypt::Sodium::XS::hash->sha3_available;

Returns true if Crypt::Sodium::XS supports SHA-3, false otherwise. SHA-3 will only be supported if Crypt::Sodium::XS was built with a new enough version of libsodium (at least 1.0.22).

Can be called as a class method.

primitives

my @primitives = $xs_hash->primitives;
my @primitives = Crypt::Sodium::XS::hash->primitives;

Returns a list of all supported primitive names, including default.

Can be called as a class method.

PRIMITIVE

my $primitive = $xs_hash->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.

hash

my $hash = $xs_hash->hash($message);

$message is the message to hash. It may be a Crypt::Sodium::XS::MemVault.

Returns the hash output of "BYTES" bytes.

init

my $multipart = $xs_hash->init($flags);

$flags is optional. It is the flags used for the multipart protected memory object. See Crypt::Sodium::XS::ProtMem.

Returns a multipart hashing object. See "MULTI-PART INTERFACE".

BYTES

my $xs_hash_size = $xs_hash->BYTES;

Returns the size, in bytes, of hash output.

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 $xs_hash = $multipart->final;

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(@messages);

Adds all given arguments (stringified) to hashed data. Any argument may be a Crypt::Sodium::XS::MemVault.

PRIMITIVES

  • sha256

  • sha512 (default)

  • sha3256

  • sha3512

Note: SHA3-256 and SHA3-512 were added in libsodium 1.0.22. Check for availability with "sha3_available".

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 :features tag imports the *_available feature test functions. 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 hash_<primitive>_* functions and constants for that primitive. A :all tag imports everything.

hash_sha3_available

Same as "sha3_available".

hash (function)

hash_<primitive>

my $hash = hash($message);

Same as "hash" (in "METHODS" above).

hash_init

hash_<primitive>_init

my $multipart = hash_init($flags);

Same as "init".

CONSTANTS

hash_PRIMITIVE

my $default_primitive = hash_PRIMITIVE();

Same as "PRIMITIVE".

hash_BYTES

hash_<primitive>_BYTES

my $hash_size = hash_BYTES();

Same as "BYTES".

SEE ALSO

Crypt::Sodium::XS
https://doc.libsodium.org/advanced/sha-2_hash_function
https://libsodium.gitbook.io/doc/advanced/sha-3_hash_function

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.