blind_index 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c05a4761d6d0ea7b3b509af0f470323b2dad0acf50b8e1278bf0c65ae77bce3
-  data.tar.gz: bc9acee38ec03827dde2faacd9f0fc83c6a1900888dbe472d3d1e3b5971c532d
+  metadata.gz: 651caa81ae68cdce70f5f0f83d3f2b1d0d2365c2c34765414d3ae0e523e5cdab
+  data.tar.gz: 4a7d274aec56ba615a9569ab19c222b24d4a052166e8acdc0bfd2a5c65b4855b
 SHA512:
-  metadata.gz: 53f9fb4eea7741c64a353e14b229a7c176bcd80d156e691a727477508aa995785611da57adf3c01d553415b39061798831a3ab49988cf4ef43a7343ead42f446
-  data.tar.gz: 4671cdb7b7f3c33476bf629ab406e35496db7a5075c0da0b5f5190ae50c68447bdff68299b151072d3118569715dd84d9b7ff0fd4ad1056c84bb7af6b58b45eb
+  metadata.gz: e169875cc33b23da106311fbbc41a2647bbd6b3abfd5e904f9ad7315ea71117d2dd69cc829ff16b222640397ba5576d12094fe2a62000e9c6962409dc6ccd478
+  data.tar.gz: a7ee41ba497568c4580d98508c204f956aff7ed1ee04bb4452b78fe2897e98015ec3e9718bc6ef174b432912bfb7cf55bd94db79c45e14041ad057f04a49055f

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.3.0
+
+- Enforce secure key generation
+- Added `encode` option
+- Added `default_options` method
+
 ## 0.2.1
 
 - Added class method to compute blind index

data/README.md

@@ -4,11 +4,13 @@ Securely search encrypted database fields
 
 Designed for use with [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted)
 
+Here’s a [full example](https://shorts.dokkuapp.com/securing-user-emails-in-rails/) of how to use it with Devise
+
 [![Build Status](https://travis-ci.org/ankane/blind_index.svg?branch=master)](https://travis-ci.org/ankane/blind_index)
 
 ## How It Works
 
-We use [this approach](https://www.sitepoint.com/how-to-search-on-securely-encrypted-database-fields/) by Scott Arciszewski. To summarize, we compute a keyed hash of the sensitive data and store it in a column. To query, we apply the keyed hash function (PBKDF2-HMAC-SHA256) to the value we’re searching and then perform a database search. This results in performant queries for equality operations, while keeping the data secure from those without the key.
+We use [this approach](https://www.sitepoint.com/how-to-search-on-securely-encrypted-database-fields/) by Scott Arciszewski. To summarize, we compute a keyed hash of the sensitive data and store it in a column. To query, we apply the keyed hash function (PBKDF2-HMAC-SHA256 by default) to the value we’re searching and then perform a database search. This results in performant queries for equality operations, while keeping the data secure from those without the key.
 
 ## Getting Started
 
@@ -35,16 +37,22 @@ And add to your model
 
 ```ruby
 class User < ApplicationRecord
-  attr_encrypted :email, key: ENV["EMAIL_ENCRYPTION_KEY"]
-  blind_index :email, key: ENV["EMAIL_BLIND_INDEX_KEY"]
+  attr_encrypted :email, key: [ENV["EMAIL_ENCRYPTION_KEY"]].pack("H*")
+  blind_index :email, key: [ENV["EMAIL_BLIND_INDEX_KEY"]].pack("H*")
 end
 ```
 
-We use environment variables to store the keys ([dotenv](https://github.com/bkeepers/dotenv) is great for this). *Do not commit them to source control.* Generate one key for encryption and one key for hashing. For development, you can use these:
+We use environment variables to store the keys ([dotenv](https://github.com/bkeepers/dotenv) is great for this). *Do not commit them to source control.* Generate one key for encryption and one key for hashing. You can generate keys in the Rails console with:
+
+```ruby
+SecureRandom.hex(32)
+```
+
+For development, you can use these:
 
 ```sh
-EMAIL_ENCRYPTION_KEY=00000000000000000000000000000000
-EMAIL_BLIND_INDEX_KEY=99999999999999999999999999999999
+EMAIL_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
+EMAIL_BLIND_INDEX_KEY=ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
 ```
 
 And query away
@@ -99,9 +107,33 @@ Search with:
 User.where(email_ci: "test@example.org")
 ```
 
-## Key Stretching
+## Index Only
 
-Key stretching increases the amount of time required to compute hashes, which slows down brute-force attacks. You can set the number of iterations with:
+If you don’t need to store the original value (for instance, when just checking duplicates), use a virtual attribute:
+
+```ruby
+class User < ApplicationRecord
+  attribute :email
+  blind_index :email, ...
+end
+```
+
+## Fixtures
+
+You can use blind indexes in fixtures with:
+
+```yml
+test_user:
+  encrypted_email_bidx: <%= User.compute_email_bidx("test@example.org").inspect %>
+```
+
+Be sure to include the `inspect` at the end, or it won’t be encoded properly in YAML.
+
+## Algorithms
+
+### PBKDF2-HMAC-SHA256
+
+The default hashing algorithm. [Key stretching](https://en.wikipedia.org/wiki/Key_stretching) increases the amount of time required to compute hashes, which slows down brute-force attacks. You can set the number of iterations with:
 
 ```ruby
 class User < ApplicationRecord
@@ -111,24 +143,72 @@ end
 
 The default is `10000`. Changing this value requires you to recompute the blind index.
 
-## Index Only
 
-If you don’t need to store the original value (for instance, when just checking duplicates), use a virtual attribute:
+### scrypt
+
+:warning: *Not production ready yet*
+
+Add [scrypt](https://github.com/pbhogan/scrypt) to your Gemfile and use:
 
 ```ruby
 class User < ApplicationRecord
-  attribute :email
-  blind_index :email, ...
+  blind_index :email, algorithm: :scrypt, ...
 end
 ```
 
-## Fixtures
+### Argon2
 
-You can use blind indexes in fixtures with:
+:warning: *Not production ready yet*
 
-```yml
-test_user:
-  encrypted_email_bidx: <%= User.compute_email_bidx("test@example.org").inspect %>
+Add [argon2](https://github.com/technion/ruby-argon2) to your Gemfile and use:
+
+```ruby
+class User < ApplicationRecord
+  blind_index :email, algorithm: :argon2, ...
+end
+```
+
+## Reference
+
+By default, blind indexes are encoded in Base64. Set a different encoding with:
+
+```ruby
+class User < ApplicationRecord
+  blind_index :email, encode: ->(v) { [v].pack("H*") }
+end
+```
+
+## Alternatives
+
+One alternative to blind indexing is to use a deterministic encryption scheme, like [AES-SIV](https://github.com/miscreant/miscreant). In this approach, the encrypted data will be the same for matches.
+
+## Upgrading
+
+### 0.3.0
+
+This version introduces a breaking change to enforce secure key generation. An error is thrown if your blind index key isn’t both binary and 32 bytes.
+
+We recommend rotating your key if it doesn’t meet this criteria. You can generate a new key in the Rails console with:
+
+```ruby
+SecureRandom.hex(32)
+```
+
+Set the new key and recompute the blind index.
+
+```ruby
+User.find_each do |user|
+  user.compute_email_bidx
+  user.save!
+end
+```
+
+To continue without rotating, set:
+
+```ruby
+class User < ApplicationRecord
+  blind_index :email, insecure_key: true, ...
+end
 ```
 
 ## History

data/Rakefile

@@ -9,3 +9,20 @@ Rake::TestTask.new(:test) do |t|
 end
 
 task default: :test
+
+task :benchmark do
+  require "securerandom"
+  require "benchmark/ips"
+  require "blind_index"
+  require "scrypt"
+  require "argon2"
+
+  key = SecureRandom.random_bytes(32)
+  value = "secret"
+
+  Benchmark.ips do |x|
+    x.report("pbkdf2_hmac") { BlindIndex.generate_bidx(value, key: key, algorithm: :pbkdf2_hmac) }
+    x.report("scrypt") { BlindIndex.generate_bidx(value, key: key, algorithm: :scrypt) }
+    x.report("argon2") { BlindIndex.generate_bidx(value, key: key, algorithm: :argon2) }
+  end
+end

data/blind_index.gemspec

@@ -28,4 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "attr_encrypted"
   spec.add_development_dependency "activerecord"
   spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "scrypt"
+  spec.add_development_dependency "argon2"
+  spec.add_development_dependency "benchmark-ips"
 end

data/lib/blind_index.rb

@@ -8,21 +8,61 @@ require "blind_index/version"
 module BlindIndex
   class Error < StandardError; end
 
-  def self.generate_bidx(value, key:, iterations:, expression: nil, **options)
-    key = key.call if key.respond_to?(:call)
+  class << self
+    attr_accessor :default_options
+  end
+  self.default_options = {
+    iterations: 10000,
+    algorithm: :pbkdf2_hmac,
+    insecure_key: false,
+    encode: true
+  }
 
-    raise BlindIndex::Error, "Missing key for blind index" unless key
+  def self.generate_bidx(value, key:, **options)
+    options = default_options.merge(options)
 
     # apply expression
-    value = expression.call(value) if expression
+    value = options[:expression].call(value) if options[:expression]
 
     unless value.nil?
-      # generate hash
-      digest = OpenSSL::Digest::SHA256.new
-      value = OpenSSL::PKCS5.pbkdf2_hmac(value.to_s, key, iterations, digest.digest_length, digest)
+      algorithm = options[:algorithm].to_sym
+
+      key = key.call if key.respond_to?(:call)
+      raise BlindIndex::Error, "Missing key for blind index" unless key
+
+      key = key.to_s
+      unless options[:insecure_key] && algorithm == :pbkdf2_hmac
+        raise BlindIndex::Error, "Key must use binary encoding" if key.encoding != Encoding::BINARY
+        # raise BlindIndex::Error, "Key must not be ASCII" if key.bytes.all? { |b| b < 128 }
+        raise BlindIndex::Error, "Key must be 32 bytes" if key.bytesize != 32
+      end
+
+      # gist to compare algorithm results
+      # https://gist.github.com/ankane/fe3ac63fbf1c4550ee12554c664d2b8c
+      value =
+        case algorithm
+        when :scrypt
+          # n, p (keep r at 8)
+          SCrypt::Engine.scrypt(value.to_s, key, 4096, 8, 1, 32)
+        when :argon2
+          # t_cost, m_cost
+          [Argon2::Engine.hash_argon2i(value.to_s, key, 2, 12)].pack("H*")
+        when :pbkdf2_hmac
+          OpenSSL::PKCS5.pbkdf2_hmac(value.to_s, key, options[:iterations], 32, "sha256")
+        else
+          raise BlindIndex::Error, "Unknown algorithm"
+        end
 
-      # encode
-      [value].pack("m")
+      encode = options[:encode]
+      if encode
+        if encode.respond_to?(:call)
+          encode.call(value)
+        else
+          [value].pack("m")
+        end
+      else
+        value
+      end
     end
   end
 end

data/lib/blind_index/model.rb

@@ -1,6 +1,6 @@
 module BlindIndex
   module Model
-    def blind_index(name, key: nil, iterations: nil, attribute: nil, expression: nil, bidx_attribute: nil, callback: true)
+    def blind_index(name, key: nil, iterations: nil, attribute: nil, expression: nil, bidx_attribute: nil, callback: true, algorithm: nil, insecure_key: nil, encode: nil)
       iterations ||= 10000
       attribute ||= name
       bidx_attribute ||= :"encrypted_#{name}_bidx"
@@ -23,8 +23,11 @@ module BlindIndex
           iterations: iterations,
           attribute: attribute,
           expression: expression,
-          bidx_attribute: bidx_attribute
-        }
+          bidx_attribute: bidx_attribute,
+          algorithm: algorithm,
+          insecure_key: insecure_key,
+          encode: encode
+        }.reject { |_, v| v.nil? }
 
         define_singleton_method method_name do |value|
           BlindIndex.generate_bidx(value, blind_indexes[name])

data/lib/blind_index/version.rb

@@ -1,3 +1,3 @@
 module BlindIndex
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blind_index
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-26 00:00:00.000000000 Z
+date: 2018-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -108,6 +108,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: scrypt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: argon2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - andrew@chartkick.com