rbsecp256k1 3.0.0 → 5.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adc488ad0d13cd01f56ce39b7c323ea57d9226b9380d747ebb8ef0c4cc62d6d1
-  data.tar.gz: 3118c92e72f09ff255483f7c90665236b9b060a881eb4c7d54b9d3a2791df747
+  metadata.gz: be2bc20e0b586daab65589d06c00e4bece13e864878d40000c0beea58b7664e7
+  data.tar.gz: cf3d966929ee5735a8aa3515e4e749233bab01e8d797804fbe4bfba33c1e8d7e
 SHA512:
-  metadata.gz: 5863c53473f0a162fffc82e319ab255b3e234acd0d425637783177e4c47e38768992b9d712f8957369e2ed53241eee377c31510e486d887e2cb6e9b12bb667b2
-  data.tar.gz: 046edbc96b3864969015ea02b2016fb167ae0c93172621801d7788ea484d3418a5868a8396aea57b4fbd21298157aa5a383b990dce00f2cceff68dd9f12106f0
+  metadata.gz: 5ca5dc9a5dde1c173be0b9dcf43beeaaab96bda3942284f2ee33184c10df18633906c9ff243337cff0b7e19e9f62b790d712ffee7a91180da61e405210e446be
+  data.tar.gz: b211a0431338b7d8a1f4b96a2f18006b779f5abd23daa92ba698043b120dbe71ff89b2c9ecef73d86fb34c58a8ef6f5ee320ef2febdf8c072803214b8cbf8270

data/README.md

@@ -0,0 +1,157 @@
+# rbsecp256k1
+
+[![Build Status](https://travis-ci.com/etscrivner/rbsecp256k1.svg?branch=master)](https://travis-ci.com/etscrivner/rbsecp256k1) [![Gem Version](https://badge.fury.io/rb/rbsecp256k1.svg)](https://badge.fury.io/rb/rbsecp256k1) [![Maintainability](https://api.codeclimate.com/v1/badges/d4b6e27bfa00030ca412/maintainability)](https://codeclimate.com/github/etscrivner/rbsecp256k1/maintainability)
+
+Native extension gem for secp256k1 ECDSA. Wraps [libsecp256k1](https://github.com/bitcoin-core/secp256k1). In
+rbsecp256k1 3.0.0 and later libsecp256k1 is bundled with the gem.
+
+* [Documentation](https://github.com/etscrivner/rbsecp256k1/blob/master/documentation/index.md)
+* [Examples](https://github.com/etscrivner/rbsecp256k1/blob/master/examples/README.md)
+
+### Why wrap libsecp256k1?
+
+[libsecp256k1](https://github.com/bitcoin-core/secp256k1) is an extremely optimized implementation of public key derivation,
+signing, and verification with the secp256k1 elliptic curve. It comes with its
+own set of benchmarks, but from [benchmarking done by Peter Wuille](https://www.reddit.com/r/Bitcoin/comments/2weymr/experiment_bitcoin_core_0100_initial_sync_time/coqghm2) it is ~4.9x
+faster than the OpenSSL implementation of the same curve. It is the only library
+that provides constant time signing of this curve and has been deployed as part
+of Bitcoin since [v0.10.0](https://bitcoin.org/en/release/v0.10.0#improved-signing-security)
+
+Natively wrapping the library in an extension gem means users don't have to
+worry about compiling or locating the library, unlike many [FFI](https://github.com/ffi/ffi) based gems.
+
+## Installation
+
+The simplest installation:
+
+```
+gem install rbsecp256k1
+```
+
+## Requirements
+
+If you want to use your system version of libsecp256k1 rather than the bundled
+version use the `--with-system-libraries` flag:
+
+```
+gem install rbsecp256k1 -- --with-system-libraries
+```
+
+#### Linux
+
+Install the dependencies for building libsecp256k1 and this library:
+
+```
+sudo apt-get install build-essential automake pkg-config libtool \
+  libffi-dev libssl-dev libgmp-dev python-dev
+```
+
+**NOTE:** If you have installed libsecp256k1 but the gem cannot find it. Ensure
+you have run `ldconfig` so that your library load paths have been updated.
+
+#### macOS
+
+Dependencies for building libsecp256k1 and this library:
+
+```
+brew install openssl libtool pkg-config gmp libffi
+```
+
+## Features
+
+See [rbsecp256k1 documentation](https://github.com/etscrivner/rbsecp256k1/blob/master/documentation/index.md) for examples and complete list of supported functionality.
+
+## Development
+
+### Cloning
+
+To clone the repository and its submodules you'll need to the following:
+
+```
+git clone git@github.com:etscrivner/rbsecp256k1.git
+```
+
+### Setup
+
+Development is largely facilitated by a makefile. After download you should run
+the following command to set up your local environment:
+
+```
+make setup
+```
+
+### Compiling Extension
+
+To compile the extension gem run the following (this is required to run tests):
+
+```
+make build
+```
+
+### Running Tests
+
+```
+make test
+```
+
+To test with recovery functionality disabled run:
+
+```
+make test WITH_RECOVERY=0
+```
+
+To test with ECDH functionality disabled run:
+
+```
+make test WITH_ECDH=0
+```
+
+To test with both disabled run:
+
+```
+make test WITH_RECOVERY=0 WITH_ECDH=0
+```
+
+Testing for memory leaks with valgrind:
+
+```
+make memcheck
+```
+
+### Building Gem
+
+```
+make gem
+```
+
+### Installing Gem Locally
+
+To install the gem locally and verify builds you can run:
+
+```
+make install
+```
+
+### Uninstall Gem Locally
+
+You can similarly uninstall the local gem by running the following:
+
+```
+make uninstall
+```
+
+### Cleaning Up
+
+To clean up and do a fresh build:
+
+```
+make clean
+```
+
+### Running YARD Documentation Server
+
+To run the [YARD](https://yardoc.org/) documentation server:
+
+```
+make docserver
+```

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rake/extensiontask"
 
 Rake::ExtensionTask.new "rbsecp256k1" do |ext|

data/documentation/context.md

@@ -0,0 +1,81 @@
+[Index](index.md)
+
+Secp256k1::Context
+==================
+
+Secp256k1::Context represents a libsecp256k1 context object. Contexts are
+thread-safe and initialization is expensive, so a single context should be used
+for multiple operations as much as possible.
+
+Initializers
+------------
+
+#### new(context_randomization_bytes: nil)
+
+Returns a newly initialized libsecp256k1 context. The context is randomized at
+initialization if given `context_randomization_bytes`. The
+`context_randomization_bytes` argument can optionally take a string containing
+32 bytes of random data, if not provided then the Context is not randomized and
+may be vulnerable to side-channel attacks.
+
+Class Methods
+-------------
+
+#### create
+
+Creates and returns a new randomized `Context` using `SecureRandom` for the
+random initialization bytes. This is the recommended method for initialization.
+
+#### create_unrandomized
+
+Creates a new unrandomized `Context`.
+
+Instance Methods
+----------------
+
+#### ecdh(point, scalar)
+
+**Requires:** libsecp256k1 was built with the experimental ECDH module.
+
+Takes a `point` ([PublicKey](public_key.md)) and a `scalar` ([PrivateKey](private_key.md)) and returns a new
+[SharedSecret](shared_secret.md) containing the 32-byte shared secret. Raises a `Secp256k1::Error` if
+the `scalar` is invalid (zero or causes an overflow).
+
+#### generate_key_pair
+
+Generates and returns a new [KeyPair](key_pair.md) using a cryptographically
+secure random number generator (CSRNG) provided by OpenSSL.
+
+#### key_pair_from_private_key(private_key_data)
+
+Returns a new [KeyPair](key_pair.md) from the given `private_key_data`. The
+`private_key_data` is expected to be a binary string. Raises a `Secp256k1::Error`
+if the private key is invalid or key derivation fails.
+
+#### recoverable_signature_from_compact(compact_signature, recovery_id)
+
+**Requires:** libsecp256k1 was build with recovery module.
+
+Attempts to load a [RecoverableSignature](recoverable_signature.md) from the given `compact_signature`
+and `recovery_id`. Raises a `Secp256k1::DeserializationError` if the signature data or recovery ID are invalid.
+
+#### sign(private_key, hash32)
+
+Signs the SHA-256 hash given by `hash32` using `private_key` and returns a new
+[Signature](signature.md). The `private_key` is expected to be a [PrivateKey](private_key.md)
+object and `data` can be either a binary string or text.
+
+#### sign_recoverable(private_key, hash32)
+
+**Requires:** libsecp256k1 was build with recovery module.
+
+Signs the data represented by the SHA-256 hash `hash32` using `private_key` and returns a
+new [RecoverableSignature](recoverable_signature.md). The `private_key` is expected to be a [PrivateKey](private_key.md) and
+`data` can be either a binary string or text.
+
+#### verify(signature, public_key, hash32)
+
+Verifies the given `signature` ([Signature](signature.md)) was signed by
+the private key corresponding to `public_key` ([PublicKey](public_key.md)) and signed `hash32`. Returns `true`
+if `signature` is valid or `false` otherwise. Note that `data` can be either a
+text or binary string.

data/documentation/index.md

@@ -0,0 +1,319 @@
+rbsecp256k1 Reference
+=====================
+
+Find your topic in the index, or refer to one of the examples below.
+
+Classes and Modules
+-------------------
+
+| Module                     | Classes                                          | Utilities
+|----------------------------|:-------------------------------------------------|:--------------------------------
+| [Secp256k1](secp256k1.md)  | [Context](context.md)                            | [Util](util.md)
+|                            | [KeyPair](key_pair.md)                           |
+|                            | [PublicKey](public_key.md)                       |
+|                            | [PrivateKey](private_key.md)                     |
+|                            | [SharedSecret](shared_secret.md)                 |
+|                            | [Signature](signature.md)                        |
+|                            | [RecoverableSignature](recoverable_signature.md) |
+
+Glossary
+--------
+
+**[Context](context.md)** is a libsecp256k1 library context. It contains
+pre-computed tables and values to make ECDSA signing and verification more
+efficient.
+
+**[KeyPair](key_pair.md)** is a Secp256k1 elliptic-curve key pair.
+
+**[PublicKey](public_key.md)** is a Secp256k1 public key. It can come in either
+compressed or uncompressed format.
+
+**[PrivateKey](private_key.md)** is a 64-byte Secp256k1 private key.
+
+**[SharedSecret](shared_secret.md)** A 32-byte shared secret computed from a
+public key (point) and private key (scalar).
+
+**[Signature](signature.md)** is an ECDSA signature of the SHA-256 message hash
+of a piece of data.
+
+**[RecoverableSignature](recoverable_signature.md)** is a recoverable ECDSA signature of the SHA-256 message
+hash of a piece of data.
+
+Examples
+--------
+
+### 1. Creating a libsecp256k1 context
+
+This example demonstrates how to create a new libsecp256k1 context. This is the
+first step of using this library:
+
+```ruby
+context = Secp256k1::Context.create
+# => #<Secp256k1::Context:0x0000559b0bd8f5d0>
+```
+
+### 2. Generating a key pair
+
+This example shows how to generate a new public-private key pair:
+
+```ruby
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+# => #<Secp256k1::KeyPair:0x0000559b0bc876b0 @public_key=#<Secp256k1::PublicKey:0x0000559b0bc876d8>, @private_key=#<Secp256k1::PrivateKey:0x0000559b0bc87700 @data="\r\xA7\xB3<\x92\xCDw\xC1\xDB\xEB[BB;=\x80\xB83\xA8]\x06\xD9\x90\xF8v\xFFi\xF0/\x1E\x96\xF9">>
+```
+
+### 3. Getting compressed and uncompressed public key representations
+
+This example shows how to generate compressed and uncompressed public keys:
+
+```ruby
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+# 1. Get the binary representation of compressed public key
+key_pair.public_key.compressed
+# => "\x03D\x88\xD6 3|3\x836\xCB(\x9CW%\xF4T\xB7\xCD\x8AF T\xE7\xE8\xCE\xB0\xC7c{\xE2:\xFE"
+
+# 2. Show hex representation of compressed public key
+Secp256k1::Util.bin_to_hex(key_pair.public_key.compressed)
+# => "034488d620337c338336cb289c5725f454b7cd8a462054e7e8ceb0c7637be23afe"
+
+# 3. Get the binary representation of uncompressed public key
+key_pair.public_key.uncompressed
+# => "\x04D\x88\xD6 3|3\x836\xCB(\x9CW%\xF4T\xB7\xCD\x8AF T\xE7\xE8\xCE\xB0\xC7c{\xE2:\xFE XRew\x1F\e\x05\xC8\xDC\xA7\xE3\x8C\xBD\x91s?\xFCW\xD5\xB3\xA8aaCCG\xD4\x94m\xA5c"
+
+# 4. Show hex representation of uncompressed public key
+Secp256k1::Util.bin_to_hex(key_pair.public_key.uncompressed)
+# => "044488d620337c338336cb289c5725f454b7cd8a462054e7e8ceb0c7637be23afe20585265771f1b05c8dca7e38cbd91733ffc57d5b3a86161434347d4946da563"
+```
+
+### 3. Signing a message
+
+This example shows how to sign a message using your private key:
+
+```ruby
+require 'digest'
+
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+signature = context.sign(key_pair.private_key, Digest::SHA256.digest("test message"))
+# => #<Secp256k1::Signature:0x0000559b0bc79358>
+```
+
+### 4. Getting DER and Compact signature encodings
+
+This example shows you how to get the DER encoded and compact encoded
+representations of a signature:
+
+```ruby
+require 'digest'
+
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+signature = context.sign(key_pair.private_key, Digest::SHA256.digest("test message"))
+
+# 1. Get the compact binary representation
+signature.compact
+# => "\xAB#e6_\x866\e\xAC\e\x92W\xC8a\x84N\xD4\xB6\x88\xF8\xEE\xDF\xFBC\xE8j\xB2\xF0\x10\xB8\xA0\x89\x13L\e\x9E\x91cB\xD7\xAC\x11\xF7\x02,Y&TM\xA5zp\xFD\xB3\xB1\xDCIV\xBB\\\xAF\x16@\xFC\x00"
+
+# 2. Get the compact hex representation
+Secp256k1::Util.bin_to_hex(signature.compact)
+# => "ab2365365f86361bac1b9257c861844ed4b688f8eedffb43e86ab2f010b8a089134c1b9e916342d7ac11f7022c5926544da57a70fdb3b1dc4956bb5caf1640fc00"
+
+# 3. Get the DER binary representation
+signature.der_encoded
+# => "0E\x02!\x00\xAB#e6_\x866\e\xAC\e\x92W\xC8a\x84N\xD4\xB6\x88\xF8\xEE\xDF\xFBC\xE8j\xB2\xF0\x10\xB8\xA0\x89\x02 \x13L\e\x9E\x91cB\xD7\xAC\x11\xF7\x02,Y&TM\xA5zp\xFD\xB3\xB1\xDCIV\xBB\\\xAF\x16@\xFC"
+
+# 4. Get the DER hex representation
+Secp256k1::Util.bin_to_hex(signature.der_encoded)
+# => "3045022100ab2365365f86361bac1b9257c861844ed4b688f8eedffb43e86ab2f010b8a0890220134c1b9e916342d7ac11f7022c5926544da57a70fdb3b1dc4956bb5caf1640fc"
+```
+
+### 5. Verifying a signature
+
+This example shows how to verify a signature using a public key:
+
+```ruby
+require 'digest'
+
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+hash = Digest::SHA256.digest("test message")
+
+signature = context.sign(key_pair.private_key, hash)
+
+# 1. Verify signature against matching message
+context.verify(signature, key_pair.public_key, hash)
+# => true
+
+# 2. Verify signature against different message
+context.verify(signature, key_pair.public_key, hash)
+# => false
+```
+
+### 6. Loading a private key or key pair from private key data
+
+This example shows how to load a key pair from raw binary private key data:
+
+```ruby
+context = Secp256k1::Context.create
+
+#1. Load private key alone
+private_key = Secp256k1::PrivateKey.from_data("I\nX\x85\xAEz}\n\x9B\xA4\\\x81)\xD4\x9Aq\xFDH\t\xBE\x8EP\xC5.\xC6\x1F7-\x86\xA0\xCB\xF9")
+# => #<Secp256k1::PrivateKey:0x00005647df1bcd30 @data="I\nX\x85\xAEz}\n\x9B\xA4\\\x81)\xD4\x9Aq\xFDH\t\xBE\x8EP\xC5.\xC6\x1F7-\x86\xA0\xCB\xF9">
+
+# 2. Load key pair from private key data
+key_pair = context.key_pair_from_private_key("I\nX\x85\xAEz}\n\x9B\xA4\\\x81)\xD4\x9Aq\xFDH\t\xBE\x8EP\xC5.\xC6\x1F7-\x86\xA0\xCB\xF9")
+# => #<Secp256k1::KeyPair:0x0000559b0bbf9a90 @public_key=#<Secp256k1::PublicKey:0x0000559b0bbf9ab8>, @private_key=#<Secp256k1::PrivateKey:0x0000559b0bbf9ae0 @data="I\nX\x85\xAEz}\n\x9B\xA4\\\x81)Ԛq\xFDH\t\xBE\x8EP\xC5.\xC6\u001F7-\x86\xA0\xCB\xF9">>
+```
+
+### 7. Loading a public key from binary data
+
+This example shows how to load a public key from binary data:
+
+```ruby
+# 1. Load public key from uncompressed pubkey
+public_key = Secp256k1::PublicKey.from_data("\x04$\xA2\xE7\xBB1\xC4|tN\xE6\xE4J-\xED\x9A[\xAFf-<\x14\x84^QQ\"\x14\xC3\x91\xE4\xF2\xB5\xEEEj\xAB\xD9\xFE\b\e7Zk\xC5{k\x12\xE3\xEA\xA2\xA5\xD7\xC1\xA5&\xE5|:K\xA9 X\xA3\x90")
+# => #<Secp256k1::PublicKey:0x0000559b0bdc72f0>
+
+# 2. Load public key from compressed pubkey
+public_key = Secp256k1::PublicKey.from_data("\x02$\xA2\xE7\xBB1\xC4|tN\xE6\xE4J-\xED\x9A[\xAFf-<\x14\x84^QQ\"\x14\xC3\x91\xE4\xF2\xB5")
+# => #<Secp256k1::PublicKey:0x0000559b0bdd3668>
+```
+
+### 8. Loading a DER or compact encoded signature
+
+This example shows how to load signatures from binary data:
+
+```ruby
+# 1. From DER encoded signature
+signature = Secp256k1::Signature.from_der_encoded("0D\x02 <\xC6\x7F/\x921l\x89Z\xFBs\x89p\xEE\x18u\x8B\x92\x9D\xA6\x84\xC5Y<t\xB7\xF1\f\xEE\f\x81J\x02 \t\"\xDF]\x1D\xA7W@^\xAAokH\b\x00\xE2L\xCF\x82\xA3\x05\x1E\x00\xF9\xFC\xB19\x0F\x93|\xB1f")
+# => #<Secp256k1::Signature:0x0000559b0b823d58>
+
+# 2. From compact signature
+signature = Secp256k1::Signature.from_compact("<\xC6\x7F/\x921l\x89Z\xFBs\x89p\xEE\x18u\x8B\x92\x9D\xA6\x84\xC5Y<t\xB7\xF1\f\xEE\f\x81J\t\"\xDF]\x1D\xA7W@^\xAAokH\b\x00\xE2L\xCF\x82\xA3\x05\x1E\x00\xF9\xFC\xB19\x0F\x93|\xB1f\x00")
+# => #<Secp256k1::Signature:0x0000559b0bdcaa68>
+```
+
+Recoverable Signature Examples
+------------------------------
+
+### 1. Checking for recovery module
+
+To check if you have compiled the recovery module into your local libsecp256k1
+run the following:
+
+```ruby
+Secp256k1.have_recovery?
+# => true
+```
+
+### 2. Sign data producing recoverable signature
+
+You can sign data producing a recoverable signature as follows:
+
+```ruby
+require 'digest'
+
+hash = Digest::SHA256.digest('test message')
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+signature = context.sign_recoverable(key_pair.private_key, hash)
+# => #<Secp256k1::RecoverableSignature:0x000055f2ea76e548>
+```
+
+### 3. Serialize recoverable signature as compact representation
+
+You can produce the compact binary serialization of a recoverable signature:
+
+```ruby
+require 'digest'
+
+hash = Digest::SHA256.digest('test message')
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+signature = context.sign_recoverable(key_pair.private_key, hash)
+compact_data, recovery_id = signature.compact
+# => ["D,\x9C\xA6%I\x14-\xCA\xC0\x11\x0F\xEB\x1E\xB0\xB6\\-\xE2\b\x98\xFB\xEA\xD5\x9BZ\xE6\xDF#\xC1\x1A\xEEL\xF02\xB1\xE9{\r\xEBhh<\\\xCF\xB6\x98\xEA\x8F\xF65\xF2\xBF\x84\xD8\xE5x\xF0\xA5)\xA2Wb\x9D", 1]
+```
+
+### 4. Recoverable signature from compact representation
+
+You can load a recoverable signature give its compact representation and
+recovery ID:
+
+```ruby
+context = Secp256k1::Context.create
+
+compact_data = "D,\x9C\xA6%I\x14-\xCA\xC0\x11\x0F\xEB\x1E\xB0\xB6\\-\xE2\b\x98\xFB\xEA\xD5\x9BZ\xE6\xDF#\xC1\x1A\xEEL\xF02\xB1\xE9{\r\xEBhh<\\\xCF\xB6\x98\xEA\x8F\xF65\xF2\xBF\x84\xD8\xE5x\xF0\xA5)\xA2Wb\x9D"
+recovery_id = 1
+
+signature = context.recoverable_signature_from_compact(compact_data, recovery_id)
+# => #<Secp256k1::RecoverableSignature:0x000055f2ea7615c8>
+```
+
+### 5. Convert recoverable signature to non-recoverable signature
+
+You can convert a recoverable signature to a non-recoverable signature suitable
+for use by all methods that take a [Signature](signature.md) object:
+
+```ruby
+require 'digest'
+
+hash = Digest::SHA256.digest('test message')
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+recoverable_signature = context.sign_recoverable(key_pair.private_key, hash)
+signature = recoverable_signature.to_signature
+# => #<Secp256k1::Signature:0x000055f2ea8ca4f0>
+```
+
+### 6. Recover public key from recoverable signature
+
+You can recover the [PublicKey](public_key.md) associated with a recoverable signature:
+
+```ruby
+require 'digest'
+
+hash = Digest::SHA256.digest('test message')
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+recoverable_signature = context.sign_recoverable(key_pair.private_key, hash)
+public_key = recoverable_signature.recover_public_key(hash)
+# => #<Secp256k1::PublicKey:0x000055f2ea756678>
+
+public_key == key_pair.public_key
+# => true
+```
+
+EC Diffie-Hellman
+-----------------
+
+### 1. Checking for ECDH module
+
+To check if you have compiled the ECDH module into your local libsecp256k1 run
+the following:
+
+```ruby
+Secp256k1.have_ecdh?
+# => true
+```
+
+### 2. Generating a shared secret
+
+To generate a shared secret run the following:
+
+```ruby
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+shared_secret = context.ecdh(key_pair.public_key, key_pair.private_key)
+shared_secret.data
+# => "\x1FQ\x90X\xA5\xF2\xAEx;\xD7i\xB6\\T,2[\x90\xD1)a$\x1CA\x17\x8F\e\x91\xE3\x06C\x93"
+```