Repository files navigation

The purpose of this project is to create a set-it-and-forget-it package that can beinstalled without much effort to encrypt and decrypt Eloquent model attributes storedin your database tables, transparently. It is therefore highly opinionated but builtfor configuration.

When enabled, it automagically begins encrypting data as it is stored in the modelattributes and decrypting data as it is recalled from the model attributes.

All data that is encrypted is prefixed with a header so that encrypted data can beeasily identified, encryption keys rotated, and (optionally) versioning of the encrypteddata format itself.

This supports columns that store either encrypted or non-encrypted data to make migrationeasier. Data can be read from columns correctly regardless of whether it is encrypted ornot but will be automatically encrypted when it is saved back into those columns. StandardLaravel Eloquent features like attribute casting will continue to work as normal, even ifthe underlying values stored in the database are encrypted by this package.

There isdocumentation forlaravel-database-encryption online,the source of which is in thedocs/directory. The most logical place to start are thedocs for theHasEncryptedAttributes trait.

• Summary
• Requirements
• Schemas
• Installation
  • Step 1: Composer
  • Step 2: Enable the package (Optional)
  • Step 3: Configure the package
• Usage
• Keys and IVs
• Unit Tests
• Overrides
• FAQ
  • Can I manually encrypt or decrypt arbitrary data?
  • Can I search encrypted data?
  • Can I encrypt all myUser model data?
• Credits
• Contributing
• License

• Laravel 5.5+
• PHP >= 7.1.0
• PHPOpenSSL extension

Encrypted values are usually longer than plain text values, sometimes much longer.You may find that the column widths in your database tables need to be altered tostore the encrypted values generated by this package.

If you are encrypting long strings such as JSON blobs then the encrypted values maybe longer than aVARCHAR field can support, and you will need to alter your columntypes toTEXT orLONGTEXT.

Via Composer command line:

$ composer require austinheap/laravel-database-encryption

Or add the package to yourcomposer.json:

{"require": {"austinheap/laravel-database-encryption":"0.1.0"    }}

This package implements Laravel 5.5's auto-discovery feature. After you install it thepackage provider and facade are added automatically.

If you would like to declare the provider and/or alias explicitly, you may do so by firstadding the service provider to yourconfig/app.php file:

'providers' => [//AustinHeap\Database\Encryption\EncryptionServiceProvider::class,];

And then add the alias to yourconfig/app.php file:

'aliases' => [//'DatabaseEncryption' =>AustinHeap\Database\EncryptionFacade::class,];

Publish the package config file:

$ php artisan vendor:publish --provider="AustinHeap\Database\Encryption\EncryptionServiceProvider"

You may now enable automagic encryption and decryption of Eloquent models by editing theconfig/database-encryption.php file:

return ['enabled' =>env('DATABASE_ENCRYPTION_ENABLED',true),];

Or simply setting the theDATABASE_ENCRYPTION_ENABLED environment variable to true, viathe Laravel.env file or hosting environment.

DATABASE_ENCRYPTION_ENABLED=true

Use theHasEncryptedAttributes trait in any Eloquent model that you wish to apply encryptionto and define aprotected $encrypted array containing a list of the attributes to encrypt.

For example:

useAustinHeap\Database\Encryption;class Userextends Eloquent {use HasEncryptedAttributes;/**         * The attributes that should be encrypted on save.         *         * @var array         */protected$encrypted = ['address_line_1','first_name','last_name','postcode'        ];    }

You can combine$casts and$encrypted to store encrypted arrays. An array will first beconverted to JSON and then encrypted.

For example:

useAustinHeap\Database\Encryption;class Userextends Eloquent {use HasEncryptedAttributes;protected$casts     = ['extended_data' =>'array'];protected$encrypted = ['extended_data'];    }

By including theHasEncryptedAttributes trait, thesetAttribute() andgetAttributeFromArray()methods provided by Eloquent are overridden to include an additional step. This additional stepsimply checks whether the attribute being accessed via setter/getter is included in the$encryptedarray on the model, and then encrypts or decrypts it accordingly.

The key and encryption algorithm used is the default LaravelEncrypter service, and configured inyourconfig/app.php:

'key' =>env('APP_KEY','SomeRandomString'),'cipher' =>'AES-256-CBC',

If you're usingAES-256-CBC as the cipher for encrypting data, use the built in command to generateyour application key if you haven't already withphp artisan key:generate. If you are encrypting longerdata, you may want to consider theAES-256-CBC-HMAC-SHA1 cipher.

The IV for encryption is randomly generated and cannot be set.

This package has aggressive unit tests built with the wonderfulorchestral/testbenchpackage which is built on top of PHPUnit. A MySQL server required for execution of unit tests.

There arecode coverage reports forlaravel-database-encryptionavailable online.

The following Laravel 5.5 methods from Eloquent are affected by this trait.

• constructor() -- callsfill().
• fill() -- callssetAttribute() which has been extended to encrypt the data.
• hydrate() -- TBD.
• create() -- callsconstructor() and hencefill().
• firstOrCreate() -- callsconstructor().
• firstOrNew() -- callsconstructor().
• updateOrCreate() -- callsfill().
• update() -- callsfill().
• toArray() -- callsattributesToArray().
• jsonSerialize() -- callstoArray().
• toJson() -- callstoArray().
• attributesToArray() -- callsgetArrayableAttributes().
• getAttribute() -- callsgetAttributeValue().
• getAttributeValue() -- callsgetAttributeFromArray().
• getAttributeFromArray() -- callsgetArrayableAttributes().
• getArrayableAttributes() -- extended to decrypt data.
• setAttribute() -- extended to encrypt data.
• getAttributes() -- extended to decrypt data.
• castAttribute() -- extended to cast encrypted data.
• isDirty() -- extended to recognize encrypted data.

Yes! You can manually encrypt or decrypt data using theencryptedAttribute() anddecryptedAttribute()functions. For example:

$user =newUser();$encryptedEmail =$user->encryptedAttribute(Input::get('email'));

No! You will not be able to search on attributes which are encrypted by this package because...it is encrypted.Comparing encrypted values would require a fixed IV, which introduces security issues.

If you need to search on data then either:

• Leave it unencrypted, or
• Hash the data and search on the hash instead of the encrypted value using a well known hash algorithmsuch asSHA256.

You could store both a hashed and an encrypted value, using the hashed value for searching and retrievethe encrypted value as needed.

No! The same issue with searching also applies to authentication because authentication requires search.

This is a fork ofdelatbabel/elocryptfive,which was a fork ofdtisgodsson/elocrypt,which was based on earlier work.

• delatbabel/elocryptfive Contributors
• dtisgodsson/elocrypt Contributors

Pull requests welcome! Please seethe contributing guide for more information.

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