ecdsa 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 112522081e19ec7215da474caa4ee348b0ccca48
-  data.tar.gz: b7ce849fcd146350259a96830992a5e68a020d88
+  metadata.gz: 25e8c83f3ce99fc8aa59227d35d585c6e9a6243d
+  data.tar.gz: 075eae949de245595465e56bc88cf343a96963a4
 SHA512:
-  metadata.gz: 4112fc44b63041825d083a5ac7fd510a8b7ba800183c89d137e7feed2656fbeca69177fb7dce11bbc44ece676540ae9970043fedbe38ce5c4dcd4add30187b15
-  data.tar.gz: 4d9695b86a32f46719dd99e4420d7b4a4c83aa6ba142dbf830d27a6f5be4af63e7208ff674bb0ceba75cfb55db23c863de2a02e98c3ff2812fa59bcdf2ed6961
+  metadata.gz: cc8301baedb1e03857302738d7573c2a9cf3a521a6f396529879a190190c2e17f2074a2105277d7296d8fe8535e8322fd51d0a763322f4018d74ac0e171eb024
+  data.tar.gz: a85fdcc62172795e57e3926e14a7c910568b68672cf51a753aa53bd46018eabddb1e8cc4800319fedfb878f0f36d9aa10c2168447ea96918119840e000ccd0d1

data/Gemfile

@@ -2,7 +2,8 @@ source 'https://rubygems.org/'
 
 gem 'rspec'
 
-gem 'rubocop', '0.19.1'
+gem 'rubocop', '0.20.1'
+gem 'simplecov'
 
 gem 'yard'
 gem 'markdown'

data/README.md

@@ -1,7 +1,7 @@
-[![Build Status](https://travis-ci.org/DavidEGrayson/ruby_ecdsa.svg?branch=master)](https://travis-ci.org/DavidEGrayson/ruby_ecdsa)
-
 # ECDSA gem for Ruby
 
+[![Build Status](https://travis-ci.org/DavidEGrayson/ruby_ecdsa.svg?branch=master)](https://travis-ci.org/DavidEGrayson/ruby_ecdsa)
+
 This gem implements the Elliptic Curve Digital Signature Algorithm (ECDSA)
 almost entirely in pure Ruby.  It aims to be easier to use and easier to
 understand than Ruby's
@@ -34,10 +34,6 @@ This gem is hosted at the [DavidEGrayson/ruby_ecdsa github repository](https://g
 
 - This gem only supports fields of integers modulo a prime number
   (_F<sub>p</sub>_).  ECDSA's characteristic 2 fields are not supported.
-- This gem can only compute square roots in prime fields over a prime _p_
-  that is one less than a multiple of 4.
-  Computing a square root is required for parsing public keys stored in
-  compressed form.
 - The algorithms have not been optimized for speed, and will probably never be,
   because that would hinder the goal of helping people understand ECDSA.
 
@@ -84,7 +80,7 @@ The `public_key` object produced by the code above is an `ECDSA::Point` object.
 ## Encoding a public key as a binary string
 
 Assuming that you have an `ECDSA::Point` object representing the public key,
-you can convert it to the standard binary format defined in SEC2 with this code:
+you can convert it to the standard binary format defined in SEC1 with this code:
 
 ```ruby
 public_key_string = ECDSA::Format::PointOctetString.encode(public_key, compression: true)
@@ -98,7 +94,7 @@ This code returns a binary string.
 
 ## Decoding a public key from a binary string
 
-To decode a SEC2 octet string, you can use the code below.  The `group` object
+To decode a SEC1 octet string, you can use the code below.  The `group` object
 is assumed to be an `ECDSA::Group`.
 
 ```ruby
@@ -169,4 +165,8 @@ puts "valid: #{valid}"
 ## Supported platforms
 
 This library should run on any Ruby interpreter that is compatible with Ruby 1.9.3.
-It has been tested on JRuby 1.7.11 and MRI.
+It has been tested on JRuby 1.7.11 and MRI.
+
+## Documentation
+
+For complete documentation, see the [ECDSA page on RubyDoc.info](http://rubydoc.info/gems/ecdsa).

data/lib/ecdsa.rb

@@ -1,7 +1,8 @@
 require_relative 'ecdsa/group'
 require_relative 'ecdsa/signature'
-require_relative 'ecdsa/verify'
 require_relative 'ecdsa/sign'
+require_relative 'ecdsa/verify'
+require_relative 'ecdsa/recover_public_key'
 require_relative 'ecdsa/format'
 require_relative 'ecdsa/version'
 
@@ -28,26 +29,21 @@ module ECDSA
   end
 
   # This method is NOT part of the public API of the ECDSA gem.
-  def self.convert_digest_to_integer(digest)
-    case digest
-    when Integer then digest
-    when String then Format::IntegerOctetString.decode(digest)
-    else raise "Invalid digest: #{digest.inspect}"
-    end
-  end
+  def self.normalize_digest(digest, bit_length)
+    if digest.is_a?(String)
+      digest = digest.dup.force_encoding('BINARY')
+      digest_bit_length = digest.size * 8
+      num = Format::IntegerOctetString.decode(digest)
 
-  # This method is NOT part of the public API of the ECDSA gem.
-  def self.leftmost_bits(n, bit_length)
-    if n >= (1 << (8 * bit_length))
-      raise 'Have not yet written code to handle this case'
+      if digest_bit_length <= bit_length
+        num
+      else
+        num >> (digest_bit_length - bit_length)
+      end
+    elsif digest.is_a?(Integer)
+      digest
     else
-      n
+      raise ArgumentError, 'Digest must be a string or integer.'
     end
   end
-
-  # This method is NOT part of the public API of the ECDSA gem.
-  def self.normalize_digest(digest, bit_length)
-    digest_num = convert_digest_to_integer(digest)
-    leftmost_bits(digest_num, bit_length)
-  end
 end

data/lib/ecdsa/group.rb

@@ -1,6 +1,9 @@
 require_relative 'prime_field'
 require_relative 'point'
 
+# TODO: we keep using this abstraction called the 'point_field' all over the place.
+# Figure out what it is really called and make it come from a method on Group.
+
 module ECDSA
   class Group
     # The name of the group.
@@ -17,6 +20,11 @@ module ECDSA
     # @return (Order)
     attr_reader :order
 
+    # The cofactor of the group.
+    # This is the number of points on the curve divided by the number of points
+    # in the group generated by the generator.
+    attr_reader :cofactor
+
     # The a parameter in the curve equation (*y^2 = x^3 + ax + b*).
     # @option opts :a (Integer)
     attr_reader :param_a
@@ -105,6 +113,25 @@ module ECDSA
       point.infinity? or point_satisfies_equation?(point)
     end
 
+    # Returns true if the point is not infinity, it is a solution to the curve's
+    # defining equation, and it is a multiple of G.  This process is defined in
+    # SEC1 2.0, Section 3.2.2.1: Elliptic Curve Public Key Partial Validation Primitive
+    def valid_public_key?(point)
+      return false if point.group != self
+      return false if point.infinity?
+      return false if !point_satisfies_equation?(point)
+      point.multiply_by_scalar(order).infinity?
+    end
+
+    # Returns true if the point is not infinity and it is a solution to
+    # the curve's defining equation.  This is defined in
+    # SEC1 2.0, Section 3.2.3.1: Elliptic Curve Public Key Partial Validation Primitive
+    def partially_valid_public_key?(point)
+      return false if point.group != self
+      return false if point.infinity?
+      point_satisfies_equation?(point)
+    end
+
     # Given the x coordinate of a point, finds all possible corresponding y coordinates.
     #
     # @return (Array)

data/lib/ecdsa/point.rb

@@ -138,6 +138,16 @@ module ECDSA
       eql?(other)
     end
 
+    # Returns a hash for this point so it can be stored in hash tables
+    # with the expected behavior.  Two points that have the same coordinates
+    # and are on the same curve are equal, so they should not get separate
+    # spots in a hash table.
+    #
+    # @return (Integer)
+    def hash
+      [group, x, y].hash
+    end
+
     # Returns true if this instance represents the infinity point (the additive
     # identity of the group).
     #

data/lib/ecdsa/prime_field.rb

@@ -88,28 +88,107 @@ module ECDSA
     end
 
     # Finds all possible square roots of the given field element.
-    # Currently this method only supports fields where the prime is one
-    # less than a multiple of four.
     #
     # @param n (Integer)
     # @return (Array) A sorted array of numbers whose square is equal to `n`.
     def square_roots(n)
       raise ArgumentError, "Not a member of the field: #{n}." if !include?(n)
-      if (prime % 4) == 3
-        square_roots_for_p_3_mod_4(n)
-      else
-        raise NotImplementedError, 'Square root is only implemented in fields where the prime is equal to 3 mod 4.'
+      case
+      when prime == 2 then [n]
+      when (prime % 4) == 3 then square_roots_for_p_3_mod_4(n)
+      when (prime % 8) == 5 then square_roots_for_p_5_mod_8(n)
+      else square_roots_default(n)
+      end
+    end
+
+    # This method is NOT part of the public API of the ECDSA gem.
+    def self.factor_out_twos(x)
+      e = 0
+      while x.even?
+        x /= 2
+        e += 1
       end
+      [e, x]
+    end
+
+    # This method is NOT part of the public API of the ECDSA gem.
+    #
+    # Algorithm algorithm 2.149 from http://cacr.uwaterloo.ca/hac/
+    def self.jacobi(n, p)
+      raise 'Jacobi symbol is not defined for primes less than 3.' if p < 3
+
+      n = n % p
+
+      return 0 if n == 0  # Step 1
+      return 1 if n == 1  # Step 2
+
+      e, n1 = factor_out_twos n                         # Step 3
+      s = (e.even? || [1, 7].include?(p % 8)) ? 1 : -1  # Step 4
+      s = -s if (p % 4) == 3 && (n1 % 4) == 3           # Step 5
+
+      # Step 6 and 7
+      return s if n1 == 1
+      s * jacobi(p, n1)
     end
 
     private
 
+    def jacobi(n)
+      self.class.send(:jacobi, n, prime)
+    end
+
     # This is Algorithm 1 from http://math.stanford.edu/~jbooher/expos/sqr_qnr.pdf
+    # It is also Algorithm 3.36 from http://cacr.uwaterloo.ca/hac/
     # The algorithm assumes that its input actually does have a square root.
     # To get around that, we double check the answer after running the algorithm to make
     # sure it works.
     def square_roots_for_p_3_mod_4(n)
       candidate = power n, (prime + 1) / 4
+      square_roots_given_candidate n, candidate
+    end
+
+    # This is Algorithm 3.37 from http://cacr.uwaterloo.ca/hac/
+    def square_roots_for_p_5_mod_8(n)
+      case power n, (prime - 1) / 4
+      when 1
+        candidate = power n, (prime + 3) / 8
+      when prime - 1
+        candidate = mod 2 * n * power(4 * n, (prime - 5) / 8)
+      else
+        # I think this can happen because we are not checking the Jacobi.
+        return []
+      end
+      square_roots_given_candidate n, candidate
+    end
+
+    # This is Algorithm 3.34 from http://cacr.uwaterloo.ca/hac/
+    # It has no limitations except prime must be at least three, so we could
+    # remove all the other square root algorithms if we wanted to.
+    def square_roots_default(n)
+      return [0] if n == 0
+      return [] if jacobi(n) == -1   # Step 1
+
+      # Step 2, except we don't want to use randomness.
+      b = (1...prime).find { |i| jacobi(i) == -1 }
+
+      s, t = self.class.factor_out_twos(prime - 1)  # Step 3
+      n_inv = inverse(n)  # Step 4
+
+      # Step 5
+      c = power b, t
+      r = power n, (t + 1) / 2
+
+      # Step 6
+      (1...s).each do |i|
+        d = power r * r * n_inv, 1 << (s - i - 1)
+        r = mod r * c if d == prime - 1
+        c = square c
+      end
+
+      square_roots_given_candidate n, r
+    end
+
+    def square_roots_given_candidate(n, candidate)
       return [] if square(candidate) != n
       [candidate, mod(-candidate)].uniq.sort
     end

data/lib/ecdsa/recover_public_key.rb

@@ -0,0 +1,61 @@
+module ECDSA
+  # Recovers the set of possible public keys from a {Signature} and the digest
+  # that it signs.
+  #
+  # If you do not pass a block to `recover_public_key` then it returns an
+  # Enumerator that will lazily find more public keys when needed.  If you
+  # are going to iterate through the enumerator more than once, you should
+  # probably convert it to an array first with `to_a` to save CPU time.
+  #
+  # If you pass a block, it will yield the public keys to the block one at a
+  # time as it finds them.
+  #
+  # This is better than just returning an array of all possibilities, because
+  # it allows the caller to stop the algorithm when the desired public key has
+  # been found, saving CPU time.
+  #
+  # This algorithm comes from Section 4.1.6 of [SEC1 2.0](http://www.secg.org/download/aid-780/sec1-v2.pdf)
+  #
+  # @param group (Group)
+  # @param digest (String or Integer)
+  # @param signature (Signature)
+  def self.recover_public_key(group, digest, signature)
+    return enum_for(:recover_public_key, group, digest, signature) if !block_given?
+
+    digest = normalize_digest(digest, group.bit_length)
+
+    each_possible_temporary_public_key(group, digest, signature) do |point|
+      yield calculate_public_key(group, digest, signature, point)
+    end
+
+    nil
+  end
+
+  private
+
+  def self.each_possible_temporary_public_key(group, digest, signature)
+    # Instead of using the cofactor as the iteration limit as specified in SEC1,
+    # we just iterate until x is too large to fit in the underlying field.
+    # That way we don't have to know the cofactor of the group.
+    signature.r.step(group.field.prime - 1, group.order) do |x|
+      group.solve_for_y(x).each do |y|
+        point = group.new_point [x, y]
+        yield point if point.multiply_by_scalar(group.order).infinity?
+      end
+    end
+  end
+
+  # Assuming that we know the public key corresponding to the (random) temporary
+  # private key used during signing, this method tells us what the actual
+  # public key was.
+  def self.calculate_public_key(group, digest, signature, temporary_public_key)
+    point_field = PrimeField.new(group.order)
+
+    # public key = (tempPubKey * s - G * e) / r
+    rs = temporary_public_key.multiply_by_scalar(signature.s)
+    ge = group.generator.multiply_by_scalar(digest)
+    r_inv = point_field.inverse(signature.r)
+
+    rs.add_to_point(ge.negate).multiply_by_scalar(r_inv)
+  end
+end

data/lib/ecdsa/sign.rb

@@ -30,6 +30,7 @@ module ECDSA
     # Steps 2 and 3
     point_field = PrimeField.new(group.order)
     r = point_field.mod(r_point.x)
+    return nil if r.zero?
 
     # Step 4, calculating the hash, was already performed by the caller.
 
@@ -38,12 +39,7 @@ module ECDSA
 
     # Step 6
     s = point_field.mod(point_field.inverse(temporary_key) * (e + r * private_key))
-
-    if s.zero?
-      # We need to go back to step 1, so the caller should generate another
-      # random number temporary_key and try again.
-      return nil
-    end
+    return nil if s.zero?
 
     Signature.new r, s
   end

data/lib/ecdsa/verify.rb

@@ -31,10 +31,10 @@ module ECDSA
     field = group.field
 
     # Step 1: r and s must be in the field and non-zero
-    raise InvalidSignatureError, 'r is not in the field.' if !field.include?(signature.r)
-    raise InvalidSignatureError, 's is not in the field.' if !field.include?(signature.s)
-    raise InvalidSignatureError, 'r is zero.' if signature.r.zero?
-    raise InvalidSignatureError, 's is zero.' if signature.s.zero?
+    raise InvalidSignatureError, 'Invalid signature: r is not in the field.' if !field.include?(signature.r)
+    raise InvalidSignatureError, 'Invalid signature: s is not in the field.' if !field.include?(signature.s)
+    raise InvalidSignatureError, 'Invalid signature: r is zero.' if signature.r.zero?
+    raise InvalidSignatureError, 'Invalid signature: s is zero.' if signature.s.zero?
 
     # Step 2 was already performed when the digest of the message was computed.
 
@@ -49,16 +49,13 @@ module ECDSA
 
     # Step 5
     r = group.generator.multiply_by_scalar(u1).add_to_point public_key.multiply_by_scalar(u2)
-    raise InvalidSignatureError, 'r is infinity in step 5.' if r.infinity?
+    raise InvalidSignatureError, 'Invalid signature: r is infinity in step 5.' if r.infinity?
 
-    # Step 6
-    xr = r.x
-
-    # Step 7
-    v = point_field.mod xr
+    # Steps 6 and 7
+    v = point_field.mod r.x
 
     # Step 8
-    raise InvalidSignatureError, 'v does not equal r.' if v != signature.r
+    raise InvalidSignatureError, 'Invalid signature: v does not equal r.' if v != signature.r
 
     true
   end

data/lib/ecdsa/version.rb

@@ -1,3 +1,3 @@
 module ECDSA
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecdsa
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - David Grayson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-06 00:00:00.000000000 Z
+date: 2014-04-20 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: davidegrayson@gmail.com
@@ -45,6 +45,7 @@ files:
 - lib/ecdsa/group.rb
 - lib/ecdsa/point.rb
 - lib/ecdsa/prime_field.rb
+- lib/ecdsa/recover_public_key.rb
 - lib/ecdsa/sign.rb
 - lib/ecdsa/signature.rb
 - lib/ecdsa/verify.rb