Sodium

Overview

The Sodium module for Drupal provides an encryption method for the Encrypt module that allows symmetric encryption and decryption of data using the Sodium (libsodium) library and the Sodium extension provided by default in PHP (starting with version 7.2). A high-level cryptography interface is provided by the Halite PHP library.

Differences between 8.x-2.x and 3.0.x

8.x-2.x supports Drupal 8, 9, and 10. The halite library can be used up to version 5.0.

3.0.x supports Drupal 10.3 and 11. The halite library is supported from version 5.1.

There are no feature differences between 2.x and 3.x, and upgrading should be as simple as updating the module as long as you are using Drupal 10 or 11.

Requirements

Version 3.0.x

• PHP 8.1 or greater
• Halite PHP library 5.1+
• Encrypt module
• Key module

If you install this module with composer, all of the relevant dependencies will be pulled in.

Version 8.x-2.x

• PHP 7.2 or greater
• Sodium (libsodium) library
• Sodium PHP extension (included with PHP 7.2)
• Halite PHP library, version 4.0 or greater
• Encrypt module
• Key module

Add this module to your project using Composer. Halite will be installed automatically as a dependency, as will Encrypt and Key, if they aren't already required as dependencies of your project.

composer require drupal/sodium:^2.0

Version 8.x-1.x

Installation of version 8.x-1.x is not recommended, since it uses Halite 1.5.x and Halite versions lower than 4.0 are no longer supported. Version 8.x-1.x of the Sodium module will become unsupported at some point soon, so you are encouraged to upgrade as soon as possible to 8.x-2.x and migrate your encrypted data.

Migrating Encrypted Data

If you need to migrate data that was encrypted with Sodium 8.x-1.x (which uses Halite 1.5.x) to be decryptable by Sodium 8.x-2.x (which uses Halite >= 4.1), Halite-Legacy can be helpful.

Using Sodium in Encrypt

Once everything is installed and operational, do the following:

1. Generate a random 256-bit key
   • Option 1: Output your key to a file using a method such as the following:
     • dd if=/dev/urandom bs=32 count=1 > /path/to/secret.key (change the path and filename to suit your needs)
   • Option 2: Output your key to standard output and Base64-encode it so it can be copied and pasted:
     • dd if=/dev/urandom bs=32 count=1 | base64 -i -
2. Create a key definition using the Key module (at /admin/config/system/keys/add)
   • Select "Encryption" for the key type
   • Select "256" for the key size
   • Select your preferred key provider
     • Select "File" if you output your key to a file in the previous step; enter the path to the file; do not check "Base64-encoded" unless you Base64-encoded the key
     • Select "Configuration" if you copied your key, rather than outputing to a file ("Configuration" is fine for development and testing, but please use something more secure in a production environment); paste the key value and check "Base64-encoded"
     • Select another, more secure option if you've installed additional providers
   • Click "Save"
3. Create an encryption profile using the Encrypt module (at /admin/config/system/encryption/profiles/add)
   • Select "Sodium" for the encryption method
   • Select the name of the key definition you created in step 2
   • Click "Save"
4. Test your encryption by selecting "Test" under "Operations" for the encryption profile on the profiles listing page (/admin/config/system/encryption/profiles)