Laravel Utilities for Encrypted Data

This package contains several Laravel utilities to work with encrypted data.

Install

Via Composer

composer require swisnl/laravel-encrypted-data

Usage

Eloquent casts

Warning

Older versions of this package needed a custom model class to encrypt data. This is now replaced with custom casts. Please see MIGRATING for a step-by-step guide on how to migrate.

You can use the Eloquent casts provided by this package and everything will be encrypted/decrypted under the hood!

Boolean

protected $casts = [
    'boolean' => \Swis\Laravel\Encrypted\Casts\AsEncryptedBoolean::class,
];

Datetime

protected $casts = [
    'date' => \Swis\Laravel\Encrypted\Casts\AsEncryptedDate::class,
    'datetime' => \Swis\Laravel\Encrypted\Casts\AsEncryptedDateTime::class,
    'immutable_date' => \Swis\Laravel\Encrypted\Casts\AsEncryptedImmutableDate::class,
    'immutable_datetime' => \Swis\Laravel\Encrypted\Casts\AsEncryptedImmutableDateTime::class,
    'date_with_custom_format' => \Swis\Laravel\Encrypted\Casts\AsEncryptedDate::format('Y-m-d'),
];

Filesystem

Configure the storage driver in config/filesystems.php.

'disks' => [
    'local' => [
        'driver' => 'local-encrypted',
        'root' => storage_path('app'),
    ],
],

You can now simply use the storage methods as usual and everything will be encrypted/decrypted under the hood!

Commands

This package provides Artisan commands to help you re-encrypt your data after rotating your encryption key. You want to run these commands because Laravel only re-encrypts data when a value actually changes. This means that after rotating your encryption key, all existing data remains encrypted with the old key until it is updated. If your previous key is ever compromised, or you want to ensure all data uses the new key, you need to re-encrypt everything. These commands automate that process, making sure all your data is protected with the latest encryption key.

Important

Before running these commands, ensure you have rotated your encryption key and have set the APP_PREVIOUS_KEYS environment variable with your previous encryption key(s).

Re-encrypt models

Re-encrypts all model attributes that use encrypted casts.

php artisan encrypted-data:re-encrypt:models

Options:

• --model=: Specify one or more model class names to re-encrypt. Auto-detects models if not provided.
• --except=: Exclude one or more model class names from re-encryption.
• --path=: Path(s) to directories where models are located. Falls back to Models directory if not provided.
• --casts=: Regex to match casts that should be re-encrypted.
• --chunk=: Number of models to process per chunk.
• --quietly: Re-encrypt models without raising events.
• --no-touch: Do not update timestamps when saving.
• --with-trashed: Include soft-deleted models.
• --force: Run without confirmation.

Re-encrypt files

Re-encrypts all files on encrypted disks.

php artisan encrypted-data:re-encrypt:files

Options:

• --disk=: Specify one or more disks to re-encrypt. Auto-detects disks if not provided.
• --dir=: Directories (within the disk) to scan for files. Defaults to root if not provided.
• --except=: Files or directories (within the disk) to exclude.
• --force: Run without confirmation.

Known issues/limitations

Due to the encryption, some issues/limitations apply:

1. Encrypted data is — depending on what you encrypt — roughly 30-40% bigger.

Casts

1. You can't query or order columns that are encrypted in your SQL-statements, but you can query or sort the results using collection methods.

Filesystem

1. You can't use the public disk as that will download the raw encrypted files, so using Storage::url() and Storage::temporaryUrl() does not make sense;
2. You can use streams with this disk, but internally we will always convert those to strings because the entire file contents need to be encrypted/decrypted at once.

Change log

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

Testing

composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Jasper Zonneveld
• All Contributors

License

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

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

SWIS ❤️ Open Source

SWIS is a web agency from Leiden, the Netherlands. We love working with open source software.