Easy Encryption provides a zero-configuration solution for securing sensitive data and credentials at rest in Drupal. Born from discussions in #3559052: [META] Improve security of AI and VDB provider credential storage and created specifically to address #3560518: Insecure credential storage used by drupal_cms_ai recipe as default, this module aims to make encryption accessible to all Drupal users without requiring cryptography expertise.

The module integrates seamlessly with the Key module to automatically encrypt sensitive values. By default it uses libsodium sealed box encryption, but the module’s public APIs are designed around encryption keys and key IDs (rather than a specific cryptography backend), so implementations can be swapped.

Why this module exists

Drupal CMS and many contributed modules handle sensitive credentials such as API keys, database passwords, and authentication tokens. Historically, these credentials were often stored in plain text in configuration or the database, creating security risks if configuration files were accidentally exposed or databases were compromised.

Easy Encryption was developed to solve this problem by:

  • Providing encryption that works out of the box with zero configuration
  • Using modern, audited cryptography (libsodium by default)
  • Integrating with Drupal's existing Key module ecosystem
  • Supporting secure workflows for teams and multi-environment deployments
  • Making encrypted configuration safely exportable and version-controllable

Features

  • Zero-configuration setup: Install and start encrypting immediately
  • Encryption keys with stable IDs: Encrypted values carry an encryption key ID so the right key can be used for decryption
  • Exportable configuration: Encrypted values can be safely committed to version control
  • Multi-environment support: Encrypt in development or CI, decrypt in production (where the private key is available)
  • Key rotation: Built-in support for rotating encryption keys via CLI
  • Transparent credential security upgrades: Automatically upgrades insecure keys (Config/State) to the Easy Encrypted provider upon creation. This works seamlessly for manual entry, Recipes, and automation, ensuring sensitive credentials never touch your storage in plaintext.
  • Uninstall protection: Prevents accidental uninstallation while encrypted keys exist
  • Pluggable cryptography backend: Ships with a libsodium sealed box encryptor by default, but can be swapped via the provided APIs
  • Provider upgrade safety: New keys created with insecure providers (such as config and state) are automatically upgraded to Easy Encrypted before being saved, which prevents plaintext credential storage and avoids data loss for recipe and automation-created keys
  • Admin UI (optional): Install the Easy Encryption Admin module to manage encryption key import and export in the UI (key transfer)

How it works

Easy Encryption’s primary abstractions are an encryption key and an encryption key ID. By default, encryption keys are backed by a libsodium sealed box key pair (public and private key), but most users only need to understand when a public key is required (encrypt) and when a private key is required (decrypt).

Initial setup

When you install the module, it automatically generates an encryption key and assigns it an encryption key ID.

In the default implementation, that encryption key is stored as a key pair consisting of:

  • Public key: Used for encryption. Safe to export and commit to your repository.
  • Private key: Used for decryption. Must be kept secure and never committed to version control.

Encrypting credentials

When you create a Key entity using the "Easy Encrypted" provider:

  1. Your sensitive value is encrypted
  2. The encrypted ciphertext is stored in configuration
  3. A reference to the encryption key ID is stored alongside the ciphertext
  4. The configuration can be safely exported and committed to your repository

Decrypting credentials

When Drupal needs to use an encrypted credential:

  1. The module loads the appropriate encryption key using the stored encryption key ID
  2. The private key decrypts the ciphertext (in the default implementation)
  3. The plaintext credential is returned to the calling code
  4. The private key is immediately cleared from memory

Key storage locations

By default, the private key is stored in a directory called .easy_encryption next to your web root, with restricted file permissions (0600). The key is wrapped in PHP code so that even if accidentally exposed via the web, it produces no output.

If file storage fails, the private key falls back to Drupal's state system (database storage). This is less secure than file-based storage but still not publicly accessible.

Important: Do NOT commit the .easy_encryption directory or its contents to version control.

For production environments, consider moving the private key to more secure storage:

  1. Environment variables (better): Store the private key in an environment variable using the Key module's Environment provider
  2. External key management (best): Use a dedicated secrets manager like HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault

While these approaches require additional configuration, Easy Encryption gives you meaningful security improvement with zero configuration, then allows you to enhance security as your needs grow.

Usage

Creating an encrypted key

  1. Navigate to Configuration > System > Keys (/admin/config/system/keys)
  2. Click Add key
  3. Fill in the key label and description
  4. For Key provider, select Easy Encrypted
  5. Enter your sensitive value (API key, password, etc.)
  6. Save the key

When you create a Key entity using the "Easy Encrypted" provider (the module sets this as the default option), your sensitive value is encrypted and stored as ciphertext in configuration alongside the encryption key identifier.

Using encrypted keys in code

Encrypted keys work exactly like any other Key entity:

<?php
$key = \Drupal::service('key.repository')->getKey('my_api_key');
$api_key_value = $key->getKeyValue();

// Use $api_key_value to authenticate with an external API.

Checking key status

Visit Reports > Status report to verify:

  • An active encryption key is configured
  • The private key is available (for environments that need decryption)

Rotating keys

If you need to rotate your encryption keys (for compliance or security):

drush easy-encryption:rotate

This generates a new encryption key and marks it as active. Existing encrypted values remain decryptable with their original keys unless you use the --reencrypt option.

Admin UI (Easy Encryption Admin)

Easy Encryption also ships with an optional admin module: Easy Encryption Admin. It adds UI screens for importing and exporting Easy Encryption encryption keys, so key transfer is not Drush-only anymore.

The admin UI is currently focused on key transfer. For planned admin features, see issues tagged with the