Real AES

Overview

Real AES provides an encryption method plugin for the Encrypt module. This plugin offers AES encryption using CBC mode and HMAC authentication through the Defuse PHP-Encryption library.

Requirements

• PHP 5.4 or later, with the OpenSSL extension
• Defuse PHP-Encryption library
  
  

  Real AES version	Defuse PHP-Encryption version
  8.x-2.x	2.x version of the library
  7.x-2.x	2.x version of the library
  7.x-1.x	A specific version of the library

Installation

8.x-2.x

Install the Drupal 8 version of Real AES using Composer, after ensuring that your composer.json file includes packages.drupal.org/8 as a repository:

composer require drupal/real_aes

7.x-2.x

Download the Real AES module and place it the usual location for contributed modules in your project. Download the PHP-Encryption library. Unzip the archive and install it as php-encryption in your libraries folder (Example: sites/all/libraries/php-encryption).

Download the PHP-Encryption autoload.php file. Unzip the archive and place it in the php-encryption directory (Example: sites/all/libraries/php-encryption/autoload.php).

If you are using a version of PHP < 7.0, you will also need to add the random_compat PHP library. Unzip the archive and install it as random_compat in your libraries folder (Example: sites/all/libraries/random_compat). For versions of PHP >= 7.0, this library is not needed.

7.x-1.x

Download the Real AES module and place it the usual location for contributed modules in your project. Download a specific version of the Defuse PHP-Encryption library, unzip the archive, name the resulting directory "php-encryption", and place it in your Libraries folder (Example: sites/all/libraries/php-encryption).

Upgrading from 7.x-1.x to 7.x-2.x

Since the key length requirement is different between the two versions, there is no upgrade path. Any encrypted data should be decrypted with 7.x-1.x and re-encrypted with 7.x-2.x.

Configuration

8.x-2.x

Configure your site for encryption in Drupal 8 as follows:

1. Enable Real AES, Encrypt, and Key
2. 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 -
3. Create a key 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 and enter provider-specific settings
     • The Configuration provider is fine for use during development, but should not be used on a production website
     • The File provider is more secure, especially if the file is stored outside of the web root directory
     • An even more secure option would be to use an off-site key management service, such as Lockr or Townsend Security's Alliance Key Manager
   • Click "Save"
4. Create an encryption profile using the Encrypt module (at
   /admin/config/system/encryption/profiles/add)
   • Select "Authenticated AES (Real AES)" for the encryption method
   • Select the name of the key definition you created in step 2
   • Click "Save"
5. Test your encryption by selecting "Test" under "Operations" for the
   encryption profile on the profiles listing page
   (/admin/config/system/encryption/profiles)

7.x-2.x

Configure your site for encryption in Drupal 7 as follows:

1. Enable Real AES and Encrypt
2. Create an encryption configuration using the Encrypt module (at
   /admin/config/system/encrypt/add)
   • Select "Authenticated AES (Real AES)" for the encryption method
   • Select your preferred key provider and enter provider-specific settings (your key should be 256 bits in length)
     • The Configuration provider is fine for use during development, but should not be used on a production website
     • The File provider is more secure, especially if the file is stored outside of the web root directory
     • An even more secure option would be to use an off-site key management service, such as Lockr or Townsend Security's Alliance Key Manager
   • Click "Save configuration"

7.x-1.x

Configure is the same as for the 7.x-2.x version, except the key needs to be 128 bits in length.

Usage in Drupal 7

• Use the Authenticated AES encryption method with the Encrypt module.
• If you implement encryption yourself, use this module as a library loader for Defuse PHP-Encryption. In your own code, include the library with libraries_load('php-encryption'), then call Crypto::encrypt, Crypto::decrypt and Crypto::createNewRandomKey directly.
• Real AES 7.x-1.x includes a submodule for the unsupported AES Encryption module.

About Authenticated Encryption

Authenticated encryption ensures data integrity of the ciphertext. When decrypting, integrity is checked first. Further decryption operations will only be executed when the integrity check passes. This prevents certain ciphertext attacks on AES in CBC mode.

Credits

This module was created by LimoenGroen after carefully considering the various encryption modules and libraries available.

The port to Drupal 8 was performed by Sven Decabooter, supported by Acquia.

The library doing the actual work, Defuse PHP-Encryption, is maintained by Taylor Hornby and Scott Arciszewski.