# 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
(
*F*). ECDSA's characteristic 2 fields are not supported._{p} - 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_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.

```
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 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'
= 'ECDSA is cool.'
digest = Digest::SHA2.digest()
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 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.