right_support 2.14.0 → 2.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1e82daed673214599b4e0206f8a766ba400d06ac
-  data.tar.gz: e6d9f64f58a4b3932e725dbbdaf071a094c4b4de
+  metadata.gz: 1dca63bf8c124604e44a21a45d56515e63fc6760
+  data.tar.gz: 224209a39c20b16906f9688755ea12b16957655e
 SHA512:
-  metadata.gz: 76d3073f77651f586ae49aa3f956498512945584abe938baaa0e3ce8e0c68c94ed90ede39316aae6551c33f49957c3b06a0cd0a545b8f35ed8c29e18d1dc2511
-  data.tar.gz: b72d3a15b6cea55871a7a1f8a0ff7709aed8bba348bae85bb279d66b937be26f6edea2b49ae5a426f8d19aa161d7b9699803a82c8ab106b48c6ab546c0764142
+  metadata.gz: ab60e79b75e481d2c374fecf4f59f5c69bade7f859b3ad34d025b397cfb431bce2c6ef769f50406723b9170c2391c089e94255a7386760884a52b41ede8c9684
+  data.tar.gz: 7fc92ba8a0e765a51c043bc39ab11fcf664d2c2fad5330b18dcb42c4257a55b91f1726889b941c06a7d83c1f63c220e853903a6b74c7aefde10fecca00406a6c

data/lib/right_support/crypto/signed_hash.rb

@@ -24,37 +24,18 @@ require 'digest/md5'
 require 'digest/sha1'
 require 'digest/sha2'
 require 'openssl'
+require 'base64'
 
 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)
+  # This class supports RSA, DSA and ECDSA signature methods. When used with
+  # ECDSA, it _only_ supports JWT envelope format. The intent is to enable
+  # consumers of this class to switch to JSON Web Token in the future.
   #
-  # 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.
+  # @deprecated please use JSON Web Token instead of this class!
   #
   # @see OpenSSL::PKey
   # @see Digest
@@ -77,40 +58,77 @@ module RightSupport::Crypto
       DefaultEncoding = nil
     end unless defined?(DefaultEncoding)
 
-    DEFAULT_OPTIONS = {
-      :digest   => Digest::SHA1,
-      :envelope => false,
-      :encoding => DefaultEncoding,
-    }
-
-    # Mapping of Ruby built-in hash algorithms to their OpenSSL counterparts
+    # List of acceptable Hash algorihtms + map of Ruby builtins to OpenSSL
+    # counterparts.
     DIGEST_MAP = {
       Digest::MD5  => OpenSSL::Digest::MD5,
       Digest::SHA1 => OpenSSL::Digest::SHA1,
       Digest::SHA2 => OpenSSL::Digest::SHA256,
-    }
+      OpenSSL::Digest::MD5 => OpenSSL::Digest::MD5,
+      OpenSSL::Digest::SHA1 => OpenSSL::Digest::SHA1,
+      OpenSSL::Digest::SHA256 => OpenSSL::Digest::SHA256,
+      OpenSSL::Digest::SHA384 => OpenSSL::Digest::SHA384,
+      OpenSSL::Digest::SHA512 => OpenSSL::Digest::SHA512,
+    }.freeze
+
+    # Digest output sizes (in bits)
+    HASHSIZE_MAP = {
+      Digest::MD5  => 128,
+      Digest::SHA1 => 160,
+      Digest::SHA2 => 256,
+      OpenSSL::Digest::MD5 => 128,
+      OpenSSL::Digest::SHA1 => 160,
+      OpenSSL::Digest::SHA256 => 256,
+      OpenSSL::Digest::SHA384 => 384,
+      OpenSSL::Digest::SHA512 => 512,
+    }.freeze
 
     # 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
+    # @param [Hash] data the actual data that is to be signed
+    # @param [OpenSSL::PKey::PKey] key
+    # @param [Digest::Base, OpenSSL::Digest] digest hash function to use
+    # @param [#dump] encoding
+    # @param [nil,:none,:right_support,:jwt] envelope serialization format and encryption scheme; default depends on key type
+    # @param [OpenSSL::PKey::PKey] private_key deprecated -- pass key instead
+    # @param [OpenSSL::PKey::PKey] public_key deprecated -- pass key instead
+    def initialize(data={}, key=nil, digest:nil, encoding:DefaultEncoding, envelope:nil, private_key:nil, public_key:nil)
+      # Cope with legacy parameter
+      if key.nil?
+        key = private_key || public_key
+        warn(':private_key and :public_key are deprecated; please pass key as 2nd parameter') if key
+      end
+
+      @data     = data
+      @encoding = encoding
+      @key      = key
+
+      # Figure out envelope type
+      env = case envelope
+      when nil then guess_envelope
+      when :none, false then :none
+      when :right_support, true then :right_support
+      when :jwt then :jwt
+      else raise ArgumentError.new("Unsupported envelope #{envelope.inspect}")
+      end
+      @envelope = env
+
+      # Figure out digest algorithm
+      @digest = digest || guess_digest
+
+      check_parameters
+    end
+
+    # Compute a signature and return a JSON Web Token representation of
+    # this hash.
     #
-    # @see DefaultEncoding
-    def initialize(hash={}, opts={})
-      opts = DEFAULT_OPTIONS.merge(opts)
-      @hash        = hash
-      @digest      = opts[:digest]
-      @encoding    = opts[:encoding]
-      @envelope    = !!opts[:envelope]
-      @public_key  = opts[:public_key]
-      @private_key = opts[:private_key]
-      duck_type_check
+    # @return [String] a signed JWT with the specified expiration timestamp
+    def to_jwt(expires_at)
+      prefix, sig = sign_with_canonical_representation(expires_at)
+      sig = RightSupport::Data::Base64URL.encode(sig)
+      "#{prefix}.#{sig}"
     end
 
     # Produce a digital signature of the hash contents, including the expiration timestamp
@@ -120,25 +138,8 @@ module RightSupport::Crypto
     # @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}
-      encoded = encode(canonicalize(frame(@hash, metadata)))
-
-      if @envelope
-        digest = DIGEST_MAP[@digest].new(encoded)
-        if @private_key.respond_to?(:dsa_sign_asn1)
-          # DSA signature with ASN.1 encoding
-          @private_key.dsa_sign_asn1(digest.digest)
-        else
-          # RSA/DSA signature as specified in PKCS #1 v1.5
-          @private_key.sign(digest, encoded)
-        end
-      else
-        digest = @digest.new.update(encoded).digest
-        @private_key.private_encrypt(digest)
-      end
+      _, sig = sign_with_canonical_representation(expires_at)
+      sig
     end
 
     # Verify a digital signature of the hash's contents. In order for the signature to verify,
@@ -151,30 +152,48 @@ module RightSupport::Crypto
     # @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
+      raise ArgumentError, "Cannot verify; missing public_key" unless @key
 
       metadata  = {:expires_at => expires_at}
-      plaintext = encode( canonicalize( frame(@hash, metadata) ) )
+      plaintext = encode(canonicalize(frame(@data, metadata)))
 
-      if @envelope
+      case @envelope
+      when :none
+        digest = @digest.new.update(plaintext).digest
+        # raw RSA decryption
+        actual = @key.public_decrypt(signature)
+        raise InvalidSignature, "Signature mismatch: expected #{digest}, got #{actual}" unless actual == digest
+      when :jwt
+        if @key.respond_to?(:dsa_verify_asn1)
+          # DSA signature with JWT-compatible encoding
+          digest = @digest.new.update(plaintext).digest
+          signature = raw_to_asn1(signature, @key)
+          result = @key.dsa_verify_asn1(digest, signature)
+          raise InvalidSignature, "Signature mismatch: DSA verify failed" unless result
+        elsif @key.respond_to?(:verify)
+          digest = @digest.new
+          result = @key.verify(digest, signature, plaintext)
+          raise InvalidSignature, "Signature mismatch: verify failed" unless result
+        else
+          raise NotImplementedError, "Cannot verify JWT with #{@key.class.name}"
+        end
+      when :right_support
         digest = DIGEST_MAP[@digest].new
-        if @public_key.respond_to?(:moo)
+        if @key.respond_to?(:dsa_verify_asn1)
           # DSA signature with ASN.1 encoding
-          @private_key.dsa_verify_asn1(digest.digest, signature)
+          @key.dsa_verify_asn1(digest.digest, signature)
         else
           # RSA/DSA signature as specified in PKCS #1 v1.5
-          result = @public_key.verify(digest, signature, plaintext)
+          result = @key.verify(digest, signature, plaintext)
         end
         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
+    rescue OpenSSL::PKey::RSAError => e
+      raise InvalidSignature, "Signature mismatch: #{e.message}"
     end
 
     # Verify a digital signature of the hash's contents. In order for the signature to verify,
@@ -187,53 +206,131 @@ module RightSupport::Crypto
     # @return [false] if the signature or expiration failed to verify
     def verify(signature, expires_at)
       verify!(signature, expires_at)
-    rescue Exception => e
+    rescue ExpiredSignature, InvalidSignature => e
       false
     end
 
     # Free the inner Hash.
     def method_missing(meth, *args)
-      @hash.__send__(meth, *args)
+      @data.__send__(meth, *args)
     end
 
     # Free the inner Hash.
     def respond_to?(meth, include_all=false)
-      super || @hash.respond_to?(meth)
+      super || @data.respond_to?(meth)
     end
 
     def respond_to_missing?(meth, include_all=false)
-      super || @hash.respond_to?(meth, include_all)
+      super || @data.respond_to?(meth, include_all)
     end
 
     private
 
-    def duck_type_check
+    # @return [Array] a pair of strings: the exact message that was signed, and its raw-binary signature
+    def sign_with_canonical_representation(expires_at)
+      raise ArgumentError, "Cannot sign; missing private_key" unless @key
+      raise ArgumentError, "expires_at must be a Time in the future" unless time_check(expires_at)
+
+      metadata = {:expires_at => expires_at}
+      plaintext = encode(canonicalize(frame(@data, metadata)))
+
+      case @envelope
+      when :none
+        digest = @digest.new.update(plaintext).digest
+        # raw RSA encryption; output is a single bignum
+        sig = @key.private_encrypt(digest)
+      when :jwt
+        if @key.respond_to?(:dsa_sign_asn1)
+          # raw ECDSA signature; output are two bignums (r, s) stuck together
+          # with no delimiter
+          digest = @digest.new.update(plaintext).digest
+          asn1 = @key.dsa_sign_asn1(digest)
+          sig = asn1_to_raw(asn1, @key)
+        elsif @key.respond_to?(:sign)
+          # RSA/DSA signature as specified in PKCS #1 v1.5
+          digest = @digest.new
+          sig = @key.sign(digest, plaintext)
+        else
+          raise NotImplementedError, "Cannot sign JWT with a #{@key.class.name}"
+        end
+      when :right_support
+        digest = DIGEST_MAP[@digest].new(plaintext)
+        if @key.respond_to?(:dsa_sign_asn1)
+          # DSA signature with ASN.1 encoding
+          sig = @key.dsa_sign_asn1(digest.digest)
+        else
+          # RSA/DSA signature as specified in PKCS #1 v1.5
+          sig = @key.sign(digest, plaintext)
+        end
+      end
+
+      return plaintext, sig
+    end
+
+    # @raise [ArgumentError] if there is anything wrong with the crypto parameters
+    def check_parameters
+      # raises if key/digest are not compatible with JOSE
+      begin
+        jose_header if @envelope == :jwt
+      rescue NotImplementedError => e
+        raise ArgumentError.new(e.message)
+      end
+
       unless DIGEST_MAP.key?(@digest)
-        raise ArgumentError, "Digest must be a built-in Ruby Digest class: MD5, SHA1 or SHA2"
+        raise ArgumentError, "Digest must be one of Digest::* class or OpenSSL::Digest::*"
       end
-      unless @encoding.respond_to?(str_or_symb('dump'))
+      unless @encoding.respond_to?(:dump)
         raise ArgumentError, "Encoding class/module/object must respond to .dump method"
       end
 
       if @envelope
-        if @public_key && !@public_key.respond_to?(str_or_symb('verify'))
+        if @key && !@key.respond_to?(:verify)
           raise ArgumentError, "Public key must respond to :verify"
         end
-        if @private_key && !@private_key.respond_to?(str_or_symb('sign'))
+        if @key && !@key.respond_to?(:sign)
           raise ArgumentError, "Private key must respond to :sign"
         end
       else
-        if @public_key && !@public_key.respond_to?(str_or_symb('public_decrypt'))
+        if @key && !@key.respond_to?(:public_decrypt)
           raise ArgumentError, "Public key must respond to :public_decrypt"
         end
-        if @private_key && !@private_key.respond_to?(str_or_symb('private_encrypt'))
+        if @key && !@key.respond_to?(:private_encrypt)
           raise ArgumentError, "Private key must respond to :private_encrypt"
         end
       end
     end
 
-    def str_or_symb(method)
-      RUBY_VERSION > '1.9' ? method.to_sym : method.to_s
+    # Figure out a default envelope if none is provided
+    def guess_envelope
+      case @key
+      when OpenSSL::PKey::EC
+        :jwt
+      else
+        :none
+      end
+    end
+
+    # Figure out a suitable default digest if none is provided
+    def guess_digest
+      case @key
+      when OpenSSL::PKey::DSA
+        OpenSSL::Digest::SHA1
+      when OpenSSL::PKey::EC
+        case @key.group.degree
+        when 256 then OpenSSL::Digest::SHA256
+        when 384 then OpenSSL::Digest::SHA384
+        when 521 then OpenSSL::Digest::SHA512
+        else
+          raise ArgumentError, "Cannot guess digest; please pass it as an option"
+        end
+      when OpenSSL::PKey::RSA
+        case @envelope
+        when :jwt then OpenSSL::Digest::SHA256
+        else OpenSSL::Digest::SHA1
+        end
+      else
+        OpenSSL::Digest::SHA1
+      end
     end
 
     # Ensure that an expiration time is in the future.
@@ -241,21 +338,28 @@ module RightSupport::Crypto
       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
-
     # Encode a canonicalized representation of the hash.
-    def encode(input)
-      @encoding.dump(input)
+    def encode(input) # :nodoc:
+      case @envelope
+      when :none, :right_support
+        @encoding.dump(input)
+      when :jwt
+        input.map { |m| RightSupport::Data::Base64URL.encode(m) }.join('.')
+      end
     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.
+    # If envelope is :jwt, return the input with each element mapped
+    # to its encoded form, but otherwise unchanged in any way.
+    #
+    # For any other envelope type, 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:
+      return input.map { |i| @encoding.dump(i) } if @envelope == :jwt
+
       case input
         when Hash
           # Hash is the only complex case. We canonicalize a Hash as an Array of pairs, each of which
@@ -296,5 +400,59 @@ module RightSupport::Crypto
 
       output
     end
+
+    # Incorporate the hash and its signature metadata into a Hash or Array
+    # that represents the logical layout of the thing to be signed or verified.
+    def frame(data, metadata) # :nodoc:
+      case @envelope
+      when :none, :right_support
+        # Proprietary framing
+        {:data => data, :metadata => metadata}
+      when :jwt
+        # JOSE framing; see http://jose.readthedocs.io
+        payload = data.dup
+        payload['exp'] = metadata[:expires_at].to_i
+        [jose_header, payload]
+      end
+    end
+
+    # @return [Hash] JOSE header defining document type (JWT) and encryption algorithm
+    def jose_header
+      key = @key || @key
+
+      prefix = case key
+      when OpenSSL::PKey::EC
+        'ES'
+      when OpenSSL::PKey::RSA
+        'RS'
+      else
+        raise NotImplementedError, "Cannot use a #{key.class.name} with JWT envelope"
+      end
+
+      size = HASHSIZE_MAP[@digest]
+      unless size
+        raise NotImplementedError, "Cannot use #{@digest.name} with JWT envelope and this kind of key"
+      end
+
+      {'typ' => 'JWT', 'alg' => "#{prefix}#{size}"}
+    end
+
+    # Convert ASN1-encoded pair of integers into raw pair of concatenated bignums
+    # This only works for OpenSSL::PKey::EC.
+    # See https://github.com/jwt/ruby-jwt/blob/master/lib/jwt.rb#L166
+    def asn1_to_raw(signature, private_key) # :nodoc:
+      byte_size = (private_key.group.degree + 7) / 8
+      OpenSSL::ASN1.decode(signature).value.map { |value| value.value.to_s(2).rjust(byte_size, "\x00") }.join
+    end
+
+    # Convert raw pair of concatenated bignums into ASN1-encoded pair of integers.
+    # This only works for OpenSSL::PKey::EC.
+    # https://github.com/jwt/ruby-jwt/blob/master/lib/jwt.rb#L159
+    def raw_to_asn1(signature, public_key) # :nodoc:
+      byte_size = (public_key.group.degree + 7) / 8
+      r = signature[0..(byte_size - 1)]
+      s = signature[byte_size..-1] || ''
+      OpenSSL::ASN1::Sequence.new([r, s].map { |int| OpenSSL::ASN1::Integer.new(OpenSSL::BN.new(int, 2)) }).to_der
+    end
   end
 end

data/lib/right_support/crypto.rb

@@ -25,6 +25,10 @@ module RightSupport
   # A namespace for cryptographic functionality.
   #
   module Crypto
+    # Exception indicating that a cryptographic message payload contains
+    # something whose state can't cleanly signed, encrypted or verified.
+    class InvalidPayload < StandardError; end
+
     # Exception indicating that a cryptographic signature is invalid. This can happen for several
     # reasons:
     #  * someone tampered with the signature

data/lib/right_support/data/base64_url.rb

@@ -0,0 +1,27 @@
+require 'base64'
+
+module RightSupport::Data
+  # Implements the base64url encoding mechanism as described in RFC7515: JSON
+  # Web Signature (JWS).
+  #
+  # This encoding is similar to base64, but omits newlines and padding
+  # `=` characters, and uses the `-` and `_` characters in place of the `+` and
+  # `/` characters. This makes it suitable for use inside URLs, cookies, and
+  # other "webby" contexts where we want to avoid text expansion due to URL
+  # encoding.
+  module Base64URL
+    # @param [String] str ASCII string to encode
+    # @return [String] base64 representation of str
+    def self.encode(text)
+      Base64.encode64(text).tr('+/', '-_').gsub(/[\n=]/, '')
+    end
+
+    # @param [String] str base64 to decode to ASCII
+    # @return [String] plain ASCII
+    def self.decode(b64)
+      b64 = b64.dup
+      b64 += '=' * (4 - b64.length.modulo(4))
+      Base64.decode64(b64.tr('-_', '+/'))
+    end
+  end
+end

data/lib/right_support/data.rb

@@ -35,3 +35,4 @@ require 'right_support/data/hash_tools'
 require 'right_support/data/uuid'
 require 'right_support/data/mash'
 require 'right_support/data/token'
+require 'right_support/data/base64_url'

data/lib/right_support/version.rb

@@ -1,4 +1,4 @@
 # encoding: utf-8
 module RightSupport
-  VERSION = '2.14.0'.freeze
+  VERSION = '2.14.1'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: right_support
 version: !ruby/object:Gem::Version
-  version: 2.14.0
+  version: 2.14.1
 platform: ruby
 authors:
 - Tony Spataro
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-14 00:00:00.000000000 Z
+date: 2016-12-20 00:00:00.000000000 Z
 dependencies: []
 description: A toolkit of useful, reusable foundation code created by RightScale.
 email: support@rightscale.com
@@ -33,6 +33,7 @@ files:
 - lib/right_support/crypto.rb
 - lib/right_support/crypto/signed_hash.rb
 - lib/right_support/data.rb
+- lib/right_support/data/base64_url.rb
 - lib/right_support/data/hash_tools.rb
 - lib/right_support/data/mash.rb
 - lib/right_support/data/serializer.rb