Skip to content

Easy Encryption#

Overview#

Easy Encryption provides a zero-configuration solution for securing sensitive data and credentials at rest in Drupal. Born from discussions in the META issue to improve security of AI and VDB provider credential storage and created specifically to address insecure credential storage concerns in Drupal CMS, 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 using modern cryptography (libsodium's sealed box encryption). It requires no manual configuration to get started, making security both practical and achievable for site builders and developers alike.

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)
  • 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
  • Asymmetric encryption: Uses public-key cryptography for flexible deployment scenarios
  • Exportable configuration: Encrypted values can be safely committed to version control
  • Multi-environment support: Encrypt on development, decrypt in production
  • Key rotation: Built-in support for rotating encryption keys via CLI
  • Uninstall protection: Prevents accidental uninstallation while encrypted keys exist
  • Modern cryptography: Built on libsodium's authenticated encryption primitives

How it works#

Easy Encryption uses sealed box encryption (libsodium's crypto_box_seal), which is asymmetric public-key encryption. Here's what happens:

Initial setup#

When you install the module, it automatically generates 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.

Both keys are stored as Key entities and can be managed through Drupal's Key module interface.

Encrypting credentials#

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

  1. Your sensitive value is encrypted using the public key
  2. The encrypted ciphertext is stored in configuration
  3. A reference to the key pair 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 key pair using the stored key pair ID
  2. The private key decrypts the ciphertext
  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 using the public key and stored as ciphertext in configuration alongside the key pair identifier.

Using encrypted keys in code#

Encrypted keys work exactly like any other Key entity:

$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 pair status#

Visit Reports > Status report to verify:

  • An active key pair 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 key pair and marks it as active. Existing encrypted values remain decryptable with their original keys unless you use the --reencrypt option.

Configuration#

Private key directory#

To change where the private key is stored, add this to your settings.php:

$settings['easy_encryption']['private_key_directory'] = '/secure/path/outside/webroot';

Make sure this directory: - Exists and is writable by the web server - Is outside the web root - Is excluded from version control - Has appropriate filesystem permissions

Encrypt-only environments#

Some deployment workflows use "encrypt-only" environments where credentials are encrypted on a development machine but the private key is not deployed to all environments.

Easy Encryption supports this workflow:

  1. Encrypt credentials on your development or CI environment (where the private key exists)
  2. Export configuration containing the encrypted values and public key
  3. Deploy to production with only the public key
  4. Production can encrypt new values but cannot decrypt (the private key is not present)

This is useful for security-conscious workflows where production environments should not have access to decrypt all credentials.

Architecture#

Easy Encryption is built with security and maintainability in mind:

  • Immutable value objects: Key pairs and encrypted values are immutable objects that prevent accidental modification
  • Exception hierarchy: Clear exception types for different failure scenarios
  • Memory safety: Private keys are cleared from memory immediately after use using sodium_memzero()
  • Type safety: Uses PHP 8.3+ features like typed properties and the #[\SensitiveParameter] attribute
  • Layered design: Separates cryptographic operations, key management, and Drupal integration

Security considerations#

What this module protects against#

  • Accidental exposure of credentials in configuration files
  • Credentials leaked through configuration exports
  • Credentials visible to users who have access to view configuration

What this module does NOT protect against#

  • Server compromise where an attacker gains filesystem or database access
  • Compromised private keys
  • Runtime memory inspection attacks
  • Social engineering or credential phishing

Easy Encryption improves your security posture significantly, but it is not a substitute for proper server hardening, access controls, and operational security practices.

Best practices#

  1. Never commit the private key: Add .easy_encryption to your .gitignore
  2. Restrict file permissions: The module sets private key files to 0600, but verify this on your server
  3. Use environment-specific keys: Consider using different key pairs per environment
  4. Rotate keys periodically: Establish a key rotation policy for compliance
  5. Monitor key access: Review logs for unexpected decryption failures
  6. Upgrade to external KMS: For production, migrate private keys to a dedicated key management system