libsodium_utils (libsodium v3.0.1)
View SourceConstant-time comparisons, little-endian number arithmetic, hexadecimal, Base64 and IP address codecs, and ISO/IEC 7816-4 padding.
memcmp/2 and is_zero/1 run in constant time for a given length and are
the right way to compare secrets such as MACs and keys. compare/2,
increment/1, add/2, and sub/2 treat their binaries as unsigned
little-endian numbers (the layout of libsodium nonces and counters) and also
run in constant time for a given length. Functions taking two binaries
raise badarg unless both have the same length.
Base64 functions take a variant from base64_variants/0 (or its libsodium
integer value) and default to original. Decoding functions return -1
for malformed input.
Hex = libsodium_utils:bin2hex(<<"hi">>),
<<"6869">> = Hex,
<<"hi">> = libsodium_utils:hex2bin(Hex),
<<"aGk">> = libsodium_utils:bin2base64(<<"hi">>, urlsafe_no_padding),
<<"hi">> = libsodium_utils:base642bin(<<"aGk">>, urlsafe_no_padding),
<<1, 1>> = libsodium_utils:increment(<<0, 1>>),
0 = libsodium_utils:memcmp(<<"secret">>, <<"secret">>).Summary
Functions
Return (A + B) mod 2^(8 * byte_size(A)), treating both as unsigned
little-endian numbers. Raises badarg unless both have the same length.
Return the length of the Base64 Variant encoding of BinLen bytes,
including one extra byte for libsodium's trailing NUL; the binary
returned by bin2base64/2 is one byte shorter.
Return the Base64 variants accepted by base64_encoded_len/2,
bin2base64/2, and base642bin/2,3: the standard (original) and
URL-safe (urlsafe) alphabets, each with or without = padding.
Decode the Base64 B64 using Variant, skipping any characters in
Ignore. Variant defaults to original and Ignore to <<>>.
Decode the Base64 B64 using Variant, skipping any characters in
Ignore. Variant defaults to original and Ignore to <<>>.
Decode the Base64 B64 using Variant, skipping any characters in
Ignore. Variant defaults to original and Ignore to <<>>.
Return the Base64 encoding of Bin using Variant, in constant time.
Variant defaults to original.
Return the Base64 encoding of Bin using Variant, in constant time.
Variant defaults to original.
Return the lowercase hexadecimal encoding of Bin, in constant time.
Format the 16-byte address Bin as text: IPv4-mapped addresses as
dotted IPv4, others as compressed IPv6 (RFC 5952).
Compare B1 and B2 as unsigned little-endian numbers in constant time.
Returns -1 if B1 is less than B2, 1 if it is greater, and 0 if
they are equal. Raises badarg unless both have the same length.
Decode the hexadecimal Hex (either case), skipping any characters in
Ignore between byte pairs. Ignore defaults to <<>>, so no
separators are accepted.
Decode the hexadecimal Hex (either case), skipping any characters in
Ignore between byte pairs. Ignore defaults to <<>>, so no
separators are accepted.
Return N plus one, treating it as an unsigned little-endian number of
the same length; the carry out of the last byte is discarded, so an
all-255 binary wraps around to zero.
Parse the IPv4 or IPv6 address Ip (an IPv6 address may carry a
%zone suffix, which is discarded) into its 16-byte IPv6 form; IPv4
addresses become IPv4-mapped IPv6 addresses. Returns -1 if Ip is
not a valid address.
Return 1 if every byte of N is zero (checked in constant time), otherwise 0.
Compare the secrets B1 and B2 in constant time. Returns 0 when they
are equal and -1 otherwise; this is not a lexicographic comparison.
Raises badarg unless both have the same length.
Pad UnpaddedBuf to a multiple of Blocksize bytes using the ISO/IEC
7816-4 scheme (a 16#80 byte followed by zeros); at least one byte is
always added. Raises badarg if Blocksize is 0 or the padded length
would overflow.
Return (A - B) mod 2^(8 * byte_size(A)), treating both as unsigned
little-endian numbers. Raises badarg unless both have the same length.
Remove the ISO/IEC 7816-4 padding added by pad/2 from PaddedBuf.
Returns -1 if the padding is invalid or Blocksize is 0 or larger
than PaddedBuf.
Types
Functions
Return (A + B) mod 2^(8 * byte_size(A)), treating both as unsigned
little-endian numbers. Raises badarg unless both have the same length.
-spec base64_encoded_len(BinLen, Variant) -> Result when BinLen :: non_neg_integer(), Variant :: original | original_no_padding | urlsafe | urlsafe_no_padding | integer(), Result :: non_neg_integer().
Return the length of the Base64 Variant encoding of BinLen bytes,
including one extra byte for libsodium's trailing NUL; the binary
returned by bin2base64/2 is one byte shorter.
-spec base64_variants() -> Result
when
Result ::
[original | original_no_padding | urlsafe | urlsafe_no_padding, ...].
Return the Base64 variants accepted by base64_encoded_len/2,
bin2base64/2, and base642bin/2,3: the standard (original) and
URL-safe (urlsafe) alphabets, each with or without = padding.
Decode the Base64 B64 using Variant, skipping any characters in
Ignore. Variant defaults to original and Ignore to <<>>.
Returns -1 if B64 is malformed for the variant, including missing or
unexpected padding.
-spec base642bin(B64, Variant) -> Result when B64 :: binary(), Variant :: original | original_no_padding | urlsafe | urlsafe_no_padding | integer(), Result :: binary() | -1.
Decode the Base64 B64 using Variant, skipping any characters in
Ignore. Variant defaults to original and Ignore to <<>>.
Returns -1 if B64 is malformed for the variant, including missing or
unexpected padding.
-spec base642bin(B64, Ignore, Variant) -> Result when B64 :: binary(), Ignore :: binary(), Variant :: original | original_no_padding | urlsafe | urlsafe_no_padding | integer(), Result :: binary() | -1.
Decode the Base64 B64 using Variant, skipping any characters in
Ignore. Variant defaults to original and Ignore to <<>>.
Returns -1 if B64 is malformed for the variant, including missing or
unexpected padding.
Return the Base64 encoding of Bin using Variant, in constant time.
Variant defaults to original.
-spec bin2base64(Bin, Variant) -> Result when Bin :: binary(), Variant :: original | original_no_padding | urlsafe | urlsafe_no_padding | integer(), Result :: binary().
Return the Base64 encoding of Bin using Variant, in constant time.
Variant defaults to original.
Return the lowercase hexadecimal encoding of Bin, in constant time.
Format the 16-byte address Bin as text: IPv4-mapped addresses as
dotted IPv4, others as compressed IPv6 (RFC 5952).
Compare B1 and B2 as unsigned little-endian numbers in constant time.
Returns -1 if B1 is less than B2, 1 if it is greater, and 0 if
they are equal. Raises badarg unless both have the same length.
Decode the hexadecimal Hex (either case), skipping any characters in
Ignore between byte pairs. Ignore defaults to <<>>, so no
separators are accepted.
Returns -1 if Hex contains an invalid character or an incomplete pair.
-spec hex2bin(Hex, Ignore) -> Result when Hex :: binary(), Ignore :: binary(), Result :: binary() | -1.
Decode the hexadecimal Hex (either case), skipping any characters in
Ignore between byte pairs. Ignore defaults to <<>>, so no
separators are accepted.
Returns -1 if Hex contains an invalid character or an incomplete pair.
Return N plus one, treating it as an unsigned little-endian number of
the same length; the carry out of the last byte is discarded, so an
all-255 binary wraps around to zero.
Parse the IPv4 or IPv6 address Ip (an IPv6 address may carry a
%zone suffix, which is discarded) into its 16-byte IPv6 form; IPv4
addresses become IPv4-mapped IPv6 addresses. Returns -1 if Ip is
not a valid address.
-spec is_zero(N) -> Result when N :: binary(), Result :: 0 | 1.
Return 1 if every byte of N is zero (checked in constant time), otherwise 0.
Compare the secrets B1 and B2 in constant time. Returns 0 when they
are equal and -1 otherwise; this is not a lexicographic comparison.
Raises badarg unless both have the same length.
-spec pad(UnpaddedBuf, Blocksize) -> Result when UnpaddedBuf :: binary(), Blocksize :: pos_integer(), Result :: binary() | -1.
Pad UnpaddedBuf to a multiple of Blocksize bytes using the ISO/IEC
7816-4 scheme (a 16#80 byte followed by zeros); at least one byte is
always added. Raises badarg if Blocksize is 0 or the padded length
would overflow.
Return (A - B) mod 2^(8 * byte_size(A)), treating both as unsigned
little-endian numbers. Raises badarg unless both have the same length.
-spec unpad(PaddedBuf, Blocksize) -> Result when PaddedBuf :: binary(), Blocksize :: non_neg_integer(), Result :: binary() | -1.
Remove the ISO/IEC 7816-4 padding added by pad/2 from PaddedBuf.
Returns -1 if the padding is invalid or Blocksize is 0 or larger
than PaddedBuf.