chef-encrypted-attributes 0.3.0 → 0.4.0

data/lib/chef/encrypted_attribute/exceptions.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,23 +19,38 @@
 
 class Chef
   class EncryptedAttribute
-
+    # Exception raised when some requirements to use the encrypted attributes
+    # are not met.
     class RequirementsFailure < StandardError; end
+    # Exception raised when the encrypted attribute format is unknown.
     class UnsupportedEncryptedAttributeFormat < StandardError; end
+    # Exception raised when the encrypted attribute format is wrong.
     class UnacceptableEncryptedAttributeFormat < StandardError; end
+    # Exception raised when there are decryption errors.
     class DecryptionFailure < StandardError; end
+    # Exception raised when there are encryption errors.
     class EncryptionFailure < StandardError; end
+    # Exception raised when there errors generating the HMAC.
     class MessageAuthenticationFailure < StandardError; end
+    # Exception raised when the public key is wrong.
     class InvalidPublicKey < StandardError; end
-    class InvalidPrivateKey < StandardError; end
+    # Exception raised when the key is wrong.
+    class InvalidKey < StandardError; end
 
+    # Exception raised when you don't have enough privileges in the Chef Server
+    # to do what you intend. Usually happens when you try to read Client or Node
+    # keys without being admin.
     class InsufficientPrivileges < StandardError; end
+    # Exception raised when the user does not exist.
     class UserNotFound < StandardError; end
+    # Exception raised when the client does not exist.
     class ClientNotFound < StandardError; end
 
+    # Exception raised for search errors.
     class SearchFailure < StandardError; end
+    # Exception raised for search fatal errors.
     class SearchFatalError < StandardError; end
+    # Exception raised when search keys are wrong.
     class InvalidSearchKeys < StandardError; end
-
   end
 end

data/lib/chef/encrypted_attribute/local_node.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,21 +19,31 @@
 
 class Chef
   class EncryptedAttribute
+    # Get name and keys from local Chef Node.
     class LocalNode
-
-      # currently not used
+      # Gets the local node name.
+      #
+      # @return [String] local node name.
+      # @note currently not used
       def name
         Chef::Config[:node_name]
       end
 
+      # Gets the local node key.
+      #
+      # The key has the private key and the public key embedded.
+      #
+      # @return [OpenSSL::PKey::RSA] the local node private and the public key.
       def key
-        OpenSSL::PKey::RSA.new(open(Chef::Config[:client_key]).read())
+        OpenSSL::PKey::RSA.new(open(Chef::Config[:client_key]).read)
       end
 
+      # Gets the local node public key.
+      #
+      # @return [OpenSSL::PKey::RSA] the local node public key.
       def public_key
         key.public_key
       end
-
     end
   end
 end

data/lib/chef/encrypted_attribute/remote_clients.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)
@@ -24,37 +25,52 @@ require 'chef/encrypted_attribute/cache_lru'
 
 class Chef
   class EncryptedAttribute
+    # Search remote Chef Clients public keys.
     class RemoteClients
       extend ::Chef::EncryptedAttribute::SearchHelper
 
+      # Remote clients search results cache.
+      #
+      # You can disable it setting it's size to zero:
+      #
+      # ```ruby
+      # Chef::EncryptedAttribute::RemoteClients.cache.max_size(0)
+      # ```
+      #
+      # @return [CacheLru] Remote clients LRU cache.
       def self.cache
         @@cache ||= Chef::EncryptedAttribute::CacheLru.new
       end
 
+      # Gets remote client public key.
+      #
+      # @param name [String] Chef client name.
+      # @return [String] Chef client public key as string.
+      # @raise [ClientNotFound] if client does not exist.
+      # @raise [Net::HTTPServerException] for Chef Server HTTP errors.
       def self.get_public_key(name)
         Chef::ApiClient.load(name).public_key
       rescue Net::HTTPServerException => e
-        case e.response.code
-        when '404' # Not Found
-          raise ClientNotFound, "Chef Client not found: \"#{name}\"."
-        else
-          raise e
-        end
+        raise e unless e.response.code == '404'
+        raise ClientNotFound, "Chef Client not found: #{name.inspect}."
       end
 
-      def self.search_public_keys(search='*:*', partial_search=true)
+      # Searches for chef client public keys.
+      #
+      # @param search [Array<String>, String] search queries to perform, the
+      #   query result will be *OR*-ed.
+      # @return [Array<String>] list of public keys.
+      # @raise [SearchFailure] if there is a Chef search error.
+      # @raise [SearchFatalError] if the Chef search response is wrong.
+      # @raise [InvalidSearchKeys] if search keys structure is wrong.
+      def self.search_public_keys(search = '*:*', partial_search = true)
         escaped_query = escape_query(search)
-        if cache.has_key?(escaped_query)
-          cache[escaped_query]
-        else
-          cache[escaped_query] = search(:client, search, {
-            'public_key' => [ 'public_key' ]
-          }, 1000, partial_search).map do |client|
-            client['public_key']
-          end.compact
-        end
+        return cache[escaped_query] if cache.key?(escaped_query)
+        cache[escaped_query] = search(
+          :client, search,
+          { 'public_key' => %w(public_key) }, 1000, partial_search
+        ).map { |client| client['public_key'] }.compact
       end
-
     end
   end
 end

data/lib/chef/encrypted_attribute/remote_node.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)
@@ -22,55 +23,77 @@ require 'chef/encrypted_attribute/cache_lru'
 
 class Chef
   class EncryptedAttribute
+    # Remote Node object to read and save node attributes remotely.
     class RemoteNode
       include ::Chef::Mixin::ParamsValidate
       include ::Chef::EncryptedAttribute::SearchHelper
 
+      # Remote Node object constructor.
+      #
+      # @param name [String] node name.
       def initialize(name)
         name(name)
       end
 
+      # Remote node attribute values cache.
+      #
+      # It is disabled by default. You can enable it changing it's size:
+      #
+      # ```ruby
+      # Chef::EncryptedAttribute::RemoteNode.cache.max_size(1024)
+      # ```
+      #
+      # @return [CacheLru] node attributes LRU cache.
       def self.cache
-        @@cache ||= Chef::EncryptedAttribute::CacheLru.new(0) # disabled by default
+        # disabled by default
+        @@cache ||= Chef::EncryptedAttribute::CacheLru.new(0)
       end
 
-      def name(arg=nil)
+      # Read or set node name.
+      #
+      # @param arg [String] node name.
+      # @return [String] node name.
+      def name(arg = nil)
+        # TODO: clean the cache when changed?
         set_or_return(
           :name,
           arg,
-          :kind_of => String
+          kind_of: String
         )
       end
 
-      def load_attribute(attr_ary, partial_search=true)
-        unless attr_ary.kind_of?(Array)
-          raise ArgumentError, "#{self.class.to_s}##{__method__} attr_ary argument must be an array of strings. You passed #{attr_ary.inspect}."
-        end
+      # Loads a remote node attribute.
+      #
+      # @param attr_ary [Array<String>] node attribute path as Array.
+      # @param partial_search [Boolean] whether to use partial search.
+      # @return [Mixed] node attribute value.
+      # @raise [ArgumentError] if the attribute path format is wrong.
+      # @raise [SearchFailure] if there is a Chef search error.
+      # @raise [SearchFatalError] if the Chef search response is wrong.
+      # @raise [InvalidSearchKeys] if search keys structure is wrong.
+      def load_attribute(attr_ary, partial_search = true)
+        assert_attribute_array(attr_ary)
         cache_key = cache_key(name, attr_ary)
-        if self.class.cache.has_key?(cache_key)
-          self.class.cache[cache_key]
-        else
-          keys = { 'value' => attr_ary }
-          res = search(:node, "name:#{@name}", keys, 1, partial_search)
-          self.class.cache[cache_key] = if res.kind_of?(Array) and
-               res[0].kind_of?(Hash) and res[0].has_key?('value')
-              res[0]['value']
-            else
-              nil
-            end
-        end
+        return self.class.cache[cache_key] if self.class.cache.key?(cache_key)
+        keys = { 'value' => attr_ary }
+        res = search(:node, "name:#{@name}", keys, 1, partial_search)
+        self.class.cache[cache_key] = parse_search_result(res)
       end
 
+      # Saves a remote node attribute.
+      #
+      # @param attr_ary [Array<String>] node attribute path as Array.
+      # @param value [Mixed] node attribute value to set.
+      # @return [Mixed] node attribute value.
+      # @raise [ArgumentError] if the attribute path format is wrong.
       def save_attribute(attr_ary, value)
-        unless attr_ary.kind_of?(Array)
-          raise ArgumentError, "#{self.class.to_s}##{__method__} attr_ary argument must be an array of strings. You passed #{attr_ary.inspect}."
-        end
+        assert_attribute_array(attr_ary)
         cache_key = cache_key(name, attr_ary)
 
         node = Chef::Node.load(name)
         last = attr_ary.pop
         node_attr = attr_ary.reduce(node.normal) do |a, k|
-          a[k] = Mash.new unless a.has_key?(k)
+          a[k] = Mash.new unless a.key?(k)
           a[k]
         end
         node_attr[last] = value
@@ -79,18 +102,22 @@ class Chef
         self.class.cache[cache_key] = value
       end
 
+      # Deletes a remote node attribute.
+      #
+      # @param attr_ary [Array<String>] node attribute path as Array.
+      # @return [Boolean] whether the node attribute has been found and
+      #   successfully deleted.
+      # @raise [ArgumentError] if the attribute path format is wrong.
       def delete_attribute(attr_ary)
-        unless attr_ary.kind_of?(Array)
-          raise ArgumentError, "#{self.class.to_s}##{__method__} attr_ary argument must be an array of strings. You passed #{attr_ary.inspect}."
-        end
+        assert_attribute_array(attr_ary)
         cache_key = cache_key(name, attr_ary)
 
         node = Chef::Node.load(name)
         last = attr_ary.pop
         node_attr = attr_ary.reduce(node.normal) do |a, k|
-          a.respond_to?(:has_key?) && a.has_key?(k) ? a[k] : nil
+          a.respond_to?(:key?) && a.key?(k) ? a[k] : nil
         end
-        if node_attr.respond_to?(:has_key?) && node_attr.has_key?(last)
+        if node_attr.respond_to?(:key?) && node_attr.key?(last)
           node_attr.delete(last)
           node.save
           self.class.cache.delete(cache_key)
@@ -102,10 +129,38 @@ class Chef
 
       protected
 
+      # Parses {SearchHelper#search} result.
+      #
+      # @param res [Array<Hash>] {SearchHelper#search} result.
+      # @return [Mixed] final search result value.
+      def parse_search_result(res)
+        if res.is_a?(Array) && res[0].is_a?(Hash) && res[0].key?('value')
+          res[0]['value']
+        else
+          nil
+        end
+      end
+
+      # Generates the cache key.
+      #
+      # @param name [String] node name.
+      # @param attr_ary [Array<String>] node attribute path as Array.
+      # @return [String] cache key.
       def cache_key(name, attr_ary)
-        "#{name}:#{attr_ary.inspect}" # TODO ok, this can be improved
+        "#{name}:#{attr_ary.inspect}" # TODO: OK, this can be improved
       end
 
+      # Asserts that the attribute path is in the correct format.
+      #
+      # @param attr_ary [Array<String>] node attribute path as Array.
+      # @return void
+      # @raise [ArgumentError] if the attribute path format is wrong.
+      def assert_attribute_array(attr_ary)
+        return if attr_ary.is_a?(Array)
+        fail ArgumentError,
+             "#{self.class}##{__method__} attr_ary argument must be an array "\
+             "of strings. You passed #{attr_ary.inspect}."
+      end
     end
   end
 end

data/lib/chef/encrypted_attribute/remote_nodes.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)
@@ -23,26 +24,76 @@ require 'chef/encrypted_attribute/remote_clients'
 
 class Chef
   class EncryptedAttribute
+    # Helpers to search nodes remotely and get it's public keys.
     class RemoteNodes
       extend ::Chef::EncryptedAttribute::SearchHelper
 
+      # Remote nodes search results cache.
+      #
+      # You can disable it setting it's size to zero:
+      #
+      # ```ruby
+      # Chef::EncryptedAttribute::RemoteNodes.cache.max_size(0)
+      # ```
+      #
+      # @return [CacheLru] Remote nodes LRU cache.
       def self.cache
         @@cache ||= Chef::EncryptedAttribute::CacheLru.new
       end
 
-      def self.search_public_keys(search='*:*', partial_search=true)
-        escaped_query = escape_query(search)
-        if cache.has_key?(escaped_query)
-          cache[escaped_query]
-        else
-          cache[escaped_query] = search(:node, search, {
-            'name' => [ 'name' ]
-          }, 1000, partial_search).map do |node|
-            RemoteClients.get_public_key(node['name'])
-          end.compact
-        end
+      # Gets remote node public key.
+      #
+      # It first tries to read the key from the `node['public_key']` attribute.
+      #
+      # If the `"public_key"` attribute does not exist, it tries to read the
+      # node client key directly using the Chef API (this require **admin**
+      # privileges).
+      #
+      # @param node [Chef::Node] Chef node object.
+      # @return [String] Chef client public key as string.
+      # @raise [InsufficientPrivileges] if you lack enoght privileges to read
+      #   the keys from the Chef Server.
+      # @raise [ClientNotFound] if client does not exist.
+      # @raise [Net::HTTPServerException] for Chef Server HTTP errors.
+      def self.get_public_key(node)
+        return node['public_key'] unless node['public_key'].nil?
+        RemoteClients.get_public_key(node['name'])
+      rescue Net::HTTPServerException => e
+        raise e unless e.response.code == '403'
+        raise InsufficientPrivileges,
+              "You cannot read #{node['name']} client key. Consider including "\
+              'the encrypted_attributes::expose_key recipe in the '\
+              "#{node['name']} node run list."
       end
 
+      # Searches for node client public keys.
+      #
+      # It first tries to read the key from the `node['public_key']` attribute.
+      #
+      # If the `"public_key"` attribute does not exist, it tries to read the
+      # node client key directly using the Chef API (this require **admin**
+      # privileges).
+      #
+      # @param search [Array<String>, String] search queries to perform, the
+      #   query result will be *OR*-ed.
+      # @return [Array<String>] list of public keys.
+      # @raise [InsufficientPrivileges] if you lack enough privileges to read
+      #   the keys from the Chef Server.
+      # @raise [ClientNotFound] if client does not exist.
+      # @raise [Net::HTTPServerException] for Chef Server HTTP errors.
+      # @raise [SearchFailure] if there is a Chef search error.
+      # @raise [SearchFatalError] if the Chef search response is wrong.
+      # @raise [InvalidSearchKeys] if search keys structure is wrong.
+      def self.search_public_keys(search = '*:*', partial_search = true)
+        escaped_query = escape_query(search)
+        return cache[escaped_query] if cache.key?(escaped_query)
+        cache[escaped_query] =
+          search(
+            :node, search,
+            { 'name' => %w(name), 'public_key' => %w(public_key) },
+            1000, partial_search
+          ).map { |node| get_public_key(node) }.compact
+      end
     end
   end
 end

data/lib/chef/encrypted_attribute/remote_users.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)
@@ -22,52 +23,90 @@ require 'chef/encrypted_attribute/cache_lru'
 
 class Chef
   class EncryptedAttribute
+    # Helpers to get remote Chef Users keys.
+    #
+    # @note This class methods require **admin** privileges.
     class RemoteUsers
-
+      # Remote users public keys cache.
+      #
+      # You can disable it setting it's size to zero:
+      #
+      # ```ruby
+      # Chef::EncryptedAttribute::RemoteUsers.cache.max_size(0)
+      # ```
+      #
+      # @return [CacheLru] Remote users LRU cache.
       def self.cache
         @@cache ||= Chef::EncryptedAttribute::CacheLru.new
       end
 
-      def self.get_public_keys(users=[])
+      # Gets some Chef users public keys.
+      #
+      # @note This method requires **admin** privileges.
+      #
+      # @param users [Array<String>, '*'] user list. Use `'*'` to get all users
+      #   public keys.
+      # @return [Array<String>] public key list.
+      # @raise [ArgumentError] if user list is wrong.
+      def self.get_public_keys(users = [])
         if users == '*' # users are [a-z0-9\-_]+, cannot be *
-          if cache.has_key?('*')
-            cache['*']
-          else
-            cache['*'] = get_all_public_keys
-          end
-        elsif users.kind_of?(Array)
+          cache.key?('*') ? cache['*'] : cache['*'] = all_public_keys
+        elsif users.is_a?(Array)
           get_users_public_keys(users)
-        elsif not users.nil?
-          raise ArgumentError, "#{self.class.to_s}##{__method__} users argument must be an array or \"*\"."
+        elsif !users.nil?
+          fail ArgumentError,
+               "#{self.class}##{__method__} users argument must be an array "\
+               'or "*".'
         end
       end
 
-      protected
-
+      # Reads a Chef user public key.
+      #
+      # @note This method requires **admin** privileges.
+      #
+      # @param name [String] user name.
+      # @return [String] user public key as string.
+      # @raise [InsufficientPrivileges] if you lack enough privileges to read
+      #   the keys from the Chef Server.
+      # @api private
       def self.get_user_public_key(name)
-        return cache[name] if cache.has_key?(name)
+        return cache[name] if cache.key?(name)
         user = Chef::User.load(name)
         cache[name] = user.public_key
       rescue Net::HTTPServerException => e
         case e.response.code
         when '403'
-          raise InsufficientPrivileges, 'Your node needs admin privileges to be able to work with Chef Users.'
-        when '404' # Not Found
-          raise UserNotFound, "Chef User not found: \"#{name}\"."
+          raise InsufficientPrivileges,
+                'Your node needs admin privileges to be able to work with '\
+                'Chef Users.'
+        when '404' then raise UserNotFound, "Chef User not found: \"#{name}\"."
         else
           raise e
         end
       end
 
+      # Gets some Chef users public keys.
+      #
+      # @note This method requires **admin** privileges.
+      #
+      # @param users [Array<String>] user list.
+      # @return [Array<String>] public key list.
+      # @api private
       def self.get_users_public_keys(users)
         users.map { |n| get_user_public_key(n) }
       end
 
-      def self.get_all_public_keys
-        # Chef::User.list(inflate=true) has a bug
+      # Gets all Chef users public keys.
+      #
+      # @note This method requires **admin** privileges.
+      #
+      # @return [Array<String>] public key list.
+      # @api private
+      def self.all_public_keys
+        # Chef::User.list(inflate=true) has a bug (fixed in 11.14.0)
+        # https://tickets.opscode.com/browse/CHEF-5328
         get_users_public_keys(Chef::User.list.keys)
       end
-
     end
   end
 end