chef-encrypted-attributes 0.3.0 → 0.4.0

data/lib/chef/encrypted_attribute/encrypted_mash.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)
@@ -21,61 +22,125 @@ require 'chef/encrypted_attribute/exceptions'
 
 class Chef
   class EncryptedAttribute
+    # Mash structure with embedded Mash structure encrypted.
+    #
+    # This is the most basic encrypted object, which inherits from `Chef::Mash`.
+    #
+    # This class is used to construct the different EncryptedAttribute versions.
+    # Each version implements the encryption in a different way or using
+    # different algorithms.
+    #
+    # Currently three {EncryptedMash} versions exists. But you can create your
+    # own versions and name it with the
+    # `Chef::EncryptedAttribute::EncryptedMash::Version` prefix.
+    #
+    # Uses {EncryptedMash::Version1} by default.
+    #
+    # This class is oriented to be easily integrable with chef in the future
+    # using `JSONCompat`.
+    #
+    # @see .create
+    # @see EncryptedMash::Version0
+    # @see EncryptedMash::Version1
+    # @see EncryptedMash::Version2
     class EncryptedMash < Mash
-
-      # This class is oriented to be easily integrable with
-      # chef in the future using JSONCompat
-
+      # Mash key name to use for JSON class name. Chef uses the `'json_class'`
+      # key internally for objects, we use a renamed key.
       JSON_CLASS =      'x_json_class'.freeze
+
+      # Mash key name to use for Chef object type.
       CHEF_TYPE =       'chef_type'.freeze
-      CHEF_TYPE_VALUE = 'encrypted_attribute'.freeze
 
-      VERSION_PREFIX = "#{self.name}::Version"
+      # Chef object type value.
+      CHEF_TYPE_VALUE = 'encrypted_attribute'.freeze
 
-      def initialize(enc_hs=nil)
+      # Name prefix for all  EncryptedAttribute version classes.
+      # Used internally by the #self.version_class method.
+      # @api private
+      VERSION_PREFIX = "#{name}::Version"
+
+      # Encrypted Mash constructor.
+      #
+      # @param enc_hs [Mash] encrypted Mash to clone.
+      # @raise [UnacceptableEncryptedAttributeFormat] if encrypted attribute
+      #   format is wrong or does not exist.
+      def initialize(enc_hs = nil)
         super
         self[JSON_CLASS] = self.class.name
         self[CHEF_TYPE] = CHEF_TYPE_VALUE
-        update_from!(enc_hs) if enc_hs.kind_of?(Hash)
+        update_from!(enc_hs) if enc_hs.is_a?(Hash)
       end
 
-      %w{encrypt decrypt can_be_decrypted_by? needs_update?}.each do |meth|
+      %w(encrypt decrypt can_be_decrypted_by? needs_update?).each do |meth|
         define_method(meth) do
-          raise NotImplementedError, "#{self.class.to_s}##{__method__} method not implemented."
+          fail NotImplementedError,
+               "#{self.class}##{__method__} method not implemented."
         end
       end
 
+      # Checks whether an encrypted Mash exists.
+      #
+      # @param enc_hs [Mash] Mash to check.
+      # @return [Boolean] returns `true` if an encrypted Mash exists.
       def self.exist?(enc_hs)
-        enc_hs.kind_of?(Hash) and
-        enc_hs.has_key?(JSON_CLASS) and
-        enc_hs[JSON_CLASS] =~ /^#{Regexp.escape(Module.nesting[1].name)}/ and
-        enc_hs.has_key?(CHEF_TYPE) and enc_hs[CHEF_TYPE] == CHEF_TYPE_VALUE
+        enc_hs.is_a?(Hash) &&
+          enc_hs.key?(JSON_CLASS) &&
+          enc_hs[JSON_CLASS] =~ /^#{Regexp.escape(Module.nesting[1].name)}/ &&
+          enc_hs.key?(CHEF_TYPE) && enc_hs[CHEF_TYPE] == CHEF_TYPE_VALUE
       end
 
+      # Checks whether an encrypted Mash exists.
+      #
+      # @param args [Mash] {exist?} arguments.
+      # @return [Boolean] returns `true` if an encrypted Mash exists.
+      # @deprecated Use {exist?} instead.
       def self.exists?(*args)
-        Chef::Log.warn("#{self.name}.exists? is deprecated in favor of #{self.name}.exist?.")
+        Chef::Log.warn(
+          "#{name}.exists? is deprecated in favor of #{name}.exist?."
+        )
         exist?(*args)
       end
 
+      # Factory method to construct an encrypted Mash.
+      #
+      # @param version [String, Fixnum] EncryptedMash version to use.
+      # @raise [RequirementsFailure] if the specified encrypted attribute
+      #   version cannot be used.
+      # @raise [UnacceptableEncryptedAttributeFormat] if encrypted attribute
+      #   format is wrong.
+      # @raise [UnsupportedEncryptedAttributeFormat] if encrypted attribute
+      #   format is not supported or unknown.
       def self.create(version)
         klass = version_klass(version)
         klass.send(:new)
       end
 
-      # Serialize this object as a Hash
+      # Serializes this object as a Hash.
+      #
+      # @param a [Hash] Ruby _#to_json_ call arguments.
+      # @return [String] JSON representation of the object.
       def to_json(*a)
         for_json.to_json(*a)
       end
 
-      # Returns a Hash for JSON
+      # Returns the object as a Ruby Hash.
+      #
+      # @return [Hash] ruby Hash represtation of the object.
       def for_json
         to_hash
       end
 
-      # Update the EncryptedMash from Hash
+      # Replaces the EncryptedMash content from a Mash.
+      #
+      # @param enc_hs [Mash] Mash to clone.
+      # @return [Mash] `self`.
+      # @raise [UnacceptableEncryptedAttributeFormat] if encrypted attribute
+      #   format is wrong or does not exist.
       def update_from!(enc_hs)
         unless self.class.exist?(enc_hs)
-          raise UnacceptableEncryptedAttributeFormat, 'Trying to construct invalid encrypted attribute. Maybe it is not encrypted?'
+          fail UnacceptableEncryptedAttributeFormat,
+               'Trying to construct invalid encrypted attribute. Maybe it is '\
+               'not encrypted?'
         end
         enc_hs = enc_hs.dup
         enc_hs.delete(JSON_CLASS)
@@ -83,26 +148,41 @@ class Chef
         update(enc_hs)
       end
 
-      # Create an EncryptedMash::Version from JSON Hash
+      # Creates an *EncryptedMash::Version* object from a JSON Hash.
+      #
+      # Reads the EncryptedMash version to create from the {JSON_CLASS} key.
+      #
+      # @param enc_hs [Mash] Encrypted Mash as a Mash. As it is read from node
+      #   attributes.
+      # @return [EncryptedMash] *EncryptedMash::Version* object.
+      # @raise [UnacceptableEncryptedAttributeFormat] if encrypted attribute
+      #   format is wrong.
+      # @raise [UnsupportedEncryptedAttributeFormat] if encrypted attribute
+      #   format is not supported or unknown.
       def self.json_create(enc_hs)
         klass = string_to_klass(enc_hs[JSON_CLASS])
         if klass.nil?
-          raise UnsupportedEncryptedAttributeFormat, "Unknown chef-encrypted-attribute class \"#{enc_hs[JSON_CLASS]}\""
+          fail UnsupportedEncryptedAttributeFormat,
+               "Unknown chef-encrypted-attribute class #{enc_hs[JSON_CLASS]}"
         end
         klass.send(:new, enc_hs)
       end
 
-      protected
-
+      # Gets the class reference from its string representation.
+      #
+      # @param class_name [String] the class name as string.
+      # @return [Class] the class reference.
+      # @raise [UnacceptableEncryptedAttributeFormat] if encrypted attribute
+      #   class name is wrong.
+      # @api private
       def self.string_to_klass(class_name)
-        unless class_name.kind_of?(String)
-          raise UnacceptableEncryptedAttributeFormat, "Bad chef-encrypted-attribute class name \"#{class_name.inspect}\""
+        unless class_name.is_a?(String)
+          fail UnacceptableEncryptedAttributeFormat,
+               "Bad chef-encrypted-attribute class name #{class_name.inspect}"
         end
         begin
-          if RUBY_VERSION < '1.9'
-            class_name.split('::').inject(Kernel) { |scope, const| scope.const_get(const) }
-          else
-            class_name.split('::').inject(Kernel) { |scope, const| scope.const_get(const, scope === Kernel) }
+          class_name.split('::').inject(Kernel) do |scope, const|
+            scope.const_get(const, scope == Kernel)
           end
         rescue NameError => e
           Chef::Log.error(e)
@@ -110,18 +190,32 @@ class Chef
         end
       end
 
+      # Gets the class reference for a EncryptedMash version.
+      #
+      # The implementation of `"Chef::EncryptedAttribute::Version#{version}"`
+      # must exists and be included (`require`) beforehand.
+      #
+      # @param version [String, Fixnum] the EncryptedMash version.
+      # @return [Class] the EncryptedMash version class reference.
+      # @raise [UnacceptableEncryptedAttributeFormat] if encrypted attribute
+      #   version is wrong.
+      # @raise [UnsupportedEncryptedAttributeFormat] if encrypted attribute
+      #   format is not supported or unknown.
+      # @api private
       def self.version_klass(version)
-        version = version.to_s unless version.kind_of?(String)
+        version = version.to_s unless version.is_a?(String)
         if version.empty?
-          raise UnacceptableEncryptedAttributeFormat, "Bad chef-encrypted-attribute version \"#{version.inspect}\""
+          fail UnacceptableEncryptedAttributeFormat,
+               "Bad chef-encrypted-attribute version #{version.inspect}"
         end
         klass = string_to_klass("#{VERSION_PREFIX}#{version}")
         if klass.nil?
-          raise UnsupportedEncryptedAttributeFormat, "This version of chef-encrypted-attribute does not support encrypted attribute item format version: \"#{version}\""
+          fail UnsupportedEncryptedAttributeFormat,
+               'This version of chef-encrypted-attribute does not support '\
+               "encrypted attribute item format version: \"#{version}\""
         end
         klass
       end
-
     end
   end
 end

data/lib/chef/encrypted_attribute/encrypted_mash/version0.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,67 @@
 
 require 'chef/encrypted_attribute/encrypted_mash'
 require 'chef/encrypted_attribute/exceptions'
-require 'yajl'
+require 'ffi_yajl'
 
-# Version0 format: using RSA without shared secret
 class Chef
   class EncryptedAttribute
     class EncryptedMash
+      # EncryptedMash Version0 format: using RSA without shared secret.
+      #
+      # This is the first version, considered old. Uses public key cryptography
+      # (PKI) to encrypt the data. There is no shared secret or HMAC for data
+      # integrity checking.
+      #
+      # # `EncryptedMash::Version0` Structure
+      #
+      # If you try to read this encrypted attribute structure, you can see a
+      # `Chef::Mash` attribute with the following content:
+      #
+      # ```
+      # EncryptedMash
+      # └── encrypted_data
+      #     ├── pub_key_hash1: The data encrypted using PKI for the public key 1
+      #     │     (base64)
+      #     ├── pub_key_hash2: The data encrypted using PKI for the public key 2
+      #     │     (base64)
+      #     └── ...
+      # ```
+      #
+      # The `public_key_hash1` key value is the *SHA1* of the public key used
+      # for encryption.
+      #
+      # Its content is the data encoded in *JSON*, then encrypted with the
+      # public key, and finally encoded in *base64*. The encryption is done
+      # using the *RSA* algorithm (PKI).
+      #
+      # @see EncryptedMash
       class Version0 < Chef::EncryptedAttribute::EncryptedMash
-
+        # Encrypts data inside the current {EncryptedMash} object.
+        #
+        # @param value [Mixed] value to encrypt, will be converted to JSON.
+        # @param public_keys [Array<String, OpenSSL::PKey::RSA>] publics keys
+        #   that will be able to decrypt the {EncryptedMash}.
+        # @return [EncryptedMash] the value encrypted.
+        # @raise [EncryptionFailure] if there are encryption errors.
+        # @raise [InvalidPublicKey] if it is not a valid RSA public key.
+        # @raise [InvalidKey] if the RSA key format is wrong.
         def encrypt(value, public_keys)
           value_json = json_encode(value)
           public_keys = parse_public_keys(public_keys)
-          self['encrypted_data'] = rsa_encrypt_multi_key(value_json, public_keys)
+          self['encrypted_data'] =
+            rsa_encrypt_multi_key(value_json, public_keys)
           self
         end
 
+        # Decrypts the current {EncryptedMash} object.
+        #
+        # @param key [String, OpenSSL::PKey::RSA] RSA private key used to
+        #   decrypt.
+        # @return [Mixed] the value decrypted.
+        # @raise [DecryptionFailure] if the data cannot be decrypted by the
+        #   provided key.
+        # @raise [InvalidPublicKey] if it is not a valid RSA public key.
+        # @raise [InvalidKey] if the RSA key format is wrong.
         def decrypt(key)
           key = parse_decryption_key(key)
           value_json = rsa_decrypt_multi_key(self['encrypted_data'], key)
@@ -40,120 +87,261 @@ class Chef
           # we avoid saving the decrypted value, only return it
         end
 
+        # Checks if the current {EncryptedMash} can be decrypted by all of the
+        # provided keys.
+        #
+        # @param keys [Array<OpenSSL::PKey::RSA>] list of public keys.
+        # @return [Boolean] `true` if all keys can decrypt the data.
+        # @raise [InvalidPublicKey] if it is not a valid RSA public key.
+        # @raise [InvalidKey] if the RSA key format is wrong.
         def can_be_decrypted_by?(keys)
           return false unless encrypted?
-          parse_public_keys(keys).reduce(true) do |r, k|
-            r and data_can_be_decrypted_by_key?(self['encrypted_data'], k)
-          end
+          data_can_be_decrypted_by_keys?(self['encrypted_data'], keys)
         end
 
+        # Checks if the current {EncryptedMash} needs to be re-encrypted.
+        #
+        # This usually happends when new keys are provided or some keys are
+        # removed from the previous encryption process.
+        #
+        # In other words, this method checks all key can decrypt the data and
+        # only those keys.
+        #
+        # @param keys [Array<String, OpenSSL::PKey::RSA>] list of RSA public
+        #   keys.
+        # @return [Boolean] `true` if all keys can decrypt the data and only
+        #   those keys can decrypt the data.
+        # @raise [InvalidPublicKey] if it is not a valid RSA public key.
+        # @raise [InvalidKey] if the RSA key format is wrong.
         def needs_update?(keys)
           keys = parse_public_keys(keys)
-          not can_be_decrypted_by?(keys) && self['encrypted_data'].keys.count == keys.count
+          !can_be_decrypted_by?(keys) ||
+            self['encrypted_data'].keys.count != keys.count
         end
 
         protected
 
+        # Checks if encrypted data exists in the current Mash.
+        #
+        # @return [Boolean] `true` if there is encrypted data.
         def encrypted?
-          has_key?('encrypted_data') and self['encrypted_data'].kind_of?(Hash)
+          key?('encrypted_data') && self['encrypted_data'].is_a?(Hash)
         end
 
+        # Converts the RSA key to an `OpenSSL::PKey::RSA` object.
+        #
+        # @param k [String, OpenSSL::PKey::RSA] RSA key to convert.
+        # @return [OpenSSL::PKey::RSA] RSA key.
+        # @raise [InvalidKey] if the RSA key format is wrong.
         def pem_to_key(k)
-          k.kind_of?(OpenSSL::PKey::RSA) ? k : OpenSSL::PKey::RSA.new(k)
-        rescue OpenSSL::PKey::RSAError, TypeError => e
-          raise InvalidPrivateKey, "The provided key is invalid: #{k.inspect}"
+          k.is_a?(OpenSSL::PKey::RSA) ? k : OpenSSL::PKey::RSA.new(k)
+        rescue OpenSSL::PKey::RSAError, TypeError
+          raise InvalidKey, "The provided key is invalid: #{k.inspect}"
         end
 
+        # Parses a RSA public key used for encryption.
+        #
+        # @param key [String, OpenSSL::PKey::RSA] RSA key to parse.
+        # @return [OpenSSL::PKey::RSA] RSA public key.
+        # @raise [InvalidPublicKey] if it is not a valid RSA public key.
+        # @raise [InvalidKey] if the RSA key format is wrong.
         def parse_public_key(key)
           key = pem_to_key(key)
           unless key.public?
-            raise InvalidPublicKey, 'Invalid public key provided.'
+            fail InvalidPublicKey, 'Invalid public key provided.'
           end
           key
         end
 
+        # Parses a RSA key used for decryption. Must contain both the public
+        # and the private key. It also checks that the current {EncryptedMash}
+        # object can be decrypted by the provided key.
+        #
+        # @param key [String, OpenSSL::PKey::RSA] RSA key to parse.
+        # @return [OpenSSL::PKey::RSA] RSA key.
+        # @raise [DecryptionFailure] if the data cannot be decrypted by the
+        #   provided key.
+        # @raise [InvalidPublicKey] if it is not a valid RSA public key.
+        # @raise [InvalidKey] if the RSA key format is wrong.
         def parse_decryption_key(key)
           key = pem_to_key(key)
-          unless key.public? and key.private?
-            raise InvalidPrivateKey, 'The provided key for decryption is invalid, a valid public and private key is required.'
+          unless key.public? && key.private?
+            fail InvalidKey,
+                 'The provided key for decryption is invalid, a valid public '\
+                 'and private key is required.'
           end
-          unless can_be_decrypted_by?(key) # TODO optimize, node key digest is calculated multiple times
-            raise DecryptionFailure, 'Attribute data cannot be decrypted by the provided key.'
+          # TODO: optimize, node key digest is calculated multiple times
+          unless can_be_decrypted_by?(key)
+            fail DecryptionFailure,
+                 'Attribute data cannot be decrypted by the provided key.'
           end
           key
         end
 
+        # Parses a list of RSA public keys, used for encryption.
+        #
+        # @param keys [Array<String, OpenSSL::PKey::RSA>] list of keys.
+        # @return [Array<OpenSSL::PKey::RSA>] list of keys parsed.
+        # @raise [InvalidPublicKey] if it is not a valid RSA public key.
+        # @raise [InvalidKey] if the RSA key format is wrong.
         def parse_public_keys(keys)
-          keys = [ keys ].flatten
-          keys.map do |k|
-            parse_public_key(k)
-          end.uniq { |k| k.public_key.to_s.chomp }
+          keys = [keys].flatten
+          keys_parsed = keys.map { |k| parse_public_key(k) }
+          keys_parsed.uniq { |k| k.public_key.to_s.chomp }
         end
 
+        # Converts an object to its JSON representation.
+        #
+        # @param o [Mixed] object to convert.
+        # @return [String] JSON object as string.
         def json_encode(o)
-          # TODO This does not check if the object is correct, should be an Array or a Hash
-          Yajl::Encoder.encode(o)
+          # TODO: This does not check if the object is correct, should be an
+          # Array or a Hash
+          FFI_Yajl::Encoder.encode(o)
         end
 
+        # Decodes a JSON string.
+        #
+        # @param o [String] JSON string to decode.
+        # @return [Mixed] Ruby representation of the JSON string.
+        # @raise [DecryptionFailure] if JSON string format is wrong.
         def json_decode(o)
-          Yajl::Parser.parse(o.to_s)
-        rescue Yajl::ParseError => e
-          raise DecryptionFailure, "#{e.class.name}: #{e.to_s}"
+          FFI_Yajl::Parser.parse(o.to_s)
+        rescue FFI_Yajl::ParseError => e
+          raise DecryptionFailure, "#{e.class.name}: #{e}"
+        end
+
+        # Encodes Ruby `< 1.9.3` RSA key using X.509 format.
+        #
+        # In Ruby `< 1.9.3` RSA keys are in [PKCS#1]
+        # (http://en.wikipedia.org/wiki/PKCS_1) format.
+        #
+        # In Ruby `>= 1.9.3` RSA keys are in [X.509]
+        # (http://en.wikipedia.org/wiki/X.509) format (private keys in [PKCS#8]
+        # (http://en.wikipedia.org/wiki/PKCS_8)).
+        #
+        # @param rsa [OpenSSL::PKey::RSA] RSA key.
+        # @return [OpenSSL::ASN1::Sequence] RSA key in X.509 format.
+        # @note Heavily based on @sl4m code:
+        #   https://gist.github.com/sl4m/1470360
+        def rsa_ensure_x509_ruby192(rsa)
+          modulus = rsa.n
+          exponent = rsa.e
+
+          asn1 = OpenSSL::ASN1
+          oid = asn1::ObjectId.new('rsaEncryption')
+          alg_id = asn1::Sequence.new([oid, asn1::Null.new(nil)])
+          ary = [asn1::Integer.new(modulus), asn1::Integer.new(exponent)]
+          pub_key = asn1::Sequence.new(ary)
+          enc_pk = asn1::BitString.new(pub_key.to_der)
+          asn1::Sequence.new([alg_id, enc_pk])
         end
 
-        # Heavily based on @sl4m code: https://gist.github.com/sl4m/1470360
+        # Returns any RSA key in X.509 format.
+        #
+        # Fixes RSA key format in Ruby `< 1.9.3`.
+        #
+        # @param rsa [OpenSSL::PKey::RSA] RSA key.
+        # @return [OpenSSL::ASN1::Sequence] RSA key in X.509 format.
+        # @see #rsa_ensure_x509_ruby192
         def rsa_ensure_x509(rsa)
-          if RUBY_VERSION < '1.9.3'
-            modulus = rsa.n
-            exponent = rsa.e
-
-            oid = OpenSSL::ASN1::ObjectId.new('rsaEncryption')
-            alg_id = OpenSSL::ASN1::Sequence.new([oid, OpenSSL::ASN1::Null.new(nil)])
-            ary = [OpenSSL::ASN1::Integer.new(modulus), OpenSSL::ASN1::Integer.new(exponent)]
-            pub_key = OpenSSL::ASN1::Sequence.new(ary)
-            enc_pk = OpenSSL::ASN1::BitString.new(pub_key.to_der)
-            subject_pk_info = OpenSSL::ASN1::Sequence.new([alg_id, enc_pk])
-          else
-            rsa
-          end
+          RUBY_VERSION < '1.9.3' ? rsa_ensure_x509_ruby192(rsa) : rsa
         end
 
+        # Gets the hash key to use for saving the encrypted data for a node.
+        #
+        # It uses a SHA1 hexadecimal digest of the public key as key.
+        #
+        # @param public_key [OpenSSL::PKey::RSA] RSA public key.
+        # @return [String] hash key for the public key.
         def node_key(public_key)
           Digest::SHA1.hexdigest(rsa_ensure_x509(public_key).to_der)
         end
 
+        # Encrypts a value using a RSA public key.
+        #
+        # @param value [String] data to encrypt.
+        # @param public_key [OpenSSL::PKey::RSA] public key used for encryption.
+        # @return [String] data encrypted in its Base64 representation.
+        # @raise [EncryptionFailure] if there are encryption errors.
         def rsa_encrypt_value(value, public_key)
           Base64.encode64(public_key.public_encrypt(value))
         rescue OpenSSL::PKey::RSAError => e
-          raise EncryptionFailure, "#{e.class.name}: #{e.to_s}"
+          raise EncryptionFailure, "#{e.class.name}: #{e}"
         end
 
+        # Decrypts a value using a RSA private key.
+        #
+        # @param value [String] encrypted data to decrypt in its Base64
+        #   representation.
+        # @param key [OpenSSL::PKey::RSA] private key used for decryption.
+        # @return [String] value decrypted.
+        # @raise [DecryptionFailure] if there are decryption errors.
         def rsa_decrypt_value(value, key)
           key.private_decrypt(Base64.decode64(value.to_s))
         rescue OpenSSL::PKey::RSAError => e
-          raise DecryptionFailure, "#{e.class.name}: #{e.to_s}"
+          raise DecryptionFailure, "#{e.class.name}: #{e}"
         end
 
+        # Returns data encrypted for multiple keys using RSA.
+        #
+        # Returns a `Mash` with the following structure:
+        # * Hash keys: hexadecimal SHA1 of the public key.
+        # * Hash values: RSA encrypted data and then converted to Base64.
+        #
+        # @param value [String] data to encrypt.
+        # @param public_keys [Array<OpenSSL::PKey::RSA>] public keys list.
+        # @return [Mash] data encrypted.
+        # @raise [EncryptionFailure] if there are encryption errors.
+        # @see #node_key
+        # @see #rsa_encrypt_value
         def rsa_encrypt_multi_key(value, public_keys)
           Mash.new(Hash[
             public_keys.map do |public_key|
-              [
-                node_key(public_key),
-                rsa_encrypt_value(value, public_key),
-              ]
+              [node_key(public_key), rsa_encrypt_value(value, public_key)]
             end
-          ])
+         ])
         end
 
+        # Decrypts RSA value from a data structure encrypted for multiple keys.
+        #
+        # @param enc_value [Mash] encrypted data structure.
+        # @param key [OpenSSL::PKey::RSA] RSA key to use (public and private key
+        #   is required).
+        # @return [String] data decrypted.
+        # @see #rsa_decrypt_value
         def rsa_decrypt_multi_key(enc_value, key)
           enc_value = enc_value[node_key(key.public_key)]
           rsa_decrypt_value(enc_value, key)
         end
 
+        # Checks if data can be decrypted by the provided key. Where data is
+        # encrypted for multiple keys.
+        #
+        # This method is not immune to any kind of data corruption. Only checks
+        # that the data seems to be decipherable by the key. No MAC checking.
+        #
+        # @param enc_value [Mash] encrypted data structure.
+        # @param key [OpenSSL::PKey::RSA] RSA key.
+        # @return [Boolean] `true` if the data can be decrypted.
+        # @see #rsa_encrypt_multi_key
         def data_can_be_decrypted_by_key?(enc_value, key)
-          enc_value.has_key?(node_key(key.public_key))
+          enc_value.key?(node_key(key.public_key))
         end
 
+        # Checks if the data can be decrypted by all of the provided keys.
+        #
+        # @param data [Mash] encrypted data to check. This usually refers to
+        #   `self['encrypted_data']`.
+        # @param keys [Array<OpenSSL::PKey::RSA>] list of public keys.
+        # @return [Boolean] `true` if all keys can decrypt the data.
+        # @raise [InvalidPublicKey] if it is not a valid RSA public key.
+        # @raise [InvalidKey] if the RSA key format is wrong.
+        def data_can_be_decrypted_by_keys?(data, keys)
+          parse_public_keys(keys).reduce(true) do |r, k|
+            r && data_can_be_decrypted_by_key?(data, k)
+          end
+        end
       end
     end
   end