adonis-encrypter v1.0.0

Adonis Encrypter

Adonis Encryption is based on the official encryption provider that ships with Adonis, the only difference is that it uses a Static Initialization Vector for encryption instead of a dynamic one as the official encrypter.

• Why Adonis Encrypter?
• Use case
  • The problem
  • The solution
• Authoring clarification
• Getting started
  • Configuration
  • Use
• Implement Model Getters and Setters
• Contributing guidelines
• License (MIT)

Why Adonis Encrypter?

This fork was born because we had the need to encrypt our database but still be able to query thru the encrypted data, picture the following scenario:

Use case

You have the following table in your database

Fields username and email where encrypted by Adonis official encryption provider using a dynamic initialization vector, that is to say, it generates a different encrypted string everytime you encrypt the data... You see the problem? if not, please continue reading.

The problem

The problem originates when you want to do a search on your encrypted data, you would normally encrypt the text and search by the encrypted string, but remember that same data won't result in the same string when encrypted again? since both strings, the one in the database and you recently encrypted text aren't the same, you won't get any matches.

The solution

The solution is very simple, actually, that is the only difference between this provider and the official one (all credit goes to Harminder Virk) is that this one uses a static IV, that's to say it does not generate an IV on each operation, you provide the IV you want to use to encrypt/decrypt your data.

By using a static IV, when you encrypt two "Hello", the resulting encrypted string will be the same and you will be able to store it in your database and search for your "Hello" value using its encrypted counterpart.

NOTE: You can use both encryption providers in the same project, deboting this one to scenarios like the explained above.

Authoring clarification

We don't like to take credit on something we didn't code ourselves, all credit goes for the original author since we just did an adaptation to our needs.

Getting Started

By installing adonis-framework you would have any dependencies covered, so you can just run

$ npm i --save adonis-encrypter

Configuration

Register the provider in your bootstrap/app.js file.

const providers = [
  'adonis-encrypter/providers/EncrypterProvider'
]

const aliases = {
  Encrypter: 'Pixeleur/Addons/Encrypter'
}

next generate your IV, a random 16 characters long alphanumeric string and add it to your ./env file

APP_IV=aRnd16CharString

next read your IV string into your Config provider, just below your App Key definition

  /*
  |--------------------------------------------------------------------------
  | App IV
  |--------------------------------------------------------------------------
  |
  | App IV is a 16 characters long Initialization Vector required
  | to encrypt/decrypt sensitive data.
  |
  | Specifying an IV will allow you to always generate the same string
  | while encrypting data, so you will be able to do encrypted database searchs.
  |
  | Do not specify if you want more security (although you won't have encrypted database searchs).
  |
  */
  appIV: Env.get('APP_IV', false),

How to use

Import Encrypter in your class

const Encrypter = use('Encrypter') 

next, use like you normally do with the official Encryption provider

Encrypt

let encrypted = Encrypter.encrypt(plainText)

Decrypt

let plainText = Encrypter.decrypt(decrypted)

Implement Model Getters and Setters

Manually encrypting and decrypting data coming from database may be tedious and is not scalable/maintainable, a better approach would be to implement getters and setters on your model:

'use strict'

const Lucid = use('Lucid')
const Encrypter = use('Encrypter')

class User extends Lucid {

  // Override table name
  static get table () {
      return 'user'
  }

  // Decrypt email after read
  getEmail (email) {
    email = Encrypter.decrypt(email)
    return email
  }

  // Encrypt email before write
  setEmail (email) {
    email = Encrypter.encrypt(email)
    return email
  }
}

module.exports = User

Contributing guidelines

In favor of active development we accept contributions for everyone. You can contribute by submitting a bug, creating pull requests or even improving documentation.

You can find a complete guide to be followed strictly before submitting your pull requests in the Adonis Official Documentation.