vault-rails 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f424a57360c1017f40c429ec2570a08eb81f582a
-  data.tar.gz: 28d0fadd3e06908c2d0b35ff7e4a1eddcbc3a4db
+  metadata.gz: 2372e9033c1ad9acaed9ba40d0a16ecaf9255389
+  data.tar.gz: 1ad8eba93c1e7214da702473a92729131902ccb5
 SHA512:
-  metadata.gz: e1d46eea0dd84f894af558a79379b470b0ace0c0d0efeb0abcd2e1d29b3b55c9985a6b78a213179176713c8a09f665d5e5241af18abb226457716b1d9190d513
-  data.tar.gz: bbe7d51daac322bf3eab796cc95912de7016097e7d188e0cebb2ae3a2982c566e0b8630ae8692cec93799d3f54d487079b7bda17ddaf86921abc81975dda0aeb
+  metadata.gz: 5fb7fc74a89248efa68c5dd0698fa08940b44d1cf129957b30922b19765b2d5a121f34c1aa821f9c9b944794a488d31ef97932d31c55aaab7867c2b382824fb8
+  data.tar.gz: 685d0b2d9a6ea88c0308defc8e7dd06f806b0dbf06d19bc3faf8d4e58353564cc37df8cf009063d5b6a61db35a4adf385e25c5140d711f0e3d92912fd41c67c2

data/README.md

@@ -3,6 +3,7 @@ Vault Rails [![Build Status](https://secure.travis-ci.org/hashicorp/vault-rails.
 
 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.**
 
 Quick Start
 -----------
@@ -19,13 +20,25 @@ Quick Start
     ```ruby
     require "vault/rails"
 
-    Vault.configure do |vault|
+    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.
+      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.
       vault.application = "my_app"
 
-      # Default: ENV["VAULT_ADDR"]
+      # The address of the Vault server. Default: ENV["VAULT_ADDR"].
       vault.address = "https://vault.corp"
 
-      # Default: ENV["VAULT_TOKEN"]
+      # The token to communicate with the Vault server.
+      # Default: ENV["VAULT_TOKEN"].
       vault.token = "abcd1234"
     end
     ```
@@ -60,21 +73,85 @@ Quick Start
     person.ssn_encrypted #=> "vault:v0:EE3EV8P5hyo9h..."
     ```
 
-    You can customize the `vault_attribute` method with the following options:
 
-    ```ruby
-    vault_attribute :credit_card,
-      encrypted_column: :cc_encrypted,
-      path: "credit-secrets",
-      key: "people_credit_cards"
-    ```
+Advanced Configuration
+----------------------
+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:
+
+```ruby
+vault_attribute :credit_card,
+  encrypted_column: :cc_encrypted
+```
+
+- **Note** Changing this value for an existing application will make existing values no longer decryptable!
+- **Note** This value **cannot** be the same name as the vault attribute!
+
+#### Specifying a custom key
+By default, the name of the key in Vault is `#{app}_#{table}_#{column}`. This is customizable by setting the `:key` coption when declaring the attribute:
+
+```ruby
+vault_attribute :credit_card,
+  key: "pci-data"
+```
+
+- **Note** Changing this value for an existing application will make existing values no longer decryptable!
 
-    - `:encrypted_column` - the name of the encrypted column
-      (default: `attribute_encrypted`)
-    - `:key` - the name of the key
-      (default: `#{app}_#{table}_#{column}`)
-    - `:path` - the path to the transit backend to use
-      (default: `transit/`)
+#### Specifying a different Vault path
+By default, the path to the transit backend in Vault is `transit/`. This is customizable by setting the `:path` option when declaring the attribute:
+
+```ruby
+vault_attribute :credit_card,
+  path: "transport"
+```
+
+- **Note** Changing this value for an existing application will make existing values no longer decryptable!
+
+#### Automatic serializing
+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
+vault_attribute :details
+  serialize: :json
+```
+
+- **Note** You can view the source for the exact serialization and deserialization options, but they are intentionally not customizable and cannot be used for a full object marshal/unmarshal.
+
+For customized solutions, you can also pass a module to the `:serializer` key. This module must have the following API:
+
+```ruby
+module MySerializer
+  # @param [String, nil] raw
+  # @return [String, nil]
+  def self.encode(raw); end
+
+  # @param [String, nil] raw
+  # @return [String, nil]
+  def self.decode(raw); end
+end
+```
+
+Your class must account for `nil` and "empty" values if necessary. Then specify the class as the serializer:
+
+```ruby
+vault_attribute :details,
+  serialize: MySerializer
+```
+
+- **Note** It is possible to encode and decode entire Ruby objects using a custom serializer. Please do not do that. You will have a bad time.
+
+#### Custom encoding/decoding
+If a custom serializer seems too heavy, you can declare an `:encode` and `:decode` proc when declaring the attribute. Both options must be given:
+
+```ruby
+vault_attribute :address,
+  encode: ->(raw) { raw.to_s.upcase },
+  decode: ->(raw) { raw.to_s }
+```
+
+- **Note** Changing the algorithm for encoding/decoding for an existing application will probably make the application crash when attempting to retrive existing values!
 
 Caveats
 -------
@@ -86,11 +163,31 @@ The Vault Rails plugin does not automatically mount a backend. It is assumed the
 $ vault mount transit
 ```
 
-The Vault Rails plugin does not automatically create transit keys in Vault. This is intentional so that you can give the policy for the token associated with the Rails application read/write access to the encrypt/decrypt backends _only_, without giving the Rails application the ability to read encryption keys from Vault.
+If you are running Vault 0.2.0 or later, the Vault Rails plugin will automatically create keys in the transit backend if it has permission. Here is an example policy to grant permissions:
+
+```javascript
+# Allow renewal of leases for secrets
+path "sys/renew/*" {
+  policy = "write"
+}
 
-If an attacker gained access to the Rails application server, they would be able to read all encryption keys in Vault, making decryption of sensitive data in the database easy.
+# Allow renewal of token leases
+path "auth/token/renew/*" {
+  policy = "write"
+}
 
-Instead, you should create keys for each column you plan to encrypt using a different policy, out-of-band from the Rails application. For example:
+path "transit/encrypt/myapp_*" {
+  policy = "write"
+}
+
+path "transit/decrypt/myapp_*" {
+  policy = "write"
+}
+```
+
+Note that you will need to have an out-of-band process to renew your Vault token.
+
+For lower versions of Vault, the Vault Rails plugin does not automatically create transit keys in Vault. Instead, you should create keys for each column you plan to encrypt using a different policy, out-of-band from the Rails application. For example:
 
 ```shell
 $ vault write transit/keys/<key> create=1
@@ -118,19 +215,6 @@ This is because the database is unaware of the plain-text data (which is part of
 the security model).
 
 
-Testing
--------
-The Vault Rails plugin includes a testing harness to avoid needing to spin up a
-real Vault server during tests:
-
-```ruby
-require "vault/rails/testing"
-Vault::Rails::Testing.enable!
-```
-
-This will stub all requests to encrypted attributes to use an in-memory store.
-
-
 Development
 -----------
 1. Clone the project on GitHub

data/lib/vault/encrypted_model.rb

@@ -1,3 +1,5 @@
+require "active_support/concern"
+
 module Vault
   module EncryptedModel
     extend ActiveSupport::Concern
@@ -27,39 +29,85 @@ module Vault
       #   the path to the transit backend (default: +transit+)
       # @option options [String] :key
       #   the name of the encryption key (default: +#{app}_#{table}_#{column}+)
-      def vault_attribute(column, options = {})
-        encrypted_column = options[:encrypted_column] || "#{column}_encrypted"
+      # @option options [Symbol, Class] :serializer
+      #   the name of the serializer to use (or a class)
+      # @option options [Proc] :encode
+      #   a proc to encode the value with
+      # @option options [Proc] :decode
+      #   a proc to decode the value with
+      def vault_attribute(attribute, options = {})
+        encrypted_column = options[:encrypted_column] || "#{attribute}_encrypted"
         path = options[:path] || "transit"
-        key = options[:key] || "#{Vault.application}_#{table_name}_#{column}"
+        key = options[:key] || "#{Vault::Rails.application}_#{table_name}_#{attribute}"
 
-        class_eval <<-EOH, __FILE__, __LINE__ + 1
-          def #{column}
-            value = instance_variable_get(:@#{column})
-            return value if !value.nil?
+        # Sanity check options!
+        _vault_validate_options!(options)
 
-            ciphertext = read_attribute(:#{encrypted_column})
-            return nil if ciphertext.nil?
+        # Get the serializer if one was given.
+        serializer = options[:serialize]
 
-            plaintext = Vault::Rails.decrypt("#{path}", "#{key}", ciphertext)
-            instance_variable_set(:@#{column}, plaintext)
-          end
+        # Unless a class or module was given, construct our serializer. (Slass
+        # is a subset of Module).
+        if serializer && !serializer.is_a?(Module)
+          serializer = Vault::Rails.serializer_for(serializer)
+        end
+
+        # See if custom encoding or decoding options were given.
+        if options[:encode] && options[:decode]
+          serializer = Class.new
+          serializer.define_singleton_method(:encode, &options[:encode])
+          serializer.define_singleton_method(:decode, &options[:decode])
+        end
 
-          def #{column}=(plaintext)
-            ciphertext = Vault::Rails.encrypt("#{path}", "#{key}", plaintext)
-            write_attribute(:#{encrypted_column}, ciphertext)
-            instance_variable_set(:@#{column}, plaintext)
+        # Getter
+        define_method("#{attribute}") do
+          instance_variable_get("@#{attribute}")
+        end
+
+        # Setter
+        define_method("#{attribute}=") do |value|
+          # If the currently set value is not the same as the given value (or
+          # not set at all), update the instance variable and mark it as dirty.
+          if instance_variable_get("@#{attribute}") != value
+            attribute_will_change!("#{attribute}")
+            instance_variable_set("@#{attribute}", value)
           end
 
-          def #{column}?
-            read_attribute(:#{encrypted_column}).present?
+          # Return the value to be consistent with other AR methods.
+          value
+        end
+
+        # Checker
+        define_method("#{attribute}?") do
+          instance_variable_get("@#{attribute}").present?
+        end
+
+        # Dirty method
+        define_method("#{attribute}_change") do
+          changes["#{attribute}"]
+        end
+
+        # Dirty method
+        define_method("#{attribute}_changed?") do
+          changed.include?("#{attribute}")
+        end
+
+        # Dirty method
+        define_method("#{attribute}_was") do
+          if changes["#{attribute}"]
+            changes["#{attribute}"][0]
+          else
+            public_send("#{attribute}")
           end
-        EOH
+        end
 
-        _vault_attributes.store(column.to_sym,
-          encrypted_column: encrypted_column,
-          path: path,
+        # Make a note of this attribute so we can use it in the future (maybe).
+        __vault_attributes[attribute.to_sym] = {
           key: key,
-        )
+          path: path,
+          serializer: serializer,
+          encrypted_column: encrypted_column,
+        }
 
         self
       end
@@ -67,9 +115,152 @@ module Vault
       # The list of Vault attributes.
       #
       # @return [Hash]
-      def _vault_attributes
+      def __vault_attributes
         @vault_attributes ||= {}
       end
+
+      # Validate that Vault options are all a-okay! This method will raise
+      # exceptions if something does not make sense.
+      def _vault_validate_options!(options)
+        if options[:serializer]
+          if options[:encode] || options[:decode]
+            raise Vault::Rails::ValidationFailedError, "Cannot use a " \
+              "custom encoder/decoder if a `:serializer' is specified!"
+          end
+        end
+
+        if options[:encode] && !options[:decode]
+          raise Vault::Rails::ValidationFailedError, "Cannot specify " \
+            "`:encode' without specifying `:decode' as well!"
+        end
+
+        if options[:decode] && !options[:encode]
+          raise Vault::Rails::ValidationFailedError, "Cannot specify " \
+            "`:decode' without specifying `:encode' as well!"
+        end
+      end
+    end
+
+    included do
+      # After a resource has been initialized, immediately communicate with
+      # Vault and decrypt any attributes.
+      after_initialize :__vault_load_attributes!
+
+      # After we save the record, persist all the values to Vault and reload
+      # them attributes from Vault to ensure we have the proper attributes set.
+      # The reason we use `after_save` here is because a `before_save` could
+      # run too early in the callback process. If a user is changing Vault
+      # attributes in a callback, it is possible that our callback will run
+      # before theirs, resulting in attributes that are not persisted.
+      after_save :__vault_persist_attributes!
+
+      # Decrypt all the attributes from Vault.
+      # @return [true]
+      def __vault_load_attributes!
+        self.class.__vault_attributes.each do |attribute, options|
+          self.__vault_load_attribute!(attribute, options)
+        end
+
+        return true
+      end
+
+      # Decrypt and load a single attribute from Vault.
+      def __vault_load_attribute!(attribute, options)
+        key        = options[:key]
+        path       = options[:path]
+        serializer = options[:serializer]
+        column     = options[:encrypted_column]
+
+        # Load the ciphertext
+        ciphertext = read_attribute(column)
+
+        # If the user provided a value for the attribute, do not try to load
+        # it from Vault
+        if instance_variable_get("@#{attribute}")
+          return
+        end
+
+        # Load the plaintext value
+        plaintext = Vault::Rails.decrypt(path, key, ciphertext)
+
+        # Deserialize the plaintext value, if a serializer exists
+        if serializer
+          plaintext = serializer.decode(plaintext)
+        end
+
+        # Write the virtual attribute with the plaintext value
+        instance_variable_set("@#{attribute}", plaintext)
+      end
+
+      # Encrypt all the attributes using Vault and set the encrypted values back
+      # on this model.
+      # @return [true]
+      def __vault_persist_attributes!
+        changes = {}
+
+        self.class.__vault_attributes.each do |attribute, options|
+          if c = self.__vault_persist_attribute!(attribute, options)
+            changes.merge!(c)
+          end
+        end
+
+        # If there are any changes to the model, update them all at once,
+        # skipping any callbacks and validation. This is okay, because we are
+        # already in a transaction due to the callback.
+        if !changes.empty?
+          self.update_columns(changes)
+        end
+
+        return true
+      end
+
+      # Encrypt a single attribute using Vault and persist back onto the
+      # encrypted attribute value.
+      def __vault_persist_attribute!(attribute, options)
+        key        = options[:key]
+        path       = options[:path]
+        serializer = options[:serializer]
+        column     = options[:encrypted_column]
+
+        # Only persist changed attributes to minimize requests - this helps
+        # minimize the number of requests to Vault.
+        if !changed.include?("#{attribute}")
+          return
+        end
+
+        # Get the current value of the plaintext attribute
+        plaintext = instance_variable_get("@#{attribute}")
+
+        # Apply the serialize to the plaintext value, if one exists
+        if serializer
+          plaintext = serializer.encode(plaintext)
+        end
+
+        # Generate the ciphertext and store it back as an attribute
+        ciphertext = Vault::Rails.encrypt(path, key, plaintext)
+
+        # Write the attribute back, so that we don't have to reload the record
+        # to get the ciphertext
+        write_attribute(column, ciphertext)
+
+        # Return the updated column so we can save
+        { column => ciphertext }
+      end
+
+      # Override the reload method to reload the Vault attributes. This will
+      # ensure that we always have the most recent data from Vault when we
+      # reload a record from the database.
+      def reload(*)
+        super.tap do
+          # Unset all the instance variables to force the new data to be pulled
+          # from Vault
+          self.class.__vault_attributes.each do |attribute, _|
+            self.instance_variable_set("@#{attribute}", nil)
+          end
+
+          self.__vault_load_attributes!
+        end
+      end
     end
   end
 end