encrypted_strings 0.1.1 → 0.2.0

data/CHANGELOG.rdoc

@@ -1,5 +1,13 @@
 == master
 
+== 0.2.0 / 2008-12-01
+
+* Remove AsymmetricEncryptor.default_algorithm, instead relying on SymmetricEncryptor.default_algorithm
+* Rename NoKeyError to NoPasswordError
+* Rename Encryptors to Ciphers
+* Remove deprecated SymmetricEncryptor#key option
+* Require that symmetric encryption be PKCS #5 compliant
+
 == 0.1.1 / 2008-12-01
 
 * Fix non-compliant PKCS #5 algorithm being used for symmetric encryption. Use :pkcs5_compliant => true for better security.

data/README.rdoc

@@ -23,58 +23,58 @@ Source
 == Description
 
 Encrypting and decrypting data is not exactly the most straightforward and DRY
-way.  encrypted_strings greatly improves upon this syntax and adds
+way.  encrypted_strings improves the syntax and reduces the complexity, adding
 straightforward support for encrypting values using SHA-1, Symmetric, and
-Asymmetric modes.
+Asymmetric ciphers.
 
 == Usage
 
 === SHA Encryption
 
-  >> password = "shhhh"
+  >> password = 'shhhh'
   => "shhhh"
-  >> crypted_password = password.encrypt
+  >> encrypted_password = password.encrypt
   => "66c85d26dadde7e1db27e15a0776c921e27143bd"
-  >> crypted_password.class
+  >> encrypted_password.class
   => String
-  >> crypted_password.encryptor
-  => #<PluginAWeek::EncryptedStrings::ShaEncryptor:0x2b9238889460 @salt="salt">
-  >> crypted_password == "shhhh"
+  >> encrypted_password.cipher
+  => #<PluginAWeek::EncryptedStrings::ShaCipher:0x2b9238889460 @salt="salt">
+  >> encrypted_password == 'shhhh'
   => true
-  >> crypted_password.decrypt
-  NotImplementedError: Decryption is not supported using a(n) PluginAWeek::EncryptedStrings::ShaEncryptor
-          from ./script/../config/../config/../vendor/plugins/encrypted_strings/lib/encrypted_strings/encryptor.rb:13:in `decrypt'
+  >> encrypted_password.decrypt
+  NotImplementedError: Decryption is not supported using a(n) PluginAWeek::EncryptedStrings::ShaCipher
+          from ./script/../config/../config/../vendor/plugins/encrypted_strings/lib/encrypted_strings/cipher.rb:13:in `decrypt'
           from ./script/../config/../config/../vendor/plugins/encrypted_strings/lib/encrypted_strings/extensions/string.rb:52:in `decrypt'
           from (irb):40
 
-When encrypt is called, it creates an +encryptor+ instance which is used for
-future encryption and decryption of the string.  The default encryptor uses
-SHA-1 encryption.  For encryption modes that do not support decryption, equality
-with other strings is tested by encrypting the other string and checking whether
-the resulting encrypted value is the same.
+When encrypt is called, it creates a +cipher+ instance which is used for
+future encryption and decryption of the string.  The default cipher uses
+SHA-1 encryption.  For ciphers that do not support decryption, equality with
+other strings is tested by encrypting the other string and checking whether the
+resulting encrypted value is the same.
 
 === Symmetric Encryption
 
-  >> password = "shhhh"
+  >> password = 'shhhh'
   => "shhhh"
-  >> crypted_password = password.encrypt(:symmetric, :password => "secret_key")
-  => "jDACXI5hMPI=\n"
+  >> crypted_password = password.encrypt(:symmetric, :password => 'secret_key')
+  => "qSg8vOo6QfU=\n"
   >> crypted_password.class
   => String
-  >> crypted_password == "shhhh"
+  >> crypted_password == 'shhhh'
   => true
   >> password = crypted_password.decrypt
   => "shhhh"
 
 === Asymmetric encryption
 
-  >> password = "shhhh"
+  >> password = 'shhhh'
   => "shhhh"
-  >> crypted_password = password.encrypt(:asymmetric, :public_key_file => "./public.key", :private_key_file => "./private.key")
+  >> crypted_password = password.encrypt(:asymmetric, :public_key_file => './public.key', :private_key_file => './private.key')
   => "NEwVzcikYUKfS8HTc9L9eg/dMxBCLZ/nFr7J1aQYjkl3I2MPUD0lmjr/saC6\nTJEPwOl60Ki24H8TUwnGtZy14A==\n"
   >> crypted_password.class
   => String
-  >> crypted_password == "shhhh"
+  >> crypted_password == 'shhhh'
   => true
   >> password = crypted_password.decrypt
   => "shhhh"

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'encrypted_strings'
-  s.version           = '0.1.1'
+  s.version           = '0.2.0'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Dead-simple string encryption/decryption syntax.'
   

data/lib/encrypted_strings/{asymmetric_encryptor.rb → asymmetric_cipher.rb}

@@ -1,8 +1,13 @@
-require 'encrypted_strings/no_private_key_error'
-require 'encrypted_strings/no_public_key_error'
-
 module PluginAWeek #:nodoc:
   module EncryptedStrings
+    # Indicates no public key was found
+    class NoPublicKeyError < StandardError
+    end
+    
+    # Indicates no private key was found
+    class NoPrivateKeyError < StandardError
+    end
+    
     # Encryption in which the keys used to encrypt/decrypt come in pairs.  Also
     # known as public key encryption.  Anything that's encrypted using the
     # public key can only be decrypted with the same algorithm and a matching
@@ -13,58 +18,50 @@ module PluginAWeek #:nodoc:
     # 
     # == Encrypting 
     # 
-    # To encrypt a string using an asymmetric algorithm, the location of the
+    # To encrypt a string using an asymmetric cipher, the location of the
     # public key file must be specified.  You can define the default for this
     # value like so:
     # 
-    #   PluginAWeek::EncryptedStrings::AsymmetricEncryptor.default_public_key_file = "./public.key"
+    #   PluginAWeek::EncryptedStrings::AsymmetricCipher.default_public_key_file = './public.key'
     # 
     # If these configuration options are not passed in to #encrypt, then the
     # default values will be used.  You can override the default values like so:
     # 
-    #   password = "shhhh"
-    #   password.encrypt(:asymmetric, :public_key_file => "./encrypted_public.key")  # => "INy95irZ8AlHmvc6ZAF/ARsTpbqPIB/4bEAKKOebjsayB7NYWtIzpswvzxqf\nNJ5yyuvxfMODrcg7RimEMFkFlg==\n"
+    #   password = 'shhhh'
+    #   password.encrypt(:asymmetric, :public_key_file => './encrypted_public.key')  # => "INy95irZ8AlHmvc6ZAF/ARsTpbqPIB/4bEAKKOebjsayB7NYWtIzpswvzxqf\nNJ5yyuvxfMODrcg7RimEMFkFlg==\n"
     # 
     # An exception will be raised if either the public key file could not be
     # found or the key could not decrypt the public key file.
     # 
     # == Decrypting
     # 
-    # To decrypt a string using an asymmetric algorithm, the location of the
+    # To decrypt a string using an asymmetric cipher, the location of the
     # private key file must be specified.  If this file is itself encrypted, you
-    # must also specify the algorithm and key used to seed the symmetric
+    # must also specify the algorithm and password used to seed the symmetric
     # algorithm that will decrypt the plublic key file.  You can define defaults
     # for these values like so:
     # 
-    #   PluginAWeek::EncryptedStrings::AsymmetricEncryptor.default_private_key_file = "./private.key"
-    #   PluginAWeek::EncryptedStrings::SymmetricEncryptor.default_algorithm = "DES-EDE3-CBC"
-    #   PluginAWeek::EncryptedStrings::SymmetricEncryptor.default_password = "secret"
+    #   PluginAWeek::EncryptedStrings::AsymmetricCipher.default_private_key_file = './private.key'
+    #   PluginAWeek::EncryptedStrings::SymmetricCipher.default_algorithm = 'DES-EDE3-CBC'
+    #   PluginAWeek::EncryptedStrings::SymmetricCipher.default_password = 'secret'
     # 
     # If these configuration options are not passed in to #decrypt, then the
     # default values will be used.  You can override the default values like so:
     # 
     #   password = "INy95irZ8AlHmvc6ZAF/ARsTpbqPIB/4bEAKKOebjsayB7NYWtIzpswvzxqf\nNJ5yyuvxfMODrcg7RimEMFkFlg==\n"
-    #   password.decrypt(:asymmetric, :public_key_file => "./encrypted_public.key", :password => "secret") # => "shhhh"
+    #   password.decrypt(:asymmetric, :public_key_file => './encrypted_public.key', :password => 'secret') # => "shhhh"
     # 
     # An exception will be raised if either the private key file could not be
-    # found or the key could not decrypt the private key file.
-    class AsymmetricEncryptor < Encryptor
+    # found or the password could not decrypt the private key file.
+    class AsymmetricCipher < Cipher
       class << self
         # The default private key to use during encryption.  Default is nil.
         attr_accessor :default_private_key_file
         
         # The default public key to use during encryption.  Default is nil.
         attr_accessor :default_public_key_file
-        
-        # The default algorithm to use.  Default is nil.
-        attr_accessor :default_algorithm
       end
       
-      # Set defaults
-      @default_private_key_file = nil
-      @default_public_key_file = nil
-      @default_algorithm = nil
-      
       # Private key used for decrypting data
       attr_reader :private_key_file
       
@@ -77,34 +74,31 @@ module PluginAWeek #:nodoc:
       # The password used during symmetric decryption of the key files
       attr_accessor :password
       
+      # Creates a new cipher that uses an asymmetric encryption strategy.
+      # 
       # Configuration options:
       # * +private_key_file+ - Encrypted private key file
       # * +public_key_file+ - Public key file
-      # * +password+ - The password to use in the symmetric encryptor
-      # * +key+ - DEPRECATED. The password to use in the symmetric encryptor
+      # * +password+ - The password to use in the symmetric cipher
       # * +algorithm+ - Algorithm to use symmetrically encrypted strings
-      # * +pkcs5_compliant+ - Whether the generated key/iv should comply to the PKCS #5 standard. Default is false.
       def initialize(options = {})
-        invalid_options = options.keys - [:private_key_file, :public_key_file, :password, :key, :algorithm, :pkcs5_compliant]
+        invalid_options = options.keys - [:private_key_file, :public_key_file, :algorithm, :password]
         raise ArgumentError, "Unknown key(s): #{invalid_options.join(", ")}" unless invalid_options.empty?
         
         options = {
           :private_key_file => self.class.default_private_key_file,
-          :public_key_file => self.class.default_public_key_file,
-          :algorithm => self.class.default_algorithm
+          :public_key_file => self.class.default_public_key_file
         }.merge(options)
         
         @public_key = @private_key = nil
         
-        self.algorithm  = options[:algorithm]
         self.private_key_file = options[:private_key_file]
         self.public_key_file  = options[:public_key_file]
-        self.password = options[:password] || options[:key]
-        warn(':key option is deprecated and will be removed from encrypted_attributes 0.2.0 (use :password)') if options[:key]
-        @pkcs5_compliant = options[:pkcs5_compliant]
-        
         raise ArgumentError, 'At least one key file must be specified (:private_key_file or :public_key_file)' unless private_key_file || public_key_file
         
+        self.algorithm  = options[:algorithm]
+        self.password = options[:password]
+        
         super()
       end
       
@@ -136,7 +130,7 @@ module PluginAWeek #:nodoc:
         @public_key_file = file and load_public_key
       end
       
-      # Does this encryptor have a public key available?
+      # Does this cipher have a public key available?
       def public?
         return true if @public_key
         
@@ -144,7 +138,7 @@ module PluginAWeek #:nodoc:
         !@public_key.nil?
       end
       
-      # Does this encryptor have a private key available?
+      # Does this cipher have a private key available?
       def private?
         return true if @private_key
         
@@ -176,7 +170,6 @@ module PluginAWeek #:nodoc:
           if password
             options = {:password => password}
             options[:algorithm] = algorithm if algorithm
-            options[:pkcs5_compliant] = @pkcs5_compliant if !@pkcs5_compliant.nil?
             
             private_key = @private_key.decrypt(:symmetric, options)
             OpenSSL::PKey::RSA.new(private_key)

data/lib/encrypted_strings/{encryptor.rb → cipher.rb}

@@ -1,9 +1,9 @@
 module PluginAWeek #:nodoc:
   module EncryptedStrings
-    # Represents the base class for all encryptors.  By default, all encryptors
-    # are assumed to be able to decrypt strings.  Note, however, that certain
+    # Represents the base class for all ciphers.  By default, all ciphers are
+    # assumed to be able to decrypt strings.  Note, however, that certain
     # encryption algorithms do not allow decryption.
-    class Encryptor
+    class Cipher
       # Can this string be decrypted?  Default is true.
       def can_decrypt?
         true

data/lib/encrypted_strings/extensions/string.rb

@@ -4,36 +4,36 @@ require 'base64'
 module PluginAWeek #:nodoc:
   module EncryptedStrings
     module Extensions #:nodoc:
-      # Adds support for encryption/decryption of strings
+      # Adds support for in-place encryption/decryption of strings
       module String
         def self.included(base) #:nodoc:
           base.class_eval do
-            attr_accessor :encryptor
+            attr_accessor :cipher
             
             alias_method :equals_without_encryption, :==
             alias_method :==, :equals_with_encryption
           end
         end
         
-        # Encrypts the current string using the specified encryption mode.
-        # The default encryption mode is sha.
+        # Encrypts the current string using the specified cipher.  The default
+        # cipher is sha.
         # 
-        # Configuration options are encryption-specific.  See the encryptor
-        # class for that mode to find out the options available.
+        # Configuration options are cipher-specific.  See each individual cipher
+        # class to find out the options available.
         # 
         # == Example
         # 
-        # The following uses SHA mode to encrypt the string:
+        # The following uses an SHA cipher to encrypt the string:
         # 
         #   password = 'shhhh'
         #   password.encrypt  # => "66c85d26dadde7e1db27e15a0776c921e27143bd"
         # 
         # == Custom encryption mode
         # 
-        # The following uses Symmetric mode (with a default key) to encrypt the
-        # string:
+        # The following uses Symmetric cipher (with a default password) to
+        # encrypt the string:
         # 
-        #   PluginAWeek::EncryptedStrings::SymmetricEncryptor.default_key = 'my_key'
+        #   PluginAWeek::EncryptedStrings::SymmetricCipher.default_password = 'secret'
         #   password = 'shhhh'
         #   password.encrypt(:symmetric)  # => "jDACXI5hMPI=\n"
         # 
@@ -46,9 +46,9 @@ module PluginAWeek #:nodoc:
         #   password = 'shhhh'
         #   password.encrypt(:sha, :salt => 'secret') # => "3b22cbe4acde873c3efc82681096f3ae69aff828"
         def encrypt(*args)
-          encryptor = encryptor_from_args(*args)
-          encrypted_string = encryptor.encrypt(self)
-          encrypted_string.encryptor = encryptor
+          cipher = cipher_from_args(*args)
+          encrypted_string = cipher.encrypt(self)
+          encrypted_string.cipher = cipher
           
           encrypted_string
         end
@@ -60,17 +60,17 @@ module PluginAWeek #:nodoc:
         # == Example
         # 
         #   password = 'shhhh'
-        #   password.encrypt!(:symmetric, :password => 'my_key') # => "jDACXI5hMPI=\n"
-        #   password                                        # => "jDACXI5hMPI=\n"
+        #   password.encrypt!(:symmetric, :password => 'secret')  # => "qSg8vOo6QfU=\n"
+        #   password                                              # => "qSg8vOo6QfU=\n"
         def encrypt!(*args)
           encrypted_string = encrypt(*args)
-          self.encryptor = encrypted_string.encryptor
+          self.cipher = encrypted_string.cipher
           
           replace(encrypted_string)
         end
         
         # Is this string encrypted?  This will return true if the string is the
-        # result of a call to #encrypt or #encrypt! was previously invoked.
+        # result of a call to #encrypt or #encrypt!.
         # 
         # == Example
         # 
@@ -79,23 +79,31 @@ module PluginAWeek #:nodoc:
         #   password.encrypt!   # => "66c85d26dadde7e1db27e15a0776c921e27143bd"
         #   password.encrypted? # => true
         def encrypted?
-          !@encryptor.nil?
+          !cipher.nil?
         end
         
-        # Decrypts this string.  If this is not a string that was previously encrypted,
-        # the encryption algorithm must be specified in the same way the
-        # algorithm is specified when encrypting a string.
+        # Decrypts this string.  If this is not a string that was previously
+        # encrypted, the cipher must be specified in the same way that it is
+        # when encrypting a string.
         # 
         # == Example
         # 
-        #   password = "jDACXI5hMPI=\n"
-        #   password.decrypt(:symmetric, :password => 'my_key')  # => "shhhh"
+        # Without being previously encrypted:
+        # 
+        #   password = "qSg8vOo6QfU=\n"
+        #   password.decrypt(:symmetric, :password => 'secret')   # => "shhhh"
+        # 
+        # After being previously encrypted:
+        # 
+        #   password = 'shhhh'
+        #   password.encrypt!(:symmetric, :password => 'secret')  # => "qSg8vOo6QfU=\n"
+        #   password.decrypt                                      # => "shhhh"
         def decrypt(*args)
-          raise ArgumentError, "An encryption algorithm must be specified since we can't figure it out" if args.empty? && !@encryptor
+          raise ArgumentError, 'Cipher cannot be inferred: must specify it as an argument' if args.empty? && !encrypted?
           
-          encryptor = args.any? ? encryptor_from_args(*args) : (@encryptor || encryptor_from_args(*args))
-          encrypted_string = encryptor.decrypt(self)
-          encrypted_string.encryptor = nil
+          cipher = args.empty? && self.cipher || cipher_from_args(*args)
+          encrypted_string = cipher.decrypt(self)
+          encrypted_string.cipher = nil
           
           encrypted_string
         end
@@ -106,21 +114,21 @@ module PluginAWeek #:nodoc:
         # 
         # For example,
         # 
-        #   password = "jDACXI5hMPI=\n"
-        #   password.decrypt!(:symmetric, :password => 'my_key') # => "shhhh"
-        #   password                                        # => "shhhh"
+        #   password = "qSg8vOo6QfU=\n"
+        #   password.decrypt!(:symmetric, :password => 'secret')  # => "shhhh"
+        #   password                                              # => "shhhh"
         def decrypt!(*args)
           value = replace(decrypt(*args))
-          self.encryptor = nil
+          self.cipher = nil
           value
         end
         
         # Can this string be decrypted?  Strings can only be decrypted if they
-        # have previously been decrypted +and+ the encryption algorithm supports
-        # decryption.  To determine whether or not the encryption algorithm
-        # supports decryption, see the api for the algorithm's encryptor class.
+        # have previously been decrypted *and* the cipher supports decryption.
+        # To determine whether or not the cipher supports decryption, see the
+        # api for the cipher.
         def can_decrypt?
-          encrypted? && @encryptor.can_decrypt?
+          encrypted? && cipher.can_decrypt?
         end
         
         # Tests whether the other object is equal to this one.  Encrypted strings
@@ -180,16 +188,17 @@ module PluginAWeek #:nodoc:
             if encrypted_value.can_decrypt?
               encrypted_value.decrypt.equals_without_encryption(value)
             else
-              # Otherwise encrypt this value based on the encryptor used on the encrypted value
+              # Otherwise encrypt this value based on the cipher used on the encrypted value
               # and test the equality of those strings
-              encrypted_value.equals_without_encryption(encrypted_value.encryptor.encrypt(value))
+              encrypted_value.equals_without_encryption(encrypted_value.cipher.encrypt(value))
             end
           end
           
-          def encryptor_from_args(*args) #:nodoc:
+          # Builds the cipher to use from the given arguments
+          def cipher_from_args(*args) #:nodoc:
             options = args.last.is_a?(Hash) ? args.pop : {}
-            mode = (args.first || :sha).to_s.gsub(/(?:^|_)(.)/) {$1.upcase}
-            PluginAWeek::EncryptedStrings.const_get("#{mode}Encryptor").new(options)
+            name = (args.first || :sha).to_s.gsub(/(?:^|_)(.)/) {$1.upcase}
+            PluginAWeek::EncryptedStrings.const_get("#{name}Cipher").new(options)
           end
       end
     end