chef-vault 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 58db597b870524dd9e554ad60f20722c3b95cf9f
-  data.tar.gz: a49a6a5af9bcb52e84830383957205dd1d4862d2
+  metadata.gz: d1d708e9e29a406be66537a1e4f2001bfca5c4fd
+  data.tar.gz: e3d77a016b45ee414f9944657f6be4037b409d53
 SHA512:
-  metadata.gz: 7a420cc9e5b246ffcf9c44f3c00ebac5d339f8fe3c6e7c2bbe4849a8fd126cecd4386831549ec0666836ac9304da7641ff1d9f18d1395058aaca5339798f38ef
-  data.tar.gz: f29af664121f81f45070bef3548894729fd0c6e88afba0f2669edd449876c4a1341738ec8e9d375c30044424a4b22b907cfa0ba74ccb8128a14d3a6ac6f479e5
+  metadata.gz: 728d1dc1cad74668f52576130e0171a1bcea7ccdf21a6f1a32861e231e194e52016d94bce5e9028f91ef87ec6a877daa22b63db05f1afe6a441910551c34bdae
+  data.tar.gz: e811b693b9363d55fea010ef9cdd20e2bfbe8955686eaf087d494cab30f1cdc6b64a9737d3a04b6e730622a24aee03dfc163f3c95c3ea5c24468d6360ab132d2

data/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -0,0 +1,97 @@
+# This configuration was generated by `rubocop --auto-gen-config`
+# on 2015-02-09 09:22:33 -0800 using RuboCop version 0.29.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 12
+Metrics/AbcSize:
+  Max: 43
+
+# Offense count: 1
+Metrics/BlockNesting:
+  Max: 4
+
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/ClassLength:
+  Max: 247
+
+# Offense count: 5
+Metrics/CyclomaticComplexity:
+  Max: 14
+
+# Offense count: 45
+# Configuration parameters: AllowURI, URISchemes.
+Metrics/LineLength:
+  Max: 136
+
+# Offense count: 22
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 40
+
+# Offense count: 4
+Metrics/PerceivedComplexity:
+  Max: 15
+
+# Offense count: 1
+Style/AccessorMethodName:
+  Enabled: false
+
+# Offense count: 43
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/AlignParameters:
+  Enabled: false
+
+# Offense count: 30
+Style/Documentation:
+  Enabled: false
+
+# Offense count: 6
+# Configuration parameters: Exclude.
+Style/FileName:
+  Enabled: false
+
+# Offense count: 77
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/HashSyntax:
+  Enabled: false
+
+# Offense count: 7
+# Cop supports --auto-correct.
+Style/MethodCallParentheses:
+  Enabled: false
+
+# Offense count: 7
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/SignalException:
+  Enabled: false
+
+# Offense count: 11
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/SpaceAroundEqualsInParameterDefault:
+  Enabled: false
+
+# Offense count: 16
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/SpaceBeforeBlockBraces:
+  Enabled: false
+
+# Offense count: 18
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles, EnforcedStyleForEmptyBraces, SpaceBeforeBlockParameters.
+Style/SpaceInsideBlockBraces:
+  Enabled: false
+
+# Offense count: 135
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/StringLiterals:
+  Enabled: false

data/Changelog.md

@@ -1,6 +1,40 @@
 ## Planned (Unreleased)
+## v2.6.0
+
+This release will focus on adding any new features covered by open issues
+
+## v2.7.0
+
+This release will focus on reducing tech debt:
+
+* improve the coverage of the RSpec suite
+* ensure there are Aruba tests for all the subcommands and scenarios that match DEMO.md
+* clean up any leftover Rubocop issues
+
+## v2.99.0
+
+This will be the last release in the 2.x branch, and is for anyone who
+is constraining to '~> 2.4' (for example).  Anything that we decide to
+deprecate for v3.0.0 will produce warnings in this release.
+
+## v3.0.0
+
+This will be a major refactor.  The primary goal is to solve the bootstrap
+problem where a vault can't be encrypted for a node until the node has been
+created.  Exactly how we will do that is open to discussion (watch the
+chef-vault issues on github for news).
+
+This release will also remove the chef-vault 1.x commands (encrypt/decrypt)
 
 ## Released
+## 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
+* Add more detailed explanation of how chef-vault works in THEORY.md (Issue #109)
+* fix a problem with the --clean-unknown-clients switch to `rotate keys` that made it impossible to delete a client that could not be searched for (i.e. the node object is deleted)
+* 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)

data/DEMO.md

@@ -8,11 +8,11 @@
 
 ###Put the hat in the magic show
 
-    export assistant=aug24                   #Change this to your chef id 
+    export assistant=aug24                   #Change this to your chef id
     export role=magician                     #Change this to the role you need to pass the secret to
-    
+
     knife vault create magicshow hat \       #Create a hat object in a data bag called magicshow
-       --mode client                 \       #Talk to the chef server rather than local 
+       --mode client                 \       #Talk to the chef server rather than local
        --file tophat                 \       #Use the hat (file) we put the bunny in
        --search "role:${role}"       \       #Encrypted for all *current* nodes with the magician role
        --admins "${assistant}"               #Encrypted for the assistant
@@ -20,34 +20,41 @@
 ###Check the magic show is on the chef server
 
     knife data bag list
+    knife vault list
 
 ###Check the hat is there (and that nobody can see what's in it)
+
     knife data bag show magicshow hat
 
 ###Check you can see what's in it
+
     knife vault show magicshow hat file-content --mode client
 
 ##'Hop' on to a node with a role of 'magician'
 
 ###Install required software
+
     sudo apt-get install ruby-dev --yes
     sudo gem install chef-vault --no-ri --no-rdoc
 
 ###Get the bunny back out of the hat!
+
     sudo chef-shell --client <<EOF
     require 'chef-vault'
     puts ChefVault::Item.load('magicshow', 'hat')['file-content']
     EOF
 
-If you are on a node which is not a magician, an exception will be thrown, 
+If you are on a node which is not a magician, an exception will be thrown,
 and the node cannot see what is in the hat.
 
 #Finally, do a disappearing act.
 
 ###Make the hat disappear...
+
     knife vault delete magicshow hat --mode client
-    
+
 ###Make the entire magic show disappear...
+
     knife data bag delete magicshow
 
-###Thank you!
+###Thank you!

data/README.md

@@ -3,10 +3,14 @@
 
 [![Build Status](https://travis-ci.org/Nordstrom/chef-vault.png?branch=master)](https://travis-ci.org/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.
 
+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:
@@ -167,16 +171,17 @@ Author:: Kevin Moser - @moserke<br>
 Author:: Eli Klein - @eliklein<br>
 Author:: Joey Geiger - @jgeiger<br>
 Author:: Joshua Timberman - @jtimberman<br>
+Author:: James FitzGibbon - @jf647<br>
 
 ## Contributors
 
-Contributor:: Matt Brimstone (https://github.com/brimstone)
-Contributor:: Thomas Gschwind (https://github.com/thg65)
-Contributor:: Reto Hermann
+Contributor:: Matt Brimstone - @brimstone<br>
+Contributor:: Thomas Gschwind - @thg65<br>
+Contributor:: Reto Hermann<br>
 
 ## License
 
-Copyright:: Copyright (c) 2013-14 Nordstrom, Inc.<br>
+Copyright:: Copyright (c) 2013-15 Nordstrom, Inc.<br>
 License:: Apache License, Version 2.0
 
 Licensed under the Apache License, Version 2.0 (the "License");

data/Rakefile

@@ -1,16 +1,53 @@
 require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'cucumber'
-require 'cucumber/rake/task'
 
-RSpec::Core::RakeTask.new(:spec)
+# Style Tests
+begin
+  require 'rubocop/rake_task'
+  RuboCop::RakeTask.new do |t|
+    t.formatters = ['progress']
+    t.options = ['-D']
+    t.patterns = %w(
+      lib/**/*.rb
+      spec/**/*.rb
+      ./Rakefile
+    )
+  end
 
-Cucumber::Rake::Task.new(:features)
+  # style is an alias for rubocop
+  task style: :rubocop
+rescue LoadError
+  puts 'Rubocop not available; disabling rubocop tasks'
+end
 
-task default: [:spec, :features]
+# Unit Tests
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new
+
+  # Coverage
+  desc 'Generate unit test coverage report'
+  task :coverage do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task[:spec].invoke
+  end
+rescue LoadError
+  puts 'RSpec not available; disabling rspec tasks'
+  # create a no-op spec task for :default
+  task :spec
+end
 
-task :coverage do
-  ENV['COVERAGE'] = '1'
-  Rake::Task[:spec].invoke
-  Rake::Task[:features].invoke
+# Feature Tests
+begin
+  require 'cucumber'
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+rescue LoadError
+  puts 'Cucumber/Aruba not available; disabling feature tasks'
+  # create a no-op spec task for :default
+  task :features
 end
+
+# test or the default task runs spec and features
+desc 'run all tests'
+task default: [:spec, :features]
+task test: :default

data/THEORY.md

@@ -0,0 +1,361 @@
+# How chef-vault works
+
+## The Problem
+
+Chef provides [encrypted data bags](https://docs.chef.io/chef/essentials_data_bags.html)
+as part of the core software, but leaves the problem of key
+distribution up to end users.  Encrypted data bags are
+symmetrically encrypted, and so you have to distribute the
+decryption key out-of-band to your nodes (e.g. baking it into
+your image or pushing it to the system before running
+chef-client).
+
+## The Solution
+
+Every node managed by chef has an associated client object
+on the Chef Server.  The client object has the public half of
+an RSA keypair.  The private half only lives on the node,
+typically in `/etc/chef/client.pem`.
+
+Every API user on the chef server also has an RSA keypair.
+This is typically kept in your `~/.chef` directory in PEM
+format.  Like nodes, the public half is stored on the Chef
+server.
+
+chef-vault creates an encrypted data bag which is symmetrically
+encrypted using a random secret (a 32-byte string generated
+using [SecureRandom.random_bytes](http://ruby-doc.org/stdlib-2.1.2/libdoc/securerandom/rdoc/SecureRandom.html#method-c-random_bytes)).  We'll refer to this secret as the 'shared secret' through
+the rest of this document.
+
+A vault has a list of administrative users and a list of
+clients.  The shared secret is asymmetrically encrypted
+for each of the administrators and clients using their public
+key (a separate copy for each).
+
+The administrators of a vault are API users named explicitly
+when the vault is created.  The clients can be provided
+explicitly, but are more often determined by running a SOLR
+query against the Chef server.  The query is stored as part
+of the \_keys data bag so that the clients can be updated by
+re-executing the search.
+
+The asymmmetrically encrypted keys are stored in a second
+data bag item whose name is appended with \_keys
+
+## Data Bag Structure
+
+These examples assume that I have two nodes in my Chef
+server/organization, named 'one' and 'two'.  I also have
+two administrators named 'alice' and 'bob'.
+
+Given a file named `item.json` containin the following:
+
+```json
+{ "foo": "bar" }
+```
+
+Running
+
+    > knife vault create foo bar -A alice,bob -S '*:*' -J item.json
+
+will create a data bag named 'foo' and two data bag items
+within named 'bar' and 'bar_keys':
+
+    > knife data bag show foo
+    bar
+    bar_keys
+
+The 'bar' item contains the symmetrically encrypted version
+of the JSON data:
+
+    > knife data bag show -F json foo bar
+    {
+      "id": "bar",
+      "foo": {
+        "encrypted_data": "k9On2aJxnLDRwOeCr60l0C41XjIJ2+5Xu0AYFbmSvFw=\n",
+        "iv": "oKeiEkIlaspvhKghee30GA==\n",
+        "version": 1,
+        "cipher": "aes-256-cbc"
+      }
+    }
+
+(this is a standard Chef encrypted data bag)
+
+The 'bar_keys' item contains four copies of the asymetrically
+encrypted shared secret:
+
+    > knife data bag show -F json foo bar_keys
+    {
+      "id": "bar_keys",
+      "admins": [
+        "alice",
+        "bob"
+      ],
+      "clients": [
+        "one",
+        "two"
+      ],
+      "search_query": "*:*",
+      "alice": "MW7hOvoc7XvYHJbbm0gWAaLNbVcHnxv5YDMnYsjiK/F1qxnFrY4X8pTwzgUI\nRsZuREpEpCSWY9C23ESolTHnBtgEHkR6Xe74NFUr9OURiAGljZL9zEzVUFJu\npds8pWjgGnqpwULxiPZT96xKEw+BnMy0ipYChdF2iaJtQzVAlIzXZoPaOXeH\nJPd1dwmD/G0X2nK0+cNEnJGUP6gideMun3S+dTN9rpP0/7bInjNRPAAXV5yY\nKNRBFgtFyG828B9uXXJ8wXaYYOzp7VLK4ehJw25g5VNkMttqNQVWyIbxGirf\nuvys/PTlCXzLkJ3+e0X5q4ZSotQ+1zJ5UVs16VOChQ==\n",
+      "bob": "h9qvmFyR3ygYUQgoW42ABIeCov16cSyYFlj9wKrscLFDzhs0jRrFRdvpcBBl\nqU3Glk79Y898L3C4+/EYomi2I7/EuxZozP+wgeTJDIcXQdeZwEWxGzY1JZq2\nxZYezdoWKATysAtPJEtNIPRzOGiloq+QanHDrxq3JVvZrJ/L5fE0eyV0Nh3T\nbX4X0KzZ4LzeGeUCXXOVa9C2rEHpf61PsMF79iAnULDpD++YdxDGHv6KgHJS\nVENHvyIWi4erRGrcwZRq709iB1BRm/14Zb9ZzZT/HcHIw5P47Ht0wgZ8x71V\nbhAjK410AWG9QtefDf6ybD/ERkKgVjeqcZ57TysdvQ==\n",
+      "one": "Ugwpeq2du2RqEzAcn1GA+Uj+dW9fHq7+coCT4LWD2CLo9og9Qu7MSkwuZXaj\nZngl31skSCyvE15ZVhhXilkwmJmrOoEU0B5FlbZTzjHxlq/ga2MhemXmASAH\nyu39if2fb++sE/g5RLy1A9EQs7oeVY53BLZCtENA5XHGjMA1WoBi1PfQTpUs\nZZKW604vs4i/zw88j1Np5o7xb77Wt7zZQsRS+uLxp7qWOTPaT85usChk5ygS\nFrPNZF/F95ODe74o6qwxAtQhKroEeUV6GSWCB2M9FTIoGH+Fhj7oDSiLT1AA\n4VqF4mCMuVMeAM2GTx5IvdIYja2GV7DbomTBNYsGiA==\n",
+      "two": "yO6eaCnDmNnQP5d1h1LxZyQdHhYh0BvhBhauVBv8RXWuyuY/8qC7iREPlN52\nRFCr38BStHO9/D4m+uv6SnJhKREe99eOtpddSXD92K/I4bMSCszC+/TmaZWj\nNibZonivam1SuutMbh6WPlHT6/yjIXb1w0cXxple5R+WmPttuMj13V0at0wY\nWMg4JC5/PpYoX8qfmUKvcrVxqFdbQ0YlgAzzdJwzWJOpN+ZEfiFSJopREt6L\n2wSkWezHylGmIWuGLmANSCdluk0oaEVyA1Panf8HL87tWlEc+BajY53JZxY1\n3YIZNWpelU6W/Nl8zu8R206ksKNNMk0yuhd++7F+yw==\n"
+    }
+
+It also contains the list of administrators and clients for
+which the key is encrypted and the query used to choose which
+clients can decrypt the vault.
+
+In practice, the search query would not be `*:*`.  More common
+practice is to select which nodes can decrypt the vault based
+on characteristics like:
+
+* which recipes are in the node's runlist
+* which chef environment the node belongs to
+* what OS or platform the node runs
+* attributes collected by Ohai Plugins (such as AWS tags).
+
+While there are four copies of the shared secret, any single
+user or node will only be able to decrypt one of the copies,
+because no user or node (should) have more than one private key.
+
+Likewise, a node or user for whom the vault was not encrypted
+is able to see the contents of the 'bar_keys' data bag,
+but since they lack a private key that can decrypt any of the
+copies of the shared secret, they cannot access the 'bar' encrypted
+data bag item.
+
+As alice or bob, I can show the contents of the vault:
+
+    > knife vault show -F json foo bar
+    {
+      "id": "bar",
+      "foo": "bar"
+    }
+
+Or in a recipe that runs on node one or two:
+
+    vaultitem = ChefVault::Item.load('foo', 'bar')
+    Chef::Log.debug "the vault value foo is #{vaultitem['foo']}"
+
+## Use Cases
+
+In these use cases, assume there are three API clients:
+
+* alice (Administrator)
+* bob (Administrator)
+* charlie (Normal User)
+
+And three nodes, of the given platform:
+
+* one (Linux, Ubuntu)
+* two (Linux, CentOS)
+* three (Windows)
+
+The use cases are written from the perspective of 'client'
+mode using a Chef server, but work similarly in 'solo' mode
+assuming that the commands are run from the directory containing
+the Chef repository.
+
+We also assume that the commands are being run from a Linux
+terminal session (paths to key files are slightly different
+on Windows)
+
+### Creating a Vault
+
+The actor in this case is alice.  When she runs
+
+    knife vault create foo bar -S os:linux -A alice,bob
+
+After editing the empty JSON document and saving it, chef-vault
+generates a random 32 byte string for the shared secret.
+
+A new data bag named 'foo/bar_keys' is created.  chef-vault then
+executes the search 'os:linux' against the node index.
+
+For each of the nodes returned from the search (one and two), the
+public keys are fetched for the like-named client and the shared
+secret is encrypted using it.  The client name is added to the
+'clients' array in the bar_keys data bag item.  The node-specific
+encrypted copy of the shared secret is stored in the bar_keys
+data bag item, keyed by node name.
+
+The search query is also stored in the keys data bag, for use
+during future update or refresh operations.
+
+In a similar fashion, the public keys for alice and bob are
+retrieved from the Chef server and the shared secret is
+asymmetrically encrypted for each.  The names of the admins are
+stored in the 'admins' array in the bar_keys data bag item.
+
+At this point, the bar_keys data bag item is only present in
+memory.  It is saved to the server, and if that operation fails
+the vault create throws an error.
+
+The data bag 'foo' is then fetched (or created if it does
+not already exist).  An encrypted data bag item named 'bar'
+is created, encrypted with the shared secret.  The data bag
+item is save to the Chef server.
+
+### Decrypting a Vault using knife
+
+The actor in this case is alice.  When she runs
+
+    knife vault show foo bar
+
+chef-vault fetches the data bag item foo/bar_keys.  It
+then looks for a key in the data bag named 'alice'.  The value
+of this key is the asymmetrically encrypted copy of the shared
+secret specific to alice.
+
+chef-vault then uses alice's private key (typically `~/.chef/alice.pem`) to decrypt the shared secret.
+
+If the \_keys data bag did not have a key 'alice', chef-vault
+would have emitted an error to the effect that the vault was not
+encrypted for her and that someone else who does have access to
+the bag needs to add her as an administrator before she can view
+it.
+
+Using the decrypted shared secret, chef-vault loads the Chef
+encrypted data bag foo/bar.  The plaintext contents of this bag
+are then displayed to alice.  If the appropriate options are
+provided on the command line, additional information such as
+the list of administrators, the list of clients and the search
+query (all of which are stored in the bar_keys data bag item)
+are also displayed.
+
+### Decrypting a Vault in a Chef Recipe
+
+The actor in this case is chef-client (running as root) on
+the server 'one'.
+
+Assuming that the recipe contains code such as this:
+
+    chef_gem 'chef-vault'
+    require 'chef-vault'
+    vaultitem = ChefVault::Item.load('foo', 'bar')
+
+chef-vault fetches the data bag item foo/bar_keys.  It
+then looks for a key in the data bag named 'one'.  The value
+of this key is the asymetrically encrypted copy of the shared
+secret specific to the node 'one'.
+
+chef-vault then uses the private key of node one (typically
+`/etc/chef/client.pem`) to decrypt the shared secret.
+
+If the \_keys data bag did not have a key 'one', chef-vault
+would have thrown an exception indicating that the vault was
+not encrypted for the node and that an administrator needs to
+refresh the vault (possibly after updating the search query)
+before the recipe can use the vault.
+
+Uncaught, this would cause chef-client to abort in the compile
+phase.  Robust recipes can be written that catch the exception
+and do other things, such as only converging resources that do
+not need the secrets, or sending an alert so that a human can
+update the vault, or even sending a request to a work queue
+to automatically update the vault.
+
+Using the decrypted shared secret, chef-vault loads the Chef
+encrypted data bag foo/bar.  The plaintext contents of this bag
+are now available to the recipe in the local variable named
+'vaultitem'.  At this point the data looks and feels like a
+normal data bag (i.e. it behaves in a hash-like way)
+
+### Adding a new Administrator
+
+The actor in this case is Alice, who wants to make charlie
+an administrator of the vault.  We assume she is working with
+the vault created in the section 'Creating a Vault'.  When she
+runs
+
+    knife vault update -A charlie foo bar
+
+This vault is decrypted in the same fashion as described
+in 'Decrypting a Vault using knife'.  This results in the
+plain text of the shared secret being available in memory.
+
+The search query is run again, returning the same two nodes.
+The shared secret is then asymmetrically encrypted for each
+as described in 'Creating a Vault'.
+
+The shared secret is then asymmetrically encrypted for all
+of the admins (alice, bob and the newly-added charlie) as
+described in 'Creating a Vault'.
+
+The data bag item 'foo/bar_keys' is then saved, followed by the
+data bag item 'foo/bar'.
+
+charlie can now view the contents of the vault using `knife
+vault show` because there is a now a copy of the shared
+secret that he can access.
+
+### Adding a new Node
+
+The actor in this case is Alice, who wants to encrypt the
+value for all nodes instead of just those running linux.
+When she runs
+
+    knife vault update -S '*:*' foo bar
+
+This vault is decrypted in the same fashion as described
+in 'Decrypting a Vault using knife'.  This results in the
+plain text of the shared secret being available in memory.
+
+The search query is run again, returning three nodes this
+time: one, two and three.  The shared secret is then
+asymmetrically encrypted for each as described in 'Creating
+a Vault'.
+
+The data bag item 'foo/bar_keys' is then saved, followed by the
+data bag item 'foo/bar'.
+
+Node three can now use the vault in a recipe because
+there is a now a copy of the shared secret that he it access.
+
+### Rotating Keys
+
+Rotating keys chooses a new shared secret for the bag and
+encrypts it for all of the administrators and clients
+who currently have access.  Unlike the `knife vault update`
+command, the search query is not re-run to pick up new clients.
+
+The actor in this case is Alice, who wants to rotate the keys
+(perhaps to conform to an internal security policy).  When
+she runs
+
+    knife vault rotate_keys foo bar
+
+The vault is decrypted in the same fashion as described
+in 'Decrypting a Vault using knife'.
+
+chef-vault generates a new 32-byte random string.  It then
+creates an asymmetrically encrypted version of the new
+shared secret for each of the clients and administrators
+listed in the data bag item 'foo/bar_keys'.
+
+The data bag item 'foo/bar_keys' is then saved, followed by the
+data bag item 'foo/bar'.
+
+## Failure Scenarios
+
+Because the secret data is just a normal Chef encrypted
+data bag item, the keys are stored separately in a data bag
+suffixed with \_keys.  When the vault is saved, the data bag
+item containing the keys is saved before the encrypted data
+bag is.
+
+If the key data bag item save succeeds, but the vault data bag
+item fails, the vault will be in an unsable state, because
+it will be encrypted with the old shared secret, but the keys
+data bag item contains asymmetrically encrypted copies of the
+new shared secret.
+
+This can be mitigated by using solo mode, which writes the
+encrypted data bags to JSON files on disk rather than making
+changes using the Chef Server API.  Another option is to use
+`knife download` to temporarily store a on-disk version of the
+vault data bag item and the keys data bag item before making
+changes.  If any probems are encountered, the old copy of
+the data bags can be loaded back into the Chef server using
+`knife data bag from file`.