chef-encrypted-attributes 0.3.0 → 0.4.0

data/lib/chef/encrypted_attribute/encrypted_mash/version1.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)
@@ -19,122 +20,334 @@
 require 'chef/encrypted_attribute/encrypted_mash/version0'
 require 'chef/encrypted_attribute/exceptions'
 
-# Version1 format: using RSA with a shared secret and message authentication (HMAC)
 class Chef
   class EncryptedAttribute
     class EncryptedMash
+      # EncryptedMash Version1 format: using RSA with a shared secret and
+      # message authentication (HMAC).
+      #
+      # This is the {EncryptedMash} version used by default. Uses public key
+      # cryptography (PKI) to encrypt a shared secret. Then this shared secret
+      # is used to encrypt the data.
+      #
+      # * This implementation can be improved, is not optimized either for
+      #   performance or for space.
+      # * Every time the `EncryptedAttribute` is updated, all the shared secrets
+      #   are regenerated.
+      #
+      # # `EncryptedMash::Version1` Structure
+      #
+      # If you try to read this encrypted attribute structure, you can see a
+      # `Mash` attribute with the following content:
+      #
+      # ```
+      # EncryptedMash
+      # ├── chef_type: "encrypted_attribute" (string).
+      # ├── x_json_class: The used `EncryptedMash` version class name (string).
+      # ├── encrypted_data
+      # │   ├── cipher: The used PKI algorithm, "aes-256-cbc" (string).
+      # │   ├── data: PKI encrypted data (base64).
+      # │   └── iv: Initialization vector (in base64).
+      # ├── encrypted_secret
+      # │   ├── pub_key_hash1: The shared secrets encrypted for the public key 1
+      # │   │     (base64).
+      # │   ├── pub_key_hash2: The shared secrets encrypted for the public key 2
+      # │   │     (base64).
+      # │   └── ...
+      # └── hmac
+      #     ├── cipher: The used HMAC algorithm, currently ignored and always
+      #     │     "sha256" (string).
+      #     └── data: Hash-based message authentication code value (base64).
+      # ```
+      #
+      # * `x_json_class` field is used, with the `x_` prefix, to be easily
+      #   integrated with Chef in the future.
+      #
+      # ## `EncryptedMash[encrypted_data][data]`
+      #
+      # The data inside `encrypted_data` is symmetrically encrypted using the
+      # secret shared key. The data is converted to *JSON* before the
+      # encryption, then encrypted and finally encoded in *base64*. By default,
+      # the `'aes-256-cbc'` algorithm is used for encryption.
+      #
+      # After decryption, the *JSON* has the following structure:
+      #
+      # ```
+      # └── encrypted_data
+      #     └── data (symmetrically encrypted JSON in base64)
+      #         └── content: attribute content as a Mash.
+      # ```
+      #
+      # * In the future, this structure may contain some metadata like default
+      #   configuration values.
+      #
+      # ## `EncryptedMash[encrypted_secret][pub_key_hash1]`
+      #
+      # The `public_key_hash1` key value is the *SHA1* of the public key used
+      # for encryption.
+      #
+      # Its content is the encrypted shared secrets in *base64*. The encryption
+      # is done using the *RSA* algorithm (PKI).
+      #
+      # After decryption, you find the following structure in *JSON*:
+      #
+      # ```
+      # └── encrypted_secret
+      #     └── pub_key_hash1 (PKI encrypted JSON in base64)
+      #         ├── data: The shared secret used to encrypt the data (base64).
+      #         └── hmac: The shared secret used for the HMAC calculation
+      #               (base64).
+      # ```
+      #
+      # ## `EncryptedMash[hmac][data]`
+      #
+      # The HMAC data is in *base64*. The hashing algorithm used is `'sha256'`.
+      #
+      # The following data is used in a alphabetically sorted *JSON* to
+      # calculate the HMAC:
+      #
+      # ```
+      # Data to calculate the HMAC from
+      # ├── cipher: The algorithm used for `encrypted_data` encryption
+      # │     ("aes-256-cbc").
+      # ├── data: The `encrypted_data` data content after the encryption
+      # │     (encrypt-then-mac).
+      # └── iv: The initialization vector used to encrypt the encrypted_data.
+      # ```
+      #
+      # * All the data required for decryption is included in the HMAC (except
+      #   the secret key, of course): `cipher`, `data` and `iv`.
+      # * The data used to calculate the HMAC is the encrypted data, not the
+      #   clear text data (**Encrypt-then-MAC**).
+      # * The secret used to calculate the HMAC is not the same as the secret
+      #   used to encrypt the data.
+      # * The secret used to calculate the HMAC is shared inside
+      #   `encrypted_secret` field with the data secret.
+      #
+      # @see EncryptedMash
       class Version1 < Chef::EncryptedAttribute::EncryptedMash::Version0
+        # Symmetric algorithm to use by default.
         SYMM_ALGORITHM = 'aes-256-cbc'
+        # Algorithm used for HMAC calculation.
         HMAC_ALGORITHM = 'sha256'
 
+        # (see EncryptedMash::Version0#encrypt)
+        # @raise [MessageAuthenticationFailure] if HMAC calculation error.
         def encrypt(value, public_keys)
           secrets = {}
           value_json = json_encode(value)
           public_keys = parse_public_keys(public_keys)
           # encrypt the data
           encrypted_data = symmetric_encrypt_value(value_json)
-          secrets['data'] = encrypted_data.delete('secret') # should no include the secret in clear
+          # should no include the secret in clear
+          secrets['data'] = encrypted_data.delete('secret')
           self['encrypted_data'] = encrypted_data
           # generate hmac (encrypt-then-mac), excluding the secret
           hmac = generate_hmac(json_encode(self['encrypted_data'].sort))
           secrets['hmac'] = hmac.delete('secret')
           self['hmac'] = hmac
           # encrypt the shared secrets
-          self['encrypted_secret'] = rsa_encrypt_multi_key(json_encode(secrets), public_keys)
+          self['encrypted_secret'] =
+            rsa_encrypt_multi_key(json_encode(secrets), public_keys)
           self
         end
 
+        # (see EncryptedMash::Version0#decrypt)
+        # @raise [MessageAuthenticationFailure] if HMAC calculation error.
         def decrypt(key)
           key = parse_decryption_key(key)
           enc_value = self['encrypted_data'].dup
           hmac = self['hmac'].dup
           # decrypt the shared secrets
-          secrets = json_decode(rsa_decrypt_multi_key(self['encrypted_secret'], key))
+          secrets =
+            json_decode(rsa_decrypt_multi_key(self['encrypted_secret'], key))
           enc_value['secret'] = secrets['data']
           hmac['secret'] = secrets['hmac']
           # check hmac (encrypt-then-mac -> mac-then-decrypt)
           unless hmac_matches?(hmac, json_encode(self['encrypted_data'].sort))
-            raise DecryptionFailure, 'Error decrypting encrypted attribute: invalid hmac. Most likely the data is corrupted.'
+            fail DecryptionFailure,
+                 'Error decrypting encrypted attribute: invalid hmac. Most '\
+                 'likely the data is corrupted.'
           end
           # decrypt the data
           value_json = symmetric_decrypt_value(enc_value)
           json_decode(value_json)
         end
 
+        # (see EncryptedMash::Version0#can_be_decrypted_by?)
         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_secret'], k)
-          end
+          data_can_be_decrypted_by_keys?(self['encrypted_secret'], keys)
         end
 
+        # (see EncryptedMash::Version0#needs_update?)
         def needs_update?(keys)
           keys = parse_public_keys(keys)
-          not can_be_decrypted_by?(keys) && self['encrypted_secret'].keys.count == keys.count
+          !can_be_decrypted_by?(keys) ||
+            self['encrypted_secret'].keys.count != keys.count
         end
 
         protected
 
+        # Checks if the encrypted data Mash contains all the fields an has the
+        # correct type.
+        #
+        # Checks the `self['encrypted_data']` structure.
+        #
+        # @param [Hash<Symbol, Class>] fields to check. For example:
+        #   `{ iv: String, data: String }`.
+        # @return [Boolean] `true` if all the fields are exists.
+        def encrypted_data_contain_fields?(fields)
+          data = self['encrypted_data']
+          fields.reduce(true) do |r, (field, kind_of)|
+            r && data.key?(field) && data[field].is_a?(kind_of)
+          end
+        end
+
+        # Checks if the encrypted data structure is correct.
+        #
+        # Checks the `self['encrypted_data']` structure.
+        #
+        # @return [Boolean] `true` if it is correct.
+        def encrypted_data?
+          encrypted_data_contain_fields?(iv: String, data: String)
+        end
+
+        # Checks if the encrypted secrets structure is correct.
+        #
+        # Checks the `self['encrypted_secret']` structure.
+        #
+        # @return [Boolean] `true` if it is correct.
+        def encrypted_secret?
+          self['encrypted_secret'].is_a?(Hash)
+        end
+
+        # Checks if the HMAC structure is correct.
+        #
+        # Checks the `self['hmac']` structure.
+        #
+        # @return [Boolean] `true` if it is correct.
+        def encrypted_hmac?
+          self['hmac'].is_a?(Hash) &&
+            self['hmac'].key?('data') &&
+            self['hmac']['data'].is_a?(String)
+        end
+
+        # (see EncryptedMash::Version0#encrypted?)
         def encrypted?
-          super and
-          self['encrypted_data'].has_key?('iv') and
-          self['encrypted_data']['iv'].kind_of?(String) and
-          self['encrypted_data'].has_key?('data') and
-          self['encrypted_data']['data'].kind_of?(String) and
-          self['encrypted_secret'].kind_of?(Hash) and
-          self['hmac'].kind_of?(Hash) and
-          self['hmac'].has_key?('data') and
-          self['hmac']['data'].kind_of?(String)
+          super &&
+            encrypted_data? &&
+            encrypted_secret? &&
+            encrypted_hmac?
         end
 
-        def symmetric_encrypt_value(value, algo=SYMM_ALGORITHM)
-          enc_value = Mash.new({ 'cipher' => algo })
+        # Encrypts a value using a symmetric cryptographic algorithm.
+        #
+        # Uses a randomly generated secret and IV.
+        #
+        # @param value [String] data to encrypt.
+        # @param algo [String] symmetric algorithm to use.
+        # @return [Mash] hash structure with symmetrically encrypted data:
+        #   * `['cipher']`: algorithm used.
+        #   * `['secret']`: random secret used for encryption in Base64.
+        #   * `['iv']`: random initialization vector in Base64.
+        #   * `['data']`: data encrypted and in Base64.
+        # @raise [EncryptionFailure] if encryption error.
+        def symmetric_encrypt_value(value, algo = SYMM_ALGORITHM)
+          enc_value = Mash.new('cipher' => algo)
           begin
             cipher = OpenSSL::Cipher.new(algo)
             cipher.encrypt
-            enc_value['secret'] = Base64.encode64(cipher.key = cipher.random_key)
+            enc_value['secret'] =
+              Base64.encode64(cipher.key = cipher.random_key)
             enc_value['iv'] = Base64.encode64(cipher.iv = cipher.random_iv)
             enc_data = cipher.update(value) + cipher.final
           rescue OpenSSL::Cipher::CipherError => e
-            raise EncryptionFailure, "#{e.class.name}: #{e.to_s}"
+            raise EncryptionFailure, "#{e.class.name}: #{e}"
           end
           enc_value['data'] = Base64.encode64(enc_data)
           enc_value
         end
 
-        def symmetric_decrypt_value(enc_value, algo=SYMM_ALGORITHM)
-          cipher = OpenSSL::Cipher.new(enc_value['cipher'] || algo) # TODO maybe it's better to ignore [cipher] ?
+        # Decrypts data using a symmetric cryptographic algorithm.
+        #
+        # @param enc_value [Mash] hash structure with encrypted data:
+        #   * `['cipher']`: algorithm used.
+        #   * `['secret']`: secret used for encryption in Base64.
+        #   * `['iv']`: initialization vector in Base64.
+        #   * `['data']`: data encrypted in Base64.
+        # @param algo [String] symmetric algorithm to use.
+        # @raise [DecryptionFailure] if decryption error.
+        # @see #symmetric_encrypt_value
+        def symmetric_decrypt_value(enc_value, algo = SYMM_ALGORITHM)
+          # TODO: maybe it's better to ignore [cipher] ?
+          cipher = OpenSSL::Cipher.new(enc_value['cipher'] || algo)
           cipher.decrypt
           # We must set key before iv: https://bugs.ruby-lang.org/issues/8221
           cipher.key = Base64.decode64(enc_value['secret'])
           cipher.iv = Base64.decode64(enc_value['iv'])
           cipher.update(Base64.decode64(enc_value['data'])) + cipher.final
         rescue OpenSSL::Cipher::CipherError => e
-          raise DecryptionFailure, "#{e.class.name}: #{e.to_s}"
+          raise DecryptionFailure, "#{e.class.name}: #{e}"
         end
 
-        def generate_hmac(data, algo=HMAC_ALGORITHM)
-          hmac = Mash.new({ 'cipher' => algo }) # [cipher] is ignored, only as info
+        # Exception list raised by the HMAC calculation process.
+        #
+        # `RuntimeError` is raised for unsupported algorithms.
+        #
+        # @api private
+        HMAC_EXCEPTIONS =
+          [OpenSSL::Digest::DigestError, OpenSSL::HMACError, RuntimeError]
+
+        # Calculates [HMAC]
+        # (http://en.wikipedia.org/wiki/Hash-based_message_authentication_code)
+        # value for data.
+        #
+        # Uses a randomly generated secret for the HMAC calculation.
+        #
+        # @param data [String] data to calculate HMAC for.
+        # @param algo [String] HMAC algorithm to use.
+        # @return [Mash] hash structure with HMAC data:
+        #   * `['cipher']`: algorithm used.
+        #   * `['secret']` random secret used for HMAC calculation in Base64.
+        #   * `['data']` HMAC value in Base64.
+        # @raise [MessageAuthenticationFailure] if HMAC calculation error.
+        def generate_hmac(data, algo = HMAC_ALGORITHM)
+          # [cipher] is ignored, only as info
+          hmac = Mash.new('cipher' => algo)
           digest = OpenSSL::Digest.new(algo)
           secret = OpenSSL::Random.random_bytes(digest.block_length)
           hmac['secret'] = Base64.encode64(secret)
-          hmac['data'] = Base64.encode64(OpenSSL::HMAC.digest(digest, secret, data))
+          hmac['data'] =
+            Base64.encode64(OpenSSL::HMAC.digest(digest, secret, data))
           hmac
-        rescue OpenSSL::Digest::DigestError, OpenSSL::HMACError, RuntimeError => e
-          # RuntimeError is raised for unsupported algorithms
-          raise MessageAuthenticationFailure, "#{e.class.name}: #{e.to_s}"
+        rescue *HMAC_EXCEPTIONS => e
+          raise MessageAuthenticationFailure, "#{e.class}: #{e}"
         end
 
-        def hmac_matches?(orig_hmac, data, algo=HMAC_ALGORITHM)
+        # Checks if the [HMAC]
+        # (http://en.wikipedia.org/wiki/Hash-based_message_authentication_code)
+        # matches
+        #
+        # Uses a randomly generated secret for the HMAC calculation.
+        #
+        # @param orig_hmac [Mash] hash structure with HMAC data:
+        #   * `['cipher']`: algorithm used (this is ignored).
+        #   * `['secret']` secret used for HMAC calculation in Base64.
+        #   * `['data']` HMAC value in Base64.
+        # @param data [String] data to calculate HMAC for.
+        # @param algo [String] HMAC algorithm to use.
+        # @return [Boolean] `true` if HMAC value matches.
+        # @raise [MessageAuthenticationFailure] if HMAC calculation error.
+        # @see #generate_hmac
+        def hmac_matches?(orig_hmac, data, algo = HMAC_ALGORITHM)
           digest = OpenSSL::Digest.new(algo)
           secret = Base64.decode64(orig_hmac['secret'])
           new_hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, secret, data))
           orig_hmac['data'] == new_hmac
-        rescue OpenSSL::Digest::DigestError, OpenSSL::HMACError, RuntimeError => e
-          # RuntimeError is raised for unsupported algorithms
-          raise MessageAuthenticationFailure, "#{e.class.name}: #{e.to_s}"
+        rescue *HMAC_EXCEPTIONS => e
+          raise MessageAuthenticationFailure, "#{e.class}: #{e}"
         end
-
       end
     end
   end

data/lib/chef/encrypted_attribute/encrypted_mash/version2.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,37 +22,119 @@ require 'chef/encrypted_attribute/encrypted_mash/version1'
 require 'chef/encrypted_attribute/assertions'
 require 'chef/encrypted_attribute/exceptions'
 
-# Version2 format: using RSA with a shared secret and GCM
 class Chef
   class EncryptedAttribute
     class EncryptedMash
+      # EncryptedMash Version2 format: using RSA with a shared secret and GCM.
+      #
+      # Uses public key cryptography (PKI) to encrypt a shared secret. Then this
+      # shared secret is used to encrypt the data using [GCM]
+      # (http://en.wikipedia.org/wiki/Galois/Counter_Mode).
+      #
+      # * This protocol version is based on the [Chef 12 Encrypted Data Bags
+      #   Version 3 implementation](https://github.com/opscode/chef/pull/1591).
+      # * To use it, the following **special requirements** must be met:
+      #   Ruby `>= 2` and OpenSSL `>= 1.0.1`.
+      # * This implementation can be improved, is not optimized either for
+      #   performance or for space.
+      # * Every time the `EncryptedAttribute` is updated, all the shared secrets
+      #   are regenerated.
+      #
+      # # `EncryptedMash::Version2` Structure
+      #
+      # If you try to read this encrypted attribute structure, you can see a
+      # `Mash` attribute with the following content:
+      #
+      # ```
+      # EncryptedMash
+      # ├── chef_type: "encrypted_attribute" (string).
+      # ├── x_json_class: The used `EncryptedMash` version class name (string).
+      # ├── encrypted_data
+      # │   ├── cipher: The used PKI algorithm, "aes-256-gcm" (string).
+      # │   ├── data: PKI encrypted data (base64).
+      # │   ├── auth_tag: GCM authentication tag (base64).
+      # │   └── iv: Initialization vector (in base64).
+      # └── encrypted_secret
+      #     ├── pub_key_hash1: The shared secret encrypted for the public key 1
+      #     │     (base64).
+      #     ├── pub_key_hash2: The shared secret encrypted for the public key 2
+      #     │     (base64).
+      #     └── ...
+      # ```
+      #
+      # * `x_json_class` field is used, with the `x_` prefix, to be easily
+      #   integrated with Chef in the future.
+      #
+      # ## `EncryptedMash[encrypted_data][data]`
+      #
+      # The data inside `encrypted_data` is symmetrically encrypted using the
+      # secret shared key. The data is converted to *JSON* before the
+      # encryption, then encrypted and finally encoded in *base64*. By default,
+      # the `'aes-256-gcm'` algorithm is used for encryption.
+      #
+      # After decryption, the *JSON* has the following structure:
+      #
+      # ```
+      # └── encrypted_data
+      #     └── data (symmetrically encrypted JSON in base64)
+      #         └── content: attribute content as a Mash.
+      # ```
+      #
+      # * In the future, this structure may contain some metadata like default
+      #   configuration values.
+      #
+      # ## `EncryptedMash[encrypted_secret][pub_key_hash1]`
+      #
+      # The `public_key_hash1` key value is the *SHA1* of the public key used
+      # for encryption.
+      #
+      # Its content is the encrypted shared secret in *raw*. The encryption is
+      # done using the *RSA* algorithm (PKI).
+      #
+      # After decryption, you find the shared secret in *raw* (in *Version1*
+      # this is a *JSON* in *base64*).
+      #
+      # @see EncryptedMash
       class Version2 < Chef::EncryptedAttribute::EncryptedMash::Version1
         include Chef::EncryptedAttribute::Assertions
 
+        # Symmetric [AEAD]
+        # (http://en.wikipedia.org/wiki/AEAD_block_cipher_modes_of_operation)
+        # algorithm to use by default.
         ALGORITHM = 'aes-256-gcm'
 
-        def initialize(enc_hs=nil)
+        # EncrytpedMash::Version2 constructor.
+        #
+        # Checks that GCM is correctly supported by Ruby and OpenSSL.
+        #
+        # @raise [RequirementsFailure] if the specified encrypted attribute
+        #   version cannot be used.
+        def initialize(enc_hs = nil)
           assert_aead_requirements_met!(ALGORITHM)
           super
         end
 
+        # (see EncryptedMash::Version1#encrypt)
         def encrypt(value, public_keys)
           value_json = json_encode(value)
           public_keys = parse_public_keys(public_keys)
           # encrypt the data
           encrypted_data = symmetric_encrypt_value(value_json)
-          secret = encrypted_data.delete('secret') # should no include the secret in clear
+          # should no include the secret in clear
+          secret = encrypted_data.delete('secret')
           self['encrypted_data'] = encrypted_data
           # encrypt the shared secret
           self['encrypted_secret'] = rsa_encrypt_multi_key(secret, public_keys)
           self
         end
 
+        # (see EncryptedMash::Version1#decrypt)
         def decrypt(key)
           key = parse_decryption_key(key)
           enc_value = self['encrypted_data'].dup
           # decrypt the shared secret
-          enc_value['secret'] = rsa_decrypt_multi_key(self['encrypted_secret'], key)
+          enc_value['secret'] =
+            rsa_decrypt_multi_key(self['encrypted_secret'], key)
           # decrypt the data
           value_json = symmetric_decrypt_value(enc_value)
           json_decode(value_json)
@@ -59,19 +142,37 @@ class Chef
 
         protected
 
+        # (see EncryptedMash::Version1#encrypted_data?)
+        def encrypted_data?
+          encrypted_data_contain_fields?(
+            iv: String, auth_tag: String, data: String
+          )
+        end
+
+        # (see EncryptedMash::Version1#encrypted?)
         def encrypted?
-          Version0.instance_method(:encrypted?).bind(self).call and
-          self['encrypted_data'].has_key?('iv') and
-          self['encrypted_data']['iv'].kind_of?(String) and
-          self['encrypted_data'].has_key?('auth_tag') and
-          self['encrypted_data']['auth_tag'].kind_of?(String) and
-          self['encrypted_data'].has_key?('data') and
-          self['encrypted_data']['data'].kind_of?(String) and
-          self['encrypted_secret'].kind_of?(Hash)
+          Version0.instance_method(:encrypted?).bind(self).call &&
+            encrypted_data? &&
+            encrypted_secret?
         end
 
-        def symmetric_encrypt_value(value, algo=ALGORITHM)
-          enc_value = Mash.new({ 'cipher' => algo })
+        # Encrypts a value using a symmetric [AEAD]
+        # (http://en.wikipedia.org/wiki/AEAD_block_cipher_modes_of_operation)
+        # cryptographic algorithm.
+        #
+        # Uses a randomly generated secret and IV.
+        #
+        # @param value [String] data to encrypt.
+        # @param algo [String] symmetric algorithm to use.
+        # @return [Mash] hash structure with symmetrically encrypted data:
+        #   * `['cipher']`: algorithm used.
+        #   * `['secret']`: random secret used for encryption in Base64.
+        #   * `['iv']`: random initialization vector in Base64.
+        #   * `['auth_tag']`: authentication tag in Base64.
+        #   * `['data']`: data encrypted and in Base64.
+        # @raise [EncryptionFailure] if encryption error.
+        def symmetric_encrypt_value(value, algo = ALGORITHM)
+          enc_value = Mash.new('cipher' => algo)
           begin
             cipher = OpenSSL::Cipher.new(algo)
             cipher.encrypt
@@ -80,14 +181,28 @@ class Chef
             enc_data = cipher.update(value) + cipher.final
             enc_value['auth_tag'] = Base64.encode64(cipher.auth_tag)
           rescue OpenSSL::Cipher::CipherError => e
-            raise EncryptionFailure, "#{e.class.name}: #{e.to_s}"
+            raise EncryptionFailure, "#{e.class.name}: #{e}"
           end
           enc_value['data'] = Base64.encode64(enc_data)
           enc_value
         end
 
-        def symmetric_decrypt_value(enc_value, algo=ALGORITHM)
-          cipher = OpenSSL::Cipher.new(enc_value['cipher'] || algo) # TODO maybe it's better to ignore [cipher] ?
+        # Decrypts data using a symmetric [AEAD]
+        # (http://en.wikipedia.org/wiki/AEAD_block_cipher_modes_of_operation)
+        # cryptographic algorithm.
+        #
+        # @param enc_value [Mash] hash structure with encrypted data:
+        #   * `['cipher']`: algorithm used.
+        #   * `['secret']`: secret used for encryption in Base64.
+        #   * `['iv']`: initialization vector in Base64.
+        #   * `['auth_tag']`: authentication tag in Base64.
+        #   * `['data']`: data encrypted in Base64.
+        # @param algo [String] symmetric algorithm to use.
+        # @raise [DecryptionFailure] if decryption error.
+        # @see #symmetric_encrypt_value
+        def symmetric_decrypt_value(enc_value, algo = ALGORITHM)
+          # TODO: maybe it's better to ignore [cipher] ?
+          cipher = OpenSSL::Cipher.new(enc_value['cipher'] || algo)
           cipher.decrypt
           # We must set key before iv: https://bugs.ruby-lang.org/issues/8221
           cipher.key = enc_value['secret']
@@ -95,9 +210,8 @@ class Chef
           cipher.auth_tag = Base64.decode64(enc_value['auth_tag'])
           cipher.update(Base64.decode64(enc_value['data'])) + cipher.final
         rescue OpenSSL::Cipher::CipherError => e
-          raise DecryptionFailure, "#{e.class.name}: #{e.to_s}"
+          raise DecryptionFailure, "#{e.class.name}: #{e}"
         end
-
       end
     end
   end