vault-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 264e4b8ae8a63d401b64370615831d735ee5341d
-  data.tar.gz: f233fcdce5a44aa0eb2c25284b37e6ac23e10d96
+  metadata.gz: 2aeef850725a949ef29fdb4ed9cc05ea02e8857a
+  data.tar.gz: 582d156fefa20941146a74eaa989c03e3dd2d948
 SHA512:
-  metadata.gz: 144e2eebb837082f62132bdd7ffe155658b567125a2daff5d11e130a8fd0fb1c0cfed75bdcb459a23916c6c1eb47a151199bc9f43389344f72b00c602e719cfe
-  data.tar.gz: ead4d9b6091b9eafcfcd28a8e33a1df102b3230dbb2349c96309a5c7abc4f7eda8ff46485c04e080162e74acf19dc917e74366bbbc9328e729b22feb679cb4d0
+  metadata.gz: 7ea41a6ca9a7c4e5c7d3298a4ef494b5a58a86b8005eb1c17f2f9b5d2e0da2c7e349fd0c13ae932f36992a7085c08d69b21b644123693b501237be0ae83e5338
+  data.tar.gz: 4c4b9a6ab95172c52338f6220a7ebe9c152dd22a283a0ed90d0ba35171fd08e8b4b08f57f732bcac4fc1e5e8ef8263b053b3e35363ad340f0f4d4425c02aea21

data/README.md

@@ -90,7 +90,7 @@ vault_attribute :credit_card,
 - **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:
+By default, the name of the key in Vault is `#{app}_#{table}_#{column}`. This is customizable by setting the `:key` option when declaring the attribute:
 
 ```ruby
 vault_attribute :credit_card,
@@ -99,7 +99,66 @@ vault_attribute :credit_card,
 
 - **Note** Changing this value for an existing application will make existing values no longer decryptable!
 
+#### Specifying a context (key derivation)
+
+Vault Transit supports key derivation, which allows the same key to be used for multiple purposes by deriving a new key based on a context value.
+
+The context can be specified as a string, symbol, or proc. Symbols (an instance method on the model) and procs are called for each encryption or decryption request, and should return a string.
+
+- **Note** Changing the context or context generator for an attribute will make existing values no longer decryptable!
+
+##### String
+
+With a string, all records will use the same context for this attribute:
+
+```ruby
+vault_attribute :credit_card,
+  context: "user-cc"
+```
+
+##### Symbol
+
+When using a symbol, a method will be called on the record to compute the context:
+
+```ruby
+belongs_to :user
+
+vault_attribute :credit_card,
+  context: :encryption_context
+
+def encryption_context
+  "user_#{user.id}"
+end
+```
+
+##### Proc
+
+Given a proc, it will be called each time to compute the context:
+
+```ruby
+belongs_to :user
+
+vault_attribute :credit_card,
+  context: ->(record) { "user_#{record.user.id}" }
+```
+
+The proc must take a single argument for the record.
+
+#### Specifying a default value
+
+An attribute can specify a default value, which will be set on initialization (`.new`) or after loading the value from the database. The default will be set if the value is `nil`.
+
+```ruby
+vault_attribute :access_level,
+  default: "readonly"
+
+vault_attribute :metadata,
+  serialize: :json,
+  default: {}
+```
+
 #### 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
@@ -109,16 +168,45 @@ vault_attribute :credit_card,
 
 - **Note** Changing this value for an existing application will make existing values no longer decryptable!
 
-#### Automatic serializing
+#### 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:
+
+
+```ruby
+class Person < ActiveRecord::Base
+  include Vault::EncryptedModel
+  vault_lazy_decrypt!
+
+  vault_attribute :ssn
+end
+
+# Without vault_lazy_decrypt:
+person = Person.find(id) # Vault communication happens here
+person.ssn
+# => "123-45-6789"
+
+# With vault_lazy_decrypt:
+person = Person.find(id)
+person.ssn # Vault communication happens here
+# => "123-45-6789"
+```
+
+#### 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
-vault_attribute :details
-  serialize: :json
+vault_attribute :details,
+  serialize: :json,
+  default: {}
 ```
 
+It is recommended to set a default matching type that you're serializing.
+
 - **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.
 
+##### Custom Serializers
+
 For customized solutions, you can also pass a module to the `:serializer` key. This module must have the following API:
 
 ```ruby
@@ -151,7 +239,7 @@ vault_attribute :address,
   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!
+- **Note** Changing the algorithm for encoding/decoding for an existing application will probably make the application crash when attempting to retrieve existing values!
 
 Caveats
 -------

data/lib/vault/encrypted_model.rb

@@ -29,6 +29,12 @@ module Vault
       #   the path to the transit backend (default: +transit+)
       # @option options [String] :key
       #   the name of the encryption key (default: +#{app}_#{table}_#{column}+)
+      # @option options [String, Symbol, Proc] :context
+      #   either a string context, or a symbol or proc used to generate a
+      #   context for key generation
+      # @option options [Object] :default
+      #   a default value for this attribute to be set to if the underlying
+      #   value is nil
       # @option options [Symbol, Class] :serializer
       #   the name of the serializer to use (or a class)
       # @option options [Proc] :encode
@@ -39,6 +45,8 @@ module Vault
         encrypted_column = options[:encrypted_column] || "#{attribute}_encrypted"
         path = options[:path] || "transit"
         key = options[:key] || "#{Vault::Rails.application}_#{table_name}_#{attribute}"
+        context = options[:context]
+        default = options[:default]
 
         # Sanity check options!
         _vault_validate_options!(options)
@@ -107,10 +115,12 @@ module Vault
 
         # Make a note of this attribute so we can use it in the future (maybe).
         __vault_attributes[attribute.to_sym] = {
+          context: context,
+          default: default,
+          encrypted_column: encrypted_column,
           key: key,
           path: path,
-          serializer: serializer,
-          encrypted_column: encrypted_column,
+          serializer: serializer
         }
 
         self
@@ -142,6 +152,13 @@ module Vault
           raise Vault::Rails::ValidationFailedError, "Cannot specify " \
             "`:decode' without specifying `:encode' as well!"
         end
+
+        if context = options[:context]
+          if context.is_a?(Proc) && context.arity != 1
+            raise Vault::Rails::ValidationFailedError, "Proc passed to " \
+              "`:context' must take 1 argument!"
+          end
+        end
       end
 
       def vault_lazy_decrypt
@@ -193,6 +210,8 @@ module Vault
         path       = options[:path]
         serializer = options[:serializer]
         column     = options[:encrypted_column]
+        context    = options[:context]
+        default    = options[:default]
 
         # Load the ciphertext
         ciphertext = read_attribute(column)
@@ -203,14 +222,25 @@ module Vault
           return
         end
 
+        # Generate context if needed
+        generated_context = __vault_generate_context(context)
+
         # Load the plaintext value
-        plaintext = Vault::Rails.decrypt(path, key, ciphertext)
+        plaintext = Vault::Rails.decrypt(
+          path, key, ciphertext,
+          context: generated_context
+        )
 
         # Deserialize the plaintext value, if a serializer exists
         if serializer
           plaintext = serializer.decode(plaintext)
         end
 
+        # Set to default if needed
+        if default && plaintext == nil
+          plaintext = default
+        end
+
         # Write the virtual attribute with the plaintext value
         instance_variable_set("@#{attribute}", plaintext)
       end
@@ -244,6 +274,7 @@ module Vault
         path       = options[:path]
         serializer = options[:serializer]
         column     = options[:encrypted_column]
+        context    = options[:context]
 
         # Only persist changed attributes to minimize requests - this helps
         # minimize the number of requests to Vault.
@@ -259,8 +290,14 @@ module Vault
           plaintext = serializer.encode(plaintext)
         end
 
+        # Generate context if needed
+        generated_context = __vault_generate_context(context)
+
         # Generate the ciphertext and store it back as an attribute
-        ciphertext = Vault::Rails.encrypt(path, key, plaintext)
+        ciphertext = Vault::Rails.encrypt(
+          path, key, plaintext,
+          context: generated_context
+        )
 
         # Write the attribute back, so that we don't have to reload the record
         # to get the ciphertext
@@ -270,6 +307,20 @@ module Vault
         { column => ciphertext }
       end
 
+      # Generates an Vault Transit encryption context for use on derived keys.
+      def __vault_generate_context(context)
+        case context
+        when String
+          context
+        when Symbol
+          send(context)
+        when Proc
+          context.call(self)
+        else
+          nil
+        end
+      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.

data/lib/vault/rails.rb

@@ -6,7 +6,7 @@ require "json"
 require_relative "encrypted_model"
 require_relative "rails/configurable"
 require_relative "rails/errors"
-require_relative "rails/serializer"
+require_relative "rails/json_serializer"
 require_relative "rails/version"
 
 module Vault
@@ -72,7 +72,7 @@ module Vault
       #
       # @return [String]
       #   the encrypted cipher text
-      def encrypt(path, key, plaintext, client = self.client)
+      def encrypt(path, key, plaintext, client: self.client, context: nil)
         if plaintext.blank?
           return plaintext
         end
@@ -82,9 +82,9 @@ module Vault
 
         with_retries do
           if self.enabled?
-            result = self.vault_encrypt(path, key, plaintext, client)
+            result = self.vault_encrypt(path, key, plaintext, client: client, context: context)
           else
-            result = self.memory_encrypt(path, key, plaintext, client)
+            result = self.memory_encrypt(path, key, plaintext, client: client, context: context)
           end
 
           return self.force_encoding(result)
@@ -104,7 +104,7 @@ module Vault
       #
       # @return [String]
       #   the decrypted plaintext text
-      def decrypt(path, key, ciphertext, client = self.client)
+      def decrypt(path, key, ciphertext, client: self.client, context: nil)
         if ciphertext.blank?
           return ciphertext
         end
@@ -114,9 +114,9 @@ module Vault
 
         with_retries do
           if self.enabled?
-            result = self.vault_decrypt(path, key, ciphertext, client)
+            result = self.vault_decrypt(path, key, ciphertext, client: client, context: context)
           else
-            result = self.memory_decrypt(path, key, ciphertext, client)
+            result = self.memory_decrypt(path, key, ciphertext, client: client, context: context)
           end
 
           return self.force_encoding(result)
@@ -143,55 +143,67 @@ module Vault
       protected
 
       # Perform in-memory encryption. This is useful for testing and development.
-      def memory_encrypt(path, key, plaintext, client)
+      def memory_encrypt(path, key, plaintext, client: , context: nil)
         log_warning(DEV_WARNING) if self.in_memory_warnings_enabled?
 
         return nil if plaintext.nil?
 
         cipher = OpenSSL::Cipher::AES.new(128, :CBC)
         cipher.encrypt
-        cipher.key = memory_key_for(path, key)
+        cipher.key = memory_key_for(path, key, context: context)
         return Base64.strict_encode64(cipher.update(plaintext) + cipher.final)
       end
 
       # Perform in-memory decryption. This is useful for testing and development.
-      def memory_decrypt(path, key, ciphertext, client)
+      def memory_decrypt(path, key, ciphertext, client: , context: nil)
         log_warning(DEV_WARNING) if self.in_memory_warnings_enabled?
 
         return nil if ciphertext.nil?
 
         cipher = OpenSSL::Cipher::AES.new(128, :CBC)
         cipher.decrypt
-        cipher.key = memory_key_for(path, key)
+        cipher.key = memory_key_for(path, key, context: context)
         return cipher.update(Base64.strict_decode64(ciphertext)) + cipher.final
       end
 
+      # The symmetric key for the given params.
+      # @return [String]
+      def memory_key_for(path, key, context: nil)
+        md5 = OpenSSL::Digest::MD5.new
+        md5 << path
+        md5 << key
+        md5 << context if context
+        md5.digest
+      end
+
       # Perform encryption using Vault. This will raise exceptions if Vault is
       # unavailable.
-      def vault_encrypt(path, key, plaintext, client)
+      def vault_encrypt(path, key, plaintext, client: , context: nil)
         return nil if plaintext.nil?
 
-        route  = File.join(path, "encrypt", key)
-        secret = client.logical.write(route,
-          plaintext: Base64.strict_encode64(plaintext),
-        )
+        route = File.join(path, "encrypt", key)
+
+        data = { plaintext: Base64.strict_encode64(plaintext) }
+        data[:context] = Base64.strict_encode64(context) if context
+
+        secret = client.logical.write(route, data)
+
         return secret.data[:ciphertext]
       end
 
       # Perform decryption using Vault. This will raise exceptions if Vault is
       # unavailable.
-      def vault_decrypt(path, key, ciphertext, client)
+      def vault_decrypt(path, key, ciphertext, client: , context: nil)
         return nil if ciphertext.nil?
 
-        route  = File.join(path, "decrypt", key)
-        secret = client.logical.write(route, ciphertext: ciphertext)
-        return Base64.strict_decode64(secret.data[:plaintext])
-      end
+        route = File.join(path, "decrypt", key)
 
-      # The symmetric key for the given params.
-      # @return [String]
-      def memory_key_for(path, key)
-        return Base64.strict_encode64("#{path}/#{key}".ljust(16, "x")).byteslice(0..15)
+        data = { ciphertext: ciphertext }
+        data[:context] = Base64.strict_encode64(context) if context
+
+        secret = client.logical.write(route, data)
+
+        return Base64.strict_decode64(secret.data[:plaintext])
       end
 
       # Forces the encoding into the default Rails encoding and returns the

data/lib/vault/rails/configurable.rb

@@ -112,7 +112,7 @@ module Vault
         @retry_max_wait ||= Vault::Defaults::RETRY_MAX_WAIT
       end
 
-      # Sets the naximum amount of time for a single retry. Please see the Vault
+      # Sets the maximum amount of time for a single retry. Please see the Vault
       # documentation for more information.
       #
       # @param [Fixnum] val

data/lib/vault/rails/{serializer.rb → json_serializer.rb}

@@ -7,17 +7,16 @@ module Vault
       }.freeze
 
       def self.encode(raw)
-        self._init!
-
-        raw = {} if raw.nil?
+        _init!
 
         JSON.fast_generate(raw)
       end
 
       def self.decode(raw)
-        self._init!
+        _init!
+
+        return nil if raw == nil || raw == ""
 
-        return {} if raw.nil? || raw.empty?
         JSON.parse(raw, DECODE_OPTIONS)
       end
 

data/lib/vault/rails/version.rb

@@ -1,5 +1,5 @@
 module Vault
   module Rails
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

data/spec/dummy/app/models/lazy_person.rb

@@ -25,4 +25,24 @@ class LazyPerson < ActiveRecord::Base
     decode: ->(raw) { raw && raw[3...-3] }
 
   vault_attribute :non_ascii
+
+  vault_attribute :default,
+    default: "abc123"
+
+  vault_attribute :default_with_serializer,
+    serialize: :json,
+    default: {}
+
+  vault_attribute :context_string,
+    context: "production"
+
+  vault_attribute :context_symbol,
+    context: :encryption_context
+
+  vault_attribute :context_proc,
+    context: ->(record) { record.encryption_context }
+
+  def encryption_context
+    "user_#{id}"
+  end
 end