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. 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.
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 and
NIST's Recommended Elliptic Curves for Federal Government Use.
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.
This gem is hosted at the DavidEGrayson/ruby_ecdsa github repository.
Current limitations
- This gem only supports fields of integers modulo a prime number (Fp). ECDSA's characteristic 2 fields are not supported.
- 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.
Installation
This library is distributed as a gem named 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:
require 'ecdsa'
require 'securerandom'
group = ECDSA::Group::Secp256k1
private_key = 1 + SecureRandom.random_number(group.order - 1)
puts 'private key: %#x' % private_keyComputing 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.
public_key = group.generator.multiply_by_scalar(private_key)
puts 'public key: '
puts ' x: %#x' % public_key.x
puts ' y: %#x' % public_key.yThe 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 SEC1 with this code:
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 SEC1 octet string, you can use the code below. The group object
is assumed to be an ECDSA::Group.
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.
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.sEncoding a signature as a DER string
Signatures can be stored and transmitted as a DER string.
The code below encodes an ECDSA::Signature object as a binary DER string.
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.
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.
valid = ECDSA.valid_signature?(public_key, digest, signature)
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.
Documentation
For complete documentation, see the ECDSA page on RubyDoc.info.