README.md in blind_index-0.1.1 vs README.md in blind_index-0.2.0
- old
+ new
@@ -6,11 +6,11 @@
[![Build Status](https://travis-ci.org/ankane/blind_index.svg?branch=master)](https://travis-ci.org/ankane/blind_index)
## How It Works
-This project uses [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) 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
Add these lines to your application’s Gemfile:
@@ -21,35 +21,34 @@
Add columns for the encrypted data and the blind index
```ruby
# encrypted data
-add_column :users, :encrypted_email, :text
-add_column :users, :encrypted_email_iv, :text
+add_column :users, :encrypted_email, :string
+add_column :users, :encrypted_email_iv, :string
# blind index
-add_column :users, :encrypted_email_bidx, :text
+add_column :users, :encrypted_email_bidx, :string
add_index :users, :encrypted_email_bidx
```
-Generate one key for encryption and one key for hashing and set them in your environment ([dotenv](https://github.com/bkeepers/dotenv) is great for this). For development, you can use these:
-
-```sh
-EMAIL_ENCRYPTION_KEY=00000000000000000000000000000000
-EMAIL_BLIND_INDEX_KEY=99999999999999999999999999999999
-```
-
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"]
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:
+
+```sh
+EMAIL_ENCRYPTION_KEY=00000000000000000000000000000000
+EMAIL_BLIND_INDEX_KEY=99999999999999999999999999999999
+```
+
And query away
```ruby
User.where(email: "test@example.org")
```
@@ -79,11 +78,11 @@
## Multiple Indexes
You may want multiple blind indexes for an attribute. To do this, add another column:
```ruby
-add_column :users, :encrypted_email_ci_bidx, :text
+add_column :users, :encrypted_email_ci_bidx, :string
add_index :users, :encrypted_email_ci_bidx
```
And update your model
@@ -117,11 +116,10 @@
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
```
## History
@@ -134,5 +132,14 @@
- [Report bugs](https://github.com/ankane/blind_index/issues)
- Fix bugs and [submit pull requests](https://github.com/ankane/blind_index/pulls)
- Write, clarify, or fix documentation
- Suggest or add new features
+
+To get started with development and testing:
+
+```sh
+git clone https://github.com/ankane/blind_index.git
+cd blind_index
+bundle install
+rake test
+```