Download the PHP package paperscissorsandglue/laravel-encryption-at-rest without Composer

Laravel Encryption at Rest

A Laravel package for encrypting sensitive data at rest and automatically decrypting it when in use. Useful for regulatory compliance requirements like GDPR, HIPAA, and other data protection standards. Compatible with Laravel 10, 11, and 12.

Features

• ✅ Encrypt user identifiable data at rest and decrypt while being used
• ✅ Encrypt specific fields within JSON columns
• ✅ Special handling for email addresses with searchable indexes
• ✅ Seamless integration with Laravel's authentication system
• ✅ Compatible with Laravel notifications and other subsystems
• ✅ Command-line tools for migrating existing data
• ✅ Simple trait-based implementation for models

Requirements

• PHP 8.1 or higher
• Laravel 10.x, 11.x, or 12.x

Installation

You can install the package via composer:

After installation, publish the configuration file:

Configuration

In your .env file, you can optionally set a custom encryption key:

If not set, the package will use your application key for encryption.

Basic Usage

Add the Encryptable trait to your model and define which attributes should be encrypted:

That's it! The specified attributes will be automatically encrypted when saved to the database and decrypted when retrieved.

Encrypting JSON Fields

For JSON columns where you only want to encrypt certain fields within the JSON structure, use the EncryptableJson trait:

With this setup, only the specified fields within your JSON structure will be encrypted while the rest of the JSON remains searchable.

Seamless Encryption/Decryption

This package uses smart dynamic getters and setters to handle all encryption and decryption transparently. All encrypted fields, including email, are automatically:

• Encrypted when saved to the database
• Decrypted when accessed through any means
• Properly handled in all Laravel subsystems

This universal approach means you don't need to write any special code to handle encryption - it just works:

For JSON attributes with encrypted fields, the package also ensures seamless operation:

Encrypted Email Authentication

This package provides special support for encrypting the email field while maintaining the ability to authenticate users by email. This is achieved by adding a searchable hash of the email (email_index) that enables efficient lookup.

Setup Encrypted Email Authentication

1. First, publish the migration to add the email_index column to your users table:

2. Add the HasEncryptedEmail trait to your User model:

3. Update your auth configuration in config/auth.php to use the encrypted email user provider:

4. For existing users, you'll need to regenerate the email index values and encrypt existing emails. Use the provided command:

Or if you prefer, create a migration:

Querying Users by Email

With the HasEncryptedEmail trait, you can still find users by their email:

How It Works

1. When a user is created or updated, the email is:

   • Encrypted before storage in the email column
   • A deterministic hash is stored in the email_index column for searching

2. When a user is retrieved:

   • The email is automatically decrypted
   • Authentication systems use the email_index column for lookups
3. The authentication provider is modified to:
   • Look up users by the hashed email index
   • Enable all standard Laravel authentication features (login, registration, password reset, etc.)

Manual Encryption/Decryption

You can also use the EncryptionService directly for custom encryption needs:

Using the Facade

You can use the provided facade for quick access to encryption functionality:

CLI Tools

This package includes several command-line tools to help you manage encrypted data.

Encrypting Existing Data

To encrypt data in an existing database table for a model that uses our traits:

Options:

• --chunk=100 - Process records in chunks (default: 100)
• --dry-run - Test the process without making changes
• --backup=true - Create a database backup before processing (default: true)
• --filter="id > 1000" - Only process records matching SQL where clause

Encrypting Emails Only

For models using the HasEncryptedEmail trait, you can use a dedicated command to process emails:

Options:

• --chunk=100 - Process records in chunks
• --dry-run - Test the process without making changes

Decrypting Data

If you need to decrypt data (for example, when migrating away from encryption):

Options:

• --chunk=100 - Process records in chunks (default: 100)
• --dry-run - Test the process without making changes
• --backup=true - Create a database backup before processing (default: true)
• --filter="id > 1000" - Only process records matching SQL where clause

⚠️ Warning: Decryption permanently removes the encryption protection from your data. Only use this command when absolutely necessary and after creating a backup.

Security Considerations

• All encrypted data is stored using Laravel's built-in encryption features
• The encrypted data cannot be searched or indexed efficiently except for email (which uses a hash-based index)
• Consider using database indexes only on non-encrypted fields
• The email hash is not a security risk as it's a one-way hash, but it does allow deterministic lookup
• Users with the same email will have the same email_index hash, making the email effectively unique in the system
• Always create a database backup before running encryption/decryption commands on production data

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Paper Scissors and Glue
• All Contributors

License

The MIT License (MIT). Please see License File for more information.