Using Libsodium in PHP Projects

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

Basic Secret-key Cryptography

Secret-key cryptography is used when only the intended participants of a communication are in possession of the same secret key. This can be the result of a shared password (see Chapter 8) or Diffie Hellman key agreement (see Chapter 9).

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.

Contrast with Public-key cryptography.

Secret-key Authenticated Encryption

Libsodium makes secret-key encryption a breeze. Instead of having to understand the fine details of encryption versus authentication, you only need to know two functions.

Encrypt a message

string sodium_crypto_secretbox(string $plaintext, string $nonce, string $key)

This operation:

  • Encrypts a message with a key and a nonce to keep it confidential
  • Computes an authentication tag. This tag is used to make sure that the message hasn't been tampered with before decrypting it.

A single key is used both to encrypt/sign and verify/decrypt messages. For this reason, it is critical to keep the key confidential.

The same message encrypted with the same key, but with two different nonces, will produce two totally different ciphertexts.

The nonce doesn't have to be confidential, but it should never ever be reused with the same key. The easiest way to generate a nonce is to use random_bytes().

// Generating your encryption key
$key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);

// Using your key to encrypt information
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$ciphertext = sodium_crypto_secretbox('test', $nonce, $key);

Decrypt a message

string|bool sodium_crypto_secretbox_open(string $ciphertext, string $nonce, string $key)

Decrypting a message requires the same nonce and key that was used to encrypt it.

$plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
if ($plaintext === false) {
    throw new Exception("Bad ciphertext");
}

Secret-key Authentication

Sometimes you don't need to hide the contents of a message with encryption, but you still want to ensure that nobody on the network can tamper with it. For example, if you want to eschew server-side session storage and instead use HTTP cookies as your storage mechanism.

First you need an encryption key that is SODIUM_CRYPTO_AUTH_KEYBYTES long.

$key = random_bytes(SODIUM_CRYPTO_AUTH_KEYBYTES);

Authenticating a Message

string sodium_crypto_auth(string $message, string $key);

This calculates a Message Authentication Code (MAC) of a given $message with a given secret $key. Typically you want to prepend or append the MAC to the message before sending it.

$message = json_encode($some_array);
$mac = sodium_crypto_auth($message, $key);
$outbound = $mac . $message;

Verifying the Authenticity of a Message

bool sodium_crypto_auth_verify(string $mac, string $message, string $key)

This function returns TRUE if the given $mac is valid for a particular $message and $key. Otherwise it returns FALSE. This operation is constant-time and side-channel resistant.

if (sodium_crypto_auth_verify($mac, $message, $key)) {
    $data = json_decode($message, true);
} else {
    sodium_memzero($key);
    throw new Exception("Malformed message or invalid MAC");
}

Extra Information