SilverStripe Encrypt module
, (*1)
Easily add encryption to your DataObjects. In a time of GDPR and data leaks, this module helps you to keep your data secure., (*2)
This module use ciphersweet under the hood to encrypt field data, (*3)
Thanks to CipherSweet, your encrypted data is searchable!, (*4)
NOTE: Current version of this module has incompatibilities for composite fields with branch 2. Plan to rotate your values or keep using previous version., (*5)
NOTE: Branch 2 of this module is not compatible with previous versions. Please use branch 1 if you need the previous encryption system., (*6)
How to use
First of all, you need to define an encryption key as part of your environment. This can be done like so in your .env file:, (*7)
ENCRYPTION_KEY='here_is_my_key'
You can generate a key with EncryptHelper::generateKey()., (*8)
Make sure your key stays safe and that nobody gets access to it, (*9)
How this module works
You define encrypted field types. By default, everything is stored as text (varchars or texts). This is easier since our encrypted
data is in text format., (*10)
class MySecureObject extends DataObject
{
use HasEncryptedFields;
private static $db = [
"Name" => 'Varchar',
"MyText" => EncryptedDBText::class,
"MyHTMLText" => EncryptedDBHTMLText::class,
"MyVarchar" => EncryptedDBVarchar::class,
"MyNumber" => EncryptedNumberField::class,
"MyIndexedVarchar" => EncryptedDBField::class,
];
private static $indexes = [
'MyIndexedVarcharBlindIndex' => true,
'MyNumberBlindIndex' => true,
'MyNumberLastFourBlindIndex' => true,
];
public function getField($field)
{
return $this->getEncryptedField($field);
}
public function setField($fieldName, $val)
{
return $this->setEncryptedField($fieldName, $val);
}
}
There are two types of fields : simple and indexes (based on Composite field)., (*11)
The value is encoded before write and is decoded when getField (or any __get) is called.
This is why we have to use the HasEncryptedFields trait, in order to transparently encode and decode data.
Otherwise, we end up loading encrypted data from the database that is never decoded if you don't
use dbObject calls., (*12)
You can of course not use the trait, just keep in mind that your calls to $myObject->myEncryptedField = 'my value'
won't be encoded automatically. But you can most certainly do $myObject->dbObject('myEncryptedField')->setValue('my value') ...
but that's really not convenient in my opinion.
Maybe I'll find some way to avoid overriding the get/set field methods, but I haven't been succesful so far., (*13)
A quick note about indexes
Please note that this module doesn't create indexes automatically for your blind indexes. Since you
are probably going to use them to search your records, it's a good idea to add a database index to avoid
full table scan., (*14)
NOTE: blind indexes can have false positives (two records get the same index) and therefore, you cannot
be sure that a given blind index will only return one record., (*15)
The function EncryptHelper::planIndexSizeForClass will help you to set the right values. It returns
an array that is similar to this:, (*16)
Array
(
[min] => 2
[max] => 32
[indexes] => 2
[coincidence_count] => 8589934592
[coincidence_ratio] => 9.3132257461548E-8
[estimated_population] => 9223372036854775807
)
For each encrypted class, you can set the following config values:, (*17)
- estimated_population: the number of expected records.
The higher the population, the higher is the coincidence count (which makes your blind index safe to use)
- output_size and domain_size: these settings are configured at field level.
private static $db = [
"MyNumber" => EncryptedNumberField::class . '(["output_size" => 4, "domain_size" => 10, "index_size" => 32])',
];
Fast hashes
By default, this module doesn't enable fast hash indexes. If you expect to do a lot of queries on large table,
you need to enable it. Make sure to run this after #encrypt to override set yml configuration in the module., (*18)
---
After:
- '#encrypt'
---
LeKoala\Encrypt\EncryptHelper:
fasthash: true
This is a global settings. Fast hashes are NOT the same as slow hashes so beware if you have existing data, you need
to migrate it before. You can use EncryptHelper::convertHashType to help you along if needed., (*19)
Simple field types
This module provides three fields without blind indexes (if you need a blind index, see next point):, (*20)
- EncryptedDBText
- EncryptedDBVarchar
- EncryptedDBHTMLText
These fields work exactly like their regular counterpart, except the data is encrypted., (*21)
JSON data type
With EncryptedDBJson you can store json data. By default, it will encrypt the whole json representation but
that will prevent using modern db engines features to access specific keys., (*22)
Instead, you can encrypt each part of the json data like so:, (*23)
// create definition somewhere...
$map = (new JsonFieldMap())
->addTextField('name')
->addBooleanField('active')
->addIntegerField('age');
$definition = EncryptHelper::convertJsonMapToDefinition($map);
// in your models...
private static $db = [
"MyEncryptedJson" => EncryptedDBJson::class . "(['map' => '7551830f{\"fields\":{\"$6e616d65\":\"string\",\"$616374697665\":\"bool\",\"$616765\":\"int\"}}'])",
];
The map needs to be stored in the field definition under the map option as a string representation. This can be created
using EncryptHelper::convertJsonMapToDefinition., (*24)
NOTE: unspecified keys will be left unencrypted., (*25)
Searching for data
Thanks to CipherSweet, data is encrypted with a blind index. This blind index can be used to search data if you know the value
or a partial value based on what kind of index you created., (*26)
To search using an index, use the EncryptedDBField instance, (*27)
$singl = singleton(MyModel::class);
$obj = $singl->dbObject('MyEncryptedField');
$searchValue = $obj->getSearchValue($value);
$query = MyModel::get()->where(array('MyEncryptedFieldBlindIndex = ?' => $searchValue));
Or use shortcut, (*28)
$singl = singleton(MyModel::class);
$obj = $singl->dbObject('MyEncryptedField');
$record = $obj->fetchRecord($value);
Or even better, (*29)
$record = MyModel::getByBlindIndex("MyEncryptedField", $value);
$list = MyModel::getAllByBlindIndex("MyEncryptedField", $value);
We cannot use a regular search filter because of the false positive., (*30)
It is highly recommended to set indexes on your fields that use blind indexes. The convention is as follows:
{Name}BlindIndex and {Name}LastFourBlindIndex, (*31)
This module provides two fields with blind indexes:, (*32)
- EncryptedDBField that holds a single value with a full blind index
- EncryptedNumberField that holds a single value with a full blind index and a blind index for the last 4 digits
You can extend EncryptedDBField to add more fields types to suit your use case. Make sure their name starts with "Encrypted"., (*33)
Encrypt and decrypt other kind of data
You can also encrypt and decrypt data using a symmetrical key with the helper, (*34)
$someText = 'some text';
$encrypt = EncryptHelper::encrypt($someText);
$decryptedValue = EncryptHelper::decrypt($encrypt);
Handling encrypted files
This module automatically adds EncryptedDBFile extension to your files. This is done in an extension of the base
File class in order to avoid adding one more table in order to add an Encrypted field in your table that tracks encryption status, (*35)
Please note that files are not encrypted by default, you need to call encryptFileIfNeeded after your uploads., (*36)
$myFile->encryptFileIfNeeded();
Or use the EncryptedFile class. It's better to use the EncryptedFile class because it will properly update the Encrypted
flag if you update the file for example. Prefer checking Encrypted flag rather than using isEncrypted because this method
is rather slow., (*37)
Also, performance wise, remember that loading a file in order to check it's state can be slow, (*38)
$file = $this->File();
$file->encryptFileIfNeeded();
// fine for one record, not fine in a loop! Use EncryptHelper::checkIfFileIsEncrypted with ID
NOTE: Even if your files are encrypted, they should not be available in your public folder., (*39)
Make sure to review SilverStripe file security documentation.
Keeping files .protected and served by a dedicated controller (using sendDecryptedFile) is necessary or through the DecryptController., (*40)
Key rotation
If you need to change algo or key, you will need to rotate encryption., (*41)
Rotating algorithm with the same key is easy and built into this module. It happens automatically by default and you
can use the needsToRotateEncryption and rotateEncryption methods., (*42)
If you need to change key, you need to refer it first in the env:, (*43)
OLD_ENCRYPTION_KEY='here_is_my_old_key'
Then call rotateEncryption like this, (*44)
$oldKey = EncryptHelper::getOldKey();
$old = EncryptHelper::getEngineForEncryption("nacl", $oldKey);
$result = $model->needsToRotateEncryption($old);
if($result) {
$result = $model->rotateEncryption($old);
}
Planning index sizes
If you are using blind indexes, you might need to plan their sizes., (*45)
It is highly recommended to read the following guide about blind index planning.
https://ciphersweet.paragonie.com/php/blind-index-planning, (*46)
This modules gives you some tools and defaults that helps you to have
your indexes properly configured., (*47)
By default, blind indexes will have a size of 32 chars which allow a large numbers
of records in your table with a really low, (*48)
Using aad
By default, this module will use AAD., (*49)
This binds the ciphertext to a specific row, thereby preventing an attacker capable of replacing ciphertexts
and using legitimate app access to decrypt ciphertexts they wouldn't otherwise have access to., (*50)
This setting is controlled by aad_source parameter that takes by default the "ID" value.
You can disable aad by setting this to an empty string., (*51)
On first write, records get their ID. Therefore, you need to make sure that the ID is set on the encrypted fields.
This can be done like this. Some safety checks are also in place in case you don't do this., (*52)
protected function writeBaseRecord($baseTable, $now)
{
parent::writeBaseRecord($baseTable, $now);
// After base record is written, we have an ID and therefore AAD has changed
$this->resetFieldValues();
}
Todo
- Figure out a way to encrypt the Email field for members
- Fetch key from external service + cache
Compatibility
Tested with SilverStripe 5+, (*53)
Maintainer
LeKoala - thomas@lekoala.be, (*54)
Wallogit.com
lekoala