Using Libsodium in PHP Projects

A guide to using the libsodium PHP extension for modern, secure, and fast cryptography. Open Source.


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


// 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
// \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 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.)

Extra Information