blind_index 0.3.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f5aab7dbd2a784f6bcc2b464c14f76621c94886ec4764bc5e51f97ac74ae0d9
-  data.tar.gz: 104135feff81321860030ca46946cd5021cfb97fcc5a3953742ac61cee842cfd
+  metadata.gz: d2a4c6e35691fe1efa918f077afda9902109591f695a3f4043ae9eb6350ffb44
+  data.tar.gz: dcbe4e3c535a2d36495370a7fa53078d6fd32979c8b7d07b7e29c3202e8fd393
 SHA512:
-  metadata.gz: b79e2f7597a572b4732f326bde1ce82de7941ffd3e97dc609834931cacb86a59c2ae6f5cc981cda0f6827956823bd01d910b56c5092409547a539a5db010e1b8
-  data.tar.gz: ba72cc3e13bb0fdd12e3502d1657e20074af745b41bb8fcb34df495e14fbddb36c3535e450950aa3ccb935a92c9cbbdcc70c7f1eaacccaba8c3fa358a3955470
+  metadata.gz: 1c80bec06e019677e606d4da2c52d0aa529f5aeb56e1091a79a138ce40b73dedb3244fdabf073a96d249e9a876e6557d73e38bd48dfddfd5b1963e19ebb91c93
+  data.tar.gz: e206e2619af60a2274f300eac56f1edf3a7f00822c8bdead7fa579252b81b7540d16832c083ed630f454c08049521b312c95f72c33e070706894a60f1c3f1eef

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 1.0.0
+
+- Added support for master key
+- Added support for Argon2id
+- Fixed `generate_key` for JRuby
+- Dropped support for Rails 4.2
+
+Breaking changes
+
+- Made Argon2id the default algorithm
+- Removed `encrypted_` prefix from columns
+- Changed default encoding to Base64 strict
+
 ## 0.3.5
 
 - Added support for hex keys

data/README.md

@@ -2,7 +2,7 @@
 
 Securely search encrypted database fields
 
-Designed for use with [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted)
+Works with [Lockbox](https://github.com/ankane/lockbox) and [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
 
@@ -28,45 +28,67 @@ Add this line to your application’s Gemfile:
 gem 'blind_index'
 ```
 
-## Getting Started
-
-> 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.
-
-Create a migration to add a column for the blind index
+On Windows, also add:
 
 ```ruby
-add_column :users, :encrypted_email_bidx, :string
-add_index :users, :encrypted_email_bidx
+gem 'argon2', git: 'https://github.com/technion/ruby-argon2.git', submodules: true
 ```
 
-Next, generate a key
+Until `argon2 >= 2.0.1` is released.
+
+## Getting Started
+
+> Note: Your model should already be set up with Lockbox or attr_encrypted. The examples are for a `User` model with `encrypts :email` or `attr_encrypted :email`. See the [full example](https://ankane.org/securing-user-emails-in-rails) if needed.
+
+First, generate a key
 
 ```ruby
 BlindIndex.generate_key
 ```
 
-Store the key with your other secrets. This is typically Rails credentials or an environment variable ([dotenv](https://github.com/bkeepers/dotenv) is great for this). Be sure to use different keys in development and production, and be sure this is different than the key you use for encryption. Keys don’t need to be hex-encoded, but it’s often easier to store them this way.
+Store the key with your other secrets. This is typically Rails credentials or an environment variable ([dotenv](https://github.com/bkeepers/dotenv) is great for this). Be sure to use different keys in development and production. Keys don’t need to be hex-encoded, but it’s often easier to store them this way.
 
-Here’s a key you can use in development
+Set the following environment variable with your key (you can use this one in development)
 
 ```sh
-EMAIL_BLIND_INDEX_KEY=ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+BLIND_INDEX_MASTER_KEY=ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+```
+
+or create `config/initializers/blind_index.rb` with something like
+
+```ruby
+BlindIndex.master_key = Rails.application.credentials.blind_index_master_key
+```
+
+Create a migration to add a column for the blind index
+
+```ruby
+add_column :users, :email_bidx, :string
+add_index :users, :email_bidx # unique: true if needed
 ```
 
 Add to your model
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, key: ENV["EMAIL_BLIND_INDEX_KEY"]
+  blind_index :email
+end
+```
+
+For more sensitive fields, use
+
+```ruby
+class User < ApplicationRecord
+  blind_index :email, slow: true
 end
 ```
 
 Backfill existing records
 
 ```ruby
-User.find_each do |user|
+User.unscoped.where(email_bidx: nil).find_each do |user|
   user.compute_email_bidx
-  user.save!
+  user.save(validate: false)
 end
 ```
 
@@ -94,7 +116,7 @@ You can apply expressions to attributes before indexing and searching. This give
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, expression: ->(v) { v.downcase } ...
+  blind_index :email, expression: ->(v) { v.downcase }
 end
 ```
 
@@ -103,25 +125,25 @@ end
 You may want multiple blind indexes for an attribute. To do this, add another column:
 
 ```ruby
-add_column :users, :encrypted_email_ci_bidx, :string
-add_index :users, :encrypted_email_ci_bidx
+add_column :users, :email_ci_bidx, :string
+add_index :users, :email_ci_bidx
 ```
 
 Update your model
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, ...
-  blind_index :email_ci, attribute: :email, expression: ->(v) { v.downcase } ...
+  blind_index :email
+  blind_index :email_ci, attribute: :email, expression: ->(v) { v.downcase }
 end
 ```
 
 Backfill existing records
 
 ```ruby
-User.find_each do |user|
+User.unscoped.where(email_ci_bidx: nil).find_each do |user|
   user.compute_email_ci_bidx
-  user.save!
+  user.save(validate: false)
 end
 ```
 
@@ -137,25 +159,23 @@ If you don’t need to store the original value (for instance, when just checkin
 
 ```ruby
 class User < ApplicationRecord
-  attribute :email
-  blind_index :email, ...
+  attribute :email, :string
+  blind_index :email
 end
 ```
 
-*Requires ActiveRecord 5.1+*
-
 ## Multiple Columns
 
 You can also use virtual attributes to index data from multiple columns:
 
 ```ruby
 class User < ApplicationRecord
-  attribute :initials
+  attribute :initials, :string
 
   # 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, ...
+  blind_index :initials
 
   def set_initials
     self.initials = "#{first_name[0]}#{last_name[0]}"
@@ -163,134 +183,176 @@ class User < ApplicationRecord
 end
 ```
 
-*Requires ActiveRecord 5.1+*
-
-## Algorithms
+## Key Rotation
 
-### PBKDF2-SHA256
+To rotate keys without downtime, add a new column:
 
-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.
+```ruby
+add_column :users, :email_bidx_v2, :string
+add_index :users, :email_bidx_v2
+```
 
-The default number of iterations is 10,000. For highly sensitive fields, set this to at least 100,000.
+And add to your model
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, iterations: 100000, ...
+  blind_index :email, rotate: {version: 2, master_key: ENV["BLIND_INDEX_MASTER_KEY_V2"]}
 end
 ```
 
-> Changing this requires you to recompute the blind index.
-
-### Argon2
+This will keep the new column synced going forward. Next, backfill the data:
 
-Argon2 is the state-of-the-art algorithm and recommended for best security.
+```ruby
+User.unscoped.where(email_bidx_v2: nil).find_each do |user|
+  user.compute_rotated_email_bidx
+  user.save(validate: false)
+end
+```
 
-To use it, add [argon2](https://github.com/technion/ruby-argon2) to your Gemfile and set:
+Then update your model
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, algorithm: :argon2, ...
+  blind_index :email, version: 2, master_key: ENV["BLIND_INDEX_MASTER_KEY_V2"]
 end
 ```
 
-The default cost parameters are `{t: 3, m: 12}`. For highly sensitive fields, set this to at least `{t: 4, m: 15}`.
+Finally, drop the old column.
+
+## Key Separation
+
+The master key is used to generate unique keys for each blind index. This technique comes from [CipherSweet](https://ciphersweet.paragonie.com/internals/key-hierarchy). The table name and blind index column name are both used in this process. If you need to rename a table with blind indexes, or a blind index column itself, get the key:
+
+```ruby
+BlindIndex.index_key(table: "users", bidx_attribute: "email_bidx")
+```
+
+And set it directly before renaming:
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, algorithm: :argon2, cost: {t: 4, m: 15}, ...
+  blind_index :email, key: ENV["USER_EMAIL_BLIND_INDEX_KEY"]
 end
 ```
 
-> Changing this requires you to recompute the blind index.
+## Algorithm
 
-The variant used is Argon2i.
+Argon2id is used for best security. The default cost parameters are 3 iterations and 4 MB of memory. For `slow: true`, the cost parameters are 4 iterations and 32 MB of memory.
 
-### Other
+A number of other algorithms are [also supported](docs/Other-Algorithms.md). Unless you have specific reasons to use them, go with Argon2id.
 
-scrypt is [also supported](docs/scrypt.md). Unless you have specific reasons to use it, go with Argon2 instead.
+## Fixtures
 
-## Key Rotation
+You can use blind indexes in fixtures with:
 
-To rotate keys without downtime, add a new column:
+```yml
+test_user:
+  email_bidx: <%= User.generate_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
+
+Set default options in an initializer with:
 
 ```ruby
-add_column :users, :encrypted_email_v2_bidx, :string
-add_index :users, :encrypted_email_v2_bidx
+BlindIndex.default_options = {algorithm: :pbkdf2_sha256}
 ```
 
-And add to your model
+By default, blind indexes are encoded in Base64. Set a different encoding with:
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, key: ENV["EMAIL_BLIND_INDEX_KEY"]
-  blind_index :email_v2, attribute: :email, key: ENV["EMAIL_V2_BLIND_INDEX_KEY"]
+  blind_index :email, encode: ->(v) { [v].pack("H*") }
 end
 ```
 
-Backfill the data
+By default, blind indexes are 32 bytes. Set a smaller size with:
 
 ```ruby
-User.find_each do |user|
-  user.compute_email_v2_bidx
-  user.save!
+class User < ApplicationRecord
+  blind_index :email, size: 16
 end
 ```
 
-Then update your model
+Set a key directly for an index with:
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, bidx_attribute: :encrypted_email_v2_bidx, key: ENV["EMAIL_V2_BLIND_INDEX_KEY"]
-
-  # remove this line after dropping column
-  self.ignored_columns = ["encrypted_email_bidx"]
+  blind_index :email, key: ENV["USER_EMAIL_BLIND_INDEX_KEY"]
 end
 ```
 
-Finally, drop the old column.
+## Alternatives
 
-## Fixtures
+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
 
-You can use encrypted attributes and blind indexes in fixtures with:
+### 1.0.0
 
-```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 %>
+1.0.0 brings a number of improvements. Here are a few to be aware of:
+
+- Argon2id is the default algorithm for stronger security
+- You can use a master key instead of individual keys for each column
+- Columns no longer have an `encrypted_` prefix
+
+For existing fields, add:
+
+```ruby
+class User < ApplicationRecord
+  blind_index :email, legacy: true
+end
 ```
 
-Be sure to include the `inspect` at the end, or it won’t be encoded properly in YAML.
+#### Optional
 
-## Reference
+To rotate to new fields that use Argon2id and a master key, generate a master key:
 
-Set default options in an initializer with:
+```ruby
+BlindIndex.generate_key
+```
+
+And set `ENV["BLIND_INDEX_MASTER_KEY"]` or `BlindIndex.master_key`.
+
+Add a new column without the `encrypted_` prefix:
 
 ```ruby
-BlindIndex.default_options[:algorithm] = :argon2
+add_column :users, :email_bidx, :string
+add_index :users, :email_bidx # unique: true if needed
 ```
 
-By default, blind indexes are encoded in Base64. Set a different encoding with:
+And add to your model
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, encode: ->(v) { [v].pack("H*") }
+  blind_index :email, key: ENV["USER_EMAIL_BLIND_INDEX_KEY"], legacy: true, rotate: true
 end
 ```
 
-By default, blind indexes are 32 bytes. Set a smaller size with:
+> For more sensitive fields, use `rotate: {slow: true}`
+
+This will keep the new column synced going forward. Next, backfill the data:
 
 ```ruby
-class User < ApplicationRecord
-  blind_index :email, size: 16
+User.unscoped.where(email_bidx: nil).find_each do |user|
+  user.compute_rotated_email_bidx
+  user.save(validate: false)
 end
 ```
 
-## Alternatives
+Then update your model
 
-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.
+```ruby
+class User < ApplicationRecord
+  blind_index :email
+end
+```
 
-## Upgrading
+> For more sensitive fields, add `slow: true`
+
+Finally, drop the old column.
 
 ### 0.3.0
 
@@ -306,16 +368,16 @@ Update your model to convert the hex key to binary.
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, key: [ENV["EMAIL_BLIND_INDEX_KEY"]].pack("H*")
+  blind_index :email, key: [ENV["USER_EMAIL_BLIND_INDEX_KEY"]].pack("H*")
 end
 ```
 
 And recompute the blind index.
 
 ```ruby
-User.find_each do |user|
+User.unscoped.find_each do |user|
   user.compute_email_bidx
-  user.save!
+  user.save(validate: false)
 end
 ```
 
@@ -323,7 +385,7 @@ To continue without rotating, set:
 
 ```ruby
 class User < ApplicationRecord
-  blind_index :email, insecure_key: true, ...
+  blind_index :email, insecure_key: true
 end
 ```
 

data/lib/blind_index.rb

@@ -1,7 +1,10 @@
 # dependencies
 require "active_support"
+require "openssl"
+require "argon2"
 
 # modules
+require "blind_index/key_generator"
 require "blind_index/model"
 require "blind_index/version"
 
@@ -10,23 +13,24 @@ module BlindIndex
 
   class << self
     attr_accessor :default_options
+    attr_writer :master_key
   end
   self.default_options = {}
 
+  def self.master_key
+    @master_key ||= ENV["BLIND_INDEX_MASTER_KEY"]
+  end
+
   def self.generate_bidx(value, key:, **options)
     options = {
-      iterations: 10000,
-      algorithm: :pbkdf2_sha256,
-      insecure_key: false,
-      encode: true,
-      cost: {}
+      encode: true
     }.merge(default_options).merge(options)
 
     # apply expression
     value = options[:expression].call(value) if options[:expression]
 
     unless value.nil?
-      algorithm = options[:algorithm].to_sym
+      algorithm = (options[:algorithm] || (options[:legacy] ? :pbkdf2_sha256 : :argon2id)).to_sym
       algorithm = :pbkdf2_sha256 if algorithm == :pbkdf2_hmac
       algorithm = :argon2i if algorithm == :argon2
 
@@ -35,18 +39,12 @@ module BlindIndex
 
       key = key.to_s
       unless options[:insecure_key] && algorithm == :pbkdf2_sha256
-        # decode hex key
-        if key.encoding != Encoding::BINARY && key =~ /\A[0-9a-f]{64}\z/i
-          key = [key].pack("H*")
-        end
-
-        raise BlindIndex::Error, "Key must use binary encoding" if key.encoding != Encoding::BINARY
-        raise BlindIndex::Error, "Key must be 32 bytes" if key.bytesize != 32
+        key = decode_key(key)
       end
 
       # gist to compare algorithm results
       # https://gist.github.com/ankane/fe3ac63fbf1c4550ee12554c664d2b8c
-      cost_options = options[:cost]
+      cost_options = options[:cost] || {}
 
       # check size
       size = (options[:size] || 32).to_i
@@ -56,11 +54,20 @@ module BlindIndex
 
       value =
         case algorithm
-        when :scrypt
-          n = cost_options[:n] || 4096
-          r = cost_options[:r] || 8
-          cp = cost_options[:p] || 1
-          SCrypt::Engine.scrypt(value, key, n, r, cp, size)
+        when :argon2id
+          t = (cost_options[:t] || (options[:slow] ? 4 : 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] || (options[:slow] ? 15 : 12)).to_i
+          # use same bounds as rbnacl
+          raise BlindIndex::Error, "m must be between 3 and 22" if m < 3 || m > 22
+
+          [Argon2::Engine.hash_argon2id(value, key, t, m, size)].pack("H*")
+        when :pbkdf2_sha256
+          iterations = cost_options[:iterations] || options[:iterations] || (options[:slow] ? 100000 : 10000)
+          OpenSSL::PKCS5.pbkdf2_hmac(value, key, iterations, size, "sha256")
         when :argon2i
           t = (cost_options[:t] || 3).to_i
           # use same bounds as rbnacl
@@ -71,14 +78,12 @@ module BlindIndex
           # 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, key, iterations, size, "sha256")
+          [Argon2::Engine.hash_argon2i(value, key, t, m, size)].pack("H*")
+        when :scrypt
+          n = cost_options[:n] || 4096
+          r = cost_options[:r] || 8
+          cp = cost_options[:p] || 1
+          SCrypt::Engine.scrypt(value, key, n, r, cp, size)
         else
           raise BlindIndex::Error, "Unknown algorithm"
         end
@@ -88,7 +93,7 @@ module BlindIndex
         if encode.respond_to?(:call)
           encode.call(value)
         else
-          [value].pack("m")
+          [value].pack(options[:legacy] ? "m" : "m0")
         end
       else
         value
@@ -98,7 +103,29 @@ module BlindIndex
 
   def self.generate_key
     require "securerandom"
-    SecureRandom.hex(32)
+    # force encoding to make JRuby consistent with MRI
+    SecureRandom.hex(32).force_encoding(Encoding::US_ASCII)
+  end
+
+  def self.index_key(table:, bidx_attribute:, master_key: nil, encode: true)
+    master_key ||= BlindIndex.master_key
+    raise BlindIndex::Error, "Missing master key" unless master_key
+
+    key = BlindIndex::KeyGenerator.new(master_key).index_key(table: table, bidx_attribute: bidx_attribute)
+    key = key.unpack("H*").first if encode
+    key
+  end
+
+  def self.decode_key(key)
+    # decode hex key
+    if key.encoding != Encoding::BINARY && key =~ /\A[0-9a-f]{64}\z/i
+      key = [key].pack("H*")
+    end
+
+    raise BlindIndex::Error, "Key must use binary encoding" if key.encoding != Encoding::BINARY
+    raise BlindIndex::Error, "Key must be 32 bytes" if key.bytesize != 32
+
+    key
   end
 end
 

data/lib/blind_index/key_generator.rb

@@ -0,0 +1,54 @@
+module BlindIndex
+  class KeyGenerator
+    def initialize(master_key)
+      @master_key = master_key
+    end
+
+    # pattern ported from CipherSweet
+    # https://ciphersweet.paragonie.com/internals/key-hierarchy
+    def index_key(table:, bidx_attribute:)
+      raise ArgumentError, "Missing table for key generation" if table.to_s.empty?
+      raise ArgumentError, "Missing field for key generation" if bidx_attribute.to_s.empty?
+
+      c = "\x7E"*32
+      root_key = hkdf(BlindIndex.decode_key(@master_key), salt: table.to_s, info: "#{c}#{bidx_attribute}", length: 32, hash: "sha384")
+      hash_hmac("sha256", pack([table, bidx_attribute, bidx_attribute]), root_key)
+    end
+
+    private
+
+    def hash_hmac(hash, ikm, salt)
+      OpenSSL::HMAC.digest(hash, salt, ikm)
+    end
+
+    def hkdf(ikm, salt:, info:, length:, hash:)
+      if OpenSSL::KDF.respond_to?(:hkdf)
+        return OpenSSL::KDF.hkdf(ikm, salt: salt, info: info, length: length, hash: hash)
+      end
+
+      prk = hash_hmac(hash, ikm, salt)
+
+      # empty binary string
+      t = String.new
+      last_block = String.new
+      block_index = 1
+      while t.bytesize < length
+        last_block = hash_hmac(hash, last_block + info + [block_index].pack("C"), prk)
+        t << last_block
+        block_index += 1
+      end
+
+      t[0, length]
+    end
+
+    def pack(pieces)
+      output = String.new
+      output << [pieces.size].pack("V")
+      pieces.map(&:to_s).each do |piece|
+        output << [piece.bytesize].pack("Q<")
+        output << piece
+      end
+      output
+    end
+  end
+end

data/lib/blind_index/model.rb

@@ -1,60 +1,85 @@
 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, size: nil)
-      iterations ||= 10000
-      attribute ||= name
-      bidx_attribute ||= :"encrypted_#{name}_bidx"
-
-      name = name.to_sym
-      attribute = attribute.to_sym
-      method_name = :"compute_#{name}_bidx"
-
-      class_eval do
-        @blind_indexes ||= {}
-
-        unless respond_to?(:blind_indexes)
-          def self.blind_indexes
-            parent_indexes =
-              if superclass.respond_to?(:blind_indexes)
-                superclass.blind_indexes
-              else
-                {}
-              end
-
-            parent_indexes.merge(@blind_indexes || {})
-          end
-        end
+    def blind_index(*attributes, rotate: false, migrating: false, **opts)
+      indexes = attributes.map { |a| [a, opts.dup] }
+      indexes.concat(attributes.map { |a| [a, rotate.merge(rotate: true)] }) if rotate
 
-        raise BlindIndex::Error, "Duplicate blind index: #{name}" if blind_indexes[name]
-
-        @blind_indexes[name] = {
-          key: key,
-          iterations: iterations,
-          attribute: attribute,
-          expression: expression,
-          bidx_attribute: bidx_attribute,
-          algorithm: algorithm,
-          insecure_key: insecure_key,
-          encode: encode,
-          cost: cost,
-          size: size
-        }.reject { |_, v| v.nil? }
-
-        # should have been named generate_#{name}_bidx
-        define_singleton_method method_name do |value|
-          BlindIndex.generate_bidx(value, blind_indexes[name])
-        end
+      indexes.each do |name, options|
+        rotate = options.delete(:rotate)
 
-        define_method method_name do
-          self.send("#{bidx_attribute}=", self.class.send(method_name, send(attribute)))
-        end
+        # check here so we validate rotate options as well
+        unknown_keywords = options.keys - [:algorithm, :attribute, :bidx_attribute,
+          :callback, :cost, :encode, :expression, :insecure_key, :iterations, :key,
+          :legacy, :master_key, :size, :slow]
+        raise ArgumentError, "unknown keywords: #{unknown_keywords.join(", ")}" if unknown_keywords.any?
 
-        if callback
-          before_validation method_name, if: -> { changes.key?(attribute.to_s) }
+        attribute = options[:attribute] || name
+        version = (options[:version] || 1).to_i
+        callback = options[:callback].nil? ? true : options[:callback]
+        if options[:bidx_attribute]
+          bidx_attribute = options[:bidx_attribute]
+        else
+          bidx_attribute = name
+          bidx_attribute = "encrypted_#{bidx_attribute}" if options[:legacy]
+          bidx_attribute = "#{bidx_attribute}_bidx"
+          bidx_attribute = "#{bidx_attribute}_v#{version}" if version != 1
         end
 
-        # use include so user can override
-        include InstanceMethods if blind_indexes.size == 1
+        name = "migrated_#{name}" if migrating
+        name = "rotated_#{name}" if rotate
+        name = name.to_sym
+        attribute = attribute.to_sym
+        method_name = :"compute_#{name}_bidx"
+        class_method_name = :"generate_#{name}_bidx"
+
+        key = options[:key]
+        key ||= -> { BlindIndex.index_key(table: table_name, bidx_attribute: bidx_attribute, master_key: options[:master_key], encode: false) }
+
+        class_eval do
+          @blind_indexes ||= {}
+
+          unless respond_to?(:blind_indexes)
+            def self.blind_indexes
+              parent_indexes =
+                if superclass.respond_to?(:blind_indexes)
+                  superclass.blind_indexes
+                else
+                  {}
+                end
+
+              parent_indexes.merge(@blind_indexes || {})
+            end
+          end
+
+          raise BlindIndex::Error, "Duplicate blind index: #{name}" if blind_indexes[name]
+
+          @blind_indexes[name] = options.merge(
+            key: key,
+            attribute: attribute,
+            bidx_attribute: bidx_attribute,
+            migrating: migrating
+          )
+
+          define_singleton_method class_method_name do |value|
+            BlindIndex.generate_bidx(value, blind_indexes[name])
+          end
+
+          define_singleton_method method_name do |value|
+            ActiveSupport::Deprecation.warn("Use #{class_method_name} instead")
+            send(class_method_name, value)
+          end
+
+          define_method method_name do
+            self.send("#{bidx_attribute}=", self.class.send(class_method_name, send(attribute)))
+          end
+
+          if callback
+            before_validation method_name, if: -> { changes.key?(attribute.to_s) }
+          end
+
+          # use include so user can override
+          include InstanceMethods if blind_indexes.size == 1
+        end
       end
     end
   end

data/lib/blind_index/version.rb

@@ -1,3 +1,3 @@
 module BlindIndex
-  VERSION = "0.3.5"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blind_index
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 1.0.0
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-29 00:00:00.000000000 Z
+date: 2019-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,14 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: argon2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -98,16 +112,16 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: scrypt
   requirement: !ruby/object:Gem::Requirement
@@ -123,7 +137,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: argon2
+  name: benchmark-ips
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -137,19 +151,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: benchmark-ips
+  name: lockbox
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
 description: 
 email: andrew@chartkick.com
 executables: []
@@ -161,6 +175,7 @@ files:
 - README.md
 - lib/blind_index.rb
 - lib/blind_index/extensions.rb
+- lib/blind_index/key_generator.rb
 - lib/blind_index/model.rb
 - lib/blind_index/version.rb
 homepage: https://github.com/ankane/blind_index
@@ -175,14 +190,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.2'
+      version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.4
 signing_key: 
 specification_version: 4
 summary: Securely search encrypted database fields