secure_string 0.9.0 → 1.0.0

data/README.rdoc

@@ -9,6 +9,127 @@ functionality that can be used individually:
 * Secure string support: Easy methods for RSA encryption, AES encoding, and
   SHA/MD5 digest hashing, of the data in the strings.
   
+One of the basic philosophies of SecureString is that it does not override--only
+extends--the feature set of String.  However there is one difference that
+was added: +inspect+ is overridden to return the data as a hex-string, rather
+than using the specified character encoding.  This does not mean it's value has
+in any way changed, just its presentation.  Use +to_s+ to recover the standard
+String version of the value.
+
+WARNING: it is important to note that the String method +length+ is not a good
+measure of a byte string's length, as depending on the encoding, it may count
+multibyte characters as a single element.  To ensure that you get the byte
+length, use the standard string method +bytesize+.
+
+= Examples
+
+== Basic Usage
+
+Creation of a SecureString from an normal String instance is easy:
+
+  ss = SecureString.new("Hello World!")
+  ss.to_s    --> "Hello World!"
+  ss.inspect --> "<48656c6c6f20576f726c6421>"
+
+Additionally, you can get at the byte data in various ways:
+
+  ss.to_hex    --> "48656c6c6f20576f726c6421"
+  ss.to_i      --> 22405534230753928650781647905
+  ss.to_base64 --> "SGVsbG8gV29ybGQh"
+
+One can initialize a SecureString from any of these types like so:
+
+  ss1 = SecureString.new(:data, "Hello World!")
+  ss2 = SecureString.new(:hex, "48656c6c6f20576f726c6421")
+  ss3 = SecureString.new(:int, 22405534230753928650781647905)
+  ss4 = SecureString.new(:base64, "SGVsbG8gV29ybGQh")
+  
+  ss1 == ss --> true
+  ss2 == ss --> true
+  ss3 == ss --> true
+  ss4 == ss --> true
+
+All of these create equal-valued strings to <tt>"HelloWorld!"</tt>.
+
+== Base64 Methods Overview
+
+The SecureString::Base64Methods module adds +to_base64+, which we've seen:
+
+  SecureString.new("Hello World!").to_base64 --> "SGVsbG8gV29ybGQh"
+
+It also adds +from_base64+, which can decode a Base64 encoded string.  The
+following example shows the various ways of decoding Bas64 data:
+
+  SecureString.new(:base64, "SGVsbG8gV29ybGQh") == "Hello World!"    --> true
+  SecureString.new("SGVsbG8gV29ybGQh") == "Hello World!"             --> false
+  SecureString.new("SGVsbG8gV29ybGQh").from_base64 == "Hello World!" --> true
+
+== Digest Methods Overview
+
+The SecureString::DigestMethods module adds convenience methods for calculating
+cryptographic hash sums for the data in the string.  Note that since SecureString
+handles binary data well, the string value returns is NOT the hex string; to get
+the hex digest, simply call to_hex:
+
+  ss.to_md5.to_hex
+    --> "ed076287532e86365e841e92bfc50d8c"
+  ss.to_sha1.to_hex
+    --> "2ef7bde608ce5404e97d5f042f95f89f1c232871"
+  ss.to_sha256.to_hex
+     --> "7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069"
+  ss.to_digest(OpenSSL::Digest::SHA512).to_hex
+    --> "861844d6704e8573fec34d967e20bcfef3d424cf48be04e6dc08f2bd58c729743371015ead891cc3cf1c9d34b49264b510751b1ff9e537937bc46b5d6ff4ecc8"
+
+== RSA Methods Overview
+
+The SecureString::RSAMethods module adds convenience methods for RSA key
+generation, encryption, and signing, and verification.
+
+The basic features of this module are illustrated on the following worked example:
+
+First, alice and bob much each generate their public and private keys.  For the
+example, we do it like so:
+
+  alice_pvt_key, alice_pub_key = SecureString.rsa_keygen
+  bob_pvt_key, bob_pub_key = SecureString.rsa_keygen
+
+Now, Alice creates a message and encrypts it for Bob and signs it.
+
+  message = SecureString.new("Hello World")
+  encrypted_message = message.to_rsa(bob_pub_key)
+  signature = encrypted_message.sign(alice_pvt_key)
+
+Alice sends Bob the data in +encrypted_message+ and +signature+.  Bob verifies
+the message's signature, and then decrypts it:
+
+  is_verified = encrypted_message.verify?(alice_pub_key, signature)
+  if( is_verified )
+    decrypted_message = encrypted_message.from_rsa(bob_pvt_key).to_s
+  else
+    raise RuntimeError, "This is not from Alice!"
+  end
+
+The value of Alice's original +message+ variable, and Bob's +decrypted_message+
+should be identical.
+
+== Cipher Methods Overview
+
+The SecureString::CipherMethods module adds convenience methods for block cipher
+encryption, particularly for the AES-256-CBC block cipher.
+
+The following methods illustrate a sample session for the default AES-256-CBC
+cipher:
+
+  # Generate a random key and initialization vector.
+  key, iv = SecureString.aes_keygen
+  
+  # Now encrypt a message:
+  message = SecureString.new("Hello World!")
+  cipher_text = message.to_aes(key, iv)
+  
+  # Now decrypt the message:
+  decoded_text = cipher_text.from_aes(key, iv)
+
 = Contact
 
 If you have any questions, comments, concerns, patches, or bugs, you can contact
@@ -21,7 +142,13 @@ or directly via e-mail at:
 mailto:jeff@paploo.net
 
 = Version History
-
+[1.0.0 - 2010-Nov-04] Added Tests, Examples, and Bugfixes
+                      * Added a full suite of spec tests.
+                      * (FEATURE) Can get a list of supported ciphers.
+                      * (FEATURE) Auto-determine AES key length in +to_aes+ and +from_aes+.
+                      * (CHANGE) RSA now defaults to 2048-bit keys instead of just 1024.
+                      * (FIX) Init from integer works now.
+                      * (FIX) RSA signatures can take digest classes, not just instances.
 [0.9.0 - 2010-Nov-03] Initial release.
                       * Feature complete, but lacks spec tests and examples.
                       
@@ -29,6 +156,15 @@ mailto:jeff@paploo.net
 
 * Add complete spec tests.
 * Add examples.
+* Pull out all methods into modules so that it can be an extension of all Strings.
+* Add a +to_ss+ or +to_secure+ method to String for easy conversion.
+* to_digest should be able to take a string that is the algorithm name.
+* Explore how encodings affect the data.  What about when finding length?  What
+  methods should be recommended to users for finding byte-length vs. char length.
+* RSA encoding/decoding should auto-detect if the given key is public or private,
+  and use the correct encoding routine?  What about key confusion?
+* RSA signature digests: accept Digest hashes, not just OpenSSL::Digest hashes.
+  
 
 = License
 

data/lib/secure_string.rb

@@ -28,7 +28,7 @@ class SecureString < String
     when :data
       data = value.to_s
     when :int
-      self.send(__method__, :hex, value.to_i.to_s(16))
+      data = self.send(__method__, :hex, value.to_i.to_s(16))
     when :base64
       data = Base64.decode64(value.to_s)
     end

data/lib/secure_string/base64_methods.rb

@@ -1,12 +1,16 @@
 require 'base64'
 
 class SecureString < String
+  # Adds methods for Base64 conversion.
+  # See Base64Methods::InstanceMethods for more details.
   module Base64Methods
     
     def self.included(mod)
       mod.send(:include, InstanceMethods)
     end
     
+    # Adds instance methods for Base64 support via inclusion of
+    # SecureString::Base64Methods to a class.
     module InstanceMethods
       
       # Encodes to Base64.  By default, the output is made URL safe, which means all

data/lib/secure_string/cipher_methods.rb

@@ -1,6 +1,8 @@
 require 'openssl'
 
 class SecureString < String
+  # Adds methods for OpenSSL::Cipher support including AES encryption.
+  # See CipherMethods::ClassMethods and CipherMethods::InstanceMethods for more details.
   module CipherMethods
     
     def self.included(mod)
@@ -8,12 +10,20 @@ class SecureString < String
       mod.send(:include, InstanceMethods)
     end
     
+    # Adds class methods for OpenSSL::Cipher support, including AES encryption,
+    # via inclusion of SecureString::CipherMethods into a class.
     module ClassMethods
       
+      # Returns a list of supported ciphers.  These can be passed directly into
+      # the cipher methods.
+      def supported_ciphers
+        return OpenSSL::Cipher.ciphers
+      end
+      
       # A convenience method for generating random cipher keys and initialization
       # vectors.
       def cipher_keygen(cipher_name)
-        cipher = OpenSSL::Cipher::Cipher.new(cipher_name)
+        cipher = OpenSSL::Cipher.new(cipher_name)
         cipher.encrypt
         return [cipher.random_key, cipher.random_iv].map {|s| self.new(s)}
       end
@@ -26,6 +36,8 @@ class SecureString < String
       
     end
     
+    # Adds instance methods for OpenSSL::Cipher support, including AES encryption,
+    # via inclusion of SecureString::CipherMethods into a class.
     module InstanceMethods
       
       # Given an OpenSSL cipher name, a key, and initialization vector,
@@ -60,13 +72,18 @@ class SecureString < String
         return self.class.new(msg)
       end
       
-      # Given an AES key and initialization vector, AES encode the data.
-      def to_aes(key, iv, key_len=256)
+      # Given an AES key and initialization vector, AES-CBC encode the data.
+      #
+      # Note that one normally never wants to use the same key and iv
+      # combination on two different messages as this weakens the security.
+      def to_aes(key, iv)
+        key_len = (key.bytesize * 8)
         return self.class.new( to_cipher("aes-#{key_len.to_i}-cbc", key, iv) )
       end
       
-      # Given an AES key and init vector, AES decode the data.
-      def from_aes(key, iv, key_len=256)
+      # Given an AES key and init vector, AES-CBC decode the data.
+      def from_aes(key, iv)
+        key_len = (key.bytesize * 8)
         return self.class.new( from_cipher("aes-#{key_len.to_i}-cbc", key, iv) )
       end
       

data/lib/secure_string/digest_methods.rb

@@ -1,12 +1,16 @@
 require 'openssl'
   
 class SecureString < String
+  # Adds methods for OpenSSL::Digest support.
+  # See DigestMethods::ClassMethods and DigestMethods::InstanceMethods for more details.
   module DigestMethods
     
     def self.included(mod)
       mod.send(:include, InstanceMethods)
     end
     
+    # Adds instance methods for OpenSSL::Digest support via inclusion of
+    # SecureString::DigestMethods to a class.
     module InstanceMethods
       
       # Returns the digest of the byte string as a SecureString, using the passed OpenSSL object.
@@ -19,6 +23,11 @@ class SecureString < String
         return to_digest( OpenSSL::Digest::MD5.new )
       end
       
+      # Returns the SHA1 of the byte string as SecureString
+      def to_sha1
+        return to_digest( OpenSSL::Digest::SHA1.new )
+      end
+      
       # Returns the SHA2 of the byte string as a SecureString.
       #
       # By default, this uses the 256 bit SHA2, but the optional arugment allows

data/lib/secure_string/rsa_methods.rb

@@ -1,6 +1,8 @@
 require 'openssl'
 
 class SecureString < String
+  # Adds methods for OpenSSL::PKey::RSA support.
+  # See RSAMethods::ClassMethods and RSAMethods::InstanceMethods for more details.
   module RSAMethods
     
     def self.included(mod)
@@ -8,15 +10,22 @@ class SecureString < String
       mod.send(:include, InstanceMethods)
     end
     
+    # Adds class methods for OpenSSL::PKey::RSA support via inclusion of
+    # SecureString::RSAMethods to a class.
     module ClassMethods
       
       # A convenience method for generating random public/private RSA key pairs.
-      # Defaults to a key length of 1024.
+      # Defaults to a key length of 2048, as 1024 is starting to be phased out
+      # as the standard for secure communications.
       #
       # Returns the private key first, then the public key.  Returns them in PEM file
       # format by default, as this is most useful for portability.  DER format can
       # be explicitly specified with the second argument.
-      def rsa_keygen(key_len=1024, format = :pem)
+      #
+      # For advanced usage of keys, instantiate an OpenSSL::PKey::RSA object
+      # passing the returned key as the argument to +new+.  This will allow
+      # introspection of common parameters such as p, q, n, e, and d.
+      def rsa_keygen(key_len=2048, format = :pem)
         private_key_obj = OpenSSL::PKey::RSA.new(key_len.to_i)
         public_key_obj = private_key_obj.public_key
         formatting_method = (format == :der ? :to_der : :to_pem)
@@ -25,6 +34,8 @@ class SecureString < String
       
     end
     
+    # Adds instance methods for OpenSSL::PKey::RSA support via inclusion of
+    # SecureString::RSAMethods to a class.
     module InstanceMethods
       
       # Given an RSA public key, it RSA encrypts the data string.
@@ -46,6 +57,7 @@ class SecureString < String
       #
       # By default, signs using SHA256, but another digest object can be given.
       def sign(private_key, digest_obj=OpenSSL::Digest::SHA256.new)
+        digest_obj = (digest_obj.kind_of?(Class) ? digest_obj.new : digest_obj)
         key = OpenSSL::PKey::RSA.new(private_key)
         return self.class.new( key.sign(digest_obj, self) )
       end
@@ -55,6 +67,7 @@ class SecureString < String
       #
       # By default, verifies using SHA256, but another digest object can be given.
       def verify?(public_key, signature, digest_obj=OpenSSL::Digest::SHA256.new)
+        digest_obj = (digest_obj.kind_of?(Class) ? digest_obj.new : digest_obj)
         key = OpenSSL::PKey::RSA.new(public_key)
         return key.verify(digest_obj, signature.to_s, self)
       end

data/spec/base64_methods_spec.rb

@@ -0,0 +1,46 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe "SecureString" do
+
+  describe "Base64 Methods" do
+    
+    before(:all) do
+      @messages = MESSAGES
+    end
+    
+    it 'should convert self to Base64; not URL safe' do
+      @messages.each do |message|
+        ss = SecureString.new(message[:string])
+        # First make sure that line feeds are being put in somewhere.
+        ss.to_base64(false).should include("\n")
+        # Now, compare the data itself (no line-feeds).
+        ss.to_base64(false).delete("\n").should == message[:base64].delete("\n")
+      end
+    end
+    
+    it 'should convert self to Base64; URL safe' do
+      @messages.each do |message|
+        ss = SecureString.new(message[:string])
+        # First make sure that there are no line feeds.
+        ss.to_base64(true).should_not include("\n")
+        # Now compare the result with the line-feed less expected value.
+        ss.to_base64(true).should == message[:base64].delete("\n")
+      end
+    end
+    
+    it 'should default to URL safe' do
+      @messages.each do |message|
+        ss = SecureString.new(message[:string])
+        ss.to_base64.should == ss.to_base64(true)
+      end
+    end
+    
+    it 'should convert self from Base64' do
+      @messages.each do |message|
+        ss = SecureString.new(message[:base64])
+        ss.from_base64.should == message[:string]
+      end
+    end
+  end
+  
+end

data/spec/cipher_methods_spec.rb

@@ -0,0 +1,128 @@
+describe "SecureString" do
+
+  describe "Cipher Methods" do
+    
+    describe "Keygen" do
+      
+      it 'should provide a keygen helper' do
+        SecureString.should respond_to(:cipher_keygen)
+      end
+      
+      it 'should provide generated keys as a SecureString class' do
+        key, iv = SecureString.cipher_keygen('DES')
+        
+        key.should_not be_nil
+        iv.should_not be_nil
+        
+        key.should be_kind_of(SecureString)
+        iv.should be_kind_of(SecureString)
+      end
+      
+      it 'should provide an AES keygen helper' do
+        SecureString.should respond_to(:aes_keygen)
+      end
+      
+      it 'should provide generated AES keysas a SecureString class' do
+        key, iv = SecureString.aes_keygen
+        
+        key.should_not be_nil
+        iv.should_not be_nil
+        
+        key.should be_kind_of(SecureString)
+        iv.should be_kind_of(SecureString)
+      end
+      
+      it 'should provide AES keys of various bit lengths' do
+        [128,192,256].each do |bits|
+          key, iv = SecureString.aes_keygen(bits)
+          (key.bytesize * 8).should == bits
+        end
+      end
+      
+      it 'should raise an exception in an invalid AES bit length' do
+        lambda {SecureString.aes_keygen(1234)}.should raise_error
+      end
+      
+      it 'should default to a 256 bit AES key' do
+        key, iv = SecureString.aes_keygen
+        (key.bytesize * 8).should == 256
+      end
+      
+      it 'should provide a list of supported ciphers' do
+        SecureString.should respond_to(:supported_ciphers)
+        SecureString.supported_ciphers.should be_kind_of(Array)
+      end
+      
+    end
+    
+    describe "Cipher" do
+      
+      before(:all) do
+        @cipher = "DES"
+        @key = SecureString.new(:hex, "4f42383e091ffc44")
+        @iv = SecureString.new(:hex, "0b9299d6c2cb5003")
+        @message = SecureString.new("We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.")
+        @encoded_message = SecureString.new(:hex, "cfe8245b2c1f3f789b8ab78930c9582d1fead6792d8fe7efd418ba06d7da4e96f8525e8b437cf29af71ec66801c2031292fc17d88f5aaa9c776b3ca048169b48394e05d5ae6cbba5c78461a25bc3d5abc646f5f760e3a159b8448d79eed80a209473ca67536ebf417a24f05cf029e9e3ca5b1fb22e4e03427705d79b622d720c7d64cf3621319581a1a89b4cbb630611eea29cbd2c48caef0cf774ea0218b16d600cb4c025dcae177b702040bd7c62569bbda33f8e775dbadba4154074f482385c56449882efa31b908dfe5be17d8c0d220fd99414a78f6ce3cfee007fbd5dfc7fd50c343e6118d1a9174bb75db7c5adbaa558010f56571d087982ae791960c31041bae08adfa4d1a88f457897e38bd56a7e92234d21c8742fa577878b2d65500877d2f910d1fdbb5460afa73642778de8bd4442981baa93a481482f1cfb90fa85025ddf8588ecc7")
+      end
+      
+      it 'should encode to a SecureString' do
+        @message.to_cipher(@cipher, @key, @iv).should be_kind_of(SecureString)
+      end
+      
+      it 'should encode with a given cipher and key' do
+        encoded_message = @message.to_cipher(@cipher, @key, @iv)
+        encoded_message.should == @encoded_message
+      end
+      
+      it 'should decode to a secure string' do
+        @encoded_message.from_cipher(@cipher, @key, @iv).should be_kind_of(SecureString)
+      end
+      
+      it 'should decode with a given cipher and key' do
+        decoded_message = @encoded_message.from_cipher(@cipher, @key, @iv)
+        decoded_message.should == @message
+      end
+      
+    end
+    
+    describe "AES" do
+      
+      before(:all) do
+        @key = SecureString.new(:hex, "83f8577c1bc406e85ceeebc166c9fd4d087670de792b0d957c58f1beae6fb514")
+        @iv = SecureString.new(:hex, "778c1086b5daf809e7abadde6995219d")
+        @message = SecureString.new("We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.")
+        @encoded_message = SecureString.new(:hex, "1fee4d01d33daf50915dc4b7aaf8b536f3b19ee9798b21200d475925460fd3aabc581d89e560b7b826e6017e02911687425d9c4a781d8e03a9d75dab5a85191f86b11fb74063133c3952201a8f2089afb0e298e29fe8becbe93ce110073b9abb968a268857aaabd94caa760fa402ce803f8643ad8870e77714b093e9ea09a4ad9d7e056836939f614a61f6b3e09057bc05f13432aa53cfc7de59d41a121f9fcb7c51825da2615c48debff6ed0fbaa0c85594aef54e11b73b8766f6e56d2cf7488909c14272e846cccca0008599bae334c5d404c122d286dcf04eec7b7711978686a66182f53e569297b91c25100ecfdad1f02de444c4de8f9d04067e885a2a17cad707b51ea8c2e8a15051138de617f8864cca8a4d201246a97b95cee5f78f742aace79629e03498f63b6385cff64d53a0425f7f52c6a8ba65771e043590b61191804fe91760e617412d842831928e57")
+      end
+      
+      it 'should encode to a SecureString' do
+        @message.to_aes(@key, @iv).should be_kind_of(SecureString)
+      end
+      
+      it 'should encode with a key' do
+        encoded_message = @message.to_aes(@key, @iv)
+        encoded_message.should == @encoded_message
+      end
+      
+      it 'should decode to a secure string' do
+        @encoded_message.from_aes(@key, @iv).should be_kind_of(SecureString)
+      end
+      
+      it 'should decode with a key' do
+        decoded_message = @encoded_message.from_aes(@key, @iv)
+        decoded_message.should == @message
+      end
+      
+      it 'should encode and decode from a non 256 bit key' do
+        key, iv = SecureString.aes_keygen(128)
+        encoded_message = @message.to_aes(key, iv)
+        decoded_message = encoded_message.from_aes(key, iv)
+        
+        encoded_message.should_not == decoded_message
+        decoded_message.should == @message
+      end
+      
+    end
+    
+  end
+  
+end

data/spec/digest_methods_spec.rb

@@ -0,0 +1,121 @@
+# Make sure to test that the cipher methods are from openssl and not jsut digest?
+
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe "SecureString" do
+
+  describe "Digest Methods" do
+    
+    describe "to_digest" do
+      
+      before(:all) do
+        @openssl_digest_class_sample = [OpenSSL::Digest::MD5, OpenSSL::Digest::SHA1, OpenSSL::Digest::SHA256, OpenSSL::Digest::SHA512]
+        @digest_class_sample = [Digest::MD5, Digest::SHA1, Digest::SHA256, Digest::SHA512]
+        
+        @message = SecureString.new("Hello World!")
+        @message_md5_hex = "ed076287532e86365e841e92bfc50d8c"
+        @message_sha512_hex = "861844d6704e8573fec34d967e20bcfef3d424cf48be04e6dc08f2bd58c729743371015ead891cc3cf1c9d34b49264b510751b1ff9e537937bc46b5d6ff4ecc8"
+      end
+      
+      it 'should encode as a SecureString' do
+        @message.to_digest(OpenSSL::Digest::MD5).should be_kind_of(SecureString)
+        @message.to_digest(OpenSSL::Digest::SHA512).should be_kind_of(SecureString)
+      end
+      
+      it 'should contain the raw value, not the hex value' do
+        md5 = @message.to_digest(OpenSSL::Digest::MD5)
+        md5.should_not == @message_md5_hex
+        md5.to_hex.should == @message_md5_hex
+        
+        sha512 = @message.to_digest(OpenSSL::Digest::SHA512)
+        sha512.should_not == @message_sha512_hex
+        sha512.to_hex.should == @message_sha512_hex
+      end
+      
+      it 'should take an OpenSSL::Digest class' do
+        @openssl_digest_class_sample.each do |klass|
+          @message.to_digest(klass).to_hex.should == klass.hexdigest(@message)
+        end
+      end
+      
+      it 'should take an OpenSSL::Digest instance' do
+        @openssl_digest_class_sample.each do |klass|
+          @message.to_digest(klass.new).to_hex.should == klass.hexdigest(@message)
+        end
+      end
+      
+      it 'should take a Digest class' do
+        @digest_class_sample.each do |klass|
+          @message.to_digest(klass).to_hex.should == klass.hexdigest(@message)
+        end
+      end
+      
+      it 'should take a Digest instance' do
+        @digest_class_sample.each do |klass|
+          @message.to_digest(klass.new).to_hex.should == klass.hexdigest(@message)
+        end
+      end
+      
+    end
+    
+    
+    describe "Convenience Methods" do
+      
+      before(:all) do
+        @message = SecureString.new("Hello World!")
+        
+        @hex_digests = {
+          :md5 => "ed076287532e86365e841e92bfc50d8c",
+          :sha1 => "2ef7bde608ce5404e97d5f042f95f89f1c232871",
+          :sha256 => "7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
+          :sha512 => "861844d6704e8573fec34d967e20bcfef3d424cf48be04e6dc08f2bd58c729743371015ead891cc3cf1c9d34b49264b510751b1ff9e537937bc46b5d6ff4ecc8"
+        }
+      end
+      
+      it 'should MD5' do
+        @message.should respond_to(:to_md5)
+        digest = @message.to_md5
+        digest.should be_kind_of(SecureString)
+        digest.to_hex.should == @hex_digests[:md5]
+      end
+      
+      it 'should SHA1' do
+        @message.should respond_to(:to_sha1)
+        digest = @message.to_sha1
+        digest.should be_kind_of(SecureString)
+        digest.to_hex.should == @hex_digests[:sha1]
+      end
+      
+      it 'should SHA2-256' do
+        @message.should respond_to(:to_sha256)
+        digest = @message.to_sha256
+        digest.should be_kind_of(SecureString)
+        digest.to_hex.should == @hex_digests[:sha256]
+      end
+      
+      it 'should SHA2=512' do
+        @message.should respond_to(:to_sha512)
+        digest = @message.to_sha512
+        digest.should be_kind_of(SecureString)
+        digest.to_hex.should == @hex_digests[:sha512]
+      end
+      
+      it 'should SHA2' do
+        @message.should respond_to(:to_sha2)
+        digest = @message.to_sha2
+        digest.should be_kind_of(SecureString)
+        digest.should == @message.to_sha2(256)
+        
+        digest = @message.to_sha2(256)
+        digest.should_not == @hex_digests[:sha256]
+        digest.to_hex.should == @hex_digests[:sha256]
+        
+        digest = @message.to_sha2(512)
+        digest.should_not == @hex_digests[:sha512]
+        digest.to_hex.should == @hex_digests[:sha512]
+      end
+      
+    end
+  end
+  
+end

data/spec/rsa_methods_spec.rb

@@ -0,0 +1,166 @@
+describe "SecureString" do
+
+  describe "RSA Methods" do
+    
+    describe "Keygen" do
+      
+      it 'should generate a public/private key pair' do
+        SecureString.should respond_to(:rsa_keygen)
+      end
+      
+      it 'should generate key pairs of varying length' do
+        [256, 512, 1024, 2048].each do |bits|
+          pvt_key, pub_key = SecureString.rsa_keygen(bits)
+          [pvt_key, pub_key].each do |key|
+            key_obj = OpenSSL::PKey::RSA.new(key)
+            # The bit length of the key is the bit length of the modulus, n.
+            # It turns out that an OpenSSL::PKey::RSA object returns an
+            # OpenSSL::BN object when you get the modulus, which has a nice
+            # little method for getting the number of bytes it is long.
+            key_length_in_bits = key_obj.n.num_bytes * 8
+            key_length_in_bits.should == bits
+          end
+        end
+      end
+      
+      it 'should default to a 2048 bit key' do
+        pvt_key, pub_key = SecureString.rsa_keygen
+        [pvt_key, pub_key].each do |key|
+          key_obj = OpenSSL::PKey::RSA.new(key)
+          # The bit length of the key is the bit length of the modulus, n.
+          # It turns out that an OpenSSL::PKey::RSA object returns an
+          # OpenSSL::BN object when you get the modulus, which has a nice
+          # little method for getting the number of bytes it is long.
+          key_length_in_bits = key_obj.n.num_bytes * 8
+          key_length_in_bits.should == 2048
+        end
+      end
+      
+      it 'should return key pairs as SecureString instances' do
+        pvt_key, pub_key = SecureString.rsa_keygen
+        [pvt_key, pub_key].each do |key|
+          key.should be_kind_of(SecureString)
+        end
+      end
+      
+      it 'should support both pem and der formats' do
+        [:pem, :der].each do |format|
+          pvt_key, pub_key = SecureString.rsa_keygen(512, format)
+          [pvt_key, pub_key].each do |key|
+            key_obj = OpenSSL::PKey::RSA.new(key)
+            key.should == key_obj.send("to_#{format}".to_sym)
+          end
+        end
+      end
+      
+      it 'should default to pem format' do
+        pvt_key, pub_key = SecureString.rsa_keygen
+        [pvt_key, pub_key].each do |key|
+          key_obj = OpenSSL::PKey::RSA.new(key)
+          key.should == key_obj.to_pem
+        end
+      end
+      
+    end
+    
+    describe "Encryption" do
+      
+      before(:all) do
+        @key_length = 128
+        @pvt_key = SecureString.new(:hex, "2d2d2d2d2d424547494e205253412050524956415445204b45592d2d2d2d2d0a4d47454341514143455143364c704764426d334a78495048513945345537443141674d424141454345474c62517a6e724a6652525762433365474b3561656b430a4351446d633569312f5669666277494a414d37536b4534554b7750624167682b7831316430564274395149494a4648372f346f784a364d4343474e646e3933330a4a43774d0a2d2d2d2d2d454e44205253412050524956415445204b45592d2d2d2d2d0a")
+        @pub_key = SecureString.new(:hex, "2d2d2d2d2d424547494e20525341205055424c4943204b45592d2d2d2d2d0a4d426743455143364c704764426d334a78495048513945345537443141674d424141453d0a2d2d2d2d2d454e4420525341205055424c4943204b45592d2d2d2d2d0a")
+        @message = SecureString.new("Hello")
+      end
+      
+      it 'should encrypt and decrypt to a SecureString' do
+        encrypted_message = @message.to_rsa(@pub_key)
+        encrypted_message.should be_kind_of(SecureString)
+        decrypted_message = encrypted_message.from_rsa(@pvt_key)
+        decrypted_message.should be_kind_of(SecureString)
+      end
+      
+      # We cannot independently test encryption because it changes everytime
+      # thanks to padding generation.
+      it 'should encrypt and decrypy a message' do
+        encrypted_message = @message.to_rsa(@pub_key)
+        (encrypted_message.bytesize * 8).should == @key_length
+        
+        decrypted_message = encrypted_message.from_rsa(@pvt_key)
+        decrypted_message.should == @message
+      end
+      
+    end
+    
+    
+    describe "Verification" do
+      
+      before(:all) do
+        @key_length = 1024
+        @alice_pvt_key, @alice_pub_key = SecureString.rsa_keygen(@key_length)
+        @bob_pvt_key, @bob_pub_key = SecureString.rsa_keygen(@key_length)
+        
+        @message = SecureString.new("Hello")
+      end
+      
+      it 'should sign and verify a message using a private key' do
+        # Alice encrypts a message for Bob and signs is.
+        @encrypted_message = @message.to_rsa(@bob_pub_key)
+        @signature = @encrypted_message.sign(@alice_pvt_key)
+        
+        # Verify it came from Alice.
+        is_verified = @encrypted_message.verify?(@alice_pub_key, @signature)
+        is_verified.should be_true
+        
+        # Verify it did not come from Bob.
+        is_verified = @encrypted_message.verify?(@bob_pub_key, @signature)
+        is_verified.should be_false
+        
+        # Bob should now decrypt it
+        @decrypted_message = @encrypted_message.from_rsa(@bob_pvt_key)
+        @decrypted_message.should == @message
+      end
+      
+      it 'should default to signing with SHA-256' do
+        encrypted_message = @message.to_rsa(@bob_pub_key)
+        encrypted_message.sign(@alice_pvt_key).should == encrypted_message.sign(@alice_pvt_key, OpenSSL::Digest::SHA256.new)
+      end
+      
+      it 'should allow signing with other digest' do
+        encrypted_message = @message.to_rsa(@bob_pub_key)
+        comparison_digest_klass = OpenSSL::Digest::SHA256
+        [OpenSSL::Digest::SHA512, OpenSSL::Digest::MD5, OpenSSL::Digest::SHA1].each do |digest_klass|
+          next if digest_klass == comparison_digest_klass
+          signature = encrypted_message.sign(@alice_pvt_key, digest_klass.new)
+          signature.should_not == encrypted_message.sign(@alice_pvt_key, comparison_digest_klass.new)
+        end
+      end
+      
+      it 'should allow passing the digest method as an instance or class' do
+        encrypted_message = @message.to_rsa(@bob_pub_key)
+        [OpenSSL::Digest::SHA512, OpenSSL::Digest::SHA256, OpenSSL::Digest::MD5, OpenSSL::Digest::SHA1].each do |digest_klass|
+          signature1 = encrypted_message.sign(@alice_pvt_key, digest_klass.new)
+          signature2 = encrypted_message.sign(@alice_pvt_key, digest_klass)
+          signature1.should == signature2
+        end
+      end
+      
+      it 'should work with Digest scoped digest classes' do
+        pending "TODO: postponing feature"
+        encrypted_message = @message.to_rsa(@bob_pub_key)
+        signature1 = encrypted_message.sign(@alice_pvt_key, Digest::SHA256)
+        signature2 = encrypted_message.sign(@alice_pvt_key, OpenSSL::Digest::SHA256)
+        signature1.should == signature2
+      end
+      
+      it 'should work with Digest scoped digest instances' do
+        pending "TODO: postponing feature"
+        encrypted_message = @message.to_rsa(@bob_pub_key)
+        signature1 = encrypted_message.sign(@alice_pvt_key, Digest::SHA256.new)
+        signature2 = encrypted_message.sign(@alice_pvt_key, OpenSSL::Digest::SHA256.new)
+        signature1.should == signature2
+      end
+      
+    end
+    
+  end
+end

data/spec/secure_string_spec.rb

@@ -0,0 +1,90 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe "SecureString" do
+  
+  before(:all) do
+    @messages = MESSAGES
+  end
+  
+  it 'should be a subclass of String' do
+    (SecureString < String).should be_true
+  end
+  
+  it 'should initialize like a string by default.' do
+    @messages.each do |message|
+      s = String.new(message[:string])
+      ss = SecureString.new(message[:string])
+      ss.should == s
+    end
+  end
+  
+  it 'should initialize from hex' do
+    @messages.each do |message| 
+      ss = SecureString.new(:hex, message[:hex])
+      ss.should == message[:string]
+    
+      ss = SecureString.new(:hex, message[:hex].upcase)
+      ss.should == message[:string]
+    end
+  end
+  
+  it 'should initialize from data' do
+    @messages.each do |message|
+      ss = SecureString.new(:data, message[:string])
+      ss.should == message[:string]
+    end
+  end
+  
+  it 'should initialize from int' do
+    @messages.each do |message|
+      ss = SecureString.new(:int, message[:int])
+      ss.should == message[:string]
+    end
+  end
+  
+  it 'should initialize from Base64' do
+    @messages.each do |message|
+      ss = SecureString.new(:base64, message[:base64])
+      ss.should == message[:string]
+    end
+    
+    # We also want to make sure non newline terminated, and multi-line messages
+    # work right.  The sample data should contain at least one with multiple
+    # linefeeds, and one with no linefeeds.
+    newline_count = @messages.map {|message| message[:base64].delete("^\n").length}
+    newline_count.should include(0)
+    newline_count.select {|nl_count| nl_count > 1}.should_not be_empty
+  end
+  
+  it 'should be able to convert to a hex string' do
+    @messages.each do |message|
+      ss = SecureString.new(message[:string])
+      ss.to_hex.should == message[:hex]
+    end
+  end
+  
+  it 'should be able to convert to an int value' do
+    @messages.each do |message|
+      ss = SecureString.new(message[:string])
+      ss.to_i.should == message[:int]
+    end
+  end
+  
+  it 'should output like a string for to_s' do
+    @messages.each do |message|
+      s = String.new(message[:string])
+      ss = SecureString.new(message[:string])
+      ss.to_s.should == s.to_s
+    end
+  end
+  
+  it 'should output the hex value with inspect' do
+    @messages.each do |message|
+      s = String.new(message[:string])
+      ss = SecureString.new(message[:string])
+      ss.inspect.should include(ss.to_hex)
+      ss.inspect.should_not include(s.to_s)
+    end
+  end
+  
+end

data/spec/spec_helper.rb

@@ -1,4 +1,20 @@
 # Add the lib dir to the load path.
 $LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
 # Require the main require file.
-require File.basename(File.expand_path(File.join(File.dirname(__FILE__),'..')))
+require File.basename(File.expand_path(File.join(File.dirname(__FILE__),'..')))
+
+MESSAGES = [
+  {
+    :string => "Hello",
+    :hex => "48656c6c6f",
+    :int => 310939249775,
+    :base64 => "SGVsbG8="
+  },
+  
+  {
+    :string => "This is a test of the emergency broadcast system; this is only a test.",
+    :hex => "5468697320697320612074657374206f662074686520656d657267656e63792062726f6164636173742073797374656d3b2074686973206973206f6e6c79206120746573742e",
+    :int => 1244344095146357680190496293767338268850834164562379171846588371816488740307922111470765515885864931093899586331709567338989540039042962957732585272476408412061178229806,
+    :base64 => "VGhpcyBpcyBhIHRlc3Qgb2YgdGhlIGVtZXJnZW5jeSBicm9hZGNhc3Qgc3lz\ndGVtOyB0aGlzIGlzIG9ubHkgYSB0ZXN0Lg==\n"
+  }
+].freeze

metadata

@@ -3,10 +3,10 @@ name: secure_string
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 9
   - 0
-  version: 0.9.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Jeff Reinecke
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-03 00:00:00 -07:00
+date: 2010-11-04 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -35,6 +35,11 @@ files:
 - lib/secure_string/digest_methods.rb
 - lib/secure_string/rsa_methods.rb
 - lib/secure_string.rb
+- spec/base64_methods_spec.rb
+- spec/cipher_methods_spec.rb
+- spec/digest_methods_spec.rb
+- spec/rsa_methods_spec.rb
+- spec/secure_string_spec.rb
 - spec/spec_helper.rb
 has_rdoc: true
 homepage: http://www.github.com/paploo/secure_string