ecdsa 0.1.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 43b972ebb083f20d5ea5875f00a6c235d77f1aec
-  data.tar.gz: 946c40b1039fc9c8fddfd194f58edc1c213f1239
+  metadata.gz: 112522081e19ec7215da474caa4ee348b0ccca48
+  data.tar.gz: b7ce849fcd146350259a96830992a5e68a020d88
 SHA512:
-  metadata.gz: 9466417bfd9244c36997edc141881472658343ba52d03e62d14b603f15ad13ac612009ceb91666c4359d32c9950b3ebd20d33232eb677b33f207c88a8b6ea5ea
-  data.tar.gz: e5293e8f992ca92257d81076755f7c96243f5e9bab1f04a92acc91d25aef5e9faada7ba83ddfe27ba0ca76ce27abe87fb5a5f0eae719cc838478a5d8fe48f8ba
+  metadata.gz: 4112fc44b63041825d083a5ac7fd510a8b7ba800183c89d137e7feed2656fbeca69177fb7dce11bbc44ece676540ae9970043fedbe38ce5c4dcd4add30187b15
+  data.tar.gz: 4d9695b86a32f46719dd99e4420d7b4a4c83aa6ba142dbf830d27a6f5be4af63e7208ff674bb0ceba75cfb55db23c863de2a02e98c3ff2812fa59bcdf2ed6961

data/Gemfile

@@ -1,4 +1,12 @@
 source 'https://rubygems.org/'
 
 gem 'rspec'
-gem 'rubocop', '0.19.1'
+
+gem 'rubocop', '0.19.1'
+
+gem 'yard'
+gem 'markdown'
+
+platforms :ruby, :rbx do
+  gem 'redcarpet'
+end

data/README.md

@@ -1,46 +1,172 @@
+[![Build Status](https://travis-ci.org/DavidEGrayson/ruby_ecdsa.svg?branch=master)](https://travis-ci.org/DavidEGrayson/ruby_ecdsa)
+
 # ECDSA gem for Ruby
 
-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 [OpenSSL EC support](http://www.ruby-doc.org/stdlib/libdoc/openssl/rdoc/OpenSSL/PKey/EC.html).
-This gem does use OpenSSL but it only uses it to decode and encode ASN1 strings for ECDSA signatures.
-All cryptographic calculations are done in pure Ruby.
+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
+[OpenSSL EC support](http://www.ruby-doc.org/stdlib/libdoc/openssl/rdoc/OpenSSL/PKey/EC.html).
+This gem does use OpenSSL but it only uses it to decode and encode ASN1 strings
+for ECDSA signatures.  All cryptographic calculations are done in pure Ruby.
 
-The main classes of this gem are `ECDSA::Group`, `ECDSA::Point`, and `ECDSA::Signature`.
-These classes operate on Ruby integers and do not deal at all with binary formatting.
-Encoding and decoding of binary formats is solely handled by classes under the `ECDSA::Format` module.
+The main classes of this gem are `ECDSA::Group`, `ECDSA::Point`, and
+`ECDSA::Signature`.  These classes operate on Ruby integers and do not deal at
+all with binary formatting.  Encoding and decoding of binary formats is solely
+handled by classes under the `ECDSA::Format` module.
 
-You can enter your own curve parameters by instantiating a new `ECDSA::Group` object or you can
-use a pre-existing group object such as `ECDSA::Group::Secp256k1`.
-The pre-existing groups can be seen in the `lib/ecdsa/group` folder, and include all the curves
-defined in [SEC2](http://www.secg.org/collateral/sec2_final.pdf) and [NIST's Recommended Elliptic Curves for Federal Government Use](http://csrc.nist.gov/groups/ST/toolkit/documents/dss/NISTReCur.pdf).
+You can enter your own curve parameters by instantiating a new `ECDSA::Group`
+object or you can use a pre-existing group object such as
+`ECDSA::Group::Secp256k1`.  The pre-existing groups can be seen in the
+`lib/ecdsa/group` folder, and include all the curves defined in
+[SEC2](http://www.secg.org/collateral/sec2_final.pdf) and
+[NIST's Recommended Elliptic Curves for Federal Government Use](http://csrc.nist.gov/groups/ST/toolkit/documents/dss/NISTReCur.pdf).
 
 This gem does not use any randomness; all the algorithms are deterministic.
-In order to sign a message, you must generate a secure random number _k_ between 0
-and the order of the group and pass it as an argument to `ECDSA.sign`.
-You should take measures to ensure that you never use the same random number to sign
-two different messages, or else it would be easy for someone to compute your
-private key from those two signatures.
+In order to sign a message, you must generate a secure random number _k_
+between 0 and the order of the group and pass it as an argument to `ECDSA.sign`.
+You should take measures to ensure that you never use the same random number to
+sign two different messages, or else it would be easy for someone to compute
+your private key from those two signatures.
 
 This gem is hosted at the [DavidEGrayson/ruby_ecdsa github repository](https://github.com/DavidEGrayson/ruby_ecdsa).
 
 ## Current limitations
 
-- 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 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.
-- There is no documentation.  If you know a little bit about ECDSA and know how to read
-  Ruby source code, you can probably figure it out though.
-- The algorithms have not been optimized for speed, and will probably never be, because that
-  would hinder the goal of helping people understand ECDSA.
+  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.
 
-This gem was not written by a cryptography expert and has not been carefully checked.
-It is provided "as is" and it is the user's responsibility to make sure it will be
-suitable for the desired purpose.
+This gem was not written by a cryptography expert and has not been carefully
+checked.  It is provided "as is" and it is the user's responsibility to make
+sure it will be suitable for the desired purpose.
 
 ## Installation
 
-This library is destributed as a gem named [ecdsa](https://rubygems.org/gems/ecdsa) at RubyGems.org.  To install it, run:
+This library is distributed as a gem named [ecdsa](https://rubygems.org/gems/ecdsa)
+at RubyGems.org.  To install it, run:
+
+    gem install ecdsa
+
+## Generating a private key
+
+An ECDSA private key is a random number between 1 and the order of the group.
+If you trust the `SecureRandom` class provided by your Ruby implementation, you
+could generate a private key using this code:
+
+```ruby
+require 'ecdsa'
+require 'securerandom'
+group = ECDSA::Group::Secp256k1
+private_key = 1 + SecureRandom.random_number(group.order - 1)
+puts 'private key: %#x' % private_key
+```
+
+## Computing the public key for a private key
+
+The public key consists of the coordinates of the point that is computed by
+multiplying the generator point of the curve with the private key.
+This is equivalent to adding the generator to itself `private_key` times.
+
+```ruby
+public_key = group.generator.multiply_by_scalar(private_key)
+puts 'public key: '
+puts '  x: %#x' % public_key.x
+puts '  y: %#x' % public_key.y
+```
+
+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:
+
+```ruby
+public_key_string = ECDSA::Format::PointOctetString.encode(public_key, compression: true)
+```
+
+Setting the `compression` option to `true` decreases the size of the string by
+almost 50% by only including one bit of the Y coordinate.  The other bits of the
+Y coordinate are deduced from the X coordinate when the string is decoded.
+    
+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
+is assumed to be an `ECDSA::Group`.
+
+```ruby
+public_key = ECDSA::Format::PointOctetString.decode(public_key_string, group)
+```
+
+## Signing a message
+
+This example shows how to generate a signature for a message.  In this example,
+we will use SHA2 as our digest algorithm, but other algorithms can be used.
+
+This example assumes that you trust the `SecureRandom` class in your Ruby
+implementation to generate the temporary key (also known as `k`).  Beware that
+if you accidentally sign two different messages with the same temporary key, it
+is easy for someone to compute your private key from those two signatures and
+then forge your signature.  Also, if someone can correctly guess the value of
+the temporary key used for a signature, they can compute your private key from
+that signature.
+
+This example assumes that you have required the `ecdsa` gem, that you have an
+`ECDSA::Group` object named `group`, and that you have the private key stored as
+an integer in a variable named `private_key`.
+
+```ruby
+require 'digest/sha2'
+message = 'ECDSA is cool.'
+digest = Digest::SHA2.digest(message)
+signature = nil
+while signature.nil?
+  temp_key = 1 + SecureRandom.random_number(group.order - 1)
+  signature = ECDSA.sign(group, private_key, digest, temp_key)
+end
+puts 'signature: '
+puts '  r: %#x' % signature.r
+puts '  s: %#x' % signature.s
+```
+    
+## Encoding a signature as a DER string
+
+Signatures can be stored and transmitted as a [DER](http://en.wikipedia.org/wiki/X.690) string.
+The code below encodes an `ECDSA::Signature` object as a binary DER string.
+
+```ruby
+signature_der_string = ECDSA::Format::SignatureDerString.encode(signature)
+```
+
+## Decoding a signature from a DER string
+
+The code below decodes a binary DER string to produce an `ECDSA::Signature` object.
+
+```ruby
+signature = ECDSA::Format::SignatureDerString.decode(signature_der_string)
+```
+    
+## Verifying a signature
+
+The code below shows how to verify an ECDSA signature.  It assumes that you have
+an `ECDSA::Point` object representing a public key, a string or integer
+representing the digest of the signed messaged, and an `ECDSA::Signature` object
+representing the signature.  The `valid_signature?` method returns `true` if the
+signature is valid and `false` if it is not.
+
+```ruby
+valid = ECDSA.valid_signature?(public_key, digest, signature)
+puts "valid: #{valid}"
+```
+
+## Supported platforms
 
-    gem install ecdsa
+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.

data/lib/ecdsa.rb

@@ -5,7 +5,9 @@ require_relative 'ecdsa/sign'
 require_relative 'ecdsa/format'
 require_relative 'ecdsa/version'
 
+# The top-level module for the ECDSA gem.
 module ECDSA
+  # This method is NOT part of the public API of the ECDSA gem.
   def self.byte_length(integer)
     length = 0
     while integer > 0
@@ -15,6 +17,7 @@ module ECDSA
     length
   end
 
+  # This method is NOT part of the public API of the ECDSA gem.
   def self.bit_length(integer)
     length = 0
     while integer > 0
@@ -24,14 +27,16 @@ module ECDSA
     length
   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 convert_octet_string_to_bit_string(digest)
+    when String then Format::IntegerOctetString.decode(digest)
     else raise "Invalid digest: #{digest.inspect}"
     end
   end
 
+  # 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'
@@ -40,20 +45,9 @@ module ECDSA
     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
-
-  # SEC1, Section 2.3.2.
-  # My interpretation of that section is that we treat the octet string as BIG endian.
-  def self.convert_octet_string_to_bit_string(string)
-    string.bytes.reduce { |n, b| (n << 8) + b }
-  end
-end
-
-class String
-  def hex_inspect
-    '"' + each_byte.map { |b| '\x%02x' % b }.join + '"'
-  end
 end

data/lib/ecdsa/format/field_element_octet_string.rb

@@ -1,17 +1,29 @@
-# Defined in http://www.secg.org/collateral/sec1_final.pdf
-# section 2.3.5: FieldElement-to-OctetString Conversion
-
 module ECDSA
   module Format
+    # This module provides methods for converting elements of a field to octet
+    # strings.  The conversions are defined in these sections of
+    # [SEC1](http://www.secg.org/collateral/sec1_final.pdf):
+    #
+    # * Section 2.3.5: FieldElement-to-OctetString Conversion
+    # * Section 2.3.6: OctetString-to-FieldElement Conversion
     module FieldElementOctetString
-      # @param integer (Integer) The integer to encode
-      # @param length (Integer) The number of bytes desired in the output string.
+      # Converts a field element to an octet string.
+      #
+      # @param element (Integer) The integer to encode.
+      # @param field (PrimeField)
+      # @return (String)
       def self.encode(element, field)
         raise ArgumentError, 'Given element is not an element of the field.' if !field.include?(element)
         length = ECDSA.byte_length(field.prime)
         IntegerOctetString.encode(element, length)
       end
 
+      # Converts an octet string to a field element.
+      # Raises a {DecodeError} if the input string is invalid for any reason.
+      #
+      # @param string (String)
+      # @param field (PrimeField)
+      # @return (Integer)
       def self.decode(string, field)
         int = IntegerOctetString.decode(string)
 

data/lib/ecdsa/format/integer_octet_string.rb

@@ -1,27 +1,34 @@
-# Defined in http://www.secg.org/collateral/sec1_final.pdf :
-# Section 2.3.7: Integer-to-OctetString Conversion
-# Section 2.3.8: OctetString-to-Integer Conversion
-
 module ECDSA
   module Format
+    # This module provides methods for converting integers to big endian octet
+    # strings.  The conversions are defined in these sections of
+    # [SEC1](http://www.secg.org/collateral/sec1_final.pdf):
+    #
+    # * Section 2.3.7: Integer-to-OctetString Conversion
+    # * Section 2.3.8: OctetString-to-Integer Conversion
+    #
+    # We use Ruby integers to represent bit strings, so this module can also be
+    # thought of as implementing these sections of SEC1:
+    #
+    # * Section 2.3.1: BitString-to-OctetString Conversion
+    # * Section 2.3.2: OctetString-to-BitString Conversion
     module IntegerOctetString
-      # @param integer (Integer) The integer to encode
+      # @param integer (Integer) The integer to encode.
       # @param length (Integer) The number of bytes desired in the output string.
+      # @return (String)
       def self.encode(integer, length)
         raise ArgumentError, 'Integer to encode is negative.' if integer < 0
         raise ArgumentError, 'Integer to encode is too large.' if integer >= (1 << (8 * length))
 
-        length.pred.downto(0).map do |i|
+        (length - 1).downto(0).map do |i|
           (integer >> (8 * i)) & 0xFF
         end.pack('C*')
       end
 
+      # @param string (String)
+      # @return (Integer)
       def self.decode(string)
-        integer = 0
-        string.each_byte do |b|
-          integer = (integer << 8) + b.ord
-        end
-        integer
+        string.bytes.reduce { |n, b| (n << 8) + b }
       end
     end
   end

data/lib/ecdsa/format/point_octet_string.rb

@@ -1,14 +1,23 @@
 # encoding: ASCII-8BIT
 
-# The point octet string format is defined in http://www.secg.org/collateral/sec1_final.pdf .
-# Section 2.3.3: EllipticCurvePoint-to-OctetString Conversion
-# Section 2.3.4: OctetString-to-EllipticCurvePoint Conversion
-
 require_relative '../point'
 
 module ECDSA
   module Format
+    # This module provides methods for converting between {Point} objects and "octet strings",
+    # which are just strings with binary data in them that have the coordinates of the point.
+    # The point octet string format is defined in two sections of [SEC1](http://www.secg.org/collateral/sec1_final.pdf):
+    #
+    # * Section 2.3.3: EllipticCurvePoint-to-OctetString Conversion
+    # * Section 2.3.4: OctetString-to-EllipticCurvePoint Conversion
     module PointOctetString
+      # Converts a {Point} to an octet string.
+      #
+      # @param point (Point)
+      # @param opts (Hash)
+      # @option opts :compression Set this option to true to generate a compressed
+      #   octet string, which only has one bit of the Y coordinate.
+      #   (Default: false)
       def self.encode(point, opts = {})
         return "\x00" if point.infinity?
 
@@ -22,9 +31,19 @@ module ECDSA
         end
       end
 
-      # This is equivalent to ec_GFp_simple_oct2point in OpenSSL:
-      # https://github.com/openssl/openssl/blob/a898936218bc279b5d7cdf76d58a25e7a2d419cb/crypto/ec/ecp_oct.c
+      # Converts an octet string to a {Point} in the specified group.
+      # Raises a {DecodeError} if the string is invalid for any reason.
+      #
+      # This is equivalent to
+      # [ec_GFp_simple_oct2point](https://github.com/openssl/openssl/blob/a898936/crypto/ec/ecp_oct.c#L325)
+      # in OpenSSL.
+      #
+      # @param string (String)
+      # @param group (Group)
+      # @return (Point)
       def self.decode(string, group)
+        string = string.dup.force_encoding('BINARY')
+
         raise DecodeError, 'Point octet string is empty.' if string.empty?
 
         case string[0].ord

data/lib/ecdsa/format/signature_der_string.rb

@@ -3,7 +3,13 @@ require_relative '../signature'
 
 module ECDSA
   module Format
+    # This module provides methods to convert between {Signature} objects and their
+    # binary DER representation.  The format used is defined in
+    # [RFC 3278 section 8.2](http://tools.ietf.org/html/rfc3278#section-8.2).
     module SignatureDerString
+      # Converts a DER string to a {Signature}.
+      # @param der_string (String)
+      # @return (Signature)
       def self.decode(der_string)
         asn1 = OpenSSL::ASN1.decode(der_string)
         r = asn1.value[0].value.to_i
@@ -11,10 +17,14 @@ module ECDSA
         Signature.new(r, s)
       end
 
+      # Converts a {Signature} to a DER string.
+      # @param signature (Signature)
+      # @return (String)
       def self.encode(signature)
-        ra = OpenSSL::ASN1::Integer.new signature.r
-        sa = OpenSSL::ASN1::Integer.new signature.s
-        asn1 = OpenSSL::ASN1::Sequence.new [ra, sa]
+        asn1 = OpenSSL::ASN1::Sequence.new [
+          OpenSSL::ASN1::Integer.new(signature.r),
+          OpenSSL::ASN1::Integer.new(signature.s),
+        ]
         asn1.to_der
       end
     end

data/lib/ecdsa/group.rb

@@ -3,26 +3,43 @@ require_relative 'point'
 
 module ECDSA
   class Group
+    # The name of the group.
+    # @return (String)
     attr_reader :name
 
+    # The generator point.
+    # @return (Point)
     attr_reader :generator
 
+    # The order of the group.  This is the smallest positive
+    # integer `i` such that the generator point multiplied by `i` is infinity.
+    # This is also the number of different points that are on the curve.
+    # @return (Order)
     attr_reader :order
 
+    # The a parameter in the curve equation (*y^2 = x^3 + ax + b*).
+    # @option opts :a (Integer)
     attr_reader :param_a
 
+    # The b parameter in the curve equation.
+    # @return (Integer)
     attr_reader :param_b
 
+    # The field that coordinates on the curve belong to.
+    # @return (PrimeField)
     attr_reader :field
 
     # These parameters are defined in http://www.secg.org/collateral/sec2_final.pdf
     #
-    # - +p+: A prime number that defines the field used.  The field will be F_p.
-    # - +a+: The a parameter in the curve equation (y^2 = x^3 + ax + b).
-    # - +b+: The b parameter in the curve equation.
-    # - +g+: The base point as an octet string.
-    # - +n+: The order of g.
-    # - +h+: The cofactor.
+    # @param opts (Hash)
+    # @option opts :p (Integer) A prime number that defines the field used.  The field will be *F<sub>p</sub>*.
+    # @option opts :a (Integer) The a parameter in the curve equation (*y^2 = x^3 + ax + b*).
+    # @option opts :b (Integer) The b parameter in the curve equation.
+    # @option opts :g (Array(Integer)) The coordinates of the generator point, with x first.
+    # @option opts :n (Integer) The order of g.  This is the smallest positive
+    #   integer `i` such that the generator point multiplied by `i` is infinity.
+    #   This is also the number of different points that are on the curve.
+    # @option opts :h (Integer) The cofactor (optional).
     def initialize(opts)
       @opts = opts
 
@@ -41,6 +58,9 @@ module ECDSA
       @param_b = field.mod @param_b
     end
 
+    # Creates a new point.
+    # The argument can either be an array of integers representing the
+    # coordinates, with x first, or it can be `:infinity`.
     def new_point(p)
       case p
       when :infinity
@@ -55,48 +75,69 @@ module ECDSA
       end
     end
 
+    # Returns the infinity point.
+    #
+    # @return (Point)
     def infinity
       @infinity ||= Point.new(self, :infinity)
     end
 
     # The number of bits that it takes to represent a member of the field.
     # Log base 2 of the prime p, rounded up.
+    #
+    # @return (Integer)
     def bit_length
       @bit_length ||= ECDSA.bit_length(field.prime)
     end
 
+    # The number of bytes that it takes to represent a member of the field.
+    # Log base 256 of the prime p, rounded up.
+    #
+    # @return (Integer)
     def byte_length
       @byte_length ||= ECDSA.byte_length(field.prime)
     end
 
-    # Verify that the point is a solution to the curve's defining equation.
+    # Returns true if the point is a solution to the curve's defining equation
+    # or if it is the infinity point.
     def include?(point)
-      raise 'Group mismatch.' if point.group != self
+      return false if point.group != self
       point.infinity? or point_satisfies_equation?(point)
     end
 
-    # You should probably use include? instead of this.
-    def point_satisfies_equation?(point)
-      field.mod(point.y * point.y) == equation_right_hand_side(point.x)
-    end
-
-    def equation_right_hand_side(x)
-      field.mod(x * x * x + param_a * x + param_b)
-    end
-
+    # Given the x coordinate of a point, finds all possible corresponding y coordinates.
+    #
+    # @return (Array)
     def solve_for_y(x)
       field.square_roots equation_right_hand_side x
     end
 
+    # @return (String)
     def inspect
       "#<#{self.class}:#{name}>"
     end
 
+    # @return (String)
     def to_s
       inspect
     end
 
+    private
+
+    def point_satisfies_equation?(point)
+      field.square(point.y) == equation_right_hand_side(point.x)
+    end
+
+    def equation_right_hand_side(x)
+      field.mod(x * x * x + param_a * x + param_b)
+    end
+
     NAMES = %w(
+      Nistp192
+      Nistp224
+      Nistp256
+      Nistp384
+      Nistp521
       Secp112r1
       Secp112r2
       Secp128r1
@@ -112,11 +153,6 @@ module ECDSA
       Secp256r1
       Secp384r1
       Secp521r1
-      Nistp192
-      Nistp224
-      Nistp256
-      Nistp384
-      Nistp521
     )
 
     NAMES.each do |name|

data/lib/ecdsa/point.rb

@@ -1,13 +1,31 @@
-# http://www.secg.org/collateral/sec1_final.pdf
-
 module ECDSA
+  # Instances of this class represent a point on an elliptic curve.
+  # The instances hold their `x` and `y` coordinates along with a reference to
+  # the {Group} (curve) they belong to.
+  #
+  # An instance of this class can also represent the infinity point
+  # (the additive identity of the group), in which case `x` and `y` are `nil`.
+  #
+  # Note: These {Point} objects are not checked when they are created so they
+  # might not actually be on the curve.  You can use {Group#include?} to see if
+  # they are on the curve.
   class Point
+    # @return {Group} the curve that the point is on.
     attr_reader :group
 
+    # @return (Integer or nil) the x coordinate, or nil for the infinity point.
     attr_reader :x
 
+    # @return (Integer or nil) the y coordinate, or nil for the infinity point.
     attr_reader :y
 
+    # Creates a new instance of {Point}.
+    # This method is NOT part of the public interface of the ECDSA gem.
+    # You should call {Group#new_point} instead of calling this directly.
+    #
+    # @param group (Group)
+    # @param args Either the x and y coordinates as integers, or just
+    #  `:infinity` to create the infinity point.
     def initialize(group, *args)
       @group = group
 
@@ -24,43 +42,62 @@ module ECDSA
       end
     end
 
+    # Returns an array of the coordinates, with `x` first and `y` second.
+    #
+    # @return (Array)
     def coords
       [x, y]
     end
 
-    def add_to_point(point)
-      check_group! point
+    # Adds this point to another point on the same curve using the standard
+    # rules for point addition defined in section 2.2.1 of
+    # [SEC1](http://www.secg.org/collateral/sec1_final.pdf).
+    #
+    # @param other (Point)
+    # @return The sum of the two points.
+    def add_to_point(other)
+      check_group! other
 
       # Assertions:
       # raise "point given (#{point.inspect}) does not belong to #{group.name}" if !group.include?(point)
       # raise "point (#{inspect}) does not belong to #{group.name}" if !group.include?(self)
 
-      # SEC1, section 2.2.1, rules 1 and 2
-      return point if infinity?
-      return self if point.infinity?
+      # Rules 1 and 2
+      return other if infinity?
+      return self if other.infinity?
 
-      # SEC1, section 2.2.1, rule 3
-      return group.infinity if x == point.x && y == field.mod(-point.y)
+      # Rule 3
+      return group.infinity if x == other.x && y == field.mod(-other.y)
 
-      # SEC1, section 2.2.1, rule 4
-      if x != point.x
-        gamma = field.mod((point.y - y) * field.inverse(point.x - x))
-        sum_x = field.mod(gamma * gamma - x - point.x)
+      # Rule 4
+      if x != other.x
+        gamma = field.mod((other.y - y) * field.inverse(other.x - x))
+        sum_x = field.mod(gamma * gamma - x - other.x)
         sum_y = field.mod(gamma * (x - sum_x) - y)
         return self.class.new(group, sum_x, sum_y)
       end
 
-      # SEC2, section 2.2.1, rule 5
-      return double if self == point
+      # Rule 5
+      return double if self == other
 
-      raise "Failed to add #{inspect} to #{point.inspect}: No addition rules matched."
+      raise "Failed to add #{inspect} to #{other.inspect}: No addition rules matched."
     end
 
+    # Returns the additive inverse of the point.
+    #
+    # @return (Point)
     def negate
       return self if infinity?
       self.class.new(group, x, field.mod(-y))
     end
 
+    # Returns the point added to itself.
+    #
+    # This algorithm is defined in
+    # [SEC1](http://www.secg.org/collateral/sec1_final.pdf), Section 2.2.1,
+    # Rule 5.
+    #
+    # @return (Point)
     def double
       return self if infinity?
       gamma = field.mod((3 * x * x + @group.param_a) * field.inverse(2 * y))
@@ -69,6 +106,10 @@ module ECDSA
       self.class.new(group, new_x, new_y)
     end
 
+    # Returns the point multiplied by a non-negative integer.
+    #
+    # @param i (Integer)
+    # @return (Point)
     def multiply_by_scalar(i)
       raise ArgumentError, 'Scalar is not an integer.' if !i.is_a?(Integer)
       raise ArgumentError, 'Scalar is negative.' if i < 0
@@ -82,19 +123,33 @@ module ECDSA
       result
     end
 
+    # Compares this point to another.
+    #
+    # @return (true or false) true if the points are equal
     def eql?(other)
       return false if !other.is_a?(Point) || other.group != group
       x == other.x && y == other.y
     end
 
+    # Compares this point to another.
+    #
+    # @return (true or false) true if the points are equal
     def ==(other)
       eql?(other)
     end
 
+    # Returns true if this instance represents the infinity point (the additive
+    # identity of the group).
+    #
+    # @return (true or false)
     def infinity?
       @infinity == true
     end
 
+    # Returns a string showing the value of the point which is useful for
+    # debugging.
+    #
+    # @return (String)
     def inspect
       if infinity?
         '#<%s: %s, infinity>' % [self.class, group.name]

data/lib/ecdsa/prime_field.rb

@@ -1,5 +1,20 @@
 module ECDSA
+  # Instances of this class represent a field where the elements are non-negative
+  # integers less than a prime *p*.
+  #
+  # To add two elements of the field:
+  #
+  # ```ruby
+  # sum = field.mod(a + b)
+  # ```
+  #
+  # To multiply two elements of the field:
+  #
+  # ```ruby
+  # product = field.mod(a * b)
+  # ```
   class PrimeField
+    # @return (Integer) the prime number that the field is based on.
     attr_reader :prime
 
     def initialize(prime)
@@ -7,23 +22,33 @@ module ECDSA
       @prime = prime
     end
 
+    # Returns true if the given object is an integer and a member of the field.
+    # @param e (Object)
+    # @return (true or false)
     def include?(e)
       e.is_a?(Integer) && e >= 0 && e < prime
     end
 
-    def mod(num)
-      num % prime
+    # Calculates the remainder of `n` after being divided by the field's prime.
+    # @param n (Integer)
+    # @return (Integer)
+    def mod(n)
+      n % prime
     end
 
-    # http://en.wikipedia.org/wiki/Extended_Euclidean_algorithm
-    def inverse(num)
-      raise ArgumentError, '0 has no multiplicative inverse.' if num.zero?
+    # Computes the multiplicative inverse of a field element using the
+    # [Extended Euclidean Algorithm](http://en.wikipedia.org/wiki/Extended_Euclidean_algorithm).
+    #
+    # @param n (Integer)
+    # @return (Integer) integer `inv` such that `(inv * num) % prime` is one.
+    def inverse(n)
+      raise ArgumentError, '0 has no multiplicative inverse.' if n.zero?
 
       # For every i, we make sure that num * s[i] + prime * t[i] = r[i].
       # Eventually r[i] will equal 1 because gcd(num, prime) is always 1.
       # At that point, s[i] is the multiplicative inverse of num in the field.
 
-      remainders = [num, prime]
+      remainders = [n, prime]
       s = [1, 0]
       t = [0, 1]
       arrays = [remainders, s, t]
@@ -34,12 +59,16 @@ module ECDSA
         end
       end
 
-      raise 'Inversion bug: remainder is not than 1.' if remainders[-2] != 1
+      raise 'Inversion bug: remainder is not 1.' if remainders[-2] != 1
       mod s[-2]
     end
 
-    # Computes n raised to the power m.
-    # This algorithm uses the same idea as Point#multiply_by_scalar.
+    # Computes `n` raised to the power `m`.
+    # This algorithm uses the same idea as {Point#multiply_by_scalar}.
+    #
+    # @param n (Integer) the base
+    # @param m (Integer) the exponent
+    # @return (Integer)
     def power(n, m)
       result = 1
       v = n
@@ -51,11 +80,19 @@ module ECDSA
       result
     end
 
-    # Computes n^2.
+    # Computes `n` multiplied by itself.
+    # @param n (Integer)
+    # @return (Integer)
     def square(n)
       mod n * n
     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
@@ -74,8 +111,7 @@ module ECDSA
     def square_roots_for_p_3_mod_4(n)
       candidate = power n, (prime + 1) / 4
       return [] if square(candidate) != n
-      return [candidate] if candidate.zero?
-      [candidate, mod(-candidate)].sort
+      [candidate, mod(-candidate)].uniq.sort
     end
   end
 end

data/lib/ecdsa/sign.rb

@@ -2,21 +2,34 @@ module ECDSA
   class SZeroError < StandardError
   end
 
-  # From http://www.secg.org/collateral/sec1_final.pdf section 4.1.3
-  # Warning: Never use the same k value twice for two different messages
-  # or else it will be trivial for someone to calculate your private key.
-  # k should be generated with a secure random number generator.
-  def self.sign(group, private_key, digest, k)
+  # Produces an ECDSA signature.
+  #
+  # This algorithm comes from section 4.1.3 of [SEC1](http://www.secg.org/collateral/sec1_final.pdf).
+  #
+  # @param group (Group) The curve that is being used.
+  # @param private_key (Integer) The private key.  (The number of times to add
+  #   the generator point to itself to get the public key.)
+  # @param digest (String or Integer)
+  #   A digest of the message to be signed, usually generated with a hashing algorithm
+  #   like SHA2.  The same algorithm must be used when verifying the signature.
+  # @param temporary_key (Integer)
+  #   A temporary private key.
+  #   This is also known as "k" in some documents.
+  #   Warning: Never use the same `temporary_key` value twice for two different messages
+  #   or else it will be easy for someone to calculate your private key.
+  #   The `temporary_key` should be generated with a secure random number generator.
+  # @return (Signature or nil)  Usually this method returns a {Signature}, but
+  #   there is a very small chance that the calculated "s" value for the
+  #   signature will be 0, in which case the method returns nil.  If that happens,
+  #   you should generate a new temporary key and try again.
+  def self.sign(group, private_key, digest, temporary_key)
     # Second part of step 1: Select ephemeral elliptic curve key pair
-    # k was already selected for us by the caller
-    r_point = group.new_point k
+    # temporary_key was already selected for us by the caller
+    r_point = group.new_point temporary_key
 
-    # Step 2
-    xr = r_point.x
-
-    # Step 3
+    # Steps 2 and 3
     point_field = PrimeField.new(group.order)
-    r = point_field.mod(xr)
+    r = point_field.mod(r_point.x)
 
     # Step 4, calculating the hash, was already performed by the caller.
 
@@ -24,11 +37,11 @@ module ECDSA
     e = normalize_digest(digest, group.bit_length)
 
     # Step 6
-    s = point_field.mod(point_field.inverse(k) * (e + r * private_key))
+    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 k and try again.
+      # random number temporary_key and try again.
       return nil
     end
 

data/lib/ecdsa/signature.rb

@@ -1,14 +1,23 @@
 module ECDSA
+  # Instances of this class represents ECDSA signatures,
+  # which are simply a pair of integers named `r` and `s`.
   class Signature
+    # @return (Integer)
     attr_reader :r
+
+    # @return (Integer)
     attr_reader :s
 
+    # @param r (Integer) the value of r.
+    # @param s (Integer) the value of s.
     def initialize(r, s)
       @r, @s = r, s
       r.is_a?(Integer) or raise ArgumentError, 'r is not an integer.'
       s.is_a?(Integer) or raise ArgumentError, 's is not an integer.'
     end
 
+    # Returns an array containing `r` first and `s` second.
+    # @return (Array)
     def components
       [r, s]
     end

data/lib/ecdsa/verify.rb

@@ -1,21 +1,38 @@
 module ECDSA
+  # An instance of this class is raised if the signature is invalid.
   class InvalidSignatureError < StandardError
   end
 
-  # Algorithm taken from http://www.secg.org/collateral/sec1_final.pdf Section 4.1.4.
+  # Verifies the given {Signature} and returns true if it is valid.
+  #
+  # This algorithm comes from Section 4.1.4 of [SEC1](http://www.secg.org/collateral/sec1_final.pdf).
+  #
+  # @param public_key (Point)
+  # @param digest (String or Integer)
+  # @param signature (Signature)
+  # @return true if the ECDSA signature if valid, returns false otherwise.
   def self.valid_signature?(public_key, digest, signature)
     check_signature! public_key, digest, signature
   rescue InvalidSignatureError
     false
   end
 
+  # Verifies the given {Signature} and raises an {InvalidSignatureError} if it
+  # is invalid.
+  #
+  # This algorithm comes from Section 4.1.4 of [SEC1](http://www.secg.org/collateral/sec1_final.pdf).
+  #
+  # @param public_key (Point)
+  # @param digest (String or Integer)
+  # @param signature (Signature)
+  # @return true
   def self.check_signature!(public_key, digest, signature)
     group = public_key.group
     field = group.field
 
     # Step 1: r and s must be in the field and non-zero
-    raise InvalidSignatureError, 'r value is not the field.' if !field.include?(signature.r)
-    raise InvalidSignatureError, 's value is not the field.' if !field.include?(signature.s)
+    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?
 

data/lib/ecdsa/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecdsa
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 1.0.0
 platform: ruby
 authors:
 - David Grayson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-18 00:00:00.000000000 Z
+date: 2014-04-06 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: davidegrayson@gmail.com
@@ -73,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '2'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.0
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: This gem implements the Ellipctic Curve Digital Signature Algorithm (ECDSA)