mathiasgrimm / laravel-encrypted-attributes
Encrypted and safe-by-default Laravel Model attributes
Installs: 2 461
Dependents: 0
Suggesters: 0
Security: 0
Stars: 10
Watchers: 2
Forks: 0
Open Issues: 0
Requires (Dev)
- orchestra/testbench: ^7.0
- phpunit/phpunit: ^9.5.11
This package is auto-updated.
Last update: 2024-10-29 06:06:39 UTC
README
This package adds secure-by-default encrypted attributes, to any Laravel Model, on demand.
By default, all serializations (toArray
, toJson
) and the default getter for any attribute
will always choose the encrypted value over the decrypted one.
To get the decrypted value you have to simply add the _decrypted
suffix:
echo $tenant->access_token_decrypted;
Installation
composer require mathiasgrimm/laravel-encrypted-attributes ^1.0
Background
I was thinking in a way to improve the existing Eloquent cast encrypted
Encrypted Casting.
Laravel Documentation:
The encrypted cast will encrypt a model's attribute value using Laravel's built-in encryption features. In addition, the encrypted:array, encrypted:collection, encrypted:object, AsEncryptedArrayObject, and AsEncryptedCollection casts work like their unencrypted counterparts; however, as you might expect, the underlying value is encrypted when stored in your database.
Laravel's default behavior is to keep it encrypted only in the database, and plain text for the rest. I think the default behaviour should be to always keep it encrypted unless you specifically ask for it decrypted.
For the rest of this reading assume the following:
local.encrypted-string
is an encrypted string, prepended with the environment > it was encrypted in.plain-text-string
is just an unencrypted plain text string.
Laravel Default Behavior
The examples bellow will all output the encrypted cast attributes in plain text:
logger($tenant, ['tenant' => $tenant]); // Will output: // [2022-06-23 12:10:32] local.DEBUG: {"access_token_github":"plain-text-string"} {"tenant":{"App\\Models\\Tenant":{"access_token_github":"plain-text-string"}}} print_r($tenant->toArray()); // Will print: // Array // ( // [access_token_github] => plain-text-string // ) echo $tenant->toJson(); // Will print: {"access_token_github":"plain-text-string"} echo $tenant->access_token_github; // Will print: plain-text-string
Configuration
To use the Encrypted attributes all you need to do is to use the trait HasEncryptedAttributes
and
add the attributes you want to be encrypted to the protected $encrypted = []
model property.
Examples
// app/Models/Tenants.php use MathiasGrimm\EncryptedAttributes\HasEncryptedAttributes; class Tenants extends Model { use HasEncryptedAttributes; protected $encrypted = [ 'access_token_github', 'access_token_facebook', ]; } // other.php $tenant = Tenant::find(1);
// ------------------------------------------------------------------- // Example 1 - New Default Getter Behaviour // ------------------------------------------------------------------- echo $tenant->access_token_github; // Will print "local.encrypted-string". // When using the accessor we always get the raw database value. // Therefore, by default it's encrypted.
// ------------------------------------------------------------------- // Example 2 - (Same) Default Setter Behaviour $tenant->access_token_github = 'plain-text-string'; // Will encrypt the value to "local.encrypted-string".
// ------------------------------------------------------------------- // Example 3 - Getting The Decrypted Value // ------------------------------------------------------------------- echo $tenant->access_token_github_decrypted; // Will print "plain-text-string".
// ------------------------------------------------------------------- // Example 4 - Setting a Raw Value // ------------------------------------------------------------------- $tenant->access_token_github_raw = 'local.encrypted-string'; // Will store the raw value echo $tenant->access_token_github; // Will print "local.encrypted-string". echo $tenant->access_token_github_decrypted; // Will print "plain-text-string".
// ------------------------------------------------------------------- // Example 5 - Update // ------------------------------------------------------------------- $tenant->update([ 'access_token_github' => 'plain-text-string' ]); // Will store/set the value "local.encrypted-string"
// ------------------------------------------------------------------- // Example 5.1 - Update With Raw // ------------------------------------------------------------------- $tenant->update([ 'access_token_github_raw' => 'local.encrypted-string' ]); // Will store/set the value of access_token_github to "local.encrypted-string"
// ------------------------------------------------------------------- // Example 6 - Query // ------------------------------------------------------------------- echo Tenant::where('access_token_github', 'plain-text-string')->count(); // Will print "0" echo Tenant::where('access_token_github', 'local.encrypted-string')->count(); // Will print "1"
// ------------------------------------------------------------------- // Example 7 - toArray() // ------------------------------------------------------------------- print_r($tenant->toArray()); // Will print: // array [ // 'access_token_github' => 'local.encrypted-string' // ]
// ------------------------------------------------------------------- // Example 8 - toJson() // ------------------------------------------------------------------- print_r($tenant->toJson()); // Will print: "{"access_token_github": "local.encrypted-string"}"
// ------------------------------------------------------------------- // Example 9 - Collection ->keyBy('access_token_github') // ------------------------------------------------------------------- $tenantsByAccessTokenGithub = collect([$tenant])->keyBy('access_token_github'); // works $tenantsByAccessTokenGithub['local.encrypted-string']; // undefined index $tenantsByAccessTokenGithub['plain-text-string'];
// ------------------------------------------------------------------- // Example 10 - Collection ->keyBy('access_token_github_decrypted') // ------------------------------------------------------------------- $tenantsByAccessTokenGithub = collect([$tenant])->keyBy('access_token_github_decrypted'); // undefined index $tenantsByAccessTokenGithub['local.encrypted-string']; // works $tenantsByAccessTokenGithub['plain-text-string'];
// ------------------------------------------------------------------- // Example 11 - Getting Encrypted Attribute Environment // ------------------------------------------------------------------- echo $tenant->access_token_github_environment; // Will print: local
Environment Scope
When using the encrypted attributes, the environment in which the value was encrypted in is prepended to the encrypted string.
Examples:
local.encrypted-string
testing.encrypted-string
staging.encrypted-string
production.encrypted-string
other.encrypted-string
By doing that we can add extra checks based on the prefix.
With that we could do things like:
// MyApiClient.php $writeMethods = ['post', 'put', 'patch', 'delete']; if (in_array($method, $writeMethods) && $this->access_token_github_environment != app()->environment()) { throw Exception("API is currently in read-only mode"); }