README.md in vault-rails-0.5.0 vs README.md in vault-rails-0.6.0

- old
+ new

@@ -3,12 +3,21 @@ Vault is the official Rails plugin for interacting with [Vault](https://vaultproject.io) by HashiCorp. **The documentation in this README corresponds to the master branch of the Vault Rails plugin. It may contain unreleased features or different APIs than the most recently released version. Please see the Git tag that corresponds to your version of the Vault Rails plugin for the proper documentation.** +## Table of Contents +1. [Quick Start](#quick-start) +1. [Advanced Configuration](#advanced-configuration) +1. [Caveats](#caveats) +1. [Development](#development) + + Quick Start ----------- +↥ [back to top](#table-of-contents) + 1. Add to your Gemfile: ```ruby gem "vault-rails", "~> 0.1", require: false ``` @@ -23,17 +32,17 @@ Vault::Rails.configure do |vault| # Use Vault in transit mode for encrypting and decrypting data. If # disabled, vault-rails will encrypt data in-memory using a similar # algorithm to Vault. The in-memory store uses a predictable encryption # which is great for development and test, but should _never_ be used in - # production. + # production. Default: ENV["VAULT_RAILS_ENABLED"]. vault.enabled = Rails.env.production? # The name of the application. All encrypted keys in Vault will be # prefixed with this application name. If you change the name of the # application, you will need to migrate the encrypted data to the new - # key namespace. + # key namespace. Default: ENV["VAULT_RAILS_APPLICATION"]. vault.application = "my_app" # The address of the Vault server. Default: ENV["VAULT_ADDR"]. vault.address = "https://vault.corp" @@ -58,11 +67,11 @@ Each attribute you want to encrypt must have a corresponding `attribute_encrypted` column in the database. For the above example: ```ruby class AddEncryptedSSNToPerson < ActiveRecord::Migration - add_column :persons, :ssn_encrypted, :string + add_column :people, :ssn_encrypted, :string end ``` That is it! The plugin will transparently handle the encryption and decryption of secrets with Vault: @@ -74,10 +83,12 @@ ``` Advanced Configuration ---------------------- +↥ [back to top](#table-of-contents) + The following section details some of the more advanced configuration options for vault-rails. As a general rule, you should try to use vault-rails without these options until absolutely necessary. #### Specifying the encrypted column By default, the name of the encrypted column is `#{column}_encrypted`. This is customizable by setting the `:encrypted_column` option when declaring the attribute: @@ -167,11 +178,11 @@ ``` - **Note** Changing this value for an existing application will make existing values no longer decryptable! #### Lazy attribute decryption -By default, `vault-rails` will decrypt a record’s encrypted attributes on that record’s initializarion. You can configure an encrypted model to decrypt attributes lazily, which will prevent communication with Vault until an encrypted attribute’s getter method is called, at which point all of the record’s encrypted attributes will be decrypted. This is useful if you do not always need access to encrypted attributes. For example: +By default, `vault-rails` will decrypt a record’s encrypted attributes on that record’s initialization. You can configure an encrypted model to decrypt attributes lazily, which will prevent communication with Vault until an encrypted attribute’s getter method is called, at which point all of the record’s encrypted attributes will be decrypted. This is useful if you do not always need access to encrypted attributes. For example: ```ruby class Person < ActiveRecord::Base include Vault::EncryptedModel @@ -189,10 +200,37 @@ person = Person.find(id) person.ssn # Vault communication happens here # => "123-45-6789" ``` +#### Single, lazy attribute decryption +By default, `vault-rails` will decrypt all encrypted attributes on that record’s initialization on a class by class basis. You can configure an encrypted model to decrypt attributes lazily and and individually. This will prevent vault from loading all vault_attributes defined on a class the moment one attribute is requested. + + +```ruby +class Person < ActiveRecord::Base + include Vault::EncryptedModel + vault_lazy_decrypt! + vault_single_decrypt! + + vault_attribute :ssn + vault_attribute :email +end + +# Without vault_single_decrypt: +person = Person.find(id) # Vault communication happens here +person.ssn # Vault communication happens here, fetches both ssn and email +# => "123-45-6789" + +# With vault_single_decrypt: +person = Person.find(id) +person.ssn # Vault communication happens here, fetches only ssn +# => "123-45-6789" +person.email # Vault communication happens here, fetches only email +# => "foobar@baz.com" +``` + #### Serialization By default, all values are assumed to be "text" fields in the database. Sometimes it is beneficial for your application to work with a more flexible data structure (such as a Hash or Array). Vault-rails can automatically serialize and deserialize these structures for you: ```ruby @@ -241,11 +279,13 @@ - **Note** Changing the algorithm for encoding/decoding for an existing application will probably make the application crash when attempting to retrieve existing values! Caveats ------- +↥ [back to top](#table-of-contents) + ### Mounting/Creating Keys in Vault The Vault Rails plugin does not automatically mount a backend. It is assumed the proper backend is mounted and accessible by the given token. You can mount a transit backend like this: ```shell $ vault mount transit @@ -303,9 +343,11 @@ the security model). Development ----------- +↥ [back to top](#table-of-contents) + 1. Clone the project on GitHub 2. Create a feature branch 3. Submit a Pull Request Important Notes: