objection-encryption v1.0.1

Objection Encryption

This is an Objection.js plugin that enables field level encryption and decryption of values stored in a database.

Usage

  // Import plugin
  const ObjectionEncryption = require('objection-encryption');

  // Create an instance with the fields that should be encrypted on insert and decrypted on find.
  const Encryption = ObjectionEncryption({
    fields: ['ssn']
  });

  // Extend your Objection Model with the Encryption instance
  class Account extends Encryption(Model) {
    static get tableName() {
      return 'Account';
    }
  }

  const insertAccount = await Account.query()
    .insert({ name: 'Jennifer', ssn: 'AAA-GG-SSSS' });
  
  console.log(insertAccount); 
  // 
  // Account {
  //   name: 'Jennifer',
  //   ssn: 'enc:XX+9B5624XevryfUnJew==:olJo1Uv3XCzv1ZRCW5Toiw==',
  //   id: 2
  // }
  //

  const findAccount = await Account.query()
    .findById(2);
  
  console.log(findAccount);
  // 
  // Account {
  //   name: 'Jennifer',
  //   ssn: 'AAA-GG-SSSS',
  //   id: 2
  // }
  //

Configuration

You can initialize the library with several options

const crypto = require('crypto');
const ObjectionEncryption = require('objection-encryption');

// Create an instance with the fields that should be encrypted on insert and decrypted on find.
const Encryption = ObjectionEncryption({
  fields: ['ssn'],
  algorithm: 'aes-256-gcm',
  aesKey: crypto.randomBytes(32)
});

Crypto

By default aes-256-gcm is used for encryption that requires a 32 randomly generated key. Each encrypted value includes an IV, the IV is unique per encryption.

Format

Example encrypted value

enc:v1:VUKkbuDKaTeV17MF6VzUiQ==:VWmo5uwsTbSacm13u704rjXg+lGzAZsJBdXAtgQe

The value is formatted into 4 parts separated by the : character. | Index | Value | Description | | ------------------- | ------------------ | ----------- | | 0 | enc | prefix identifier | | 1 | v1 | version | | 2 | VUKkbuDKaTeV17MF6VzUiQ== | initialization vector (IV) (base64) | | 3 | VWmo5uwsTbSacm13u704rjXg+lGzAZsJBdXAtgQe | ciphertext (base64) |

Hashicorp Vault

objection-encryption can be configured to use and AES key from Hashicorp Vault. This is only compatible with the default aes-256-gcm algorithm.

Setup

You must generate an exportable key from Vault, this will assume you have Vault installed on your local machine

Start Vault in Dev mode

vault server -dev

Enable transit encryption

vault secrets enable transit

Create a key that is exportable with the exportable flag set to true.

curl --header "X-Vault-Token: ..." \
  --request POST \
  --data '{"type": "aes256-gcm96", "exportable": true}' \
  http://127.0.0.1:8200/v1/transit/keys/objection-encryption

Get the key details

curl --header "X-Vault-Token: ..." \
  http://127.0.0.1:8200/v1/transit/export/encryption-key/objection-encryption/1

Note

The key returned from Vault will be base64 encoded, to pass this to objection-encryption in the correct format create a Buffer with base64 input encoding.

  const Encryption = ObjectionEncryption({
    fields: ['ssn'],
    aesKey: Buffer.from(vaultKey, 'base64)
  });