Implement encrypted attributes and tests

Author: simonratner

.travis.yml

@@ -0,0 +1,3 @@
+language: node_js
+node_js:
+  - "8"

README.md

@@ -1,2 +1,111 @@
-# node-encrypted-attr
-Encrypted model attribute implementation that can be easily plugged into your favourite ORM.
+# Encrypted Attributes
+
+Encrypted model attribute implementation that can be easily plugged into your
+favourite ORM.
+
+# Security model
+
+* AES-256-GCM
+* 96-bit random nonce
+* 128-bit authentication tag
+* Additional authenticated data:
+    * Key id, allowing use of different keys for different attributes, or
+      rotating keys over time without re-encrypting all data
+    * [*Optional*] Object id, allowing to detect substitutions of encrypted
+      values
+
+All keys should be 32 bytes long, and cryptographically random. Manage these
+keys as you would any other credentials (environment config, keychain, vault).
+
+Best way to generate keys:
+```
+node -p "require('crypto').randomBytes(32).toString('base64')"
+```
+
+# Threat model
+
+This is designed to protect you from leaking sensitive user data under very
+specific scenarios:
+
+* Full database dump
+    * Misplaced unencrypted backups
+    * Compromised database host
+* Partial database dump
+    * Query injection via unsanitized input
+
+Specifically, this does *not* provide any protection in cases of a compromised
+web app host, app-level vulnerabilities, or accidental leaks into persistent
+logs. It is also in no way a substitute for actually encrypting your backups,
+sanitizing all you input, et cetera.
+
+# Install
+
+```
+npm install node-encrypted-attr
+```
+
+# Use
+
+While this module can be used stand-alone to encrypt individual values (see
+[tests](/test/)), it is designed to be wrapped in a plugin or hook for your
+favourite ORM. Eventually, this package may include such plugins for common
+ORMs, but for now, here's an example of integrating with [thinky](https://github.com/neumino/thinky):
+
+## Thinky
+
+```
+const EncryptedAttributes = require('node-encrypted-attr')
+const thinky = require('thinky')()
+const _ = require('lodash')
+
+let Model = thinky.createModel('Model', {})
+
+Model.encryptedAttributes = EncryptedAttributes(['secret'], {
+  keys: {
+    k1: 'bocZRaBnmtHb2pXGTGixiQb9W2MmOtRBpbJn3ADX0cU='
+  },
+  keyId: 'k1'
+})
+
+// Pre-save hook: encrypt any model attributes that need to be encrypted.
+Model.pre('save', function (next) {
+  try {
+    this.encryptedAttributes.encryptAll(obj)
+    process.nextTick(next)
+  } catch (err) {
+    process.nextTick(next, err)
+  }
+})
+
+// Post-save hook: decrypt any model attributes that need to be decrypted.
+Model.post('save', function (next) {
+  try {
+    this.encryptedAttributes.decryptAll(obj)
+    process.nextTick(next)
+  } catch (err) {
+    process.nextTick(next, err)
+  }
+})
+
+// Post-retrieve hook: ditto.
+Model.post('retrieve', function (next) {
+  try {
+    this.encryptedAttributes.decryptAll(obj)
+    process.nextTick(next)
+  } catch (err) {
+    process.nextTick(next, err)
+  }
+})
+
+// Optionally, add some helper methods in case you need to set or read a value
+// directly, without going through model parser.
+for (let attr of Model.encryptedAttributes.attributes) {
+  Mode.define(_.camelCase(`encrypted ${attr}`), function (val) {
+    return Model.encryptedAttributes.encryptAttribute(this, val)
+  }
+}
+```
+
+# License
+
+[MIT](LICENSE)

index.js

@@ -0,0 +1 @@
+module.exports = require('./lib/encrypted-attr')

lib/encrypted-attr.js

@@ -0,0 +1,83 @@
+'use strict'
+
+const crypto = require('crypto')
+const gcm = require('node-aes-gcm')
+const { get, set } = require('lodash')
+
+function EncryptedAttributes (attributes, options) {
+  options = options || {}
+
+  function encryptAttribute (obj, val) {
+    // Encrypted attributes are prefixed with "aes-256-gcm$", the base64
+    // encoding of which is "YWVzLTI1Ni1nY20k". Nulls are not encrypted.
+    if (val == null || (typeof val === 'string' && val.startsWith('YWVzLTI1Ni1nY20k'))) {
+      return val
+    }
+    if (typeof val !== 'string') {
+      throw new Error('Encrypted attribute must be a string')
+    }
+    if (options.verifyId && !obj.id) {
+      throw new Error('Cannot encrypt without \'id\' attribute')
+    }
+    // Recommended 96-bit nonce with AES-GCM.
+    let iv = crypto.randomBytes(12)
+    let aad = Buffer.from(
+      `aes-256-gcm$${options.verifyId ? obj.id.toString() : ''}$${options.keyId}`)
+    let key = Buffer.from(options.keys[options.keyId], 'base64')
+    let result = gcm.encrypt(key, iv, Buffer.from(val), aad)
+    return aad.toString('base64') + '$' +
+           iv.toString('base64') + '$' +
+           result.ciphertext.toString('base64') + '$' +
+           result.auth_tag.toString('base64').slice(0, 22)
+  }
+
+  function encryptAll (obj) {
+    for (let attr of attributes) {
+      set(obj, attr, encryptAttribute(obj, get(obj, attr)))
+    }
+    return obj
+  }
+
+  function decryptAttribute (obj, val) {
+    // Encrypted attributes are prefixed with "aes-256-gcm$", the base64
+    // encoding of which is "YWVzLTI1Ni1nY20k". Nulls are not encrypted.
+    if (typeof val !== 'string' || !val.startsWith('YWVzLTI1Ni1nY20k')) {
+      return val
+    }
+    if (options.verifyId && !obj.id) {
+      throw new Error('Cannot decrypt without \'id\' attribute')
+    }
+    let [aad, iv, payload, tag] = val.split('$').map((x) => Buffer.from(x, 'base64'))
+    let [, id, keyId] = aad.toString().split('$')
+    if (options.verifyId && (id !== obj.id.toString())) {
+      throw new Error('Encrypted attribute has invalid id')
+    }
+    if (!options.keys[keyId]) {
+      throw new Error('Encrypted attribute has invalid key id')
+    }
+    let key = Buffer.from(options.keys[keyId], 'base64')
+    let result = gcm.decrypt(key, iv, payload, aad, tag)
+    if (!result.auth_ok) {
+      throw new Error('Encrypted attribute has invalid auth tag')
+    }
+    return result.plaintext.toString()
+  }
+
+  function decryptAll (obj) {
+    for (let attr of attributes) {
+      set(obj, attr, decryptAttribute(obj, get(obj, attr)))
+    }
+    return obj
+  }
+
+  return {
+    attributes,
+    options,
+    encryptAttribute,
+    encryptAll,
+    decryptAttribute,
+    decryptAll
+  }
+}
+
+module.exports = EncryptedAttributes