Modern Cryptography in PHP 72
November 6, 2018

Sodium: Modern Cryptography Library that Works With PHP 7.2

PHP Development
Zend Server

Recently, at ZendCon & OpenEnterprise 2018, I presented a session about the usage of Sodium in PHP 7.2. Here you can find the slides of this session.

Sodium is a powerful library for modern cryptography. It is a portable, cross-compilable, installable and packageable fork of NaCl, a famous cryptographic tool designed by Prof. D.J. Bernstein.

Sodium details

Sodium (and NaCl) is an “opinionated” library: this means the algorithms used have been selected and cannot be changed. The library uses some of the most robust algorithms available, including Elliptic-curve cryptography (ECC). Some of the algorithms used by Sodium are:

If you need to use different algorithms, for instance for compatibility reason with existing cryptosystems, you need to look for a different library (e.g. OpenSSL).

Apart from the selection of the best algorithms available, Sodium (and NaCl) has been designed to prevent side-channel attacks. This is a very good point for security because the majority of attacks are based on issues in the implementations, rather than weaknesses in the algorithm itself.

Just to give you an idea, one of the most successful side-channel attacks in history was performed by Adi Shamir, Eran Tromer, and Dag Arne Osvik in 2006 to discover, in **65 milliseconds**, the secret key used in widely deployed software for hard-disk encryption (here is the extended article).

PHP developers can use the advantages of Sodium starting from PHP 7.2. For PHP 7.0 or 7.1, you need to install a PECL extension.

Sodium use cases

In my talk at ZendCon & OpenEnterprise, I covered the basic usage of Sodium showing six different use cases:

Encrypt/Authenticate with a shared key: This is an example of how to encrypt and/or authenticate a string using a shared-key (i.e. symmetric encryption). Sodium uses the XSalsa20 algorithm to encrypt and HMAC-SHA512 for the authentication.

Sending secret messages: This example shows how to encrypt a message in a end-to-end scenario (e.g. a user wants to send a secret message to another user). Here, Sodium uses the algorithms XSalsa20 to encrypt, Poly1305 for MAC, and XS25519 for key exchange.

Digital signature: This example shows how to generate a digital signature for a string (e.g. a message/file). Here, Sodium uses an Elliptic Curve algorithm, Ed25519.

Authenticated encryption with AES-GCM: Sodium offers authenticated encryption using the AES algorithm with Galois/Counter Mode (GCM).

Store passwords safely: This is an important topic for PHP developers. The first suggestion is to never encrypt it, always store a hash value of the password. The hash algorithm used by Sodium is Argon2i. This algorithm is resistant to side-channel attacks and GPU cracking attacks.

Derive a key from a user's password: This example shows how to generate an encryption key starting from a user's password (using the Argon2i algorithm). REMEMBER: __never use a user's password as the encryption key!__

Code sample

The Sodium APIs are quite simple to use. Just to give you an idea, here’s example code on how to encrypt a message with a shared-key:

$msg = 'This is a super secret message!';

// Generating an encryption key and a nonce
$key   = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES); // 256 bit
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES); // 24 bytes

// Encrypt
$ciphertext = sodium_crypto_secretbox($msg, $nonce, $key);
// Decrypt
$plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);

echo $plaintext === $msg ? 'Success' : 'Error';


And here how to authenticate a message (without encryption):

$msg = 'This is the message to authenticate!';
$key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES); // 256 bit

// Generate the Message Authentication Code
$mac = sodium_crypto_auth($msg, $key);

// Altering $mac or $msg, verification will fail
echo sodium_crypto_auth_verify($mac, $msg, $key) ? 'Success' : 'Error';


To see more PHP code examples, see the slides from my ZendCon & OpenEnterprise 2018 talk.

View Presentation

Haven't upgraded to PHP 7? See the common reasons development teams aren't upgrading and why they should here. Zend Server has the long-term support you need.