Hashing
Cryptographic hash functions take arbitrary-length inputs and deterministically produce a fixed-size output.
Generic Hashing
string \Sodium\crypto_generichash(string $msg, string $key = null, string $length = 32)
This function computes a fixed-length fingerprint for an arbitrary long message. This might be useful for:
- File integrity checking
- Creating unique identifiers to index arbitrary long data
Examples:
// Fast, unkeyed hash function.
// Can be used as a secure replacement for MD5
$h = \Sodium\crypto_generichash('msg');
// Fast, keyed hash function.
// The key can be of any length between \Sodium\CRYPTO_GENERICHASH_KEYBYTES_MIN
// and \Sodium\CRYPTO_GENERICHASH_KEYBYTES_MAX, in bytes.
// \Sodium\CRYPTO_GENERICHASH_KEYBYTES is the recommended length.
$h = \Sodium\crypto_generichash('msg', $key);
// Fast, keyed hash function, with user-chosen output length, in bytes.
// Output length can be between \Sodium\CRYPTO_GENERICHASH_BYTES_MIN and
// \Sodium\CRYPTO_GENERICHASH_BYTES_MAX.
// \Sodium\CRYPTO_GENERICHASH_BYTES is the default length.
$h = \Sodium\crypto_generichash('msg', $key, 64);
Multi-part Generic Hashing
// Deterministic hash function, multi-part message
$state = \Sodium\crypto_generichash_init();
\Sodium\crypto_generichash_update($state, 'message part 1');
\Sodium\crypto_generichash_update($state, 'message part 2');
$h = \Sodium\crypto_generichash_final();
// Keyed hash function, multi-part message
$state = \Sodium\crypto_generichash_init($key);
\Sodium\crypto_generichash_update($state, 'message part 1');
\Sodium\crypto_generichash_update($state, 'message part 2');
$h = \Sodium\crypto_generichash_final();
// Keyed hash function, multi-part message with user-chosen output length
$state = \Sodium\crypto_generichash_init($key, 64);
\Sodium\crypto_generichash_update($state, 'message part 1');
\Sodium\crypto_generichash_update($state, 'message part 2');
$h = \Sodium\crypto_generichash_final(64);
Short Hashing
string \Sodium\crypto_shorthash(string $message, string $key)
Many applications and programming language implementations were recently found to be vulnerable to denial-of-service attacks when a hash function with weak security guarantees, such as Murmurhash 3, was used to construct a hash table.
In order to address this, Sodium provides the crypto_shorthash() function,
which outputs short but unpredictable (without knowing the secret key) values
suitable for picking a list in a hash table for a given key.
// $key must be \Sodium\CRYPTO_SHORTHASH_KEYBYTES (16 bytes, 128 bits) long
$h = \Sodium\crypto_shorthash('message', $key);
This function has been optimized for short messages. Its short output length doesn't make it collision resistant.
Typical uses for \Sodium\crypto_shorthash() are:
- Building data structures such as hash tables and bloom filters.
- Adding authentication tags to network traffic.
When in doubt, use \Sodium\crypto_generichash() instead. Unless you are trying
to hash a password. (See Chapter 8 if you need to
handle user-provided secrets.)