A simple symmetric encryption plugin for individual fields. The goal of this plugin is to encrypt data but still allow searching over fields with string values. This plugin relies on the Node
crypto module. Encryption and decryption happen transparently during save and find.
As of the stable 1.0.0 release, this plugin works on individual fields of any type. However, note that for non-string fields, the original value is set to undefined after encryption. This is because if the schema has defined a field as an array, it would not be possible to replace it with a string value.
Also consider mongoose-encryption if you have other requirements.
Encryption is performed using
AES-256-CTR. To encrypt, the relevant fields are encrypted with the provided secret and the resulting hex string is put in place of the actual value for
string values. An extra
boolean field with the prefix
__enc_ is added to the document which indicates if the provided field is encrypted or not.
Fields which are either objects or of a different type are converted to strings using
JSON.stringify and the value stored in an extra marker field of type
string with a naming scheme of
__enc_ as prefix and
_d as suffix on the original field name. The original field is then set to
undefined. Please note that this might break any custom validation and application of this plugin on non-string fields needs to be done with care.
npm install mongoose-field-encryption
Keep your secret a secret. Ideally it should only live as an environment variable but definitely not stored anywhere in your repository.
For example, given a schema as follows:
let mongoose = ;let mongooseFieldEncryption = fieldEncryption;let Schema = mongooseSchema;let Post =title: Stringmessage: Stringreferences:author: Stringdate: Date;Post;
The resulting documents will have the following format:
_id: ObjectIdtitle: Stringmessage: String // encrypted hex value as string__enc_message: true // boolean marking if the field is encrypted or notreferences: undefined // encrypted object set to undefined__enc_references: true // boolean marking if the field is encrypted or not__enc_references_d: String // encrypted hex object value as string
find works transparently and you can make new documents as normal, but you should not use the
lean option on a find if you want the fields of the document to be decrypted.
save also all work as normal.
update works only for string fields and you would also need to manually set the
__enc_ field value to false if you're updating an encrypted field.
From the mongoose package documentation: Note that findAndUpdate/Remove do not execute any hooks or validation before making the change in the database. If you need hooks and validation, first query for the document and then save it.
Also note that if you manually set the value
__enc_ prefix field to true then the encryption is not run on the corresponding field and this may result in the plain value being stored in the db.
fields: an array list of the required fields
secret: a string cipher which is used to encrypt the data (don't lose this!)
For performance reasons, once the document has been encrypted, it remains so. The following methods are thus added to the schema:
encryptFieldsSync(): synchronous call that encrypts all fields as given by the plugin options
decryptFieldsSync(): synchronous call that decrypts encrypted fields as given by the plugin options
stripEncryptionFieldMarkers(): synchronous call that removes the encryption field markers (useful for returning documents without letting the user know that something was encrypted)
Multiple calls to the above methods have no effect, i.e. once a field is encrypted and the
__enc_ marker field value is set to true then the ecrypt operation is ignored. Same for the decrypt operation. Of course if the field markers have been removed via the
stripEncryptionFieldMarkers() call, then the encryption will be executed if invoked.
To enable searching over the encrypted fields the
decrypt methods have also been exposed.
let fieldEncryption = require('mongoose-field-encryption') let encrypted = fieldEncryption.encrypt('some text', 'secret')); let decrypted = fieldEncryption.decrypt(encrypted, 'secret')); // decrypted = 'some text'
npm installand install mongo if you don't have it yet.
npm test. Additionally you can pass your own mongodb uri as an environment variable if you would like to test against your own database, for e.g.
URI='mongodb://username:password@localhost/mongoose-field-encryption-test' npm test