chef-encrypted-attributes 0.3.0 → 0.4.0

data/lib/chef/encrypted_attribute/assertions.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 #
 # Author:: Xabier de Zuazo (<xabier@onddo.com>)
 # Copyright:: Copyright (c) 2014 Onddo Labs, SL. (www.onddo.com)
@@ -20,17 +21,26 @@ require 'chef/encrypted_attribute/exceptions'
 
 class Chef
   class EncryptedAttribute
+    # Include some assertions that throw exceptions if not met.
     module Assertions
-
+      # Checks some assertions related with OpenSSL AEAD support, required to
+      # to use [GCM](http://en.wikipedia.org/wiki/Galois/Counter_Mode).
+      #
+      # @param algorithm [String] the name of the algorithm to use.
+      # @return void
+      # @raise [RequirementsFailure] if any of the requirements to use AEAD is
+      #   not met.
       def assert_aead_requirements_met!(algorithm)
         unless OpenSSL::Cipher.method_defined?(:auth_data=)
-          raise RequirementsFailure, 'The used Encrypted Attributes protocol version requires Ruby >= 1.9'
-        end
-        unless OpenSSL::Cipher.ciphers.include?(algorithm)
-          raise RequirementsFailure, "The used Encrypted Attributes protocol version requires an OpenSSL version with \"#{algorithm}\" algorithm support"
+          fail RequirementsFailure,
+               'The used Encrypted Attributes protocol version requires Ruby '\
+               '>= 1.9'
         end
+        return if OpenSSL::Cipher.ciphers.include?(algorithm)
+        fail RequirementsFailure,
+             'The used Encrypted Attributes protocol version requires an '\
+             "OpenSSL version with \"#{algorithm}\" algorithm support"
       end
-
     end
   end
 end

data/lib/chef/encrypted_attribute/cache_lru.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 #
 # Author:: Xabier de Zuazo (<xabier@onddo.com>)
 # Copyright:: Copyright (c) 2014 Onddo Labs, SL. (www.onddo.com)
@@ -18,33 +19,63 @@
 
 require 'chef/mixin/params_validate'
 
-# Based on https://github.com/SamSaffron/lru_redux
 class Chef
   class EncryptedAttribute
+    # Implements an LRU (Least Recently Used) cache object.
+    #
+    # The LRU cache algorithm discards the least recently used items first.
+    #
+    # This class extends from *Hash* class and adds methods to behave as a
+    # cache.
+    #
+    # You can use the `clear` class method to clean a cache:
+    #
+    # ```ruby
+    # Chef::EncryptedAttribute::RemoteClients.cache.clear
+    # Chef::EncryptedAttribute::RemoteNodes.cache.clear
+    # Chef::EncryptedAttribute::RemoteUsers.cache.clear
+    # Chef::EncryptedAttribute::RemoteNode.cache.clear
+    # ```
+    #
+    # @note Based on [SamSaffron](https://github.com/SamSaffron) work:
+    #   https://github.com/SamSaffron/lru_redux
+    # @see API
     class CacheLru < Hash
       include ::Chef::Mixin::ParamsValidate
 
-      def initialize(size=nil)
+      # Constructs a new Cache LRU object.
+      #
+      # @param size [Fixnum] Cache maximum size in object count.
+      def initialize(size = nil)
         super
         max_size(size)
       end
 
-      def max_size(arg=nil)
+      # Reads or sets the cache maximum size.
+      #
+      # Removes some values if needed (when the size is reduced).
+      #
+      # The cache size is `1024` by default.
+      #
+      # @param arg [Fixnum] cache maximum size to set.
+      # @return [Fixnum] cache maximum size.
+      def max_size(arg = nil)
         set_or_return(
           :max_size,
           arg,
-          :kind_of => [ Fixnum ],
-          :default => 1024,
-          :callbacks => begin
-            { 'should not be lower that zero' => lambda { |x| x >= 0 } }
-          end
+          kind_of: [Fixnum], default: 1024,
+          callbacks: { 'should not be lower that zero' => ->(x) { x >= 0 } }
         )
         pop_tail unless arg.nil?
         @max_size
       end
 
+      # Reads a cache key.
+      #
+      # @param key [String, Symbol] cache key to read.
+      # @return [Mixed] cache key value.
       def [](key)
-        if has_key?(key)
+        if key?(key)
           val = super(key)
           self[key] = val
         else
@@ -52,6 +83,14 @@ class Chef
         end
       end
 
+      # Sets a cache key.
+      #
+      # Some keys will be removed if the cache size grows too much. The keys to
+      # be removed will be chosen using the LRU algorithm.
+      #
+      # @param key [String, Symbol] cache key to set.
+      # @param val [Mixed] cache key value.
+      # @return [Mixed] cache key value.
       def []=(key, val)
         if max_size > 0 # unnecessary "if", small optimization?
           delete(key)
@@ -63,12 +102,14 @@ class Chef
 
       protected
 
+      # Removes the tail elements until the size is correct.
+      #
+      # This method is needed to implement the LRU algorithm.
+      #
+      # @return void
       def pop_tail
-        while size > max_size
-          delete(first[0])
-        end
+        delete(first[0]) while size > max_size
       end
-
     end
   end
 end

data/lib/chef/encrypted_attribute/config.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 #
 # Author:: Xabier de Zuazo (<xabier@onddo.com>)
 # Copyright:: Copyright (c) 2014 Onddo Labs, SL. (www.onddo.com)
@@ -20,137 +21,191 @@ require 'chef/mixin/params_validate'
 
 class Chef
   class EncryptedAttribute
+    # Encrypted attributes configuration options object.
     class Config
       include ::Chef::Mixin::ParamsValidate
 
+      # Returns configuration options list.
+      #
+      # @api private
       OPTIONS = [
         :version,
         :partial_search,
         :client_search,
         :node_search,
         :users,
-        :keys,
+        :keys
       ].freeze
 
-      def initialize(config=nil)
+      # Constructs a {Config} object.
+      #
+      # @param config [Config, Hash] configuration object to clone.
+      def initialize(config = nil)
         update!(config) unless config.nil?
       end
 
-      def version(arg=nil)
-        unless arg.nil? or not arg.kind_of?(String)
-          arg = Integer(arg) rescue arg
+      # Reads or sets Encrypted Mash protocol version.
+      #
+      # @param arg [String, Fixnum] protocol version to use. Must be a number.
+      # @return [Fixnum] protocol version.
+      def version(arg = nil)
+        unless arg.nil? || !arg.is_a?(String)
+          begin
+            arg = Integer(arg)
+          rescue ArgumentError
+            arg
+          end
         end
-        set_or_return(
-          :version,
-          arg,
-          :kind_of => [ Fixnum, String ],
-          :default => 1
-        )
+        set_or_return(:version, arg, kind_of: [Fixnum, String], default: 1)
       end
 
-      def partial_search(arg=nil)
+      # Reads or sets partial search support.
+      #
+      # Set it to `false` to disable partial search. Defaults to `true`.
+      #
+      # @param arg [Boolean] whether to enable partial search.
+      # @return [Boolean] partial search usage.
+      # @see
+      #   http://docs.getchef.com/chef_search.html Chef Search documentation
+      def partial_search(arg = nil)
         set_or_return(
-          :partial_search,
-          arg,
-          :kind_of => [ TrueClass, FalseClass ],
-          :default => true
+          :partial_search, arg, kind_of: [TrueClass, FalseClass], default: true
         )
       end
 
-      def client_search(arg=nil)
-        unless arg.nil? or not arg.kind_of?(String)
-          arg = [ arg ]
-        end
-        set_or_return(
-          :client_search,
-          arg,
-          :kind_of => Array,
-          :default => [],
-          :callbacks => config_search_array_callbacks
-        )
+      # Reads or sets client search query.
+      #
+      # This query will return a list of clients that will be able to read the
+      # encrypted attribute.
+      #
+      # @param arg [String, Array<String>] list of client queries to perform.
+      # @return [Array<String>] list of client queries.
+      # @see
+      #   http://docs.getchef.com/chef_search.html Chef Search documentation
+      def client_search(arg = nil)
+        set_or_return_search_array(:client_search, arg)
       end
 
-      def node_search(arg=nil)
-        unless arg.nil? or not arg.kind_of?(String)
-          arg = [ arg ]
-        end
-        set_or_return(
-          :node_search,
-          arg,
-          :kind_of => Array,
-          :default => [],
-          :callbacks => config_search_array_callbacks
-        )
+      # Reads or sets node search query.
+      #
+      # This query will return a list of nodes that will be able to read the
+      # encrypted attribute.
+      #
+      # @param arg [String, Array<String>] list of node queries to perform.
+      # @return [Array<String>] list of node queries.
+      def node_search(arg = nil)
+        set_or_return_search_array(:node_search, arg)
       end
 
-      def users(arg=nil)
+      # Reads or sets user list.
+      #
+      # This contains the user list that will be able to read the encrypted
+      # attribute.
+      #
+      # @param arg [String, Array<String>] list of users to set.
+      # @return [Array<String>] list of users.
+      def users(arg = nil)
         set_or_return(
-          :users,
-          arg,
-          :kind_of => [ String, Array ],
-          :default => [],
-          :callbacks => config_users_arg_callbacks
+          :users, arg,
+          kind_of: [String, Array], default: [],
+          callbacks: config_users_arg_callbacks
         )
       end
 
-      def keys(arg=nil)
+      # Reads or sets key list.
+      #
+      # This contains the raw key list that will be able to read the encrypted
+      # attribute.
+      #
+      # @param arg [Array<String, OpenSSL::PKey::RSA>] the keys in PEM format.
+      # @return [Array<String, OpenSSL::PKey::RSA>] the keys in PEM format
+      def keys(arg = nil)
         set_or_return(
-          :keys,
-          arg,
-          :kind_of => Array,
-          :default => [],
-          :callbacks => config_valid_keys_array_callbacks
+          :keys, arg,
+          kind_of: Array, default: [],
+          callbacks: config_valid_keys_array_callbacks
         )
       end
 
+      # Replaces the current config.
+      #
+      # When setting using a {Chef::EncryptedAttribute::Config} class, all the
+      # configuration options will be replaced.
+      #
+      # When setting using a _Hash_, only the provided keys will be replaced.
+      #
+      # @param config [Config, Hash] the configuration to set.
+      # @return [Config] `self`.
       def update!(config)
-        if config.kind_of?(self.class)
-          OPTIONS.each do |attr|
-            value = dup_object(config.send(attr))
-            self.instance_variable_set("@#{attr.to_s}", value)
-          end
-        elsif config.kind_of?(Hash)
-          config.each do |attr, value|
-            attr = attr.to_sym if attr.kind_of?(String)
-            if OPTIONS.include?(attr)
-              value = dup_object(value)
-              self.send(attr, value)
-            else
-              Chef::Log.warn("#{self.class.to_s}: configuration method not found: \"#{attr.to_s}\".")
-            end
-          end
+        if config.is_a?(self.class)
+          update_from_config!(config)
+        elsif config.is_a?(Hash)
+          update_from_hash!(config)
         end
       end
 
+      # Reads a configuration option.
+      #
+      # @param key [String, Symbol] configuration option to read.
+      # @return [Mixed] configuration value.
       def [](key)
-        key = key.to_sym if key.kind_of?(String)
-        if OPTIONS.include?(key)
-          self.send(key)
-        end
+        key = key.to_sym if key.is_a?(String)
+        send(key) if OPTIONS.include?(key)
       end
 
+      # Sets a configuration option.
+      #
+      # @param key [String, Symbol] configuration option name to set.
+      # @param value [Mixed] configuration value to set.
+      # @return [Mixed] configuration value.
       def []=(key, value)
-        key = key.to_sym if key.kind_of?(String)
-        if OPTIONS.include?(key)
-          self.send(key, value)
-        end
+        key = key.to_sym if key.is_a?(String)
+        send(key, value) if OPTIONS.include?(key)
       end
 
       protected
 
+      # Duplicates an object avoiding Ruby exceptions if not supported.
+      #
+      # @param o [Object] object to duplicate.
+      # @return [Object] duplicated object.
       def dup_object(o)
         o.dup
       rescue TypeError
         o
       end
 
+      # Creates getter and setter method for **search array** configuration
+      # options.
+      #
+      # This configuration options contains an array of search queries.
+      #
+      # @param name [Symbol] configuration option name.
+      # @param arg [Array<String>, String] configuration option value to set.
+      # @return [Array<String>] configuration option value.
+      def set_or_return_search_array(name, arg = nil)
+        arg = [arg] unless arg.nil? || !arg.is_a?(String)
+        set_or_return(
+          name, arg,
+          kind_of: Array, default: [], callbacks: config_search_array_callbacks
+        )
+      end
+
+      # Checks a search query array list.
+      #
+      # @param s_ary [Array<String>] search query array.
+      # @return [Boolean] `true` if the search query list is in the correct
+      #   format.
       def config_valid_search_array?(s_ary)
         s_ary.each do |s|
-          return false unless s.kind_of?(String)
+          return false unless s.is_a?(String)
         end
         true
       end
 
+      # Returns configuration option callback function for search arrays.
+      #
+      # @return [Proc] search arrays checking callback function.
       def config_search_array_callbacks
         {
           'should be a valid array of search patterns' => lambda do |cs|
@@ -159,14 +214,22 @@ class Chef
         }
       end
 
+      # Checks a user list option value.
+      #
+      # @param users [Array<String>, '*'] user list to check.
+      # @return [Boolean] `true` if the user list is in the correct
+      #   format.
       def config_valid_user_arg?(users)
-        return users == '*' if users.kind_of?(String)
+        return users == '*' if users.is_a?(String)
         users.each do |u|
-          return false unless u.kind_of?(String) and u.match(/^[a-z0-9\-_]+$/)
+          return false unless u.is_a?(String) && u.match(/^[a-z0-9\-_]+$/)
         end
         true
       end
 
+      # Returns configuration option callback function for user lists.
+      #
+      # @return [Proc] user lists checking callback function.
       def config_users_arg_callbacks
         {
           'should be a valid array of search patterns' => lambda do |us|
@@ -175,32 +238,45 @@ class Chef
         }
       end
 
+      # Checks if an OpenSSL key is in the correct format.
+      #
+      # Only checks that has a public key. It may lack private key.
+      #
+      # @param k [String, OpenSSL::PKey::RSA] key to check.
+      # @return [Boolean] `true` if the public key is correct.
       def config_valid_key?(k)
-        rsa_k = case k
-        when OpenSSL::PKey::RSA
-          k
-        when String
-          begin
-            OpenSSL::PKey::RSA.new(k)
-          rescue OpenSSL::PKey::RSAError, TypeError
+        rsa_k =
+          case k
+          when OpenSSL::PKey::RSA then k
+          when String
+            begin
+              OpenSSL::PKey::RSA.new(k)
+            rescue OpenSSL::PKey::RSAError, TypeError
+              nil
+            end
+          else
             nil
           end
-        else
-          nil
-        end
         return false if rsa_k.nil?
         rsa_k.public?
       end
 
+      # Checks if an OpenSSL key array is in the correct format.
+      #
+      # Only checks that the keys have a public key. They may lack private key.
+      #
+      # @param k_ary [Array<String, OpenSSL::PKey::RSA>] array of keys to check.
+      # @return [Boolean] `true` if the public keys are all correct.
       def config_valid_keys_array?(k_ary)
         k_ary.each do |k|
-          unless config_valid_key?(k)
-            return false
-          end
+          return false unless config_valid_key?(k)
         end
         true
       end
 
+      # Returns configuration option callback function for public keys.
+      #
+      # @return [Proc] public keys checking callback function.
       def config_valid_keys_array_callbacks
         {
           'should be a valid array of keys' => lambda do |keys|
@@ -209,6 +285,39 @@ class Chef
         }
       end
 
+      # Copies a configuration. All the current configuration options will be
+      # replaced.
+      #
+      # Called by {#update_from!} for {Config} objects.
+      #
+      # @param config [Config] configuration options to copy.
+      def update_from_config!(config)
+        OPTIONS.each do |attr|
+          value = dup_object(config.send(attr))
+          instance_variable_set("@#{attr}", value)
+        end
+      end
+
+      # Copies a configuration option. Only the provided Hash keys will be
+      # replaced, the others will be preserved.
+      #
+      # Called by {#update_from!} for *Hash* objects.
+      #
+      # @param config [Hash] configuration options to copy.
+      def update_from_hash!(config)
+        config.each do |attr, value|
+          attr = attr.to_sym if attr.is_a?(String)
+          if OPTIONS.include?(attr)
+            value = dup_object(value)
+            send(attr, value)
+          else
+            Chef::Log.warn(
+              "#{self.class}: configuration method not found: "\
+              "#{attr.to_s.inspect}."
+            )
+          end
+        end
+      end
     end
   end
 end