Utilities and Helpers
These functions are useful in general, regardless of which cryptographic utility your application needs.
Hexadecimal Encoding
string \Sodium\bin2hex(string $binary)
Libsodium offers a variant of PHP's bin2hex() feature designed to be resistant
to side-channel attacks. You can use it just like PHP's bin2hex() function:
$hex_string = \Sodium\bin2hex($binary_string);
Hexadecimal Decoding
string \Sodium\hex2bin(string $hex, string $ignore = '')
Similar to above, libsodium also offers a complementary function for the inverse operation.
$binary_string = \Sodium\hex2bin($hex_string);
Libsodium's hex2bin() also accepts a second optional string argument for
characters to ignore. This is useful if, for example, you want to convert an
IPv6 address into a raw binary string without the : separators breaking your
algorithm.
$binary = \Sodium\hex2bin($ipv6_addr, ':');
Like \Sodium\bin2hex(), \Sodium\hex2bin() is resistant to side-channel
attacks while PHP's built-in function is not.
Wiping Sensitive Data from Memory
void \Sodium\memzero(&string $secret);
When you are done handling sensitive information, use \Sodium\memzero() to erase
the contents of a variable.
Warning: If you're running PHP 7, make sure you're using version 1.0.1 of the PHP extension before using this function.
$ciphertext = \Sodium\crypto_secretbox($message, $nonce, $key);
\Sodium\memzero($message);
\Sodium\memzero($key);
Incrementor for Sequential Nonces
void \Sodium\increment(&string $binary_string)
If you need to increment a value (e.g. given a randomly generated nonce, obtain
the next nonce), use \Sodium\increment().
Warning: If you're running PHP 7, make sure you're using version 1.0.1 of the PHP extension before using this function.
$x = \Sodium\randombytes_buf(\Sodium\CRYPTO_SECRETBOX_NONCEBYTES);
// After an encryption
\Sodium\increment($x);
Constant-Time String Comparison
int \Sodium\compare(string $str1, string $str2)
Timing-safe variant of PHP's native strcmp().
Returns -1 if $str1 is less than $str2; 1 if $str1 is greater than $str2,
and 0 if they are equal. This is mostly useful for comparing nonces to prevent
replay attacks.
Example:
if (\Sodium\compare($message['nonce'], $expected_nonce) === 0) {
// Proceed with crypto_box decryption
}
Constant-Time Memory Equality Comparison
int \Sodium\memcmp(string $a, string $b)
Compare two strings in constant time. (Similar to hash_equals().)
- Returns 0 if successful
- Returns -1 otherwise
Example:
if (\Sodium\memcmp($mac, $given_mac) !== 0) {
// Failure
}
Libsodium Version Checks
int \Sodium\library_version_major()
Returns the major version of the current version of the sodium library installed.
var_dump(\Sodium\library_version_major());
# int(7)
int \Sodium\library_version_minor()
Returns the minor version of the current version of the sodium library installed.
var_dump(\Sodium\library_version_minor());
# int(6)
string \Sodium\version_string()
Returns a string identifier of the current version of the sodium library installed. (This is irrelevant to the version of the PHP extension!)
var_dump(\Sodium\version_string());
# string(5) "1.0.4"