chef-vault 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d1d708e9e29a406be66537a1e4f2001bfca5c4fd
-  data.tar.gz: e3d77a016b45ee414f9944657f6be4037b409d53
+  metadata.gz: 9b27ba9a529d3f084f1e83119a6b6bf91819ba3a
+  data.tar.gz: eacae88edbe78fc8e0a27c7f6e5680b1e75e974d
 SHA512:
-  metadata.gz: 728d1dc1cad74668f52576130e0171a1bcea7ccdf21a6f1a32861e231e194e52016d94bce5e9028f91ef87ec6a877daa22b63db05f1afe6a441910551c34bdae
-  data.tar.gz: e811b693b9363d55fea010ef9cdd20e2bfbe8955686eaf087d494cab30f1cdc6b64a9737d3a04b6e730622a24aee03dfc163f3c95c3ea5c24468d6360ab132d2
+  metadata.gz: 1d18b4a6f3cfedf225041ee9b6e8c05b2c476f9fa8f04903038cec23bf631ee9a135c6c7199c26ce49971ed415651b22ec552bacd2cc684aa4a749096db90c81
+  data.tar.gz: 0895619aff3da11cb0d024bb87d8cbe00ba1330b4aa80bd6537cf1d2600f6b814e63ea291338c69d08456633d572d0464ab6a0b278018a0d7f95a8d2cd74070f

data/.rubocop_todo.yml

@@ -5,6 +5,10 @@
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
+AllCops:
+  Exclude:
+    - 'features/step_definitions/*.rb'
+
 # Offense count: 12
 Metrics/AbcSize:
   Max: 43
@@ -16,7 +20,7 @@ Metrics/BlockNesting:
 # Offense count: 1
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 247
+  Max: 306
 
 # Offense count: 5
 Metrics/CyclomaticComplexity:

data/.travis.yml

@@ -2,6 +2,10 @@ language: ruby
 rvm:
   - "1.9.3-p551"
   - "2.0.0-p598"
-  - "2.1.5"
+  - "2.1.6"
+  - "2.2.2"
 install: bundle install --binstubs
 env: TRAVIS_BUILD=true
+matrix:
+  allow_failures:
+    - rvm: "1.9.3-p551"

data/Changelog.md

@@ -1,7 +1,4 @@
 ## Planned (Unreleased)
-## v2.6.0
-
-This release will focus on adding any new features covered by open issues
 
 ## v2.7.0
 
@@ -27,7 +24,24 @@ chef-vault issues on github for news).
 This release will also remove the chef-vault 1.x commands (encrypt/decrypt)
 
 ## Released
+
+## v2.6.0 / 2015-05-13
+
+* ChefVault::Item#clients can now accept a Chef::ApiClient object instead of a search string.  Requested by @lamont-granquist to make implementing chef-vault into `knife bootstrap` easier
+* allow Ruby 1.9.3 failures to not cause the overall build to fail on Travis
+* switch to latest 2.0.x, 2.1.x, and 2.2.x releases of Ruby
+* add --clean-unknown-clients switch to `knife vault refresh`
+  * as a side effect, `ChefVault::Item` now has a `#refresh` method which can be used to programatically perform the same operation as `knife vault refresh`
+* enhance 'knife vault show VAULTNAME' (without an item name) to list the names of the items in the vault for parity with 'knife data bag show'
+* add #raw_keys to ChefVault::Item that calls #keys on the underlying data bag item.  We can't make ChefVault::Item work like a true hash without breaking the public API, but this at least makes it easier to get a list of keys
+* allow ChefVault::Item.new and ChefVault::Item.load to specify an alternate node name and client key path.  See the README for the use case this serves.
+* added ChefVault::Item.vault? predicate that returns true if the item is a vault and false otherwise
+* added ChefVault::Item.data_bag_item_type method that returns one of :normal, :encrypted or :vault
+* added 'knife vault isvault VAULT ITEM' subcommand that exits 0 if the item is a vault and 1 if it is not
+* added 'knife vault itemtype VAULT ITEM' subcommand that outputs 'normal', 'encrypted' or 'vault'
+
 ## v2.5.0 / 2015-02-09
+
 * when decrypting, if the vault is encrypted for the node but decryption fails, emit a more friendly error message than 'OpenSSL::PKey::RSAError: padding check failed'
 * when attempting to add a client key to a vault item, warn and skip if the node doesn't have a public key (reported by Nik Ormseth)
 * add a new 'knife vault list' command that lists the data bags that are vaults
@@ -36,23 +50,28 @@ This release will also remove the chef-vault 1.x commands (encrypt/decrypt)
 * add rubocop tasks to Rakefile and take a first pass at the low-hanging fruit
 
 ## v2.4.0 / 2014-12-03
+
 * add simplecov test coverage configuration (Doug Ireton)
 * add --clean-unknown-clients switch to knife remove/rotate (Thomas Gschwind and Reto Hermann)
 
 ## v2.3.0 / 2014-10-22
+
 * add --clean switch to knife update (thanks to Matt Brimstone)
 * added aruba CLI testing framework (just for --clean option for now)
 * add Ruby 2.0.x and 2.1.x to Travis platforms
 
 ## v2.2.2 / 2014-06-03
+
 * Add knife vault refresh command
 * Use node_name as a default admin
 * Add DEMO for users
 
 ## v2.2.1 / 2014-02-26
+
 * Add vault_admins to knife.rb for a default set of vault admins
 
 ## v2.2.0 / 2014-01-21
+
 * Validate data bag ID before saving
 * Add search_query to vault metadata
 * Refactor knife commands to be knife vault verb
@@ -64,16 +83,19 @@ This release will also remove the chef-vault 1.x commands (encrypt/decrypt)
 * Fix more README typos
 
 ## v2.1.0 / 2013-12-23
+
 * Update README to correct typos
 * Modify admin loading to fall back to clients endpoint if not found in users endpoint
 * Add --file to "knife encrypt update" & "knife encrypt create" to do file encryption in chef-vault.  It will create a key called "file-content" & "file-name"
 * When VALUES is not supplied print the whole vault item
 
 ## v2.0.2 / 2013-09-10
+
 * Modify written data bag json files in solo mode to be valid for the knife data bag from file command
 * Modify knife encrypt remove to automatically rotate keys
 
 ## v2.0.1 / 2013-09-03
+
 * Removal of knife encrypt certs
 * Removal of knife encrypt passwords
 * Add knife encrypt create
@@ -89,33 +111,44 @@ This release will also remove the chef-vault 1.x commands (encrypt/decrypt)
 * Modify ChefVault::Certificate to use ChefVault::Item to maintain backwards compatability
 
 ## v1.2.5 / 2013-07-22
+
 * Update compat to be class ChefVault not module ChefVault to remove knife errors
 * Allow nodes/clients to be used as Admins
 
 ## v1.2.4 / 2013-07-01
+
 * Move compat include into the lazy-load deps
 * Modify open file commands in knife commands to avoid file locking on windows
 
 ## v1.2.3 / 2013-04-30
+
 * Update to use attr_accessor in chef_vault
 * Add rspec tests
 
 ## v1.2.2 / 2013-04-23
+
 * Update to create data bag folder if it does not already exist
 
 ## v1.2.1 / 2013-04-23
+
 * Clarify Readme
 
 ## v1.0.1 / 2013-04-12
+
 * Compatibility with Chef 10/11 (Shef vs Chef-Shell)
 
 ## v1.0.0 / 2013-04-08
+
 * Rename from Chef-Keepass to Chef-Vault
 
 ## v0.2.1 / 2013-04/05
+
 * Add Certificate class
 
 ## v0.2.0 / 2013-04-05
+
 * Add encrypt cert
 
 ## v0.1.1 / 2013-03-14
+
+* initial release

data/KNIFE_EXAMPLES.md

@@ -1,13 +1,14 @@
 # knife examples
 
 ## vault
-knife vault *\<command\>* VAULT ITEM VALUES
+
+    knife vault SUBCOMMAND VAULT ITEM VALUES
 
 These are the commands that are used to take data in JSON format and encrypt that data into chef-vault style encrypted data bags in chef.
 
-* Vault - This is the name of the vault in which to store the encrypted item.  This is analogous to a chef data bag name
-* Item - The name of the item going in to the vault.  This is analogous to a chef data bag item id
-* Values - This is the JSON clear text data to be stored in the vault encrypted.  This is analogous to a chef data bag item data
+* vault - This is the name of the vault in which to store the encrypted item.  This is analogous to a chef data bag name
+* item - The name of the item going in to the vault.  This is analogous to a chef data bag item id
+* values - This is the JSON clear text data to be stored in the vault encrypted.  This is analogous to a chef data bag item data
 
 ## vault commands
 
@@ -31,6 +32,7 @@ Create a vault called passwords and put an item called root in it encrypted for
 Note: A JSON file can be used in place of specifying the values on the command line, see global options below for details
 
 ### update
+
 Update the values in username and password in the vault passwords and item root.  Will overwrite existing values if values already exist!
 
     knife vault update passwords root '{"username": "root", "password": "mypassword"}'
@@ -62,6 +64,7 @@ Add admin1 & admin2 to encrypted admins and role:webserver to encrypted clients
 Note: A JSON file can be used in place of specifying the values on the command line, see global options below for details
 
 ### remove
+
 Remove the values in username and password from the vault passwords and item root.
 
     knife vault remove passwords root '{"username": "root", "password": "mypassword"}'
@@ -91,18 +94,24 @@ Remove admin1 & admin2 from encrypted admins and role:webserver from encrypted c
     knife vault remove passwords root -S "role:webserver" -A "admin1,admin2"
 
 ### delete
+
 Delete the item root from the vault passwords
 
     knife vault delete passwords root
 
 ### show
-knife vault show VAULT ITEM [VALUES]
+
+knife vault show VAULT [ITEM] [VALUES]
 
 These are the commands that are used to decrypt a chef-vault encrypted item and show the requested values.
 
-* Vault - This is the name of the vault in which to store the encrypted item.  This is analogous to a chef data bag name
-* Item - The name of the item going in to the vault.  This is analogous to a chef data bag item id
-* Values - This is a comma list of values to decrypt from the vault item.  This is analogous to a list of hash keys.
+* vault - This is the name of the vault in which to store the encrypted item.  This is analogous to a chef data bag name
+* item - The name of the item going in to the vault.  This is analogous to a chef data bag item id
+* values - This is a comma list of values to decrypt from the vault item.  This is analogous to a list of hash keys.
+
+Show the items in a vault
+
+    knife vault show passwords
 
 Show the entire root item in the passwords vault and print in JSON format.
 
@@ -121,6 +130,7 @@ Show the contents for the item user_pem in the vault certs.
     knife vault show certs user_pem "contents"
 
 ### edit
+
 knife vault edit VAULT ITEM
 
 These are the commands that are used to edit a chef-vault encrypted item.
@@ -133,11 +143,13 @@ Decrypt the entire root item in the passwords vault and open it in json format i
     knife vault edit passwords root
 
 ### download
+
 Decrypt and download an encrypted file to the specified path.
 
     knife vault download certs user_pem ~/downloaded_user_pem
 
 ### rotate keys
+
 Rotate the shared key for the vault passwords and item root. The shared key is that which is used for the chef encrypted data bag item.
 
     knife vault rotate keys passwords root
@@ -147,6 +159,7 @@ To remove clients which have been deleted from Chef but not from the vault, add
     knife vault rotate keys passwords root --clean-unknown-clients
 
 ### rotate all keys
+
 Rotate the shared key for all vaults and items. The shared key is that which is used for the chef encrypted data bag item.
 
     knife vault rotate all keys
@@ -156,74 +169,36 @@ To remove clients which have been deleted from Chef but not from the vault, add
     knife vault rotate keys passwords root --clean-unknown-clients
 
 ### refresh
+
 This command reads the search_query in the vault item, performs the search, and reapplies the results.
 
     knife vault refresh VAULT ITEM
 
+To remove clients which have been deleted from Chef but not from the vault, add the --clean-unknown-clients switch:
+
+    knife vault refresh passwords root --clean-unknown-clients
+
+### isvault
+
+This command checks if the given item is a vault or not, and exit with a status of 0 if it is and 1 if it is not.
+
+    knife vault isvault VAULT ITEM
+
+### itemtype
+
+This command outputs the type of the data bag item: normal, encrypted or vault
+
+    knife vault itemtype VAULT ITEM
+
 ### global options
-<table>
-  <tr>
-    <th>Short</th>
-    <th>Long</th>
-    <th>Description</th>
-    <th>Default</th>
-    <th>Valid Values</th>
-    <th>Sub-Commands</th>
-  </tr>
-  <tr>
-    <td>-M MODE</td>
-    <td>--mode MODE</td>
-    <td>Chef mode to run in</td>
-    <td>solo</td>
-    <td>"solo", "client"</td>
-    <td>all</td>
-  </tr>
-  <tr>
-    <td>-S SEARCH</td>
-    <td>--search SEARCH</td>
-    <td>Chef Server SOLR Search Of Nodes</td>
-    <td>nil</td>
-    <td></td>
-    <td>create, remove, update</td>
-  </tr>
-  <tr>
-    <td>-A ADMINS</td>
-    <td>--admins ADMINS</td>
-    <td>Chef clients or users to be vault admins, can be comma list</td>
-    <td>nil</td>
-    <td></td>
-    <td>create, remove, update</td>
-  </tr>
-  <tr>
-    <td>-J FILE</td>
-    <td>--json FILE</td>
-    <td>JSON file to be used for values, will be merged with VALUES if VALUES is passed</td>
-    <td>nil</td>
-    <td></td>
-    <td>create, update</td>
-  </tr>
-  <tr>
-    <td>nil</td>
-    <td>--file FILE</td>
-    <td>File that chef-vault should encrypt.  It adds "file-content" & "file-name" keys to the vault item</td>
-    <td>nil</td>
-    <td></td>
-    <td>create, update</td>
-  </tr>
-  <tr>
-    <td>-p DATA</td>
-    <td>--print DATA</td>
-    <td>Print extra vault data</td>
-    <td>nil</td>
-    <td>"search", "clients", "admins", "all"</td>
-    <td>show</td>
-  </tr>
-  <tr>
-    <td>-F FORMAT</td>
-    <td>--format FORMAT</td>
-    <td>Format for decrypted output</td>
-    <td>summary</td>
-    <td>"summary", "json", "yaml", "pp"</td>
-    <td>show</td>
-  </tr>
-</table>
+
+Short | Long | Description | Default | Valid Values | Sub-Commands
+------|------|-------------|---------|--------------|-------------
+-M MODE | --mode MODE | Chef mode to run in. Can be set in knife.rb | solo | solo, client | all
+-S SEARCH | --search SEARCH | Chef Server SOLR Search Of Nodes | | | create, remove , update
+-A ADMINS | --admins ADMINS | Chef clients or users to be vault admins, can be comma list | | | create, remove, update
+-J FILE | --json FILE | JSON file to be used for values, will be merged with VALUES if VALUES is passed | | | create, update
+| --file FILE | File that chef-vault should encrypt.  It adds "file-content" & "file-name" keys to the vault item | | | create, update
+-p DATA | --print DATA | Print extra vault data | | search, clients, admins, all | show
+-F FORMAT | --format FORMAT | Format for decrypted output | summary | summary, json, yaml, pp | show
+| --clean-unknown-clients | Remove unknown clients during key rotation | | | refresh, remove, rotate

data/README.md

@@ -1,19 +1,26 @@
 # Chef-Vault
+
 [![Gem Version](https://badge.fury.io/rb/chef-vault.png)](http://badge.fury.io/rb/chef-vault)
 
 [![Build Status](https://travis-ci.org/Nordstrom/chef-vault.png?branch=master)](https://travis-ci.org/Nordstrom/chef-vault)
 
+[![Inline docs](http://inch-ci.org/github/nordstrom/chef-vault.svg?branch=master)](http://inch-ci.org/github/nordstrom/chef-vault)
+
 [![Code Climate](https://codeclimate.com/github/Nordstrom/chef-vault/badges/gpa.svg)](https://codeclimate.com/github/Nordstrom/chef-vault)
 
 ## DESCRIPTION:
 
-Gem that allows you to encrypt a Chef Data Bag Item using the public keys of a list of chef nodes. This allows only those chef nodes to decrypt the encrypted values.
+Gem that allows you to encrypt a Chef Data Bag Item using the public keys of
+a list of chef nodes. This allows only those chef nodes to decrypt the
+encrypted values.
 
-For a more detailed explanation of how chef-vault works, please refer to the file THEORY.md
+For a more detailed explanation of how chef-vault works, please refer to the
+file THEORY.md.
 
 ## INSTALLATION:
 
-Be sure you are running the latest version Chef. Versions earlier than 0.10.0 don't support plugins:
+Be sure you are running the latest version Chef. Versions earlier than
+0.10.0 don't support plugins:
 
     gem install chef
 
@@ -21,23 +28,28 @@ This plugin is distributed as a Ruby Gem. To install it, run:
 
     gem install chef-vault
 
-Depending on your system's configuration, you may need to run this command with root privileges.
+Depending on your system's configuration, you may need to run this command
+with root privileges.
 
 ## KNIFE COMMANDS:
+
 See KNIFE_EXAMPLES.md for examples of commands
 
 ### knife.rb
+
 To set 'client' as the default mode, add the following line to the knife.rb file.
 
-```knife[:vault_mode] = 'client'```
+    knife[:vault_mode] = 'client'
 
-To set the default list of admins for creating and updating vaults, add the following line to the knife.rb file.
+To set the default list of admins for creating and updating vaults, add the
+following line to the knife.rb file.
 
-```knife[:vault_admins] = [ 'example-alice', 'example-bob', 'example-carol' ]```
+    knife[:vault_admins] = [ 'example-alice', 'example-bob', 'example-carol' ]
 
 (These values can be overridden on the command line by using -A)
 
-NOTE: chef-vault 1.0 knife commands are not supported!  Please use chef-vault 2.0 commands.
+NOTE: chef-vault 1.0 knife commands are not supported! Please use chef-vault
+2.0 commands.
 
 ### Vault
 
@@ -49,122 +61,172 @@ NOTE: chef-vault 1.0 knife commands are not supported!  Please use chef-vault 2.
     knife vault delete VAULT ITEM
     knife vault rotate keys VAULT ITEM
     knife vault rotate all keys
-    knife vault show VAULT ITEM [VALUES]
+    knife vault show VAULT [ITEM] [VALUES]
     knife vault download VAULT ITEM PATH
-
-<i>Global Options:</i>
-<table>
-  <tr>
-    <th>Short</th>
-    <th>Long</th>
-    <th>Description</th>
-    <th>Default</th>
-    <th>Valid Values</th>
-    <th>Sub-Commands</th>
-  </tr>
-  <tr>
-    <td>-M MODE</td>
-    <td>--mode MODE</td>
-    <td>Chef mode to run in. Can be set in knife.rb</td>
-    <td>solo</td>
-    <td>"solo", "client"</td>
-    <td>all</td>
-  </tr>
-  <tr>
-    <td>-S SEARCH</td>
-    <td>--search SEARCH</td>
-    <td>Chef Server SOLR Search Of Nodes</td>
-    <td>nil</td>
-    <td></td>
-    <td>create, remove, update</td>
-  </tr>
-  <tr>
-    <td>-A ADMINS</td>
-    <td>--admins ADMINS</td>
-    <td>Chef clients or users to be vault admins, can be comma list</td>
-    <td>nil</td>
-    <td></td>
-    <td>create, remove, update</td>
-  </tr>
-  <tr>
-    <td>-J FILE</td>
-    <td>--json FILE</td>
-    <td>JSON file to be used for values, will be merged with VALUES if VALUES is passed</td>
-    <td>nil</td>
-    <td></td>
-    <td>create, update</td>
-  </tr>
-  <tr>
-    <td>nil</td>
-    <td>--file FILE</td>
-    <td>File that chef-vault should encrypt.  It adds "file-content" & "file-name" keys to the vault item</td>
-    <td>nil</td>
-    <td></td>
-    <td>create, update</td>
-  </tr>
-  <tr>
-    <td>-p DATA</td>
-    <td>--print DATA</td>
-    <td>Print extra vault data</td>
-    <td>nil</td>
-    <td>"search", "clients", "admins", "all"</td>
-    <td>show</td>
-  </tr>
-  <tr>
-    <td>-F FORMAT</td>
-    <td>--format FORMAT</td>
-    <td>Format for decrypted output</td>
-    <td>summary</td>
-    <td>"summary", "json", "yaml", "pp"</td>
-    <td>show</td>
-  </tr>
-  <tr>
-    <td>nil</td>
-    <td>--clean</td>
-    <td>Remove all client keys before re-encrypting with saved or specified search</td>
-    <td>nil</td>
-    <td>nil</td>
-    <td>update</td>
-  </tr>
-  <tr>
-    <td>nil</td>
-    <td>--clean-unknown-clients</td>
-    <td>Remove unknown clients during key rotation</td>
-    <td>nil</td>
-    <td>nil</td>
-    <td>remove, rotate</td>
-  </tr>
-</table>
+    knife vault isvault VAULT ITEM
+    knife vault itemtype VAULT ITEM
+
+#### Global Options
+
+Short | Long | Description | Default | Valid Values | Sub-Commands
+------|------|-------------|---------|--------------|-------------
+-M MODE | --mode MODE | Chef mode to run in. Can be set in knife.rb | solo | solo, client | all
+-S SEARCH | --search SEARCH | Chef Server SOLR Search Of Nodes | | | create, remove , update
+-A ADMINS | --admins ADMINS | Chef clients or users to be vault admins, can be comma list | | | create, remove, update
+-J FILE | --json FILE | JSON file to be used for values, will be merged with VALUES if VALUES is passed | | | create, update
+| --file FILE | File that chef-vault should encrypt.  It adds "file-content" & "file-name" keys to the vault item | | | create, update
+-p DATA | --print DATA | Print extra vault data | | search, clients, admins, all | show
+-F FORMAT | --format FORMAT | Format for decrypted output | summary | summary, json, yaml, pp | show
+| --clean-unknown-clients | Remove unknown clients during key rotation | | | refresh, remove, rotate
 
 ## USAGE IN RECIPES
 
-To use this gem in a recipe to decrypt data you must first install the gem via a chef_gem resource.  Once the gem is installed require the gem and then you can create a new instance of ChefVault.
+To use this gem in a recipe to decrypt data you must first install the gem
+via a chef_gem resource. Once the gem is installed require the gem and then
+you can create a new instance of ChefVault.
 
-NOTE: chef-vault 1.0 style decryption is supported, however it has been deprecated and chef-vault 2.0 decryption should be used instead
+NOTE: chef-vault 1.0 style decryption is supported, however it has been
+deprecated and chef-vault 2.0 decryption should be used instead
 
 ### Example Code
 
-```ruby
-chef_gem "chef-vault"
+    chef_gem 'chef-vault' do
+      compile_time true if respond_to?(:compile_time)
+    end
+
+    require 'chef-vault'
+
+    item = ChefVault::Item.load("passwords", "root")
+    item["password"]
+
+Note that in this case, the gem needs to be installed at compile time
+because the require statement is at the top-level of the recipe.  If
+you move the require of chef-vault and the call to `::load` to
+library or provider code, you can install the gem in the converge phase
+instead.
+
+### Specifying an alternate node name or client key path
+
+Normally, the value of `Chef::Config[:node_name]` is used to find the
+per-node encrypted secret in the keys data bag item, and the value of
+`Chef::Config[:client_key]` is used to locate the private key to decrypt
+this secret.
+
+These can be overridden by passing a hash with the keys `:node_name` or
+`:client_key_path` to `ChefVault::Item.load`:
+
+    item = ChefVault::Item.load(
+      'passwords', 'root',
+      node_name: 'service_foo',
+      client_key_path: '/secure/place/service_foo.pem'
+    )
+    item['password']
 
-require 'chef-vault'
+The above example assumes that you have transferred
+`/secure/place/service_foo.pem` to your system via a secure channel.
 
-item = ChefVault::Item.load("passwords", "root")
-item["password"]
-```
+This usage allows you to decrypt a vault using a key shared among several
+nodes, which can be helpful when working in cloud environments or other
+configurations where nodes are created dynamically.
+
+### chef_vault_item helper
+
+The [chef-vault cookbook](https://supermarket.chef.io/cookbooks/chef-vault)
+contains a recipe to install the chef-vault gem and a helper method
+`chef_vault_helper` which makes it easier to test cookbooks that use
+chef-vault using Test Kitchen.
+
+## DETERMINING IF AN ITEM IS A VAULT
+
+ChefVault provides a helper method to determine if a data bag item is a vault,
+which can be helpful if you produce a recipe for community consumption and want
+to support both normal data bags and vaults:
+
+    if ChefVault::Item.vault?('passwords', 'root')
+      item = ChefVault::Item.load('passwords', 'root')
+    else
+      item = Chef::DataBagItem.load('passwords', 'root')
+    end
+
+This functionality is also available from the command line as `knife vault isvault VAULT ITEM`.
+
+## DETERMINING THE TYPE OF A DATA BAG ITEM
+
+ChefVault provides a helper method to determine the type of a data bag item.
+It returns one of the symbols :normal, :encrypted or :vault
+
+    case ChefVault::Item.data_bag_item_type('passwords', 'root')
+    when :normal
+      ...
+    when :encrypted
+      ...
+    when :vault
+      ...
+    end
+
+This functionality is also available from the command line as `knife vault itemtype VAULT ITEM`.
 
 ## USAGE STAND ALONE
 
-`chef-vault` can be used as a stand alone binary to decrypt values stored in Chef.  It requires that Chef is installed on the system and that you have a valid knife.rb.  This is useful if you want to mix `chef-vault` into non-Chef recipe code, for example some other script where you want to protect a password.
+`chef-vault` can be used as a stand alone binary to decrypt values stored in
+Chef. It requires that Chef is installed on the system and that you have a
+valid knife.rb. This is useful if you want to mix `chef-vault` into non-Chef
+recipe code, for example some other script where you want to protect a
+password.
 
-It does still require that the data bag has been encrypted for the user's or client's pem and pushed to the Chef server. It mixes Chef into the gem and uses it to go grab the data bag.
+It does still require that the data bag has been encrypted for the user's or
+client's pem and pushed to the Chef server. It mixes Chef into the gem and
+uses it to go grab the data bag.
 
-Do `chef-vault --help` for all available options
+Use `chef-vault --help` to see all all available options
 
 ### Example usage (password)
 
     chef-vault -v passwords -i root -a password -k /etc/chef/knife.rb
 
+## TESTING
+
+To stub vault items in ChefSpec, use the
+[chef-vault-testfixtures](https://rubygems.org/gems/chef-vault-testfixtures)
+gem.
+
+To fall back to unencrypted JSON files in Test Kitchen, use the
+`chef_vault_item` helper in the aforementioned chef-vault cookbook.
+
+## THE FUTURE OF chef-vault
+
+It has become clear that supporting alternate keying mechanisms like GPG and
+Amazon KMS is something that chef-vault users want, but the implementation
+of chef-vault v2 makes this difficult, as much of the code is tied to the
+"side-along data bag item" implementation.
+
+chef-vault v3.x.x will be a major rewrite. While the core vault item will
+remain a Chef encrypted data bag item, the way in which you get the secret
+to decrypt that data bag item will be delegated to plugins. At release,
+there will be at least a plugin that emulates the 2.x.x implementation, and
+hopefully one for KMS. Anyone who wants to support an alternate keying
+implementation will be able to write one and distribute it as a gem for
+others to use.
+
+With that in mind, the 2.6.0 release is the last one that will receive new
+features. If you refer to the
+[milestones](https://github.com/Nordstrom/chef-vault/milestones) on Github,
+the plan is for two releases prior to 3.x:
+
+* v2.7.x will focus on reducing tech debt - getting the test coverage up to 100%
+in both RSpec and Aruba, and getting the internal API docs completed.
+* v2.99.x will be a transitional release. This release will add deprecation
+warnings for any API or CLI option that will be changing in v3.x. Any user
+who wants to stay with the 2.x series can use a '~> 2.x' constraint (where x
+is any minor release of chef-vault) and be certain that they won't
+accidentally get the new release.
+
+If you are interested helping with the robustness fixes in v2.7.x, please
+feel free to fork the repo and add more RSpec and Aruba tests. Frequent
+small pull requests are preferred to large omnibus patches, as the
+robustness pass is a multi-person effort and we don't want to create merge
+conflicts unnecessarily.
+
 ## Authors
 
 Author:: Kevin Moser - @moserke<br>