secure_string 0.9.0

data/LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2010, Jeffrey C. Reinecke
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the copyright holders nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL JEFFREY REINECKE BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,63 @@
+= Overview
+
+SecureString is a special string subclass that provides two pieces of
+functionality that can be used individually:
+
+* Byte string support:  Although a string can already contain bytes, this makes
+  it easier to view and work with strings holding binary data, including
+  conversion to/from raw hex or Base64 encoded values.
+* Secure string support: Easy methods for RSA encryption, AES encoding, and
+  SHA/MD5 digest hashing, of the data in the strings.
+  
+= Contact
+
+If you have any questions, comments, concerns, patches, or bugs, you can contact
+me via the github repository at:
+
+http://github.com/paploo/secure_string
+
+or directly via e-mail at:
+
+mailto:jeff@paploo.net
+
+= Version History
+
+[0.9.0 - 2010-Nov-03] Initial release.
+                      * Feature complete, but lacks spec tests and examples.
+                      
+= TODO List
+
+* Add complete spec tests.
+* Add examples.
+
+= License
+
+The files contained in this repository are released under the commercially and
+GPL compatible "New BSD License", given below:
+
+== License Text
+
+    Copyright (c) 2010, Jeffrey C. Reinecke
+    All rights reserved.
+    
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+        * Redistributions of source code must retain the above copyright
+          notice, this list of conditions and the following disclaimer.
+        * Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+        * Neither the name of the copyright holders nor the
+          names of its contributors may be used to endorse or promote products
+          derived from this software without specific prior written permission.
+    
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL JEFFREY REINECKE BE LIABLE FOR ANY
+    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rake'
+require "rake/rdoctask"
+
+# ===== RDOC BUILDING =====
+# This isn't necessary if installing from a gem.
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.rdoc_files.add "lib/**/*.rb", "README.rdoc"
+end
+
+# ===== SPEC TESTING =====
+
+begin
+  require "spec/rake/spectask"
+  
+  Spec::Rake::SpecTask.new(:spec) do |spec|
+    spec.spec_opts = ['-c' '-f specdoc']
+    spec.spec_files = ['spec']
+  end
+  
+  Spec::Rake::SpecTask.new(:spec_with_backtrace) do |spec|
+    spec.spec_opts = ['-c' '-f specdoc', '-b']
+    spec.spec_files = ['spec']
+  end
+rescue LoadError
+  task :spec do
+    puts "You must have rspec installed to run this task."
+  end
+end
+
+# ===== GEM BUILDING =====
+
+desc "Build the gem file for this package"
+task :build_gem do
+  STDOUT.puts `gem build secure_string.gemspec`
+end

data/lib/secure_string.rb

@@ -0,0 +1,59 @@
+require 'base64'
+
+require_relative 'secure_string/digest_methods'
+require_relative 'secure_string/base64_methods'
+require_relative 'secure_string/cipher_methods'
+require_relative 'secure_string/rsa_methods'
+
+# SecureString is a String subclass whose emphasis is on byte data rather than
+# human readable strings. class gives a number of conveniences, such
+# as  easier viewing of the byte data as hex, digest methods, and encryption
+# and decryption methods.
+class SecureString < String
+  include Base64Methods
+  include DigestMethods
+  include RSAMethods
+  include CipherMethods
+  
+  # Creates the string from one many kinds of values:
+  # [:data] (default) The passed string value is directly used.
+  # [:hex] Initialize using a hexidecimal string.
+  # [:int] Initialize using the numeric value of the hexidecimal string.
+  # [:base64] Initialize using the given base64 encoded data.
+  def initialize(mode = :data, value)
+    case mode
+    when :hex
+      hex_string = value.to_s
+      data = [hex_string].pack('H' + hex_string.length.to_s)
+    when :data
+      data = value.to_s
+    when :int
+      self.send(__method__, :hex, value.to_i.to_s(16))
+    when :base64
+      data = Base64.decode64(value.to_s)
+    end
+    
+    self.replace(data)
+  end
+  
+  # Override the default String inspect to return the hexidecimal
+  # representation of the data contained in this string.
+  def inspect
+    return "<#{to_hex}>"
+  end
+  
+  # Returns the hexidecimal string representation of the data.
+  def to_hex
+    return (self.empty? ? '' : self.unpack('H' + (self.length*2).to_s)[0])
+  end
+  
+  # Returns the data converted from hexidecimal into an integer.
+  # This is usually as a BigInt.
+  #
+  # WARNING: If the data string is empty, then this returns -1, as there is no
+  # integer representation of the absence of data.
+  def to_i
+    return (self.empty? ? -1 : to_hex.hex)
+  end
+  
+end

data/lib/secure_string/base64_methods.rb

@@ -0,0 +1,28 @@
+require 'base64'
+
+class SecureString < String
+  module Base64Methods
+    
+    def self.included(mod)
+      mod.send(:include, InstanceMethods)
+    end
+    
+    module InstanceMethods
+      
+      # Encodes to Base64.  By default, the output is made URL safe, which means all
+      # newlines are stripped out.  If you want standard formatted Base64 with
+      # newlines, then call this method with url_safe as false.
+      def to_base64(url_safe = true)
+        encoded_data = (url_safe ? Base64.urlsafe_encode64(self) : Base64.encode64(self))
+        return self.class.new( encoded_data )
+      end
+      
+      # Decode self as a Base64 data string and return the result.
+      def from_base64
+        return self.class.new( Base64.decode64(self) )
+      end
+      
+    end
+    
+  end
+end

data/lib/secure_string/cipher_methods.rb

@@ -0,0 +1,76 @@
+require 'openssl'
+
+class SecureString < String
+  module CipherMethods
+    
+    def self.included(mod)
+      mod.send(:extend, ClassMethods)
+      mod.send(:include, InstanceMethods)
+    end
+    
+    module ClassMethods
+      
+      # A convenience method for generating random cipher keys and initialization
+      # vectors.
+      def cipher_keygen(cipher_name)
+        cipher = OpenSSL::Cipher::Cipher.new(cipher_name)
+        cipher.encrypt
+        return [cipher.random_key, cipher.random_iv].map {|s| self.new(s)}
+      end
+      
+      # A convenience method for generating a random key and init vector for AES keys.
+      # Defaults to a key length of 256.
+      def aes_keygen(key_len=256)
+        return cipher_keygen("aes-#{key_len.to_i}-cbc")
+      end
+      
+    end
+    
+    module InstanceMethods
+      
+      # Given an OpenSSL cipher name, a key, and initialization vector,
+      # encrypt the data.
+      #
+      # Use OpenSSL::Cipher.ciphers to get a list of available cipher names.
+      #
+      # To generate a new key and iv, do the following:
+      #   cipher = OpenSSL::Cipher::Cipher.new(cipher_name)
+      #   cipher.encrypt
+      #   key = cipher.random_key
+      #   iv = cipher.random_iv
+      def to_cipher(cipher_name, key, iv)
+        cipher = OpenSSL::Cipher.new(cipher_name)
+        cipher.encrypt # MUST set the mode BEFORE setting the key and iv!
+        cipher.key = key
+        cipher.iv = iv
+        msg = cipher.update(self)
+        msg << cipher.final
+        return self.class.new(msg)
+      end
+      
+      # Given an OpenSSL cipher name, a key, and an init vector,
+      # decrypt the data.
+      def from_cipher(cipher_name, key, iv)
+        cipher = OpenSSL::Cipher.new(cipher_name)
+        cipher.decrypt # MUST set the mode BEFORE setting the key and iv!
+        cipher.key = key
+        cipher.iv = iv
+        msg = cipher.update(self)
+        msg << cipher.final
+        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)
+        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)
+        return self.class.new( from_cipher("aes-#{key_len.to_i}-cbc", key, iv) )
+      end
+      
+    end
+    
+  end
+end

data/lib/secure_string/digest_methods.rb

@@ -0,0 +1,48 @@
+require 'openssl'
+  
+class SecureString < String
+  module DigestMethods
+    
+    def self.included(mod)
+      mod.send(:include, InstanceMethods)
+    end
+    
+    module InstanceMethods
+      
+      # Returns the digest of the byte string as a SecureString, using the passed OpenSSL object.
+      def to_digest(digest_obj)
+        return self.class.new( digest_obj.digest(self) )
+      end
+      
+      # Returns the MD5 of the byte string as a SecureString.
+      def to_md5
+        return to_digest( OpenSSL::Digest::MD5.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
+      # specification of which bit length to use.
+      def to_sha2(length=256)
+        if [224,256,384,512].include?(length)
+          digest_klass = OpenSSL::Digest.const_get("SHA#{length}", false)
+          return to_digest( digest_klass )
+        else
+          raise ArgumentError, "Invalid SHA2 length: #{length}"
+        end
+      end
+      
+      # Returns the SHA2 256 of the data string.  See +to_sha2+.
+      def to_sha256
+        return to_sha2(256)
+      end
+      
+      # Returns the SHA2 512 of the data string.  See +to_sha2+.
+      def to_sha512
+        return to_sha2(512)
+      end
+      
+    end
+    
+  end
+end

data/lib/secure_string/rsa_methods.rb

@@ -0,0 +1,65 @@
+require 'openssl'
+
+class SecureString < String
+  module RSAMethods
+    
+    def self.included(mod)
+      mod.send(:extend, ClassMethods)
+      mod.send(:include, InstanceMethods)
+    end
+    
+    module ClassMethods
+      
+      # A convenience method for generating random public/private RSA key pairs.
+      # Defaults to a key length of 1024.
+      #
+      # 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)
+        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)
+        return [private_key_obj, public_key_obj].map {|k| self.new( k.send(formatting_method) )}
+      end
+      
+    end
+    
+    module InstanceMethods
+      
+      # Given an RSA public key, it RSA encrypts the data string.
+      #
+      # Note that the key must be 11 bytes longer than the data string or it doesn't
+      # work.
+      def to_rsa(public_key)
+        key = OpenSSL::PKey::RSA.new(public_key)
+        return self.class.new( key.public_encrypt(self) )
+      end
+      
+      # Given an RSA private key, it decrypts the data string back into the original text.
+      def from_rsa(private_key)
+        key = OpenSSL::PKey::RSA.new(private_key)
+        return self.class.new( key.private_decrypt(self) )
+      end
+      
+      # Signs the given message using hte given private key.
+      #
+      # By default, signs using SHA256, but another digest object can be given.
+      def sign(private_key, digest_obj=OpenSSL::Digest::SHA256.new)
+        key = OpenSSL::PKey::RSA.new(private_key)
+        return self.class.new( key.sign(digest_obj, self) )
+      end
+      
+      # Verifies the given signature matches the messages digest, using the
+      # signer's public key.
+      #
+      # By default, verifies using SHA256, but another digest object can be given.
+      def verify?(public_key, signature, digest_obj=OpenSSL::Digest::SHA256.new)
+        key = OpenSSL::PKey::RSA.new(public_key)
+        return key.verify(digest_obj, signature.to_s, self)
+      end
+      
+    end
+    
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+# 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__),'..')))

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: secure_string
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 9
+  - 0
+  version: 0.9.0
+platform: ruby
+authors: 
+- Jeff Reinecke
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-03 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: "    A String subclass to simplify handling of:\n      1. Binary data, including HEX encoding and Bin64 encoding.\n      2. Encryption such as RSA, AES, and digest methods such as SHA and MD5.\n"
+email: jeff@paploo.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- LICENSE.txt
+- Rakefile
+- lib/secure_string/base64_methods.rb
+- lib/secure_string/cipher_methods.rb
+- lib/secure_string/digest_methods.rb
+- lib/secure_string/rsa_methods.rb
+- lib/secure_string.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://www.github.com/paploo/secure_string
+licenses: 
+- BSD
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 9
+      - 2
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A String subclass for simple handling of binary data and encryption.
+test_files: []
+