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

Crypt::Sodium::XS::Util - libsodium utilities

SYNOPSIS

use Crypt::Sodium::XS::Util ':all';

...

DESCRIPTION

Provides access to libsodium-provided utilities. IMPROVEME.

NOTE: Except where otherwise mentioned (see "sodium_random_bytes"), these functions are not intended for use with sensitive data. Crypt::Sodium::XS::MemVault provides much of the same functionality for use with sensitive data.

FUNCTIONS

Nothing is exported by default. The tag :functions imports all "FUNCTIONS". The tag :all imports everything.

sodium_add

my $sum = sodium_add($bytes, $other_bytes);

Add $other_bytes to $bytes as arbitrarily long little-endian unsigned numbers. This function runs in constant time for a given length.

Byte strings may be of arbitrary size. $sum will be the size of the larger operand. Addition wraps if $sum would overflow.

sodium_bin2hex

my $string = sodium_bin2hex($bytes);

No real advantage over unpack("H*", $bytes).

sodium_compare

my $lt_eq_or_gt = sodium_compare($bytes, $other_bytes, $size);

Returns 0 if the bytes are equal, -1 if $bytes is less than $other_bytes, or 1 if $mv is greater. This function runs in fixed-time (for a given size), and compares bytes as little-endian arbitrary-length integers. Comparible to the cmp perl operator.

$size is optional iif $bytes and $other_bytes are equal sizes. If provided, only $size bytes are compared.

Note: This function is similar to memcmp(3); that is, it returns -1, 0, or 1 for the comparison results. For simple true/false equality comparisons, see "sodium_memcmp". The naming is chosen here to be consistent with libsodium.

sodium_hex2bin

my $bytes = sodium_hex2bin($string);

No real advantage over pack("H*", $bytes). Stops parsing at any invalid hex bytes ([0-9a-f] case insensitive). $bytes will be empty if $string could not be validly interpreted as hex (i.e., if the output would not be a multiple of 8 bits.)

sodium_increment

my $incremented = sodium_increment($bytes);

Interpret $bytes as an arbitrarily long little-endian unsigned number and add one to it. This is intended for the return values of nonce functions. This function runs in constant time for a given $bytes size. Incrementing wraps if $incremented would overflow.

sodium_is_zero

my $is_zero = sodium_is_zero($bytes)

Returns true iif $bytes consists only of null bytes. Returns false otherwise. This function runs in constant time for a given $bytes length.

sodium_memcmp

my $is_equal = sodium_memcmp($bytes, $other_bytes, $size);

Returns true if the operands are exactly equal, false otherwise. This method runs in fixed-time (for a given size), and compares bytes as little-endian arbitrary-length integers.

$size is optional iif $bytes and $other_bytes are equal sizes. If provided, only $size bytes are compared. Note: Croaks if operands are unequal sizes and $size was not provided, or if $size is larger than either of the operands.

When a comparison involves secret data (e.g. a key, a password, etc.), it is critical to use a constant-time comparison function. This property does not relate to computational complexity: it means the time needed to perform the comparison is the same for all data of the same size. The goal is to mitigate side-channel attacks.

Note: "sodium_memcmp" is different than memcmp(3). This method returns only true/false for equality, not -1, 0, or 1 for the comparison results. For that, see "sodium_compare". The naming is chosen here to be consistent with libsodium.

sodium_pad

sodium_unpad

my $padded = sodium_pad($bytes, $blocksize);
my $unpadded = sodium_unpad($bytes, $blocksize);

Returns $bytes padded or unpadded respectively, to the next multiple of $blocksize bytes.

These functions use the ISO/IEC 7816-4 padding algorithm. It supports arbitrary block sizes, ensures that the padding data are checked for computing the unpadded length, and is more resistant to some classes of attacks than other standard padding algorithms.

Notes:

    Padding should be applied before encryption and removed after decryption.

    Usage of padding to hide the length of a password is not recommended. A client willing to send a password to a server should hash it instead, even with a single iteration of the hash function.

    This ensures that the length of the transmitted data is constant and that the server doesn’t effortlessly get a copy of the password.

    Applications may eventually leak the unpadded length via side channels, but the sodium_pad() and sodium_unpad() functions themselves try to minimize side channels for a given length & <block size mask> value.

sodium_random_bytes

my $bytes = sodium_random_bytes($num_of_bytes, $use_memory_vault, $flags);

Generates unpredictable sequence of $num_of_bytes bytes.

The length of the returned $bytes equals $num_of_bytes.

Depending on the boolean $use_memory_vault, returns either a plain scalar (if false or omitted), or a Crypt::Sodium::XS::MemVault object (if true). Either will contain $num_of_bytes bytes of random data. For generating random keys and nonces, it is preferable to use the provided *_keygen(), *_keypair(), and *_nonce() functions.

If $use_memory_vault is true, $flags will be the memory protection flags of the returned object. See Crypt::Sodium::XS::ProtMem. The default is "protmem_flags_memvault_default" in Crypt::Sodium::XS::ProtMem.

sodium_sub

my $diff = sodium_sub($bytes, $other_bytes);

Subtract $other_bytes from $bytes as arbitrarily long little-endian unsigned numbers. This function runs in constant time for a given length.

Byte strings may be of arbitrary size. $diff will be the size of the larger operand. Subtraction wraps if $diff would overflow.

sodium_memzero

sodium_memzero($x);
sodium_memzero($x, $y, $z, ...);

Helper utility for clearing out sensitive memory contents. The PV values of any given arguments will be overwritten with (the same length of) null bytes.

SEE ALSO

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.