right_support 2.8.1 → 2.8.2

data/VERSION

@@ -1 +1 @@
-2.8.1
+2.8.2

data/lib/right_support/crypto/signed_hash.rb

@@ -20,72 +20,181 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+require 'digest/md5'
 require 'digest/sha1'
+require 'digest/sha2'
+require 'openssl'
 
 module RightSupport::Crypto
+  # An easy way to compute digital signatures of data contained in a Ruby hash. To work with
+  # signed hashes, you must first obtain an asymmetric key pair (any subclass of OpenSSL::PKey);
+  # you can generate it from scratch or load it from a file on disk.
+  #
+  # Signature computation is influenced by four factors:
+  #    - The digital signature algorithm and key length
+  #    - The encoding used to serialize the hash contents to a byte stream
+  #    - The hash algorithm used to compute a message digest of the byte stream
+  #    - The OpenSSL API level used (EVP or raw crypto API)
+  #
+  # You are responsible for providing the PKey object, which determines the signature algorithm
+  # and key length. This occasionally constrains your choice of hash algorithm; for instance,
+  # a 512-bit RSA key would not be sufficiently long to create signatures of a SHA3-512 hash
+  # due to the mathematical underpinnings of the RSA cipher. In practice this is not an issue,
+  # because you should be using strong RSA keys (2048 bit or higher) for security reasons,
+  # and even the strongest hash algorithms do not exceed 512-bit output. 
+  #
+  # SignedHash provides reasonable defaults for the other three factors:
+  #     - JSON for message encoding (Yajl gem, JSON gem, Oj gem or built-in Ruby 1.9 JSON)
+  #     - SHA1 for message digest
+  #     - raw crypto API (for compatibility with older RightSupport versions)
+  #
+  # If you are adopting SignedHash for a new use case, it's best to use the default
+  # encoding and message digest, but specify :envelope=>true to use the OpenSSL EVP
+  # API! Using an envelope provides better protection against various cryptographic
+  # attacks and ensures that the sign and verify operations can't be used.
+  #
+  # SignedHash defaults to raw-crypto signatures for compatibility reasons, but
+  # with RightSupport v3 the raw-crypto will be deprecated and EVP will be used by default.
+  #
+  # @see OpenSSL::PKey
+  # @see Digest
   class SignedHash
+    # The default encoding to use when dumping the hash to binary form. Defaults to any available
+    # commonly-known JSON library, in the following order of preference:
+    #  - Yajl (ruby-yajl gem)
+    #  - JSON (json gem, or built-in JSON parser for ruby >= 1.9)
+    #  - Oj (oj gem)
+    #  - nil (if no JSON library is present)
+    # @!parse DefaultEncoding = nil
 
     if require_succeeds?('yajl')
       DefaultEncoding = ::Yajl
-    elsif require_succeeds?('oj')
-      DefaultEncoding = ::Oj
     elsif require_succeeds?('json')
       DefaultEncoding = ::JSON
+    elsif require_succeeds?('oj')
+      DefaultEncoding = ::Oj
     else
       DefaultEncoding = nil
     end unless defined?(DefaultEncoding)
 
     DEFAULT_OPTIONS = {
       :digest   => Digest::SHA1,
-      :encoding => DefaultEncoding
+      :envelope => false,
+      :encoding => DefaultEncoding,
+    }
+
+    # Mapping of Ruby built-in hash algorithms to their OpenSSL counterparts
+    DIGEST_MAP = {
+      Digest::MD5  => OpenSSL::Digest::MD5,
+      Digest::SHA1 => OpenSSL::Digest::SHA1,
+      Digest::SHA2 => OpenSSL::Digest::SHA256,
     }
 
-    def initialize(hash={}, options={})
-      options = DEFAULT_OPTIONS.merge(options)
+    # Create a new sign/verify context, passing in a Hash full of data that is to be signed or
+    # verified. The new SignedHash will store a reference to the raw data, so be careful not to
+    # modify the data hash in a way that will influence the outcome of sign/verify!
+    #
+    # @param [Hash] hash the actual data that is to be signed
+    # @option opts [Class] :digest hash-algorithm class from Ruby's Digest module MD5, SHA1 or SHA2; default SHA1
+    # @option opts [true,false] :envelope use the OpenSSL EVP API if true, or raw-crypto API if false; default false
+    # @option opts [#dump] :encoding serialization method for dumping hash data; default DefaultEncoding
+    # @option opts [OpenSSL::PKey] :public_key key to use when verifying digital signatures
+    # @option opts [OpenSSL::PKey] :private_key key to use when computing digital signatures
+    #
+    # @see DefaultEncoding
+    def initialize(hash={}, opts={})
+      opts = DEFAULT_OPTIONS.merge(opts)
       @hash        = hash
-      @digest      = options[:digest]
-      @encoding    = options[:encoding]
-      @public_key  = options[:public_key]
-      @private_key = options[:private_key]
+      @digest      = opts[:digest]
+      @encoding    = opts[:encoding]
+      @envelope    = !!opts[:envelope]
+      @public_key  = opts[:public_key]
+      @private_key = opts[:private_key]
       duck_type_check
     end
 
+    # Produce a digital signature of the hash contents, including the expiration timestamp
+    # of the signature. The caller must provide the exact same hash and expires_at in order
+    # to successfully verify the signature.
+    #
+    # @param [Time] expires_at
+    # @return [String] a binary signature of the hash's contents
     def sign(expires_at)
       raise ArgumentError, "Cannot sign; missing private_key" unless @private_key
       raise ArgumentError, "expires_at must be a Time in the future" unless time_check(expires_at)
 
       metadata = {:expires_at => expires_at}
-      @private_key.private_encrypt( digest( encode( canonicalize( frame(@hash, metadata) ) ) ) )
+      encoded = encode(canonicalize(frame(@hash, metadata)))
+
+      if @envelope
+        digest = DIGEST_MAP[@digest].new(encoded)
+
+        @private_key.sign(digest, encoded)
+      else
+        digest = @digest.new.update(encoded).digest
+        @private_key.private_encrypt(digest)
+      end
     end
 
+    # Verify a digital signature of the hash's contents. In order for the signature to verify,
+    # the expires_at, signature and hash contents must be identical to those used by the
+    # signer.
+    #
+    # @param [String] signature a binary signature to verify
+    # @param [Time] expires_at
+    # @return [true] always returns true (except when it raises)
+    # @raise [ExpiredSignature] if the signature is expired
+    # @raise [InvalidSignature] if the signature is invalid
     def verify!(signature, expires_at)
       raise ArgumentError, "Cannot verify; missing public_key" unless @public_key
 
-      metadata = {:expires_at => expires_at}
-      expected = digest( encode( canonicalize( frame(@hash, metadata) ) ) )
-      actual = @public_key.public_decrypt(signature)
-      raise SecurityError, "Signature mismatch: expected #{expected}, got #{actual}" unless actual == expected
-      raise SecurityError, "The signature has expired (or expires_at is not a Time)" unless time_check(expires_at)
+      metadata  = {:expires_at => expires_at}
+      plaintext = encode( canonicalize( frame(@hash, metadata) ) )
+
+      if @envelope
+        digest = DIGEST_MAP[@digest].new
+        result = @public_key.verify(digest, signature, plaintext)
+        raise InvalidSignature, "Signature verification failed" unless true == result
+      else
+        expected = @digest.new.update(plaintext).digest
+        actual = @public_key.public_decrypt(signature)
+        raise InvalidSignature, "Signature mismatch: expected #{expected}, got #{actual}" unless actual == expected
+      end
+
+      raise ExpiredSignature, "The signature has expired (or expires_at is not a Time)" unless time_check(expires_at)
+
+      true
     end
 
+    # Verify a digital signature of the hash's contents. In order for the signature to verify,
+    # the expires_at, signature and hash contents must be identical to those used by the
+    # signer.
+    #
+    # @param [String] signature a binary signature to verify
+    # @param [Time] expires_at
+    # @return [true] if the signature and expiration verify OK
+    # @return [false] if the signature or expiration failed to verify
     def verify(signature, expires_at)
       verify!(signature, expires_at)
-      true
     rescue Exception => e
       false
     end
 
+    # Free the inner Hash.
     def method_missing(meth, *args)
       @hash.__send__(meth, *args)
     end
 
+    # Free the inner Hash.
+    def respond_to?(meth)
+      super || @hash.respond_to?(meth)
+    end
+
     private
 
     def duck_type_check
-      unless @digest.is_a?(Class) &&
-             @digest.instance_methods.include?(str_or_symb('update')) &&
-             @digest.instance_methods.include?(str_or_symb('digest'))
-        raise ArgumentError, "Digest class must respond to #update and #digest instance methods"
+      unless DIGEST_MAP.key?(@digest)
+        raise ArgumentError, "Digest must be a built-in Ruby Digest class: MD5, SHA1 or SHA2"
       end
       unless @encoding.respond_to?(str_or_symb('dump'))
         raise ArgumentError, "Encoding class/module/object must respond to .dump method"
@@ -102,22 +211,25 @@ module RightSupport::Crypto
       RUBY_VERSION > '1.9' ? method.to_sym : method.to_s
     end
 
+    # Ensure that an expiration time is in the future.
     def time_check(t)
       t.is_a?(Time) && (t >= Time.now)
     end
 
+    # Incorporate the hash and its signature metadata into an enclosing hash.
     def frame(data, metadata) # :nodoc:
       {:data => data, :metadata => metadata}
     end
 
-    def digest(input) # :nodoc:
-      @digest.new.update(input).digest
-    end
-
+    # Encode a canonicalized representation of the hash.
     def encode(input)
       @encoding.dump(input)
     end
 
+    # Canonicalize the hash (and any nested data) by transforming it deterministically into a
+    # structure of arrays-in-arrays whose elements are ordered according to the lexical ordering
+    # of hash keys. Canonicalization ensures that the signer and verifier agree on the contents
+    # of the thing being signed irrespective of Ruby version, CPU architecture, etc.
     def canonicalize(input) # :nodoc:
       case input
         when Hash

data/lib/right_support/crypto.rb

@@ -25,7 +25,15 @@ module RightSupport
   # A namespace for cryptographic functionality.
   #
   module Crypto
+    # Exception indicating that a cryptographic signature is invalid. This can happen for several
+    # reasons:
+    #  * someone tampered with the signature
+    #  * someone tampered with the signed data
+    #  * the public key being used to verify the signature is mismatched with the signing key
+    class InvalidSignature < SecurityError; end
 
+    # Exception indicating that a cryptographic signature has expired.
+    class ExpiredSignature < SecurityError; end
   end
 end
 

data/right_support.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{right_support}
-  s.version = "2.8.1"
+  s.version = "2.8.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tony Spataro", "Sergey Sergyenko", "Ryan Williamson", "Lee Kirchhoff", "Alexey Karpik", "Scott Messier"]
-  s.date = %q{2013-08-28}
+  s.date = %q{2013-09-06}
   s.description = %q{A toolkit of useful, reusable foundation code created by RightScale.}
   s.email = %q{support@rightscale.com}
   s.extra_rdoc_files = [
@@ -143,6 +143,7 @@ Gem::Specification.new do |s|
   s.summary = %q{Reusable foundation code.}
 
   if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then

data/spec/crypto/signed_hash_spec.rb

@@ -7,54 +7,67 @@ describe RightSupport::Crypto::SignedHash do
     @expires_at = Time.at(Time.now.to_i + 60*60) #one hour from now
   end
 
-  context :sign do
-    it 'computes a signature' do
-      signature = RightSupport::Crypto::SignedHash.new(@data, :private_key=>@rsa_key).sign(@expires_at)
-      signature.should_not be_nil
-      RightSupport::Crypto::SignedHash.new(@data, :public_key=>@rsa_key).verify(signature, @expires_at).should be_true
-    end
-  end
-
-  context :verify do
-    before(:each) do
-      @signature = RightSupport::Crypto::SignedHash.new(@data, :private_key=>@rsa_key).sign(@expires_at)
-      @hash = RightSupport::Crypto::SignedHash.new(@data, :public_key=>@rsa_key)
-    end
+  [true, false].each do |use_envelope|
+    context "given :envelope=>#{use_envelope} option" do
+      context '#sign' do
+        it 'computes a signature' do
+          signature = RightSupport::Crypto::SignedHash.
+            new(@data, :private_key=>@rsa_key, :envelope=>use_envelope).sign(@expires_at)
+          signature.should_not be_nil
 
-    context 'when the signature and data are good' do
-      it 'returns true' do
-        @hash.verify(@signature, @expires_at).should be_true
+          RightSupport::Crypto::SignedHash.
+            new(@data, :public_key=>@rsa_key, :envelope=>use_envelope).
+            verify(signature, @expires_at).should be_true
+        end
       end
-    end
 
-    context 'when expires_at is in the past' do
-      it 'returns false' do
-        @hash.verify(@signature, Time.at(@expires_at.to_i - 86400)).should be_false
-      end
-    end
+      context '#verify' do
+        before(:each) do
+          @signature = RightSupport::Crypto::SignedHash.
+            new(@data, :private_key=>@rsa_key, :envelope=>use_envelope).
+            sign(@expires_at)
 
-    context 'when expires_at has been tampered with' do
-      it 'returns false' do
-        @hash.verify(@signature + 'xyzzy', @expires_at).should be_false
-      end
-    end
+          @hash = RightSupport::Crypto::SignedHash.
+            new(@data, :public_key=>@rsa_key, :envelope=>use_envelope)
+        end
 
-    context 'when the data is bad' do
-      before(:each) do
-        modified_data = @data.dup
-        modified_data[modified_data.keys.first] = 'gabba gabba hey!'
-        @modified_hash = RightSupport::Crypto::SignedHash.new(modified_data, :public_key=>@rsa_key)
-      end
-      it 'returns false' do
-        @modified_hash.verify(@signature, @expires_at).should be_false
-      end
-    end
+        context 'when the signature and data are good' do
+          it 'returns true' do
+            @hash.verify(@signature, @expires_at).should be_true
+          end
+        end
+
+        context 'when expires_at is in the past' do
+          it 'returns false' do
+            @hash.verify(@signature, Time.at(@expires_at.to_i - 86400)).should be_false
+          end
+        end
+
+        context 'when expires_at has been tampered with' do
+          it 'returns false' do
+            @hash.verify(@signature + 'xyzzy', @expires_at).should be_false
+          end
+        end
+
+        context 'when the data is bad' do
+          before(:each) do
+            modified_data = @data.dup
+            modified_data[modified_data.keys.first] = 'gabba gabba hey!'
+            @modified_hash = RightSupport::Crypto::SignedHash.
+              new(modified_data, :public_key=>@rsa_key, :envelope=>use_envelope)
+          end
+          it 'returns false' do
+            @modified_hash.verify(@signature, @expires_at).should be_false
+          end
+        end
 
-    context 'when the signature is bad' do
-      it 'returns false' do
-        @signature << 'xyzzy'
-        @hash.verify(@signature, @expires_at).should be_false
+        context 'when the signature is bad' do
+          it 'returns false' do
+            @signature << 'xyzzy'
+            @hash.verify(@signature, @expires_at).should be_false
+          end
+        end
       end
     end
   end
-end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: right_support
 version: !ruby/object:Gem::Version 
-  hash: 45
+  hash: 43
   prerelease: false
   segments: 
   - 2
   - 8
-  - 1
-  version: 2.8.1
+  - 2
+  version: 2.8.2
 platform: ruby
 authors: 
 - Tony Spataro
@@ -20,7 +20,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-09-06 00:00:00 -07:00
+date: 2013-10-03 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency