uwdoem / encryption
Propel Behavior for seamless encryption/decryption of data columns
Installs: 918
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 1
Type:propel-behavior
Requires
- propel/propel: ~2.0@dev
Requires (Dev)
- athens/standard: *
- codeclimate/php-test-reporter: dev-master
- phpdocumentor/phpdocumentor: 2.7.*
- phpunit/phpunit: 4.5.*
README
Athens\Encryption
Seamlessly encrypt/decrypt Propel2 data fields. This library is a plugin for the Propel2 ORM framework.
For example:
// schema.xml
<table name="my_class">
<column name="id" type="integer" required="true" primaryKey="true" autoIncrement="true"/>
<column name="my_data" type="varchar" size="255" />
<column name="my_secret_data" type="varbinary" size="255" />
<behavior name="encryption">
<parameter name="column_name_1" value="my_secret_data" />
</behavior>
</table>
// Before any database queries:
use Athens\Encryption\Cipher;
Cipher::createInstance("mysecretpassphrase");
// In your program:
$o = new MyClass();
$o->setMyData("Some data that will remain as plain text.");
$o->setMySecretData("Some data that will be encrypted.");
$o->save();
// Later:
$o = MyClassQuery::create()->findOneByMyData("Some data that will remain as plain text.");
echo $o->getMySecretData();
// "Some data that will be encrypted."
Given the table definition above, the string "Some data that will be encrypted."
is encrypted in memory before being sent to the database. When we retrieve MySecretData
later, the ciphertext is decrypted before being returned.
Note/Tradeoff
Athens/Encryption breaks Propel's native search/find/sort methods on the encrypted field(s). Because the plain-texts of encrypted fields are not available to the database, no database method of search or sort can operate on these fields. A search or sort can only be accomplished by retrieving all rows, decrypting all values, and performing a search/sort on those. If you have many rows and you need to search/sort on encrypted fields, this process may be impractically slow.
Installation
This library is published on packagist. To install using Composer, add the "Athens/Encryption": "0.1.*"
line to your "require" dependencies:
{
"require": {
"Athens/Encryption": ">=0.1"
}
}
Of course, if you're not using Composer then you can download the repository using the Download ZIP button at right.
Use
This client library provides a Cipher
class and one Propel2 Behavior class.
To designate a field as encrypted in your Propel schema, set its type as varbinary
and include the encryption
behavior. You may include multiple columns in the encryption
behavior:
<table name="my_class">
<column name="id" type="integer" required="true" primaryKey="true" autoIncrement="true"/>
<column name="my_data" type="varchar" size="255" />
<column name="my_secret_data" type="varbinary" size="255" />
<column name="my_secret_data2" type="varbinary" size="255" />
<behavior name="encryption">
<parameter name="column_name_1" value="my_secret_data" />
<parameter name="column_name_2" value="my_secret_data2" />
</behavior>
</table>
Then build your models and database as usual.
Before querying the database, you must initialize the Cipher class with your passphrase:
// Intialize the cipher
Cipher::createInstance($my_passphrase);
The argument $my_passphrase
should be a string of random characters. A length of 32-64 characters is appropriate for your passphrase. Because the cipher is initialized with every page load, the passphrase must be stored on your server in a location accessible to PHP. However, the passphrase should not be in a file which is viewable to web-visitors, and it almost certainly should not be included in your source/version control (git, scm, etc.).
That's it! The class setters for MySecretData
and MySecretData2
now seamlessly encrypt their data before it is sent to the database. The class getters for MySecretData
and MySecretData2
seamlessly decrypt data after retrieving it from the database.
Remember that search/find and sort are now broken for MySecretData
and MySecretData2
, for reasons discussed above.
Compatibility
- PHP 5.5, 5.6, 7.0
- Propel2
Todo
See GitHub issue tracker.
Getting Involved
Feel free to open pull requests or issues. GitHub is the canonical location of this project.
Here's the general sequence of events for code contribution:
- Open an issue in the issue tracker.
- In any order:
- Submit a pull request with a failing test that demonstrates the issue/feature.
- Get acknowledgement/concurrence.
- Revise your pull request to pass the test in (2). Include documentation, if appropriate.