Using Libsodium in PHP Projects

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

Introduction to Libsodium Development in PHP

This e-book is intended for PHP developers with no prior cryptography experience. To that end, we will not go too in-depth to the nature of the lower-level cryptography features that each libsodium feature uses.

Towards the end of each chapter, we will link to other resources that explain the finer details for readers that are interested.

Let's jump right in, shall we?

To view the old API documentation, click here.

What is Libsodium?

(Copied from the Official Libsodium Documentation.)

The Sodium crypto library (libsodium) is a modern, easy-to-use software library for encryption, decryption, signatures, password hashing and more.

It is a portable, cross-compilable, installable, packageable fork of NaCl, with a compatible API, and an extended API to improve usability even further.

Its goal is to provide all of the core operations needed to build higher-level cryptographic tools.

Sodium supports a variety of compilers and operating systems, including Windows (with MinGW or Visual Studio, x86 and x64), iOS and Android.

The design choices emphasize security, and "magic constants" have clear rationales.

And despite the emphasis on high security, primitives are faster across-the-board than most implementations of the NIST standards.

Version 1.0.14 was released on September 21, 2017.

What is PECL Libsodium?

PECL Libsodium refers to the PHP extension available as a PECL package that exposes the libsodium API for PHP developers.

There are two important things to keep in mind here:

  1. The PECL package doesn't work unless you install libsodium. You need both.
  2. Just because libsodium has a feature doesn't mean it's available (or intended) for use by PHP developers.

What is ext/sodium?

Version 7.2.0 and newer of the PHP programming language includes the Sodium extension (referred to as ext/sodium) as a core cryptography library. Version 2 of the PHP extension in PECL is compatible with ext/sodium in PHP 7.2.

Which Version of the Extension Should I Install?

PHP Versions Supported PECL Version Libsodium Version
7.2 and newer 1.0.9 or newer
7.0, 7.1 2.0.7 1.0.9 or newer
5.4, 5.5, 5.6, 7.0, 7.1 1.0.6 1.0.3 or newer

Can We Use Libsodium on Older PHP and/or If We Cannot Install PHP Extensions?

You're looking for sodium_compat, which supports PHP 5.2 through 7.2, but doesn't support all of libsodium's features. In particular, it provides no password hashing algorithms.

Terms and Concepts

The remaining pages will proceed under the assumption that you have read these terms and and understood basic cryptography concepts.

  • Cryptography:
    A subset of computer science that focuses on secure communication.

  • Key:
    In cryptography, a key is a piece of information that determines the output of a cryptographic algorithm.

  • Nonce:
    A number that should only be used once (i.e. for a given key or set of keys).

  • Cryptographic hash functions (hashes):
    A deterministic one-way transformation of variable-length data into a fixed-size output -- by itself, a hash function does not use a key.

  • Secret-key Cryptography:
    Cryptographic algorithms and protocols where both participants share the same secret key.

  • Public-key Cryptography:
    Cryptographic algorithms and protocols where each participant possesses a private key and a related public key.

    Their private key is never shared; their public key is. The public key is always mathematically related to the private key, such that someone possessing the private key can generate the correct public key, but the opposite is not practical.

  • Encryption:
    The reversible transformation of data, with the use of one or more keys, to ensure the only someone possessing the correct key can read the contents of a given message.

  • Authentication:
    Provides assurance that a message was sent by someone in possession of the secret authentication key.

  • Digital Signature:
    Calculated from a message and a private key; allows anyone in possession of the message, signature, and public key to verify that a particular message is authentic.

Installing Libsodium and the PHP extension

Installing Libsodium (precompiled)

On Debian >= 8 and Ubuntu >= 15.04, libsodium can be installed with:

apt-get install libsodium-dev

If you're running an older LTS version of Ubuntu (e.g. 12.04), you can use one of these PPAs to get libsodium installed:

For example:

# If this doesn't work...
    sudo add-apt-repository ppa:chris-lea/libsodium
# Run these two lines instead...
    sudo echo "deb http://ppa.launchpad.net/chris-lea/libsodium/ubuntu precise main" >> /etc/apt/sources.list
    sudo echo "deb-src http://ppa.launchpad.net/chris-lea/libsodium/ubuntu precise main" >> /etc/apt/sources.list
# Finally...
sudo apt-get update && sudo apt-get install libsodium-dev

On OSX, libsodium can be installed with

brew install libsodium

On Fedora, libsodium can be installed with:

dnf install libsodium-devel

On RHEL and CentOS, libsodium can be installed from EPEL repository with:

yum install libsodium-devel

Installing Libsodium and the PHP Extension on Windows

On Windows, download the appropriate zip file for your version of PHP and then follow these three steps.

  1. For libsodium.dll, copy the DLL to %SYSTEM32% or the same directory as php.exe
  2. For php_libsodium.dll, copy it to the extension directory
    • The extension directory is usually, but not always, ext/ from the directory that contains php.exe
    • The extension_dir configuration directive in php.ini will point you in the right place
  3. Add extension=php_libsodium.dll to your php.ini file.

Installing Libsodium (from source)

If you're wanting the latest release of libsodium and it hasn't yet made its way into your operating system's package management repositories, the best option is to compile it from source.

Installing libsodium from source on OS X is easy; simply provide the --build-from-source flag when installing with brew:

brew install --build-from-source libsodium

For other operating systems, some prerequisites are necessary to build and install libsodium from source.

Debian-based distributions can install the necessary utilities with:

apt-get install build-essential

RHEL-based distributions can install the necessary utilities with:

yum groupinstall "Development Tools"

After installing the necessary utilities, libsodium can be compiled as such:

# Clone the libsodium source tree
git clone -b stable https://github.com/jedisct1/libsodium.git
# Build libsodium, perform any defined tests, install libsodium
cd libsodium && ./configure && make check && make install

Installing the PHP Extension via PECL

For PHP 7.2, you can skip this step. Just make sure you install your OS's equivalent of the php7.2-sodium package when you're installing PHP, and all these steps should be taken care of for you.


If you don't have the PECL package manager installed on your system, make sure you do that first. There are guides for installing PECL available on the Internet for virtually every operating system that PHP supports.

Once you have libsodium installed on your system, the next thing to do is to install the PHP extension. The easiest way to do this is to install the PECL package.

You can get ext/sodium by running this command.

pecl install libsodium

And add the following line to your php.ini file:

extension=sodium.so

You might be able to achieve this result by running phpenmod sodium or php5enmod sodium, depending on which webserver you use. Make sure you restart your webserver after installing ext/sodium.

Verifying your Libsodium Version

After installing both the library and the PHP extension, make a quick test script to verify that you have the correct version of libsodium installed.

<?php
var_dump([
    SODIUM_LIBRARY_MAJOR_VERSION,
    SODIUM_LIBRARY_MINOR_VERSION,
    SODIUM_LIBRARY_VERSION
]);

If you're using libsodium 1.0.14, you should see this when you run this test script:

user@hostname:~/dir$ php version_check.php
array(2) {
  [0] =>
  int(9)
  [1] =>
  int(6)
  [2] =>
  string(6) "1.0.14"
}

If you get different numbers, you won't have access to some of the features that should be in libsodium 1.0.14. If you need them, you'll need to go through the ritual of compiling from source instead (shown above).

Then run pecl uninstall libsodium and pecl install libsodium. When you run the version check PHP script again, you should see the correct numbers.

Extra Information