rbsecp256k1 6.0.1 → 6.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a9f1c61d2e9881ffc8ba67ad800fe73d5b54b0e03728a18886c11cb865e00d4
-  data.tar.gz: 007d212fbc0d6a669f2fc9fc944c9e6b823c67cca59d98401c1840bc424f1944
+  metadata.gz: 713b484c223a4c3fec618c6d8050c964657a26ff73d9f4022a87b26b6009812b
+  data.tar.gz: c87b25bee566a967d8d3f9f28b5f99a4841942bb46ee062fbf9734e8082b02dc
 SHA512:
-  metadata.gz: 35c81811e74cecf9d268d447296956aefccb8de97dbf877b83b43f9ad09fcdccd8c4e93ae55dd24939227933835715336d6eac42753a9d762c2e939df0859580
-  data.tar.gz: f86d36d6c52ff5c9ed2d08c90d62170dd9dc66c411ff6c374c3904c57497940137415f5281a3f0080f54b53478813494f289ad3a66300f8ffe0ad896879112e4
+  metadata.gz: ad34fd4905564c2afd5694966ff783a05e851048530c255996f496db35f5ef109558609a2a28d944b9a7c6a9b4c3a9d4cc0d95b4e5be63473bfc4d489913fae3
+  data.tar.gz: a8b5a50de652d42050f42d38a3dbc87b7c2a923747d9cedd1b2c5651fbf995131b1a43cd0fb9253bfed304eb6e3215ca80dc73906a053f080c391a36e7542c2c

data/LICENSE

@@ -1,24 +1,24 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-For more information, please refer to <https://unlicense.org>
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

data/README.md

@@ -1,129 +1,134 @@
-# rbsecp256k1
-
-[![Spec](https://github.com/etscrivner/rbsecp256k1/actions/workflows/spec.yml/badge.svg?branch=master)](https://github.com/etscrivner/rbsecp256k1/actions/workflows/spec.yml) [![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 and Schnorr signatures. Wraps [libsecp256k1](https://github.com/bitcoin-core/secp256k1) without the need for FFI.
-
-* [Documentation](https://github.com/etscrivner/rbsecp256k1/blob/master/documentation/index.md)
-* [Examples](https://github.com/etscrivner/rbsecp256k1/blob/master/examples/README.md)
-
-### Features
-
-* Native extension gem wrapping [libsecp256k1](https://github.com/bitcoin-core/secp256k1), no FFI.
-* Schnorr signature support.
-
-### 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 python3-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 automake 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
-```
-
-### 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
-```
+# rbsecp256k1
+
+[![Spec](https://github.com/etscrivner/rbsecp256k1/actions/workflows/spec.yml/badge.svg?branch=master)](https://github.com/etscrivner/rbsecp256k1/actions/workflows/spec.yml) [![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 and Schnorr signatures. Wraps [libsecp256k1](https://github.com/bitcoin-core/secp256k1) without the need for FFI.
+
+* [Documentation](https://github.com/etscrivner/rbsecp256k1/blob/master/documentation/index.md)
+* [Examples](https://github.com/etscrivner/rbsecp256k1/blob/master/examples/README.md)
+
+### Features
+
+* Native extension gem wrapping [libsecp256k1](https://github.com/bitcoin-core/secp256k1), no FFI.
+* Schnorr signature support.
+
+### 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 python3-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 automake 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
+```
+
+### Line Endings
+
+.gitattributes keeps text files in Unix LF format across Windows, Linux, and
+macOS. Git detects binary files automatically and leaves their contents unchanged.
+
+### 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
+```
+
+### 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,18 +1,23 @@
-# frozen_string_literal: true
-
-require "rake/extensiontask"
-require "ruby_memcheck"
-require "rspec/core/rake_task"
-require 'ruby_memcheck/rspec/rake_task'
-
-RubyMemcheck.config(binary_name: "rbsecp256k1")
-
-# See: https://guides.rubygems.org/gems-with-extensions/
-Rake::ExtensionTask.new "rbsecp256k1" do |ext|
-  ext.lib_dir = 'lib/rbsecp256k1'
-end
-
-RSpec::Core::RakeTask.new(:spec)
-namespace :spec do
-  RubyMemcheck::RSpec::RakeTask.new(valgrind: :spec)
-end
+# frozen_string_literal: true
+
+require "rake/extensiontask"
+require "ruby_memcheck"
+require "rspec/core/rake_task"
+require 'ruby_memcheck/rspec/rake_task'
+require 'shellwords'
+
+memcheck_options = RubyMemcheck::Configuration::DEFAULT_VALGRIND_OPTIONS.dup
+if ENV['MEMCHECK_DEBUGINFO_PATH']
+  memcheck_options << "--extra-debuginfo-path=#{Shellwords.escape(File.expand_path(ENV['MEMCHECK_DEBUGINFO_PATH']))}"
+end
+RubyMemcheck.config(binary_name: "rbsecp256k1", valgrind_options: memcheck_options)
+
+# See: https://guides.rubygems.org/gems-with-extensions/
+Rake::ExtensionTask.new "rbsecp256k1" do |ext|
+  ext.lib_dir = 'lib/rbsecp256k1'
+end
+
+RSpec::Core::RakeTask.new(:spec)
+namespace :spec do
+  RubyMemcheck::RSpec::RakeTask.new(valgrind: :spec)
+end

data/documentation/context.md

@@ -1,98 +1,125 @@
-[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)
-
-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 Ruby's built-in
-`SecureRandom` cryptographically secure random number generator. This method
-simply invokes `key_pair_from_private_key` with the value from
-`SecureRandom.random_bytes`.
-
-#### 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.
-
-#### sign_schnorr(keypair, message)
-
-Same as `sign_schnorr_custom(keypair, message, auxrand)` but generates
-`auxrand` for you using `SecureRandom`. This should almost always be the method
-used for Schnorr signing.
-
-#### sign_schnorr_custom(keypair, message, auxrand)
-
-Sign the given 32-byte binary string `message` using the given `keypair`. It is
-recommend that `message` be generated using `tagged_sha256`. `auxrand` should
-be 32-bytes of fresh randomness, but can optionally be `nil` if generating
-randomness is expensive.
-
-#### tagged_sha256(tag, message)
-
-Computes the tagged hash as defined in [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki). Returns the 32-byte binary string tagged hash.
-
-#### 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.
+[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.
+
+`dup` and `clone` create independently owned native contexts using
+`secp256k1_context_clone`. The original and copy can be used and collected
+independently. Copying preserves the source context state; it does not provide
+fresh randomization. Use `Context.create` for a newly randomized context.
+Normal Ruby copy behavior applies: `clone` preserves frozen state, while `dup`
+returns an unfrozen copy. Copying an uninitialized context raises
+`Secp256k1::Error`.
+
+Native operations on an allocated context that has not completed initialization raise
+`Secp256k1::Error`. Reinitializing an existing context also raises
+`Secp256k1::Error` and leaves the existing context usable.
+
+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)
+
+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 Ruby's built-in
+`SecureRandom` cryptographically secure random number generator. This method
+simply invokes `key_pair_from_private_key` with the value from
+`SecureRandom.random_bytes`.
+
+#### 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.
+
+#### sign_schnorr(keypair, message)
+
+Signs a Ruby `String` containing any number of bytes, including zero bytes.
+
+Same as `sign_schnorr_custom(keypair, message, auxrand)` but generates
+`auxrand` for you using `SecureRandom`. This should almost always be the method
+used for Schnorr signing.
+
+#### sign_schnorr_custom(keypair, message, auxrand)
+
+Signs the bytes of the Ruby `String` `message` using the given [KeyPair](key_pair.md)
+and returns a [SchnorrSignature](schnorr_signature.md). Messages may have any byte
+length, including zero, and may contain null bytes. String encoding does not
+change the bytes being signed.
+
+The message is signed directly, without implicit hashing, padding, or truncation.
+If your protocol requires a tagged hash for domain separation, compute it
+explicitly with `tagged_sha256` before signing. Verification must use the same
+message bytes.
+
+`auxrand` must be a `String` containing exactly 32 bytes of fresh randomness,
+or `nil`. With `nil`, the default BIP-340 nonce function treats auxiliary
+randomness as 32 zero bytes. Prefer `sign_schnorr`, which generates fresh
+randomness automatically.
+
+Non-string messages or non-string, non-`nil` randomness raise `TypeError`.
+Randomness strings with a byte length other than 32 raise `Secp256k1::Error`.
+
+#### tagged_sha256(tag, message)
+
+Computes the tagged hash as defined in [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki). Returns the 32-byte binary string tagged hash.
+
+#### 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.