Using Libsodium in PHP Projects

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

Hashing

Cryptographic hash functions take arbitrary-length inputs and deterministically produce a fixed-size output.

Before you decide whether or not to use a feature, check the quick reference page, which explains what each function does and where each should be used.

To view the old API documentation, click here.

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

Extra Information