schnorr_sig 0.2.1.1 → 1.0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22902f36da6e027cac43fc471364294806a80fdc6d88e3743566d06ae632b3a1
-  data.tar.gz: a3759fb782d4aec2fd78b02113d6717bbf9892f6fb3b82be866b08e07ba38d5a
+  metadata.gz: d07355d7c8e4e0ce43bd586ba7cea831b72d2fd40b6c2efa1d49c46c536ab3ab
+  data.tar.gz: 346f2e23f326259d0e86f0837377e03cef56518b31828b22d3f7fa7ddca8b76b
 SHA512:
-  metadata.gz: 5afe8575ec3355d303720539e2e5019639214374f26cefa9c89f52dabd625dc79e12f055b4f5c775f40cf334a7ac11deaa095cc6295e6cd6e5ed3b3f27439dc2
-  data.tar.gz: 5950afef772f28370c7f1ca12bda717f560f8cf2f76d1c255fede1a8ce1677dea8dbd17ba4e4c55af7ac475058892c0da17e13235d6574b3155b7da6912d9f8c
+  metadata.gz: f91e124755a889779f7b5bda0991f9cd082078c855a5f8bcf2fe30886b779d5033d712801d776558bc454a5e5ba1a219fbd05f66b77dfd53098551dc7d6462e1
+  data.tar.gz: 7709c7e780d437dce791ac7f959350b71622c05c9838cdd6f5173fef3f232ace1a2e4b258ba56f697c4025266fab6e7b8ab0e0f6a77358d07880412963ae717f

data/README.md

@@ -1,3 +1,5 @@
+[![Tests Status](https://github.com/rickhull/schnorr_sig/actions/workflows/tests.yaml/badge.svg)](https://github.com/rickhull/schnorr_sig/actions/workflows/tests.yaml)
+
 # Schnorr Signatures
 
 This is a simple, minimal library written in Ruby for the purpose of
@@ -77,19 +79,101 @@ msg = 'hello world'
 # generate secret key and public key
 sk, pk = SchnorrSig.keypair
 
-# sign a message; exception raised on failure
+# we can sign the message itself
 sig = SchnorrSig.sign(sk, msg)
 
 # the signature has already been verified, but let's check
 SchnorrSig.verify?(pk, msg, sig)  # => true
+
+# more commonly, you can sign a SHA256 hash of the message
+h = Digest::SHA256.digest(msg)
+sig = SchnorrSig.sign(sk, h)
+SchnorrSig.verify?(pk, h, sig)    # => true
+
+# you can even use SchnorrSig's concept of a tagged hash
+h = SchnorrSig.tagged_hash('signing', msg)
+sig = SchnorrSig.sign(sk, h)
+SchnorrSig.verify?(pk, h, sig)    # => true
+
+# validate that the hash corresponds to the message
+# re-hash the message with the same tag
+SchnorrSig.tagged_hash('signing', msg) == h  # => true
 ```
 
-### Fast Implementation
+## Fundamentals
+
+Here are the fundamental functions common to both implementations:
+
+* `sign(32B sk, str msg)` *returns* `64B sig`
+* `verify?(32B pk, str msg, 64B sig)` *returns* `bool`
+* `pubkey(32B sk)` *returns* `32B pk`
+* `tagged_hash(str tag, str msg)` *returns* `32B hash`
+* `keypair()` *returns* `[32B sk, 32B pk]`
+
+Use `soft_verify?(pk, msg, sig)` to yield `false` if errors are raised.
+
+### Differences
+
+* Fast: `sign(32B sk, 32B msg)`
+
+The fast implementation only signs 32 byte payloads.  It expects to sign
+a hash of the message and not the message itself.  The pure implementation
+is happy to sign any payload.
+
+* Pure: `sign(32B sk, str msg, auxrand: 32B)` *(auxrand is optional)*
+
+The fast implementation always generates `auxrand` at signing time via
+`SecureRandom`.  The pure implementation allows `auxrand` to be passed in,
+but when omitted it will be generated by default by `SecureRandom`,
+though `Random` may also be used via `NO_SECURERANDOM` environment variable.
+
+## Enable Fast Implementation
+
+*The `rbsecp256k1` gem must be installed,
+otherwise there will be a `LoadError`.*
+
+Ensure `ENV['SCHNORR_SIG']&.downcase == 'fast'`, and then
+`require 'schnorr_sig'` will try the fast implementation first, before
+falling back to the pure implementation.
+
+After `require 'schnorr_sig'`, you can check which implementation is loaded
+by the presence of `SchnorrSig::Pure` or `SchnorrSig::Fast`.
+
+### Load Directly
+
+```ruby
+require 'schnorr_sig/fast'
+
+include SchnorrSig
+
+sk, pk = Fast.keypair
+msg = 'hello world'
+hsh = Fast.tagged_hash('message', msg)
+
+sig = Fast.sign(sk, hsh)
+Fast.verify?(pk, hsh, sig) # => true
+```
+
+### Side by Side
+
+You can run each implementation side by side as follows:
 
 ```ruby
-require 'schnorr_sig/fast' # not 'schnorr_sig'
+require 'schnorr_sig/pure'
+require 'schnorr_sig/fast'
+
+include SchnorrSig
+
+sk, pk = Pure.keypair  # or Fast.keypair
+
+msg = 'hello world'
+hsh = Fast.tagged_hash('message', msg)
+
+sig1 = Pure.sign(sk, hsh)
+sig2 = Fast.sign(sk, hsh)
 
-# everything else as above ...
+Fast.verify?(pk, hsh, sig1) # => true
+Pure.verify?(pk, hsh, sig2) # => true
 ```
 
 # Elliptic Curves
@@ -186,7 +270,7 @@ pk = big2bin(point.x)            # public key: point.x as a binary string
 ```
 
 The implementation of
-[big2bin](https://github.com/rickhull/schnorr_sig/blob/master/lib/schnorr_sig/util.rb#L30)
+[big2bin](https://github.com/rickhull/schnorr_sig/blob/master/lib/schnorr_sig/utils.rb#L26)
 is left as an exercise for the reader.
 
 ## Formatting

data/Rakefile

@@ -1,7 +1,26 @@
 require 'rake/testtask'
 
 Rake::TestTask.new :test do |t|
-  t.pattern = "test/*.rb"
+  t.test_files = [
+    'test/utils.rb',
+    'test/pure.rb',
+  ]
+  t.warning = true
+end
+
+Rake::TestTask.new :vectors do |t|
+  t.test_files = [
+    'test/vectors.rb',
+    'test/vectors_extra.rb',
+  ]
+  t.warning = true
+end
+
+Rake::TestTask.new :fast do |t|
+  t.test_files = [
+    'test/utils.rb',
+    'test/fast.rb',
+  ]
   t.warning = true
 end
 

data/VERSION

@@ -1 +1 @@
-0.2.1.1
+1.0.0.2

data/lib/schnorr_sig/fast.rb

@@ -1,85 +1,123 @@
-require 'schnorr_sig/util' # project
-require 'rbsecp256k1'      # gem, C extension
+require 'schnorr_sig/utils'
+require 'rbsecp256k1' # gem, C extension
 
-# re-open SchnorrSig to add more functions, errors, and constants
 module SchnorrSig
   CONTEXT = Secp256k1::Context.create
-  Error = Secp256k1::Error # enable: rescue SchnorrSig::Error
-  FORCE_32_BYTE_MSG = true
-
-  # Input
-  #   The secret key, sk: 32 bytes binary
-  #   The message, m:     UTF-8 / binary / agnostic
-  # Output
-  #   64 bytes binary
-  def self.sign(sk, m)
-    bytestring!(sk, 32) and string!(m)
-    m = m[0..31].ljust(32, ' ') if FORCE_32_BYTE_MSG
-    CONTEXT.sign_schnorr(key_pair(sk), m).serialized
-  end
 
-  # Input
-  #   The public key, pk: 32 bytes binary
-  #   The message, m:     UTF-8 / binary / agnostic
-  #   A signature, sig:   64 bytes binary
-  # Output
-  #   Boolean, may raise SchnorrSig::Error
-  def self.verify?(pk, m, sig)
-    bytestring!(pk, 32) and string!(m) and bytestring!(sig, 64)
-    signature(sig).verify(m, Secp256k1::XOnlyPublicKey.from_data(pk))
-  end
+  # KeyPair
+  # - Create / Split
+  #   * Context.create.generate_keypair => KeyPair
+  #   * KeyPair#xonly_public_key => XOnlyPublicKey
+  #   * KeyPair#private_key => PrivateKey
+  # - String Conversion
+  #   * Context.create.keypair_from_private_key(sk) => KeyPair
+  #   * XOnlyPublicKey.from_data(pk) => XOnlyPublicKey
+  #   * XOnlyPublicKey#serialized => pk
+  #   * PrivateKey#data => sk
+
+  # Signature
+  # - Sign / Verify
+  #   * Context.create.sign_schnorr(KeyPair, m) => Signature
+  #   * Signature#verify(m, XOnlyPublicKey) => bool
+  # - String Conversion
+  #   * Signature#serialized => sig (64B String)
+  #   * Signature#from_data(sig) => Signature
 
-  # Input
-  #   (The secret key, sk: 32 bytes binary)
-  # Output
-  #   Secp256k1::KeyPair
-  def self.key_pair(sk = nil)
-    if sk
-      bytestring!(sk, 32)
-      CONTEXT.key_pair_from_private_key(sk)
-    else
-      CONTEXT.generate_key_pair
+  module Fast
+
+    #
+    # Keys
+    #
+
+    # Input
+    #   (The secret key, sk: 32 bytes binary)
+    # Output
+    #   Secp256k1::KeyPair
+    def keypair_obj(sk = nil)
+      if sk
+        binary!(sk, KEY)
+        CONTEXT.key_pair_from_private_key(sk)
+      else
+        CONTEXT.generate_key_pair
+      end
     end
-  end
 
-  # Input
-  #   (The secret key, sk: 32 bytes binary)
-  # Output
-  #   [sk, pk]
-  def self.keypair(sk = nil)
-    kp = self.key_pair(sk)
-    [kp.private_key.data, kp.xonly_public_key.serialized]
-  end
+    # Input
+    #   Secp256k1::KeyPair
+    # Output
+    #  [sk, pk] (32 bytes binary)
+    def extract_keys(keypair_obj)
+      [keypair_obj.private_key.data, keypair_obj.xonly_public_key.serialized]
+    end
 
-  # Input
-  #   The secret key, sk: 32 bytes binary
-  # Output
-  #   The public key: 32 bytes binary
-  def self.pubkey(sk)
-    keypair(sk)[1]
-  end
+    # Input
+    #   The secret key, sk: 32 bytes binary
+    # Output
+    #   The public key: 32 bytes binary
+    def pubkey(sk) = keypair_obj(sk).xonly_public_key.serialized
 
-  # Input
-  #   The signature, str: 64 bytes binary
-  # Output
-  #   Secp256k1::SchnorrSignature
-  def self.signature(str)
-    bytestring!(str, 64)
-    Secp256k1::SchnorrSignature.from_data(str)
-  end
-end
+    # Output
+    #   [sk, pk] (32 bytes binary)
+    def keypair = extract_keys(keypair_obj())
 
-if __FILE__ == $0
-  msg = 'hello world'
+    #
+    # Signatures
+    #
 
-  sk, pk = SchnorrSig.keypair
-  puts "Message: #{msg}"
-  puts "Secret key: #{SchnorrSig.bin2hex(sk)}"
-  puts "Public key: #{SchnorrSig.bin2hex(pk)}"
+    # Input
+    #   The signature, str: 64 bytes binary
+    # Output
+    #   Secp256k1::SchnorrSignature
+    def signature(str)
+      binary!(str, SIG)
+      Secp256k1::SchnorrSignature.from_data(str)
+    end
+
+    # Input
+    #   The secret key, sk: 32 bytes binary
+    #   The message, m:     32 byte hash value
+    # Output
+    #   64 bytes binary
+    def sign(sk, m)
+      binary!(sk, KEY) and binary!(m, 32)
+      CONTEXT.sign_schnorr(keypair_obj(sk), m).serialized
+    end
+
+    # Input
+    #   The public key, pk: 32 bytes binary
+    #   The message, m:     32 byte hash value
+    #   A signature, sig:   64 bytes binary
+    # Output
+    #   Boolean, may raise SchnorrSig::Error, Secp256k1::Error
+    def verify?(pk, m, sig)
+      binary!(pk, KEY) and binary!(m, 32) and binary!(sig, SIG)
+      signature(sig).verify(m, Secp256k1::XOnlyPublicKey.from_data(pk))
+    end
+
+    # as above but swallow internal errors and return false
+    def soft_verify?(pk, m, sig)
+      begin
+        verify?(pk, m, sig)
+      rescue Secp256k1::Error
+        false
+      end
+    end
+
+    #
+    # Utility
+    #
+
+    # Input
+    #   tag: UTF-8 > binary > agnostic
+    #   msg: UTF-8 / binary / agnostic
+    # Output
+    #   32 bytes binary
+    def tagged_hash(tag, msg)
+      check!(tag, String) and check!(msg, String)
+      CONTEXT.tagged_sha256(tag, msg)
+    end
+  end
 
-  sig = SchnorrSig.sign(sk, msg)
-  puts
-  puts "Verified signature: #{SchnorrSig.bin2hex(sig)}"
-  puts "Encoding: #{sig.encoding}"
-  puts "Length: #{sig.length}"
+  Fast.include Utils
+  Fast.extend Fast
 end

data/lib/schnorr_sig/pure.rb

@@ -1,221 +1,228 @@
-require 'schnorr_sig/util'             # project
-require 'ecdsa_ext'                    # gem
+require 'schnorr_sig/utils'
+require 'ecdsa_ext'                    # gem, depends on ecdsa gem
 autoload :SecureRandom, 'securerandom' # stdlib
 
 # This implementation is based on the BIP340 spec: https://bips.xyz/340
-# re-open SchnorrSig to add more functions, errors, and constants
 module SchnorrSig
-  class Error < RuntimeError; end
-  class BoundsError < Error; end
   class SanityCheck < Error; end
-  class VerifyFail < Error; end
-  class InfinityPoint < Error; end
 
   GROUP = ECDSA::Group::Secp256k1
   P = GROUP.field.prime # smaller than 256**32
   N = GROUP.order       # smaller than P
   B = GROUP.byte_length # 32
 
-  # val (dot) G, returns ECDSA::Point
-  def self.dot_group(val)
-    # ecdsa_ext uses jacobian projection: 10x faster than GROUP.generator * val
-    (GROUP.generator.to_jacobian * val).to_affine
-  end
+  module Pure
 
-  # returns even_val or N - even_val
-  def self.select_even_y(point, even_val)
-    point.y.even? ? even_val : N - even_val
-  end
+    #
+    # Utils
+    #
 
-  # int(x) function signature matches BIP340, returns a bignum (presumably)
-  class << self
-    alias_method :int, :bin2big
-  end
+    # use SecureRandom unless ENV['NO_SECURERANDOM'] is nonempty
+    def random_bytes(count)
+      nsr = ENV['NO_SECURERANDOM']
+      (nsr and !nsr.empty?) ? Random.bytes(count) : SecureRandom.bytes(count)
+    end
 
-  # bytes(val) function signature matches BIP340, returns a binary string
-  def self.bytes(val)
-    case val
-    when Integer
-      # BIP340: The function bytes(x), where x is an integer,
-      # returns the 32-byte encoding of x, most significant byte first.
-      big2bin(val)
-    when ECDSA::Point
-      # BIP340: The function bytes(P), where P is a point, returns bytes(x(P)).
-      val.infinity? ? raise(InfinityPoint, va.inspect) : big2bin(val.x)
-    else
-      raise(SanityCheck, val.inspect)
+    # int (dot) G, returns ECDSA::Point
+    def point(int)
+      (GROUP.generator.to_jacobian * int).to_affine # 10x faster via ecdsa_ext
     end
-  end
 
-  # Input
-  #   The secret key, sk:       32 bytes binary
-  #   The message, m:           binary / UTF-8 / agnostic
-  #   Auxiliary random data, a: 32 bytes binary
-  # Output
-  #   The signature, sig:       64 bytes binary
-  def self.sign(sk, m, a = Random.bytes(B))
-    bytestring!(sk, B) and string!(m) and bytestring!(a, B)
-
-    # BIP340: Let d' = int(sk)
-    # BIP340: Fail if d' = 0 or d' >= n
-    d0 = int(sk)
-    raise(BoundsError, "d0") if !d0.positive? or d0 >= N
-
-    # BIP340: Let P = d' . G
-    p = dot_group(d0) # this is a point on the elliptic curve
-    bytes_p = bytes(p)
-
-    # BIP340: Let d = d' if has_even_y(P), otherwise let d = n - d'
-    d = select_even_y(p, d0)
-
-    # BIP340: Let t be the bytewise xor of bytes(d) and hash[BIP0340/aux](a)
-    t = d ^ int(tagged_hash('BIP0340/aux', a))
-
-    # BIP340: Let rand = hash[BIP0340/nonce](t || bytes(P) || m)
-    nonce = tagged_hash('BIP0340/nonce', bytes(t) + bytes_p + m)
-
-    # BIP340: Let k' = int(rand) mod n
-    # BIP340: Fail if k' = 0
-    k0 = int(nonce) % N
-    raise(BoundsError, "k0") if !k0.positive?
-
-    # BIP340: Let R = k' . G
-    r = dot_group(k0) # this is a point on the elliptic curve
-    bytes_r = bytes(r)
-
-    # BIP340: Let k = k' if has_even_y(R), otherwise let k = n - k'
-    k = select_even_y(r, k0)
-
-    # BIP340:
-    #   Let e = int(hash[BIP0340/challenge](bytes(R) || bytes(P) || m)) mod n
-    e = int(tagged_hash('BIP0340/challenge', bytes_r + bytes_p + m)) % N
-
-    # BIP340: Let sig = bytes(R) || bytes((k + ed) mod n)
-    # BIP340: Fail unless Verify(bytes(P), m, sig)
-    # BIP340: Return the signature sig
-    sig = bytes_r + bytes((k + e * d) % N)
-    raise(VerifyFail) unless verify?(bytes_p, m, sig)
-    sig
-  end
+    # returns even_val or N - even_val
+    def select_even_y(point, even_val)
+      point.y.even? ? even_val : N - even_val
+    end
 
-  # see https://bips.xyz/340#design (Tagged hashes)
-  # Input
-  #   A tag:            UTF-8 > binary > agnostic
-  #   The payload, msg: UTF-8 / binary / agnostic
-  # Output
-  #   32 bytes binary
-  def self.tagged_hash(tag, msg)
-    string!(tag) and string!(msg)
-    warn("tag expected to be UTF-8") unless tag.encoding == Encoding::UTF_8
-
-    # BIP340: The function hash[name](x) where x is a byte array
-    #         returns the 32-byte hash
-    #         SHA256(SHA256(tag) || SHA256(tag) || x)
-    #         where tag is the UTF-8 encoding of name.
-    tag_hash = Digest::SHA256.digest(tag)
-    Digest::SHA256.digest(tag_hash + tag_hash + msg)
-  end
+    # int(x) function signature matches BIP340, returns a bignum (presumably)
+    def int(x) = bin2big(x)
+
+    # bytes(val) function signature matches BIP340, returns a binary string
+    def bytes(val)
+      case val
+      when Integer
+        # BIP340: The function bytes(x), where x is an integer,
+        # returns the 32-byte encoding of x, most significant byte first.
+        big2bin(val)
+      when ECDSA::Point
+        # BIP340: The function bytes(P), where P is a point,
+        # returns bytes(x(P)).
+        val.infinity? ? raise(SanityCheck, val.inspect) : big2bin(val.x)
+      else
+        raise(SanityCheck, val.inspect)
+      end
+    end
 
-  # Input
-  #   The public key, pk: 32 bytes binary
-  #   The message, m:     UTF-8 / binary / agnostic
-  #   A signature, sig:   64 bytes binary
-  # Output
-  #   Boolean
-  def self.verify?(pk, m, sig)
-    bytestring!(pk, B) and string!(m) and bytestring!(sig, B * 2)
-
-    # BIP340: Let P = lift_x(int(pk))
-    p = lift_x(int(pk))
-
-    # BIP340: Let r = int(sig[0:32]) fail if r >= p
-    r = int(sig[0..B-1])
-    raise(BoundsError, "r >= p") if r >= P
-
-    # BIP340: Let s = int(sig[32:64]); fail if s >= n
-    s = int(sig[B..-1])
-    raise(BoundsError, "s >= n") if s >= N
-
-    # BIP340:
-    #   Let e = int(hash[BIP0340/challenge](bytes(r) || bytes(P) || m)) mod n
-    e = bytes(r) + bytes(p) + m
-    e = int(tagged_hash('BIP0340/challenge', e)) % N
-
-    # BIP340: Let R = s . G - e . P
-    # BIP340: Fail if is_infinite(R)
-    # BIP340: Fail if not has_even_y(R)
-    # BIP340: Fail if x(R) != r
-    # BIP340: Return success iff no failure occurred before reaching this point
-    big_r = dot_group(s) + p.multiply_by_scalar(e).negate
-    !big_r.infinity? and big_r.y.even? and big_r.x == r
-  end
+    # BIP340: The function lift_x(x), where x is a 256-bit unsigned integer,
+    #         returns the point P for which x(P) = x and has_even_y(P),
+    #         or fails if x is greater than p-1 or no such point exists.
+    # Input
+    #   A large integer, x
+    # Output
+    #   ECDSA::Point
+    def lift_x(x)
+      check!(x, Integer)
 
-  # BIP340: The function lift_x(x), where x is a 256-bit unsigned integer,
-  #         returns the point P for which x(P) = x and has_even_y(P),
-  #         or fails if x is greater than p-1 or no such point exists.
-  # Input
-  #   A large integer, x
-  # Output
-  #   ECDSA::Point
-  def self.lift_x(x)
-    integer!(x)
+      # BIP340: Fail if x >= p
+      raise(SanityCheck, "x") if x >= P or x <= 0
 
-    # BIP340: Fail if x >= p
-    raise(BoundsError, "x") if x >= P or x <= 0
+      # BIP340: Let c = x^3 + 7 mod p
+      c = (x.pow(3, P) + 7) % P
 
-    # BIP340: Let c = x^3 + 7 mod p
-    c = (x.pow(3, P) + 7) % P
+      # BIP340: Let y = c ^ ((p + 1) / 4) mod p
+      y = c.pow((P + 1) / 4, P) # use pow to avoid Bignum overflow
 
-    # BIP340: Let y = c ^ ((p + 1) / 4) mod p
-    y = c.pow((P + 1) / 4, P) # use pow to avoid Bignum overflow
+      # BIP340: Fail if c != y^2 mod p
+      raise(SanityCheck, "c != y^2 mod p") if c != y.pow(2, P)
 
-    # BIP340: Fail if c != y^2 mod p
-    raise(SanityCheck, "c != y^2 mod p") if c != y.pow(2, P)
+      # BIP340: Return the unique point P such that:
+      #   x(P) = x and y(P) = y    if y mod 2 = 0
+      #   y(P) = p - y             otherwise
+      GROUP.new_point [x, y.even? ? y : P - y]
+    end
 
-    # BIP340: Return the unique point P such that:
-    #   x(P) = x and y(P) = y    if y mod 2 = 0
-    #   y(P) = p - y             otherwise
-    GROUP.new_point [x, y.even? ? y : P - y]
-  end
+    # see https://bips.xyz/340#design (Tagged hashes)
+    # Input
+    #   A tag:            UTF-8 > binary > agnostic
+    #   The payload, msg: UTF-8 / binary / agnostic
+    # Output
+    #   32 bytes binary
+    def tagged_hash(tag, msg)
+      check!(tag, String) and check!(msg, String)
+      warn("tag expected to be UTF-8") unless tag.encoding == Encoding::UTF_8
+
+      # BIP340: The function hash[name](x) where x is a byte array
+      #         returns the 32-byte hash
+      #         SHA256(SHA256(tag) || SHA256(tag) || x)
+      #         where tag is the UTF-8 encoding of name.
+      tag_hash = Digest::SHA256.digest(tag)
+      Digest::SHA256.digest(tag_hash + tag_hash + msg)
+    end
 
-  # Input
-  #   The secret key, sk: 32 bytes binary
-  # Output
-  #   32 bytes binary (represents P.x for point P on the curve)
-  def self.pubkey(sk)
-    bytestring!(sk, B)
-
-    # BIP340: Let d' = int(sk)
-    # BIP340: Fail if d' = 0 or d' >= n
-    # BIP340: Return bytes(d' . G)
-    d0 = int(sk)
-    raise(BoundsError, "d0") if !d0.positive? or d0 >= N
-    bytes(dot_group(d0))
-  end
+    #
+    # Keys
+    #
+
+    # Input
+    #   The secret key, sk: 32 bytes binary
+    # Output
+    #   32 bytes binary (represents P.x for point P on the curve)
+    def pubkey(sk)
+      binary!(sk, KEY)
+
+      # BIP340: Let d' = int(sk)
+      # BIP340: Fail if d' = 0 or d' >= n
+      # BIP340: Return bytes(d' . G)
+      d0 = int(sk)
+      raise(SanityCheck, "d0") if !d0.positive? or d0 >= N
+      bytes(point(d0))
+    end
 
-  # generate a new keypair based on random data
-  def self.keypair
-    sk = Random.bytes(B)
-    [sk, pubkey(sk)]
-  end
+    # generate a new keypair based on random data
+    def keypair
+      sk = random_bytes(KEY)
+      [sk, pubkey(sk)]
+    end
 
-  # as above, but using SecureRandom
-  def self.secure_keypair
-    sk = SecureRandom.bytes(B)
-    [sk, pubkey(sk)]
+    #
+    # Signatures
+    #
+
+    # Input
+    #   The secret key, sk:       32 bytes binary
+    #   The message, m:           binary / UTF-8 / agnostic
+    #   Auxiliary random data, a: 32 bytes binary
+    # Output
+    #   The signature, sig:       64 bytes binary
+    def sign(sk, m, auxrand: nil)
+      a = auxrand.nil? ? random_bytes(B) : auxrand
+      binary!(sk, KEY) and check!(m, String) and binary!(a, B)
+
+      # BIP340: Let d' = int(sk)
+      # BIP340: Fail if d' = 0 or d' >= n
+      d0 = int(sk)
+      raise(SanityCheck, "d0") if !d0.positive? or d0 >= N
+
+      # BIP340: Let P = d' . G
+      p = point(d0) # this is a point on the elliptic curve
+      bytes_p = bytes(p)
+
+      # BIP340: Let d = d' if has_even_y(P), otherwise let d = n - d'
+      d = select_even_y(p, d0)
+
+      # BIP340: Let t be the bytewise xor of bytes(d) and hash[BIP0340/aux](a)
+      t = d ^ int(tagged_hash('BIP0340/aux', a))
+
+      # BIP340: Let rand = hash[BIP0340/nonce](t || bytes(P) || m)
+      nonce = tagged_hash('BIP0340/nonce', bytes(t) + bytes_p + m)
+
+      # BIP340: Let k' = int(rand) mod n
+      # BIP340: Fail if k' = 0
+      k0 = int(nonce) % N
+      raise(SanityCheck, "k0") if !k0.positive?
+
+      # BIP340: Let R = k' . G
+      r = point(k0) # this is a point on the elliptic curve
+      bytes_r = bytes(r)
+
+      # BIP340: Let k = k' if has_even_y(R), otherwise let k = n - k'
+      k = select_even_y(r, k0)
+
+      # BIP340:
+      #   Let e = int(hash[BIP0340/challenge](bytes(R) || bytes(P) || m)) mod n
+      e = int(tagged_hash('BIP0340/challenge', bytes_r + bytes_p + m)) % N
+
+      # BIP340: Let sig = bytes(R) || bytes((k + ed) mod n)
+      # BIP340: Fail unless Verify(bytes(P), m, sig)
+      # BIP340: Return the signature sig
+      sig = bytes_r + bytes((k + e * d) % N)
+      raise(SanityCheck, "sig did not verify") unless verify?(bytes_p, m, sig)
+      sig
+    end
+
+    # Input
+    #   The public key, pk: 32 bytes binary
+    #   The message, m:     UTF-8 / binary / agnostic
+    #   A signature, sig:   64 bytes binary
+    # Output
+    #   Boolean
+    def verify?(pk, m, sig)
+      binary!(pk, KEY) and check!(m, String) and binary!(sig, SIG)
+
+      # BIP340: Let P = lift_x(int(pk))
+      p = lift_x(int(pk))
+
+      # BIP340: Let r = int(sig[0:32]) fail if r >= p
+      r = int(sig[0..KEY-1])
+      raise(SanityCheck, "r >= p") if r >= P
+
+      # BIP340: Let s = int(sig[32:64]); fail if s >= n
+      s = int(sig[KEY..-1])
+      raise(SanityCheck, "s >= n") if s >= N
+
+      # BIP340:
+      #   Let e = int(hash[BIP0340/challenge](bytes(r) || bytes(P) || m)) mod n
+      e = bytes(r) + bytes(p) + m
+      e = int(tagged_hash('BIP0340/challenge', e)) % N
+
+      # BIP340: Let R = s . G - e . P
+      # BIP340: Fail if is_infinite(R)
+      # BIP340: Fail if not has_even_y(R)
+      # BIP340: Fail if x(R) != r
+      # BIP340: Return success iff no prior failure
+      big_r = point(s) + p.multiply_by_scalar(e).negate
+      !big_r.infinity? and big_r.y.even? and big_r.x == r
+    end
+
+    # as above but swallow internal errors and return false
+    def soft_verify?(pk, m, sig)
+      begin
+        verify?(pk, m, sig)
+      rescue SanityCheck
+        false
+      end
+    end
   end
-end
 
-if __FILE__ == $0
-  msg = 'hello world'
-  sk, pk = SchnorrSig.keypair
-  puts "Message: #{msg}"
-  puts "Secret key: #{SchnorrSig.bin2hex(sk)}"
-  puts "Public key: #{SchnorrSig.bin2hex(pk)}"
-
-  sig = SchnorrSig.sign(sk, msg)
-  puts
-  puts "Verified signature: #{SchnorrSig.bin2hex(sig)}"
-  puts "Encoding: #{sig.encoding}"
-  puts "Length: #{sig.length}"
+  Pure.include Utils
+  Pure.extend Pure
 end

data/lib/schnorr_sig/utils.rb

@@ -0,0 +1,36 @@
+module SchnorrSig
+  class Error < RuntimeError; end
+  class SpecError < Error; end
+
+  KEY = 32 # bytes
+  SIG = 64 # bytes
+
+  module Utils
+    # raise SpecError or return val
+    def check!(val, cls)
+      val.is_a?(cls) ? val : raise(SpecError, "#{cls}: #{val.inspect}")
+    end
+
+    # raise SpecError or return str
+    def binary!(str, length)
+      check!(str, String)
+      if str.encoding != Encoding::BINARY
+        raise(SpecError, "Encoding: #{str.encoding}")
+      end
+      raise(SpecError, "Length: #{str.length}") if str.length != length
+      str
+    end
+
+    # likely returns a Bignum, larger than a 64-bit hardware integer
+    def bin2big(str) = bin2hex(str).to_i(16)
+
+    # convert a giant integer to a binary string
+    def big2bin(bignum) = hex2bin(bignum.to_s(16).rjust(64, '0'))
+
+    # convert a binary string to a lowercase hex string
+    def bin2hex(str) = str.unpack1('H*')
+
+    # convert a hex string to a binary string
+    def hex2bin(hex) = [hex].pack('H*')
+  end
+end

data/lib/schnorr_sig.rb

@@ -1,10 +1,16 @@
+loaded = false
+
 if ENV['SCHNORR_SIG']&.downcase == 'fast'
   begin
     require 'schnorr_sig/fast'
-  rescue LoadError
-    warn "LoadError: schnorr_sig/fast cannot be loaded"
-    require 'schnorr_sig/pure'
+    SchnorrSig.extend SchnorrSig::Fast
+    loaded = true
+  rescue LoadError => e
+    warn [e.class, e.message].join(': ')
   end
-else
+end
+
+unless loaded
   require 'schnorr_sig/pure'
+  SchnorrSig.extend SchnorrSig::Pure
 end

data/schnorr_sig.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'schnorr_sig'
-  s.summary = "Schnorr signatures in Ruby, multiple implementations"
+  s.summary = "Schnorr signatures in Ruby; multiple implementations"
   s.description = "Pure ruby based on ECDSA gem; separate libsecp256k1 impl"
   s.authors = ["Rick Hull"]
   s.homepage = "https://github.com/rickhull/schnorr_sig"
@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.files = %w[schnorr_sig.gemspec VERSION README.md Rakefile]
   s.files += Dir['lib/**/*.rb']
   s.files += Dir['test/**/*.rb']
-  # s.files += Dir['examples/**/*.rb']
+  s.files += Dir['sig/**/*.rbs']
 
   s.add_dependency "ecdsa_ext", "~> 0"
 end

data/sig/fast.rbs

@@ -0,0 +1,15 @@
+module SchnorrSig
+  CONTEXT: Secp256k1::Context
+
+  module Fast
+    def keypair_obj: (?String sk) -> Secp256k1::KeyPair
+    def extract_keys: (Secp256k1::KeyPair keypair_obj) -> [String, String]
+    def pubkey: (String sk) -> String
+    def keypair: -> [String, String]
+    def signature: (String str) -> Secp256k1::SchnorrSignature
+    def sign: (String sk, String m) -> String
+    def verify?: (String pk, String m, String sig) -> bool
+    def soft_verify?: (String pk, String m, String sig) -> bool
+    def tagged_hash: (String tag, String msg) -> String
+  end
+end

data/sig/pure.rbs

@@ -0,0 +1,24 @@
+module SchnorrSig
+  class SanityCheck < Error
+  end
+
+  GROUP: ECDSA::Group::Secp256k1
+  P: Integer
+  N: Integer
+  B: Integer
+
+  module Pure
+    def random_bytes: (Integer count) -> String
+    def point: (Integer int) -> ECDSA::Point
+    def select_even_y: (ECDSA::Point point, Integer even_val) -> Integer
+    def int: (String x) -> Integer
+    def bytes: (Integer | ECDSA::Point val) -> String
+    def lift_x: (Integer x) -> ECDSA::Point
+    def tagged_hash: (String tag, String msg) -> String
+    def pubkey: (String sk) -> String
+    def keypair: -> [String, String]
+    def sign: (String sk, String m, ?auxrand: String?) -> String
+    def verify?: (String pk, String m, String sig) -> bool
+    def soft_verify?: (String pk, String m, String sig) -> bool
+  end
+end

data/sig/utils.rbs

@@ -0,0 +1,18 @@
+module SchnorrSig
+  class Error < RuntimeError
+  end
+  class SpecError < Error
+  end
+
+  KEY: 32
+  SIG: 64
+
+  module Utils
+    def check!: (untyped val, Class cls) -> untyped
+    def binary!: (String str, Integer length) -> String
+    def bin2big: (String str) -> Integer
+    def big2bin: (Integer bignum) -> String
+    def bin2hex: (String str) -> String
+    def hex2bin: (String hex) -> String
+  end
+end

data/test/fast.rb

@@ -0,0 +1,76 @@
+require 'schnorr_sig/fast'
+require 'minitest/autorun'
+
+include SchnorrSig
+
+describe Fast do
+  describe "keys" do
+    it "generates a Secp256k1::KeyPair" do
+      kp = Fast.keypair_obj
+      expect(kp).must_be_kind_of Secp256k1::KeyPair
+
+      kp = Fast.keypair_obj(Random.bytes(32))
+      expect(kp).must_be_kind_of Secp256k1::KeyPair
+    end
+
+    it "extracts 32 byte binary strings from KeyPair" do
+      keys = Fast.extract_keys(Fast.keypair_obj)
+      keys.each { |key|
+        expect(key).must_be_kind_of String
+        expect(key.length).must_equal 32
+        expect(key.encoding).must_equal Encoding::BINARY
+      }
+    end
+
+    it "generates a pubkey for any secret key" do
+      sk = Random.bytes(32)
+      pk = Fast.pubkey(sk)
+      expect(pk).must_be_kind_of String
+      expect(pk.length).must_equal 32
+      expect(pk.encoding).must_equal Encoding::BINARY
+    end
+
+    it "generates a keypair of 32 byte binary strings" do
+      keys = Fast.keypair
+      keys.each { |key|
+        expect(key).must_be_kind_of String
+        expect(key.length).must_equal 32
+        expect(key.encoding).must_equal Encoding::BINARY
+      }
+    end
+  end
+
+  describe "signatures" do
+    it "generates a Secp256k1::SchnorrSignature" do
+      sk = Random.bytes(32)
+      m = Fast.tagged_hash('test', 'hello world')
+      sig = Fast.sign(sk, m)
+      obj = Fast.signature(sig)
+      expect(obj).must_be_kind_of Secp256k1::SchnorrSignature
+    end
+
+    it "signs a message with a 64 byte binary signature" do
+      sk = Random.bytes(32)
+      m = Fast.tagged_hash('test', 'hello world')
+      sig = Fast.sign(sk, m)
+      expect(sig).must_be_kind_of String
+      expect(sig.length).must_equal 64
+      expect(sig.encoding).must_equal Encoding::BINARY
+    end
+
+    it "verifies signatures" do
+      sk, pk = Fast.keypair
+      m = Fast.tagged_hash('test', 'hello world')
+      sig = Fast.sign(sk, m)
+      expect(Fast.verify?(pk, m, sig)).must_equal true
+    end
+  end
+
+  it "implements tagged hashes" do
+    # SHA256.digest
+    h = Fast.tagged_hash('BIP0340/challenge', 'hello world')
+    expect(h).must_be_kind_of String
+    expect(h.length).must_equal 32
+    expect(h.encoding).must_equal Encoding::BINARY
+  end
+end

data/test/pure.rb

@@ -0,0 +1,111 @@
+require 'schnorr_sig/pure'
+require 'minitest/autorun'
+
+include SchnorrSig
+
+ENV['NO_SECURERANDOM'] = '1'
+
+describe Pure do
+  describe "Utils" do
+    it "converts any integer to a point on the curve" do
+      expect(Pure.point(99)).must_be_kind_of ECDSA::Point
+      expect(Pure.point(0).infinity?).must_equal true
+      p1 = Pure.point(1)
+      expect(p1.x).must_be :>, 999_999
+      expect(p1.y).must_be :>, 999_999
+    end
+
+    it "selects (x) or (N-x), if point.y is even or odd" do
+      even_y = Pure.point(99)
+      expect(even_y.y.even?).must_equal true
+
+      expect(Pure.select_even_y(even_y, 0)).must_equal 0
+      expect(Pure.select_even_y(even_y, 1)).must_equal 1
+
+      odd_y = Pure.point(10)
+      expect(odd_y.y.even?).must_equal false
+
+      expect(Pure.select_even_y(odd_y, 0)).wont_equal 0
+      expect(Pure.select_even_y(odd_y, 1)).wont_equal 1
+    end
+
+    it "converts up to 64 byte binary values to large integers" do
+      b32 = Random.bytes(32)
+      expect(b32).must_be_kind_of String
+      expect(b32.length).must_equal 32
+      b64 = Random.bytes(64)
+
+      i32 = Pure.int(b32)     # Pure.int() is an alias to bin2big()
+      i64 = Pure.bin2big(b64) # this comes from schnorr_sig/utils.rb
+
+      expect(i32).must_be_kind_of Integer
+      expect(i32.positive?).must_equal true
+
+      expect(i64).must_be :>, i32
+
+      expect(Pure.int("\x00")).must_equal 0
+      expect(Pure.int("\x00\xFF")).must_equal 255
+    end
+
+    it "converts an integer or point to a binary string" do
+      str = Pure.bytes(0)
+      expect(str).must_be_kind_of String
+      expect(str.length).must_equal 32
+      expect(str).must_equal ("\x00" * 32).b
+
+      p = Pure.point(1234)
+      expect(Pure.bytes(p)).must_equal Pure.big2bin(p.x)
+    end
+
+    it "implements lift_x()" do
+      expect(Pure.lift_x(1)).must_be_kind_of ECDSA::Point
+    end
+
+    it "implements tagged hashes" do
+      h = Pure.tagged_hash('BIP0340/challenge', 'hello world') # SHA256
+      expect(h).must_be_kind_of String
+      expect(h.length).must_equal 32
+      expect(h.encoding).must_equal Encoding::BINARY
+    end
+  end
+
+  describe "Keys" do
+    it "generates a pubkey for any secret key value" do
+      sk = Random.bytes(32)
+      pk = Pure.pubkey(sk)
+      expect(pk).must_be_kind_of String
+      expect(pk.length).must_equal 32
+      expect(pk.encoding).must_equal Encoding::BINARY
+    end
+
+    it "generates a keypair of 32 byte binary values" do
+      keys = Pure.keypair
+      keys.each { |key|
+        expect(key).must_be_kind_of String
+        expect(key.length).must_equal 32
+        expect(key.encoding).must_equal Encoding::BINARY
+      }
+    end
+  end
+
+  describe "Signatures" do
+    it "signs a message" do
+      sk = Random.bytes(32)
+      m = 'hello world'
+
+      # typically you want to just sign the hash of the message (SHA256)
+      # but sure, you can sign the message itself
+      sig = Pure.sign(sk, m)
+      expect(sig).must_be_kind_of String
+      expect(sig.length).must_equal 64
+      expect(sig.encoding).must_equal Encoding::BINARY
+    end
+
+    it "verifies signatures" do
+      sk, pk = Pure.keypair
+      m = 'hello world'
+      sig = Pure.sign(sk, m)
+      expect(Pure.verify?(pk, m, sig)).must_equal true
+    end
+  end
+end

data/test/utils.rb

@@ -0,0 +1,49 @@
+require 'schnorr_sig/utils'
+require 'minitest/autorun'
+
+include SchnorrSig
+
+Utils.extend(Utils)
+
+describe Utils do
+  describe "type enforcement" do
+    it "enforces the class of any object" do
+      expect(Utils.check!('123', String)).must_equal '123'
+      expect(Utils.check!(123, Integer)).must_equal 123
+      expect { Utils.check!([], String) }.must_raise SpecError
+    end
+
+    it "enforces binary strings: type, encoding, length" do
+      expect(Utils.binary!("\x00\x01".b, 2)).must_equal "\x00\x01".b
+      expect {
+        Utils.binary!("\x00\x01".b, 3)
+      }.must_raise SpecError
+      expect {
+        Utils.binary!("\x00\x01", 2)
+      }.must_raise SpecError
+    end
+  end
+
+  describe "conversion functions" do
+    it "converts binary strings (network order, big endian) to integers" do
+      expect(Utils.bin2big("\00")).must_equal 0
+      expect(Utils.bin2big("\xFF\xFF")).must_equal 65535
+    end
+
+    it "converts large integers to binary strings, null padded to 32 bytes" do
+      expect(Utils.big2bin(0)).must_equal ("\x00" * 32).b
+      expect(Utils.big2bin(1)).must_equal ("\x00" * 31 + "\x01").b
+    end
+
+    it "converts binary strings to lowercase hex strings" do
+      expect(Utils.bin2hex("\xDE\xAD\xBE\xEF")).must_equal "deadbeef"
+    end
+
+    it "converts hex strings to binary strings" do
+      expect(Utils.hex2bin("deadbeef")).must_equal "\xDE\xAD\xBE\xEF".b
+      expect(Utils.hex2bin("deadbeef")).must_equal "\xde\xad\xbe\xef".b
+      expect(Utils.hex2bin("DEADBEEF")).must_equal "\xDE\xAD\xBE\xEF".b
+      expect(Utils.hex2bin("DEADBEEF")).must_equal "\xde\xad\xbe\xef".b
+    end
+  end
+end

data/test/vectors.rb

@@ -1,11 +1,14 @@
 require 'schnorr_sig'
 require 'csv'
 
+ENV['NO_SECURERANDOM'] = '1'
+
 path = File.join(__dir__, 'vectors.csv')
 table = CSV.read(path, headers: true)
 
 success = []
 failure = []
+skip    = []
 
 table.each { |row|
   pk       = SchnorrSig.hex2bin row.fetch('public key')
@@ -14,18 +17,23 @@ table.each { |row|
   expected = row.fetch('verification result') == 'TRUE'
 
   result = begin
-             SchnorrSig.verify?(pk, m, sig)
-           rescue SchnorrSig::Error
-             false
+             SchnorrSig.soft_verify?(pk, m, sig)
+           rescue SchnorrSig::SpecError
+             skip << row
+             next
            end
-  (result == expected ? success : failure) << row
+
+  if result == expected
+    success << row
+  else
+    failure << row
+  end
   print '.'
 }
 puts
 
 puts "Success: #{success.count}"
 puts "Failure: #{failure.count}"
+puts "Skipped: #{skip.count}"
 
-puts failure unless failure.empty?
-
-# exit failure.count
+failure.each { |row| p row }

data/test/vectors_extra.rb

@@ -1,13 +1,14 @@
 require 'schnorr_sig'
 require 'csv'
 
+ENV['NO_SECURERANDOM'] = '1'
+
 path = File.join(__dir__, 'vectors.csv')
 table = CSV.read(path, headers: true)
 
 table.each { |row|
   sk       = SchnorrSig.hex2bin row.fetch('secret key')
   pk       = SchnorrSig.hex2bin row.fetch('public key')
-  #aux_rand = SchnorrSig.hex2bin row.fetch('aux_rand')
   m        = SchnorrSig.hex2bin row.fetch('message')
   sig      = SchnorrSig.hex2bin row.fetch('signature')
 
@@ -28,16 +29,24 @@ table.each { |row|
     pk_msg = (pubkey == pk) ? "pk match" : "pk mismatch"
 
     # calculate a signature
-    calc_sig = SchnorrSig.sign(sk, m)
-    sig_msg = (calc_sig == sig) ? "sig match" : "sig mismatch"
+    begin
+      calc_sig = SchnorrSig.sign(sk, m)
+      sig_msg = (calc_sig == sig) ? "sig match" : "sig mismatch"
+    rescue SchnorrSig::SpecError
+      sig_msg = "sig error"
+    end
   end
 
-  result = begin
-             SchnorrSig.verify?(pk, m, sig)
-           rescue SchnorrSig::Error
-             false
-           end
-  verify_msg = (result == expected) ? "verify match" : "verify mismatch"
+  if sig_msg != "sig error"
+    begin
+      result = SchnorrSig.soft_verify?(pk, m, sig)
+      verify_msg = (result == expected) ? "verify match" : "verify mismatch"
+    rescue SchnorrSig::SpecError
+      verify_msg = "verify error"
+    end
+  else
+    verify_msg = "sig error"
+  end
   puts [index, pk_msg, sig_msg, verify_msg, comment].join("\t")
 }
 puts

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schnorr_sig
 version: !ruby/object:Gem::Version
-  version: 0.2.1.1
+  version: 1.0.0.2
 platform: ruby
 authors:
 - Rick Hull
@@ -36,8 +36,14 @@ files:
 - lib/schnorr_sig.rb
 - lib/schnorr_sig/fast.rb
 - lib/schnorr_sig/pure.rb
-- lib/schnorr_sig/util.rb
+- lib/schnorr_sig/utils.rb
 - schnorr_sig.gemspec
+- sig/fast.rbs
+- sig/pure.rbs
+- sig/utils.rbs
+- test/fast.rb
+- test/pure.rb
+- test/utils.rb
 - test/vectors.rb
 - test/vectors_extra.rb
 homepage: https://github.com/rickhull/schnorr_sig
@@ -62,5 +68,5 @@ requirements: []
 rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
-summary: Schnorr signatures in Ruby, multiple implementations
+summary: Schnorr signatures in Ruby; multiple implementations
 test_files: []

data/lib/schnorr_sig/util.rb

@@ -1,44 +0,0 @@
-module SchnorrSig
-  class InputError < RuntimeError; end
-  class SizeError < InputError; end
-  class TypeError < InputError; end
-  class EncodingError < InputError; end
-
-  # true or raise
-  def self.integer!(i)
-    i.is_a?(Integer) or raise(TypeError, i.class)
-  end
-
-  # true or raise
-  def self.string!(str)
-    str.is_a?(String) or raise(TypeError, str.class)
-  end
-
-  # true or raise
-  def self.bytestring!(str, size)
-    string!(str)
-    raise(EncodingError, str.encoding) unless str.encoding == Encoding::BINARY
-    str.bytesize == size or raise(SizeError, str.bytesize)
-  end
-
-  # likely returns a Bignum, larger than a 64-bit hardware integer
-  def self.bin2big(str)
-    bin2hex(str).to_i(16)
-  end
-
-  # convert a giant integer to a binary string
-  def self.big2bin(bignum)
-    # much faster than ECDSA::Format -- thanks ParadoxV5
-    hex2bin(bignum.to_s(16).rjust(B * 2, '0'))
-  end
-
-  # convert a binary string to a lowercase hex string
-  def self.bin2hex(str)
-    str.unpack1('H*')
-  end
-
-  # convert a hex string to a binary string
-  def self.hex2bin(hex)
-    [hex].pack('H*')
-  end
-end