README.md in lockbox-0.4.7 vs README.md in lockbox-0.4.8

@@ -1,15 +1,13 @@
 # Lockbox
 
 :package: Modern encryption for Rails
 
-- Uses state-of-the-art algorithms
 - Works with database fields, files, and strings
+- Maximizes compatibility with existing code and libraries
 - Makes migrating existing data and key rotation easy
 
-Lockbox aims to make encryption as friendly and intuitive as possible. Encrypted fields and files behave just like unencrypted ones for maximum compatibility with 3rd party libraries and existing code.
-
 Learn [the principles behind it](https://ankane.org/modern-encryption-rails), [how to secure emails with Devise](https://ankane.org/securing-user-emails-lockbox), and [how to secure sensitive data in Rails](https://ankane.org/sensitive-data-rails).
 
 [![Build Status](https://travis-ci.org/ankane/lockbox.svg?branch=master)](https://travis-ci.org/ankane/lockbox)
 
 ## Installation
@@ -87,10 +85,20 @@
 User.create!(email: "[e-mail]")
 ```
 
 If you need to query encrypted fields, check out [Blind Index](https://github.com/ankane/blind_index).
 
+#### Multiple Fields
+
+You can specify multiple fields in single line.
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email, :phone, :city
+end
+```
+
 #### Types
 
 Fields are strings by default. Specify the type of a field with:
 
 ```ruby
@@ -186,10 +194,18 @@
 class User < ApplicationRecord
   blind_index :email, migrating: true
 end
 ```
 
+#### Decryption
+
+To decrypt data outside the model, use:
+
+```ruby
+User.decrypt_email_ciphertext(user.email_ciphertext)
+```
+
 ## Action Text
 
 **Note:** Action Text uses direct uploads for files, which cannot be encrypted with application-level encryption like Lockbox. This only encrypts the database field.
 
 Create a migration with:
@@ -220,10 +236,14 @@
 Lockbox.encrypts_action_text_body
 ```
 
 And drop the unencrypted column.
 
+#### Options
+
+You can pass any Lockbox options to the `encrypts_action_text_body` method.
+
 ## Mongoid
 
 Add to your model:
 
 ```ruby
@@ -741,22 +761,70 @@
 
 Make sure `decryption_key` is `nil` on servers that shouldn’t decrypt.
 
 This uses X25519 for key exchange and XSalsa20 for encryption.
 
-## Key Separation
+## Key Configuration
 
-The master key is used to generate unique keys for each column. This technique comes from [CipherSweet](https://ciphersweet.paragonie.com/internals/key-hierarchy). The table name and column name are both used in this process. If you need to rename a table with encrypted columns, or an encrypted column itself, get the key:
+Lockbox supports a few different ways to set keys for database fields and files.
 
+1. Master key
+2. Per field/uploader
+3. Per record
+
+### Master Key
+
+By default, the master key is used to generate unique keys for each field/uploader. This technique comes from [CipherSweet](https://ciphersweet.paragonie.com/internals/key-hierarchy). The table name and column/uploader name are both used in this process. You can get an individual key with:
+
 ```ruby
 Lockbox.attribute_key(table: "users", attribute: "email_ciphertext")
 ```
 
-And set it directly before renaming:
+To rename a table with encrypted columns/uploaders, use:
 
 ```ruby
 class User < ApplicationRecord
+  encrypts :email, key_table: "original_table"
+end
+```
+
+To rename an encrypted column itself, use:
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email, key_attribute: "original_column"
+end
+```
+
+### Per Field/Uploader
+
+To set a key for an individual field/uploader, use a string:
+
+```ruby
+class User < ApplicationRecord
   encrypts :email, key: ENV["USER_EMAIL_ENCRYPTION_KEY"]
+end
+```
+
+Or a proc:
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email, key: -> { code }
+end
+```
+
+### Per Record
+
+To use a different key for each record, use a symbol:
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email, key: :some_method
+
+  def some_method
+    # code to get key
+  end
 end
 ```
 
 ## Key Management