blind_index 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26d5a803099fa8b408065a43056697f24eaf10a89c6a778979e5bdd8d54bbb5e
-  data.tar.gz: '0288069afcdd54f3f3917ef25177550bd3c912333aca346d1ae77d0d237eb5ce'
+  metadata.gz: 0a5e0cf17996a671847cd6b7d9c89820c4dfa319c1f6e8c60bff430d5fdbb222
+  data.tar.gz: 82d7b94d12cd4391d48d845613a75740c0edbcb38d9d8272054b3bea58574c81
 SHA512:
-  metadata.gz: 1f062a2b9d1aa2d251dd38b6c815423afa146a34df0825d655bd9ac0ea666af9d0382d958995c7899e16a729b15e7e3d696d661485a246220e93bade67104641
-  data.tar.gz: 1478bb3716c6ad099e42ed95b286d7aa5a13c6be7f75d4ec6e7d5c82898c95d1fc7db2537d53c6daa5754ad398579bca5e924a60551423402e064f24b52ee2ff
+  metadata.gz: ff9d3d7b14c867a1972faa2600bfec2918fee21b2c2108bfa5a358990d1fc661c2aab84cc39c1610a0064cfd6a9b0ad461c1269b4bfdc8b85414f944235d864b
+  data.tar.gz: 87f28352c529b0cb61a0b4cf050a3619234da3e21fb06b5ba36d3d605119910678947994d381bb3a1bad81716300fe184d0adf8aa73cb78a95bd93ce93a23206

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.3.4
+
+- Added `size` option
+- Added sanity checks for Argon2 cost parameters
+- Fixed ActiveRecord callback issues introduced in 0.3.3
+
 ## 0.3.3
 
 - Added support for string keys in finders

data/README.md

@@ -4,31 +4,29 @@ Securely search encrypted database fields
 
 Designed for use with [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted)
 
-Here’s a [full example](https://ankane.org/securing-user-emails-in-rails) of how to use it with Devise
+Here’s a [full example](https://ankane.org/securing-user-emails-in-rails) of how to use it
 
 [![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 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.
+We use [this approach](https://paragonie.com/blog/2017/05/building-searchable-encrypted-databases-with-php-and-sql) 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-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
+## Installation
 
-Add these lines to your application’s Gemfile:
+Add this line to your application’s Gemfile:
 
 ```ruby
-gem 'attr_encrypted'
 gem 'blind_index'
 ```
 
-Add columns for the encrypted data and the blind index
+## Getting Started
 
-```ruby
-# encrypted data
-add_column :users, :encrypted_email, :string
-add_column :users, :encrypted_email_iv, :string
+> Note: Your model should already be set up with attr_encrypted. The examples are for a `User` model with `attr_encrypted :email`. See the [full example](https://ankane.org/securing-user-emails-in-rails) if needed.
 
-# blind index
+Create a migration to add a column for the blind index
+
+```ruby
 add_column :users, :encrypted_email_bidx, :string
 add_index :users, :encrypted_email_bidx
 ```
@@ -37,24 +35,31 @@ And add to your model
 
 ```ruby
 class User < ApplicationRecord
-  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 as hex-encoded strings ([dotenv](https://github.com/bkeepers/dotenv) is great for this). [Here’s an explanation](https://ankane.org/encryption-keys) of why `pack` is used. *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:
+We use an environment variable to store the key as a hex-encoded string ([dotenv](https://github.com/bkeepers/dotenv) is great for this). [Here’s an explanation](https://ankane.org/encryption-keys) of why `pack` is used. *Do not commit it to source control.* This should be different than the key you use for encryption. You can generate a key in the Rails console with:
 
 ```ruby
 SecureRandom.hex(32)
 ```
 
-For development, you can use these:
+For development, you can use this:
 
 ```sh
-EMAIL_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
 EMAIL_BLIND_INDEX_KEY=ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
 ```
 
+Backfill existing records
+
+```ruby
+User.find_each do |user|
+  user.compute_email_bidx
+  user.save!
+end
+```
+
 And query away
 
 ```ruby
@@ -92,7 +97,7 @@ add_column :users, :encrypted_email_ci_bidx, :string
 add_index :users, :encrypted_email_ci_bidx
 ```
 
-And update your model
+Update your model
 
 ```ruby
 class User < ApplicationRecord
@@ -101,7 +106,16 @@ class User < ApplicationRecord
 end
 ```
 
-Search with:
+Backfill existing records
+
+```ruby
+User.find_each do |user|
+  user.compute_email_ci_bidx
+  user.save!
+end
+```
+
+And query away
 
 ```ruby
 User.where(email_ci: "test@example.org")
@@ -128,8 +142,9 @@ You can also use virtual attributes to index data from multiple columns:
 class User < ApplicationRecord
   attribute :initials
 
-  # must come before blind_index method
+  # must come before the blind_index method so it runs first
   before_validation :set_initials, if: -> { changes.key?(:first_name) || changes.key?(:last_name) }
+
   blind_index :initials, ...
 
   def set_initials
@@ -140,68 +155,49 @@ end
 
 *Requires ActiveRecord 5.1+*
 
-## Fixtures
-
-You can use encrypted attributes and blind indexes in fixtures with:
-
-```yml
-test_user:
-  encrypted_email: <%= User.encrypt_email("test@example.org", iv: Base64.decode64("0000000000000000")) %>
-  encrypted_email_iv: "0000000000000000"
-  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
+### PBKDF2-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:
+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.
+
+The default number of iterations is 10,000. For highly sensitive fields, set this to at least 100,000.
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, iterations: 1000000, ...
+  blind_index :email, iterations: 100000, ...
 end
 ```
 
-The default is `10000`. Changing this value requires you to recompute the blind index.
+> Changing this requires you to recompute the blind index.
+
+### Argon2
 
-### scrypt
+Argon2 is the state-of-the-art algorithm and recommended for best security.
 
-Add [scrypt](https://github.com/pbhogan/scrypt) to your Gemfile and use:
+To use it, add [argon2](https://github.com/technion/ruby-argon2) to your Gemfile and set:
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, algorithm: :scrypt, ...
+  blind_index :email, algorithm: :argon2, ...
 end
 ```
 
-Set the cost parameters with:
+The default cost parameters are `{t: 3, m: 12}`. For highly sensitive fields, set this to at least `{t: 4, m: 15}`.
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, algorithm: :scrypt, cost: {n: 4096, r: 8, p: 1}, ...
+  blind_index :email, algorithm: :argon2, cost: {t: 4, m: 15}, ...
 end
 ```
 
-### Argon2
+> Changing this requires you to recompute the blind index.
 
-Add [argon2](https://github.com/technion/ruby-argon2) to your Gemfile and use:
+The variant used is Argon2i.
 
-```ruby
-class User < ApplicationRecord
-  blind_index :email, algorithm: :argon2, ...
-end
-```
-
-Set the cost parameters with:
+### Other
 
-```ruby
-class User < ApplicationRecord
-  blind_index :email, algorithm: :argon2, cost: {t: 3, m: 12}, ...
-end
-```
+scrypt is [also supported](docs/scrypt.md). Unless you have specific reasons to use it, go with Argon2 instead.
 
 ## Key Rotation
 
@@ -243,6 +239,19 @@ end
 
 Finally, drop the old column.
 
+## Fixtures
+
+You can use encrypted attributes and blind indexes in fixtures with:
+
+```yml
+test_user:
+  encrypted_email: <%= User.encrypt_email("test@example.org", iv: Base64.decode64("0000000000000000")) %>
+  encrypted_email_iv: "0000000000000000"
+  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.
+
 ## Reference
 
 By default, blind indexes are encoded in Base64. Set a different encoding with:
@@ -253,6 +262,14 @@ class User < ApplicationRecord
 end
 ```
 
+By default, blind indexes are 32 bytes. Set a smaller size with:
+
+```ruby
+class User < ApplicationRecord
+  blind_index :email, size: 16
+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.

data/lib/blind_index.rb

@@ -13,7 +13,7 @@ module BlindIndex
   end
   self.default_options = {
     iterations: 10000,
-    algorithm: :pbkdf2_hmac,
+    algorithm: :pbkdf2_sha256,
     insecure_key: false,
     encode: true,
     cost: {}
@@ -27,14 +27,15 @@ module BlindIndex
 
     unless value.nil?
       algorithm = options[:algorithm].to_sym
+      algorithm = :pbkdf2_sha256 if algorithm == :pbkdf2_hmac
+      algorithm = :argon2i if algorithm == :argon2
 
       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
+      unless options[:insecure_key] && algorithm == :pbkdf2_sha256
         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
 
@@ -42,20 +43,37 @@ module BlindIndex
       # https://gist.github.com/ankane/fe3ac63fbf1c4550ee12554c664d2b8c
       cost_options = options[:cost]
 
+      # check size
+      size = (options[:size] || 32).to_i
+      raise BlindIndex::Error, "Size must be between 1 and 32" unless (1..32).include?(size)
+
+      value = value.to_s
+
       value =
         case algorithm
         when :scrypt
           n = cost_options[:n] || 4096
           r = cost_options[:r] || 8
           cp = cost_options[:p] || 1
-          SCrypt::Engine.scrypt(value.to_s, key, n, r, cp, 32)
-        when :argon2
-          t = cost_options[:t] || 3
-          m = cost_options[:m] || 12
-          [Argon2::Engine.hash_argon2i(value.to_s, key, t, m)].pack("H*")
-        when :pbkdf2_hmac
+          SCrypt::Engine.scrypt(value, key, n, r, cp, size)
+        when :argon2i
+          t = (cost_options[:t] || 3).to_i
+          # use same bounds as rbnacl
+          raise BlindIndex::Error, "t must be between 3 and 10" if t < 3 || t > 10
+
+          # m is memory in kibibytes (1024 bytes)
+          m = (cost_options[:m] || 12).to_i
+          # use same bounds as rbnacl
+          raise BlindIndex::Error, "m must be between 3 and 22" if m < 3 || m > 22
+
+          # 32 byte digest size is limitation of argon2 gem
+          # this is no longer the case on master
+          # TODO add conditional check when next version of argon2 is released
+          raise BlindIndex::Error, "Size must be 32" unless size == 32
+          [Argon2::Engine.hash_argon2i(value, key, t, m)].pack("H*")
+        when :pbkdf2_sha256
           iterations = cost_options[:iterations] || options[:iterations]
-          OpenSSL::PKCS5.pbkdf2_hmac(value.to_s, key, iterations, 32, "sha256")
+          OpenSSL::PKCS5.pbkdf2_hmac(value, key, iterations, size, "sha256")
         else
           raise BlindIndex::Error, "Unknown algorithm"
         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, algorithm: nil, insecure_key: nil, encode: nil, cost: nil)
+    def blind_index(name, key: nil, iterations: nil, attribute: nil, expression: nil, bidx_attribute: nil, callback: true, algorithm: nil, insecure_key: nil, encode: nil, cost: nil, size: nil)
       iterations ||= 10000
       attribute ||= name
       bidx_attribute ||= :"encrypted_#{name}_bidx"
@@ -36,7 +36,8 @@ module BlindIndex
           algorithm: algorithm,
           insecure_key: insecure_key,
           encode: encode,
-          cost: cost
+          cost: cost,
+          size: size
         }.reject { |_, v| v.nil? }
 
         # should have been named generate_#{name}_bidx
@@ -49,12 +50,7 @@ module BlindIndex
         end
 
         if callback
-          if ActiveRecord::VERSION::STRING >= "5.1"
-            before_validation method_name, if: :"will_save_change_to_#{attribute}?"
-          else
-            before_validation method_name, if: -> { changes.key?(attribute.to_s) }
-          end
-
+          before_validation method_name, if: -> { changes.key?(attribute.to_s) }
         end
 
         # use include so user can override

data/lib/blind_index/version.rb

@@ -1,3 +1,3 @@
 module BlindIndex
-  VERSION = "0.3.3"
+  VERSION = "0.3.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blind_index
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-12 00:00:00.000000000 Z
+date: 2018-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -183,7 +183,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Securely search encrypted database fields