symmetric-encryption 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 94fbb4339aaed37c7526621cf7dd768aaae56fb7
-  data.tar.gz: bc40aa329637465ca0747be1efac9a29a9154007
+  metadata.gz: 32af889e864031974d67cc49ed09fca4fc6a9ceb
+  data.tar.gz: be8ef6b6193bd44dbf4b3c760b31e9223f0e4ce1
 SHA512:
-  metadata.gz: 04f23adcb3fbdf114a28a7460c9e120aa33fbb3d5897b2adf7700b559cf4fa78ae8cebb7b972383816c9a4b1f5202fead4abb5d87e1335cc65cdb6020169e6bc
-  data.tar.gz: bce09dff95ff11023aab38965f02a12f1ae6c49069256c54963b7db8bc5dd0889680c878d4b906b1f603599dbf9431d4239c987004d13ee00c5751420793f444
+  metadata.gz: cfdba0c992f3f82765ab3592a386cdceb9eb81265d0f6fef31cd324d02d1d4d21bbd8bf51032b0e3a01f4b0afd2e885f94a6976fab427b8c617c83db554f5e71
+  data.tar.gz: 7dd486b715dcd74ac6ae88451a39e12c61f1b2b525e62f1e52a0e18dfe0a485b3f853ff37ac6f183a30b20383c6cc7410a8cbc6fa9e0fdbcef129b9f188a0697

data/README.md

@@ -50,22 +50,53 @@ From a security perspective it is important then to properly secure the system s
 no hacker can switch to and run as the rails user and thereby gain access to the
 encryption and decryption capabilities
 
+## Limitations
+
+By default symmetric encryption uses the same initialization vector (IV) and
+encryption key to encrypt data using the SymmetricEncryption.encrypt call.
+This technique is required in cases where the encrypted data is used as a key
+to lookup for example a Social Security Number, since for the same input data it
+must always return the same encrypted result. The drawback is that this
+technique is not considered secure when encypting large amounts of data.
+
+For non-key fields, such as storing encrypted raw responses,
+use the :random_iv => true option where possible so that a
+randomly generated IV is used and included in every encrypted string.
+
+The Symmetric Encryption streaming interface SymmetricEncryption::Writer avoids this
+problem by using a random IV and key in every file/stream by default.
+The random IV and key are stored in the header of the output stream so that it
+is available when reading back the encrypted file/stream.
+
+The ActiveRecord attr_encrypted method supports the :random_iv => true option.
+Similarly for Mongoid the :random_iv => true option can be added.
+
+Note that encrypting the same input string with the same key and :random_iv => true
+option will result in different encrypted output every time it is encrypted.
+
 ## Features
 
 * Encryption of passwords in configuration files
 * Encryption of ActiveRecord model attributes by prefixing attributes / column
 names with encrypted_
+* Encryption of Mongoid model fields by adding :encrypted => true to field
+  definitions
 * Externalization of symmetric encryption keys so that they are not in the
   source code, or the source code control system
-* Drop in replacement for attr_encrypted. Just remove the attr_encrypted gem
-* Compatible with the default Encryption algorithm in attr_encrypted
-* More efficient replacement for attr_encrypted since only ActiveRecord Models
-are extended with encrypted_ behavior, rather than every object in the system
-* Custom validator for ActiveRecord Models
+* Validator for ActiveRecord Models to ensure fields contain encrypted data
 * Stream based encryption and decryption so that large files can be read or
-  written with encryption
+  written with encryption, along with a random key and IV for every file
 * Stream based encryption and decryption also supports compression and decompression
   on the fly
+* When :compress => true option is specified Symmetric Encryption will transparently
+  compress the data prior to decryption. When decrypting compressed data Symmetric
+  Encryption will transparently decompress the data after decryption based on the
+  header stored in the encrypted data
+* Uses built-in support in Ruby for OpenSSL and Zlib for high performance and
+  maximum portability without introducing any additional dependencies
+* Drop in replacement for attr_encrypted. Just remove the attr_encrypted gem
+* For maximum security supports fully random keys and initialization vectors
+  extracted from the entire encryption key space
 
 ## Examples
 
@@ -215,9 +246,9 @@ Before generating keys we can use SymmetricEncryption in a standalone test envir
 ```ruby
 # Use test encryption keys
 SymmetricEncryption.cipher = SymmetricEncryption::Cipher.new(
-  :key    => '1234567890ABCDEF1234567890ABCDEF',
-  :iv     => '1234567890ABCDEF',
-  :cipher => 'aes-128-cbc'
+  :key         => '1234567890ABCDEF1234567890ABCDEF',
+  :iv          => '1234567890ABCDEF',
+  :cipher_name => 'aes-128-cbc'
 )
 encrypted = SymmetricEncryption.encrypt('hello world')
 puts SymmetricEncryption.decrypt(encrypted)
@@ -408,7 +439,7 @@ Create a configuration file in config/symmetric-encryption.yml per the following
 development: &development_defaults
   key:    1234567890ABCDEF1234567890ABCDEF
   iv:     1234567890ABCDEF
-  cipher: aes-128-cbc
+  cipher_name: aes-128-cbc
 
 test:
   <<: *development_defaults
@@ -457,7 +488,7 @@ production:
 		key_filename: /etc/rails/.rails.key
 		iv_filename:  /etc/rails/.rails.iv
 
-		# Encryption cipher
+		# Encryption cipher_name
 		#   Recommended values:
 		#      aes-256-cbc
 		#         256 AES CBC Algorithm. Very strong
@@ -467,7 +498,7 @@ production:
 		#         128 AES CBC Algorithm. Less strong.
 		#         Ruby 1.8.7 MRI Approximately 100,000 encryptions or decryptions per second
 		#         JRuby 1.6.7 with Ruby 1.8.7 Approximately 22,000 encryptions or decryptions per second
-		cipher: aes-256-cbc
+		cipher_name:  aes-256-cbc
 
 	 -
 		# OPTIONAL:
@@ -478,27 +509,48 @@ production:
 		# to be used
 		key_filename: /etc/rails/.rails_old.key
 		iv_filename:  /etc/rails/.rails_old.iv
-		cipher:       aes-256-cbc
+		cipher_name:  aes-256-cbc
 ```
 
-## Future Enhancements
+## New features in V1.1 and V2
 
 * Ability to randomly generate a new initialization vector (iv) with every
-  encryption and put the iv in the encrypted data as its header
+  encryption and put the iv in the encrypted data as its header, without having
+  to use SymmetricEncryption::Writer
 
 * With file encryption randomly generate a new key and initialization vector (iv) with every
   file encryption and put the key and iv in the encrypted data as its header which
   is encrypted using the global key and iv
 
-Submit an issue ticket to request any of the following features:
-
-* Ability to entirely disable encryption for a specific environment.
-  SymmetricEncryption.encrypt() would return the supplied data without encrypting it and
-  SymmetricEncryption.decrypt() would return the supplied data without decrypting it
+* Support for compression via SymmetricEncryption.encrypt, attr_encrypted and Mongoid
+  fields
 
-* Support for automatically compressing data prior to encrypting it when the
-  data exceeds some predefined size. And automatically decompressing the data
-  during decryption
+* SymmetricEncryption.encrypt has two additional optional parameters:
+```
+   random_iv [true|false]
+     Whether the encypted value should use a random IV every time the
+     field is encrypted.
+     It is recommended to set this to true where feasible. If the encrypted
+     value could be used as part of a SQL where clause, or as part
+     of any lookup, then it must be false.
+     Setting random_iv to true will result in a different encrypted output for
+     the same input string.
+     Note: Only set to true if the field will never be used as part of
+       the where clause in an SQL query.
+     Note: When random_iv is true it will add a 8 byte header, plus the bytes
+       to store the random IV in every returned encrypted string, prior to the
+       encoding if any.
+     Default: false
+     Highly Recommended where feasible: true
+
+   compress [true|false]
+     Whether to compress str before encryption
+     Should only be used for large strings since compression overhead and
+     the overhead of adding the 'magic' header may exceed any benefits of
+     compression
+     Note: Adds a 6 byte header prior to encoding, only if :random_iv is false
+     Default: false
+```
 
 Meta
 ----

data/lib/rails/generators/symmetric_encryption/config/templates/symmetric-encryption.yml

@@ -5,10 +5,11 @@
 # For the development and test environments the test symmetric encryption keys
 # can be placed directly in the source code.
 # And therefore no RSA private key is required
-development: &development_defaults
-  key:       1234567890ABCDEF1234567890ABCDEF
-  iv:        1234567890ABCDEF
-  cipher:    aes-128-cbc
+development:   &development_defaults
+  key:         1234567890ABCDEF1234567890ABCDEF
+  iv:          1234567890ABCDEF
+  cipher_name: aes-128-cbc
+  encoding:    :base64strict
 
 test:
   <<: *development_defaults
@@ -27,7 +28,7 @@ release:
       # RSA public key derived from the private key above
       key_filename: <%= File.join(key_path, "#{app_name}_release.key") %>
       iv_filename:  <%= File.join(key_path, "#{app_name}_release.iv") %>
-      cipher:       aes-256-cbc
+      cipher_name:  aes-256-cbc
       # Base64 encode encrypted data without newlines
       encoding:     :base64strict
       version:      1
@@ -46,7 +47,7 @@ production:
       # RSA public key derived from the private key above
       key_filename: <%= File.join(key_path, "#{app_name}_production.key") %>
       iv_filename:  <%= File.join(key_path, "#{app_name}_production.iv") %>
-      cipher:       aes-256-cbc
+      cipher_name:  aes-256-cbc
       # Base64 encode encrypted data without newlines
       encoding:     :base64strict
       version:      1

data/lib/symmetric_encryption/cipher.rb

@@ -7,39 +7,31 @@ module SymmetricEncryption
   # threads at the same time without needing an instance of Cipher per thread
   class Cipher
     # Cipher to use for encryption and decryption
-    attr_reader :cipher, :version
+    attr_reader :cipher_name, :version
     attr_accessor :encoding
 
     # Available encodings
     ENCODINGS = [:none, :base64, :base64strict, :base16]
 
+    # Backward compatibility
+    alias_method :cipher, :cipher_name
+
     # Generate a new Symmetric Key pair
     #
     # Returns a hash containing a new random symmetric_key pair
     # consisting of a :key and :iv.
-    # The cipher is also included for compatibility with the Cipher initializer
-    def self.random_key_pair(cipher = 'aes-256-cbc', generate_iv = true)
-      openssl_cipher = OpenSSL::Cipher.new(cipher)
+    # The cipher_name is also included for compatibility with the Cipher initializer
+    def self.random_key_pair(cipher_name = 'aes-256-cbc', generate_iv = true)
+      openssl_cipher = ::OpenSSL::Cipher.new(cipher_name)
       openssl_cipher.encrypt
 
       {
-        :key    => openssl_cipher.random_key,
-        :iv     => generate_iv ? openssl_cipher.random_iv : nil,
-        :cipher => cipher
+        :key         => openssl_cipher.random_key,
+        :iv          => generate_iv ? openssl_cipher.random_iv : nil,
+        :cipher_name => cipher_name
       }
     end
 
-    # Returns a new Cipher with a random key and iv
-    #
-    # The cipher and encoding used are from the global encryption cipher
-    #
-    def self.random_cipher(cipher=nil, encoding=nil)
-      global_cipher = SymmetricEncryption.cipher
-      options = random_key_pair(cipher || global_cipher.cipher)
-      options[:encoding] = encoding || global_cipher.encoding
-      new(options)
-    end
-
     # Create a Symmetric::Key for encryption and decryption purposes
     #
     # Parameters:
@@ -50,7 +42,7 @@ module SymmetricEncryption
     #     Optional. The Initialization Vector to use with Symmetric Key
     #     Highly Recommended as it is the input into the CBC algorithm
     #
-    #   :cipher [String]
+    #   :cipher_name [String]
     #     Optional. Encryption Cipher to use
     #     Default: aes-256-cbc
     #
@@ -76,7 +68,7 @@ module SymmetricEncryption
     def initialize(parms={})
       raise "Missing mandatory parameter :key" unless @key = parms[:key]
       @iv = parms[:iv]
-      @cipher = parms[:cipher] || 'aes-256-cbc'
+      @cipher_name = parms[:cipher_name] || parms[:cipher] || 'aes-256-cbc'
       @version = parms[:version]
       raise "Cipher version has a maximum of 255. #{@version} is too high" if @version.to_i > 255
       @encoding = (parms[:encoding] || :base64).to_sym
@@ -84,28 +76,45 @@ module SymmetricEncryption
       raise("Invalid Encoding: #{@encoding}") unless ENCODINGS.include?(@encoding)
     end
 
-    # Encryption of supplied string
-    # The String is encoded to UTF-8 prior to encryption
+    # Returns encrypted and then encoded string
+    # Returns nil if str is nil
+    # Returns "" str is empty
     #
-    #  Returns result as an encoded string if encode is true
-    #  Returns nil if the supplied str is nil
-    #  Returns "" if it is a string and it is empty
-    if defined?(Encoding)
-      def encrypt(str, encode = true)
-        return if str.nil?
-        str = str.to_s  #.force_encoding(SymmetricEncryption::BINARY_ENCODING)
-        return str if str.empty?
-        encrypted = crypt(:encrypt, str)
-        encode ? self.encode(encrypted) : encrypted
-      end
-    else
-      def encrypt(str, encode = true)
-        return if str.nil?
-        buf = str.to_s
-        return str if buf.empty?
-        encrypted = crypt(:encrypt, buf)
-        encode ? self.encode(encrypted) : encrypted
-      end
+    # Parameters
+    #
+    #   str [String]
+    #     String to be encrypted. If str is not a string, #to_s will be called on it
+    #     to convert it to a string
+    #
+    #   random_iv [true|false]
+    #     Whether the encypted value should use a random IV every time the
+    #     field is encrypted.
+    #     It is recommended to set this to true where feasible. If the encrypted
+    #     value could be used as part of a SQL where clause, or as part
+    #     of any lookup, then it must be false.
+    #     Setting random_iv to true will result in a different encrypted output for
+    #     the same input string.
+    #     Note: Only set to true if the field will never be used as part of
+    #       the where clause in an SQL query.
+    #     Note: When random_iv is true it will add a 8 byte header, plus the bytes
+    #       to store the random IV in every returned encrypted string, prior to the
+    #       encoding if any.
+    #     Default: false
+    #     Highly Recommended where feasible: true
+    #
+    #   compress [true|false]
+    #     Whether to compress str before encryption
+    #     Should only be used for large strings since compression overhead and
+    #     the overhead of adding the 'magic' header may exceed any benefits of
+    #     compression
+    #     Note: Adds a 6 byte header prior to encoding, only if :random_iv is false
+    #     Default: false
+    def encrypt(str, random_iv=false, compress=false)
+      return if str.nil?
+      str = str.to_s
+      return str if str.empty?
+      encrypted = binary_encrypt(str, random_iv, compress)
+      self.encode(encrypted)
     end
 
     # Decryption of supplied string
@@ -116,25 +125,16 @@ module SymmetricEncryption
     #  Returns nil if the supplied str is nil
     #  Returns "" if it is a string and it is empty
     if defined?(Encoding)
-      def decrypt(str, decode = true)
-        decoded = self.decode(str) if decode
-        return unless decoded
-
-        return decoded if decoded.empty?
-        crypt(:decrypt, decoded).force_encoding(SymmetricEncryption::UTF8_ENCODING)
-      end
-
-      # Returns a binary decrypted string
-      def decrypt_binary(str, decode = true)
-        decoded = self.decode(str) if decode
+      def decrypt(str)
+        decoded = self.decode(str)
         return unless decoded
 
         return decoded if decoded.empty?
-        crypt(:decrypt, decoded).force_encoding(SymmetricEncryption::BINARY_ENCODING)
+        binary_decrypt(decoded).force_encoding(SymmetricEncryption::UTF8_ENCODING)
       end
     else
-      def decrypt(str, decode = true)
-        decoded = self.decode(str) if decode
+      def decrypt(str)
+        decoded = self.decode(str)
         return unless decoded
 
         return decoded if decoded.empty?
@@ -142,15 +142,15 @@ module SymmetricEncryption
       end
     end
 
-    # Return a new random key using the configured cipher
+    # Return a new random key using the configured cipher_name
     # Useful for generating new symmetric keys
     def random_key
-      ::OpenSSL::Cipher::Cipher.new(@cipher).random_key
+      ::OpenSSL::Cipher::Cipher.new(@cipher_name).random_key
     end
 
-    # Returns the block size for the configured cipher
+    # Returns the block size for the configured cipher_name
     def block_size
-      ::OpenSSL::Cipher::Cipher.new(@cipher).block_size
+      ::OpenSSL::Cipher::Cipher.new(@cipher_name).block_size
     end
 
     # Returns UTF8 encoded string after encoding the supplied Binary string
@@ -193,12 +193,13 @@ module SymmetricEncryption
       end
     end
 
-    # Returns an Array with the first element being Symmetric Cipher that must
-    # be used to decrypt the data. The second element indicates whether the data
-    # must be decompressed after decryption
-    #
-    # If the buffer does not start with the Magic Header the global cipher will
-    # be returned
+    # Returns an Array of the following values extracted from header or nil
+    # if any value was not specified in the header
+    #   compressed [true|false]
+    #   iv [String]
+    #   key [String]
+    #   cipher_name [String}
+    #   decryption_cipher [SymmetricEncryption::Cipher]
     #
     # The supplied buffer will be updated directly and will have the header
     # portion removed
@@ -215,19 +216,21 @@ module SymmetricEncryption
     #     If no header is present, this is the default value for the compression
     def self.parse_magic_header!(buffer, default_version=nil, default_compressed=false)
       buffer.force_encoding(SymmetricEncryption::BINARY_ENCODING)
-      return [SymmetricEncryption.cipher(default_version), default_compressed] unless buffer.start_with?(MAGIC_HEADER)
+      return [default_compressed, nil, nil, nil, SymmetricEncryption.cipher(default_version)] unless buffer.start_with?(MAGIC_HEADER)
 
       # Header includes magic header and version byte
       # Remove header and extract flags
-      header, flags = buffer.slice!(0..MAGIC_HEADER_SIZE+1).unpack(MAGIC_HEADER_UNPACK)
+      _, flags      = buffer.slice!(0..MAGIC_HEADER_SIZE+1).unpack(MAGIC_HEADER_UNPACK)
       compressed    = (flags & 0b1000_0000_0000_0000) != 0
       include_iv    = (flags & 0b0100_0000_0000_0000) != 0
       include_key   = (flags & 0b0010_0000_0000_0000) != 0
       include_cipher= (flags & 0b0001_0000_0000_0000) != 0
+      # Version of the key to use to decrypt the key if present,
+      # otherwise to decrypt the data following the header
       version       = flags & 0b0000_0000_1111_1111
       decryption_cipher = SymmetricEncryption.cipher(version)
       raise "Cipher with version:#{version.inspect} not found in any of the configured SymmetricEncryption ciphers" unless decryption_cipher
-      iv, key, cipher   = nil
+      iv, key, cipher_name   = nil
 
       if include_iv
         len = buffer.slice!(0..1).unpack('v').first
@@ -235,22 +238,14 @@ module SymmetricEncryption
       end
       if include_key
         len = buffer.slice!(0..1).unpack('v').first
-        key = decryption_cipher.send(:crypt, :decrypt, buffer.slice!(0..len-1))
+        key = decryption_cipher.binary_decrypt(buffer.slice!(0..len-1))
       end
       if include_cipher
         len    = buffer.slice!(0..1).unpack('v').first
-        cipher = buffer.slice!(0..len-1)
-      end
-
-      if iv || key || cipher
-        decryption_cipher = SymmetricEncryption::Cipher.new(
-          :iv     => iv,
-          :key    => key || decryption_cipher.key,
-          :cipher => cipher || decryption_cipher.cipher
-        )
+        cipher_name = buffer.slice!(0..len-1)
       end
 
-      [decryption_cipher, compressed]
+      [compressed, iv, key, cipher_name, decryption_cipher]
     end
 
     # Returns a magic header for this cipher instance that can be placed at
@@ -259,85 +254,125 @@ module SymmetricEncryption
     # Parameters
     #   compressed
     #     Sets the compressed indicator in the header
+    #     Default: false
     #
-    #   include_iv
-    #     Includes the encrypted Initialization Vector from this cipher if present
-    #     The IV is encrypted using the global encryption key
+    #   iv
+    #     The iv to to put in the header
+    #     Default: nil : Exclude from header
     #
-    #   include_key
-    #     Includes the encrypted Key in this cipher
+    #   key
+    #     The key to to put in the header
     #     The key is encrypted using the global encryption key
+    #     Default: nil : Exclude key from header
     #
-    #   include_cipher
-    #     Includes the cipher used. For example 'aes-256-cbc'
-    #
-    #  encryption_cipher
-    #    Encryption cipher to use when encrypting the iv and key.
-    #    When supplied, the version is set to it's version so that decryption
-    #    knows which cipher to use
-    #    Default: Global cipher: SymmetricEncryption.cipher
-    def magic_header(compressed=false, include_iv=false, include_key=false, include_cipher=false, encryption_cipher=nil)
+    #   cipher_name
+    #     Includes the cipher_name used. For example 'aes-256-cbc'
+    #     The cipher_name string to to put in the header
+    #     Default: nil : Exclude cipher_name name from header
+    def self.magic_header(version, compressed=false, iv=nil, key=nil, cipher_name=nil)
       # Ruby V2 named parameters would be perfect here
 
       # Encryption version indicator if available
       flags = version || 0 # Same as 0b0000_0000_0000_0000
 
-      # Replace version with cipher used to encrypt Random IV and Key
-      if include_iv || include_key
-        encryption_cipher ||= SymmetricEncryption.cipher
-        flags = (encryption_cipher.version || 0)
+      # Replace version with global cipher that will be used to encrypt the random key
+      if iv || key
+        flags = (SymmetricEncryption.cipher.version || 0)
       end
 
       # If the data is to be compressed before being encrypted, set the
       # compressed bit in the flags word
       flags |= 0b1000_0000_0000_0000 if compressed
-      flags |= 0b0100_0000_0000_0000 if @iv && include_iv
-      flags |= 0b0010_0000_0000_0000 if include_key
-      flags |= 0b0001_0000_0000_0000 if include_cipher
+      flags |= 0b0100_0000_0000_0000 if iv
+      flags |= 0b0010_0000_0000_0000 if key
+      flags |= 0b0001_0000_0000_0000 if cipher_name
       header = "#{MAGIC_HEADER}#{[flags].pack('v')}".force_encoding(SymmetricEncryption::BINARY_ENCODING)
-      if @iv && include_iv
-        header << [@iv.length].pack('v')
-        header << @iv
+      if iv
+        header << [iv.length].pack('v')
+        header << iv
       end
-      if include_key
-        encrypted = encryption_cipher.crypt(:encrypt, @key).force_encoding(SymmetricEncryption::BINARY_ENCODING)
+      if key
+        encrypted = SymmetricEncryption.cipher.binary_encrypt(key, false, false)
         header << [encrypted.length].pack('v').force_encoding(SymmetricEncryption::BINARY_ENCODING)
         header << encrypted
       end
-      if include_cipher
-        header << [cipher.length].pack('v')
-        header << cipher
+      if cipher_name
+        header << [cipher_name.length].pack('v')
+        header << cipher_name
       end
       header
     end
 
-    protected
-
-    # Only for use by Symmetric::EncryptedStream
-    def openssl_cipher(cipher_method)
-      openssl_cipher = ::OpenSSL::Cipher.new(self.cipher)
-      openssl_cipher.send(cipher_method)
+    # Advanced use only
+    #
+    # Returns a Binary encrypted string without applying any Base64, or other encoding
+    #
+    #   Adds the 'magic' header if a random_iv is required or compression is enabled
+    #
+    # Creates a new OpenSSL::Cipher with every call so that this call
+    # is thread-safe
+    #
+    # See #encrypt to encrypt and encode the result as a string
+    def binary_encrypt(string, random_iv=false, compress=false)
+      openssl_cipher = ::OpenSSL::Cipher.new(self.cipher_name)
+      openssl_cipher.encrypt
       openssl_cipher.key = @key
-      openssl_cipher.iv = @iv if @iv
-      openssl_cipher
+      result = if random_iv || compress
+        # Random iv and compress both add the magic header
+        iv = random_iv ? openssl_cipher.random_iv : @iv
+        openssl_cipher.iv = iv if iv
+        self.class.magic_header(version, compress, random_iv ? iv : nil) +
+          openssl_cipher.update(compress ? Zlib::Deflate.deflate(string) : string)
+      else
+        openssl_cipher.iv = @iv if @iv
+        openssl_cipher.update(string)
+      end
+      result << openssl_cipher.final
     end
 
+    # Advanced use only
+    #
+    # Returns a Binary decrypted string without decoding the string first
+    #
+    # Reads the 'magic' header if present for key, iv, cipher_name and compression
+    #
+    # encrypted_string must be in raw binary form when calling this method
+    #
     # Creates a new OpenSSL::Cipher with every call so that this call
     # is thread-safe
-    # Return a binary encoded decrypted or encrypted string
-    def crypt(cipher_method, string) #:nodoc:
-      openssl_cipher = ::OpenSSL::Cipher.new(self.cipher)
-      openssl_cipher.send(cipher_method)
-      openssl_cipher.key = @key
-      openssl_cipher.iv = @iv if @iv
-      result = openssl_cipher.update(string)
-      result << openssl_cipher.final
-      result.force_encoding(SymmetricEncryption::BINARY_ENCODING)
+    #
+    # See #decrypt to decrypt encoded strings
+    def binary_decrypt(encrypted_string)
+      str = encrypted_string.to_s
+      if str.start_with?(MAGIC_HEADER)
+        str = str.dup
+        compressed, iv, key, cipher_name = self.class.parse_magic_header!(str)
+        openssl_cipher = ::OpenSSL::Cipher.new(cipher_name || self.cipher_name)
+        openssl_cipher.decrypt
+        openssl_cipher.key = key || @key
+        iv ||= @iv
+        openssl_cipher.iv = iv if iv
+        result = openssl_cipher.update(str)
+        result << openssl_cipher.final
+        compressed ? Zlib::Inflate.inflate(result) : result
+      else
+        openssl_cipher = ::OpenSSL::Cipher.new(self.cipher_name)
+        openssl_cipher.decrypt
+        openssl_cipher.key = @key
+        openssl_cipher.iv = @iv if @iv
+        result = openssl_cipher.update(encrypted_string)
+        result << openssl_cipher.final
+      end
+    end
+
+    # Returns [String] object represented as a string
+    # Excluding the key and iv
+    def inspect
+       "#<#{self.class}:0x#{self.__id__.to_s(16)} @cipher_name=#{cipher_name.inspect}, @version=#{version.inspect}, @encoding=#{encoding.inspect}"
     end
 
     private
 
     attr_reader :key, :iv
-
   end
 end