cipher.rb in symmetric-encryption-0.9.0

- old
+ new

@@ -30,17 +30,37 @@
     end
 
     # Create a Symmetric::Key for encryption and decryption purposes
     #
     # Parameters:
-    #   :key
+    #   :key [String]
     #     The Symmetric Key to use for encryption and decryption
-    #   :iv
+    #
+    #   :iv [String]
     #     Optional. The Initialization Vector to use with Symmetric Key
-    #   :cipher
+    #     Highly Recommended as it is the input into the CBC algorithm
+    #
+    #   :cipher [String]
     #     Optional. Encryption Cipher to use
     #     Default: aes-256-cbc
+    #
+    #   :encoding [Symbol]
+    #     :base64strict
+    #       Return as a base64 encoded string that does not include additional newlines
+    #       This is the recommended format since newlines in the values to
+    #       SQL queries are cumbersome. Also the newline reformatting is unnecessary
+    #       It is not the default for backward compatibility
+    #     :base64
+    #       Return as a base64 encoded string
+    #     :binary
+    #       Return as raw binary data string. Note: String can contain embedded nulls
+    #     Default: :base64
+    #     Recommended: :base64strict
+    #
+    #   :version [Fixnum]
+    #     Optional. The version number of this encryption key
+    #     Used by SymmetricEncryption to select the correct key when decrypting data
     def initialize(parms={})
       raise "Missing mandatory parameter :key" unless @key = parms[:key]
       @iv = parms[:iv]
       @cipher = parms[:cipher] || 'aes-256-cbc'
       @version = parms[:version]
@@ -48,38 +68,50 @@
 
       raise("Invalid Encoding: #{@encoding}") unless ENCODINGS.include?(@encoding)
     end
 
     # AES Symmetric Encryption of supplied string
+    # The String is encoded to UTF-8 prior to encryption
+    #
     #  Returns result as a Base64 encoded string
     #  Returns nil if the supplied str is nil
     #  Returns "" if it is a string and it is empty
-    #
-    #  options:
-    #    :encoding
-    #       :base64 Return as a base64 encoded string
-    #       :binary Return as raw binary data string. Note: String can contain embedded nulls
-    #      Default: :base64
-    #    :compress
-    #      [true|false] Whether or not to compress the data _before_ encrypting
-    #      Default: false
-    def encrypt(str)
-      return if str.nil?
-      buf = str.to_s
-      return str if buf.empty?
-      crypt(:encrypt, buf)
+    if defined?(Encoding)
+      def encrypt(str)
+        return if str.nil?
+        buf = str.to_s.encode(SymmetricEncryption::UTF8_ENCODING)
+        return str if buf.empty?
+        crypt(:encrypt, buf)
+      end
+    else
+      def encrypt(str)
+        return if str.nil?
+        buf = str.to_s
+        return str if buf.empty?
+        crypt(:encrypt, buf)
+      end
     end
 
     # AES Symmetric Decryption of supplied string
-    #  Returns decrypted string
+    # The encoding of the supplied string is ignored since it must be binary data
+    #  Returns a UTF-8 encoded, decrypted string
     #  Returns nil if the supplied str is nil
     #  Returns "" if it is a string and it is empty
-    def decrypt(str)
-      return if str.nil?
-      buf = str.to_s
-      return str if buf.empty?
-      crypt(:decrypt, buf)
+    if defined?(Encoding)
+      def decrypt(str)
+        return if str.nil?
+        buf = str.to_s.force_encoding(SymmetricEncryption::BINARY_ENCODING)
+        return str if buf.empty?
+        crypt(:decrypt, buf).force_encoding(SymmetricEncryption::UTF8_ENCODING)
+      end
+    else
+      def decrypt(str)
+        return if str.nil?
+        buf = str.to_s
+        return str if buf.empty?
+        crypt(:decrypt, buf)
+      end
     end
 
     # Return a new random key using the configured cipher
     # Useful for generating new symmetric keys
     def random_key
@@ -102,9 +134,10 @@
       openssl_cipher
     end
 
     # 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
\ No newline at end of file