README.md in blind_index-1.0.2 vs README.md in blind_index-2.0.0
- old
+ new
@@ -24,42 +24,18 @@
```ruby
gem 'blind_index'
```
-On Windows, also add:
-
-```ruby
-gem 'argon2', git: 'https://github.com/technion/ruby-argon2.git', submodules: true
-```
-
-Until `argon2 > 2.0.2` 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 examples for [Lockbox](https://ankane.org/securing-user-emails-lockbox) and [attr_encrypted](https://ankane.org/securing-user-emails-in-rails) if needed.
+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 examples for [Lockbox](https://ankane.org/securing-user-emails-lockbox) and [attr_encrypted](https://ankane.org/securing-user-emails-in-rails) if needed.
-First, generate a key
+Also, if you use attr_encrypted, [generate a key](#key-generation).
-```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. Keys don’t need to be hex-encoded, but it’s often easier to store them this way.
-
-Set the following environment variable with your key (you can use this one in development)
-
-```sh
-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
@@ -167,22 +143,41 @@
You can also use virtual attributes to index data from multiple columns:
```ruby
class User < ApplicationRecord
attribute :initials, :string
+ blind_index :initials
- # 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
self.initials = "#{first_name[0]}#{last_name[0]}"
end
end
```
+## Migrating Data
+
+If you’re encrypting a column and adding a blind index at the same time, use the `migrating` option.
+
+```ruby
+class User < ApplicationRecord
+ blind_index :email, migrating: true
+end
+```
+
+This allows you to backfill records while still querying the unencrypted field.
+
+```ruby
+User.unscoped.where(email_bidx: nil).find_each do |user|
+ user.compute_migrated_email_bidx
+ user.save(validate: false)
+end
+```
+
+Once that completes, you can remove the `migrating` option.
+
## Key Rotation
To rotate keys without downtime, add a new column:
```ruby
@@ -258,10 +253,34 @@
class User
field :email_bidx, type: String
end
```
+## Key Generation
+
+This is optional for Lockbox, as its master key is used by default.
+
+Generate a key with:
+
+```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. Keys don’t need to be hex-encoded, but it’s often easier to store them this way.
+
+Set the following environment variable with your key (you can use this one in development)
+
+```sh
+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
+```
+
## Reference
Set default options in an initializer with:
```ruby
@@ -298,9 +317,17 @@
1. You can keep encryption consistent for all fields (both searchable and non-searchable)
2. Blind indexing supports expressions
## Upgrading
+
+### 2.0.0
+
+2.0.0 brings a number of improvements.
+
+- Blind indexes are updated immediately instead of in a `before_validation` callback
+- Better Lockbox integration - no need to generate a separate key
+- There’s a new gem for Argon2 that has no dependencies and (officially) supports Windows
### 1.0.0
1.0.0 brings a number of improvements. Here are a few to be aware of: