bls12-381 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2660bb6049da204d945d3d40a6bf06f26ed1c041794d959ea9b0662b725a1b8b
-  data.tar.gz: ad30c4cc593a729823bd51d05a1bdecc68566ed0e5b100cd31dc8130bf6e1353
+  metadata.gz: 24158dde28a5367b3fd19c5d77dfeb70ba7429c43f501f1e15345dc5792cfcd2
+  data.tar.gz: ee9dd866975f45538e1bd4cfa044fd88741cd0e01176fc6dea075111eab88cfe
 SHA512:
-  metadata.gz: eab97d8693ad91b412a1f7c8dd362b0b82c241e96c220ba686e79208c0828b3cd27303ecc8fa68ae51e18ca1f596d87bceff9b35ab009795e438784b8cab66a6
-  data.tar.gz: f1672d9beb73fa230f0d1bfe1b2ef56955599ed79d46ebd9a98cf344f593f705e6a63351dd87c7e65b8de25867705e915ae3f04d8e047ab9bd01741219dd5345
+  metadata.gz: 1751863707f75ea0d6bcc0fe8d4e1e1da82fb9657256f4a272efb129288dfec205be049dd6dde478f96488dcbf083d9131ba50779f3467f364a2b6c8659e1f4a
+  data.tar.gz: f523b7e1d92e900b44aa395359a9fa2a98e701a381e5b217d934cd50fa9f194908f5789ee197047007e3b80f41cf2a67fcbbb224779219292b4c8ab557b4bfd7

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-11-02
+
+### Fixed
+
+- `PointG2.from_hex` now rejects a coordinate at or above the field order. A coordinate written as `c + P` used to decode to the same point as `c`, giving one point several encodings.
+- `expand_message_xmd`, and so `hash_to_curve` with a custom `dst:`, handles a domain separation tag longer than 255 bytes by hashing it as RFC 9380 section 5.3.3 prescribes, instead of failing inside I2OSP.
+- Raising a field element to a negative power raises `ArgumentError`; `Fp2`, `Fp6` and `Fp12` used to answer with one.
+- `expand_message_xmd` computes exactly the blocks RFC 9380 asks for. It used to compute one more, which cost a SHA-256 per call and failed outright at the largest permitted length.
+- `==` on `Fp2`, `Fp6` and `Fp12` returns false for anything that is not the same kind of element instead of raising `NoMethodError`.
+- `==` on a point returns false for a point of the other group, nil or anything else that is not a point of the same group, instead of raising `BLS::PointError`.
+- `BLS.pairing` refuses a point outside the prime-order subgroup with `BLS::PointError`; it used to check only that the point was on the curve.
+
+### Changed
+
+- Scalar multiplication sizes its wNAF window table from the 255 bits of the group order rather than the base field, reduces the scalar modulo the order first, and skips zero windows instead of adding a throwaway point. `multiply` on G2 runs about three times faster and precompute tables shrink to a third.
+- Subgroup membership (`in_group?`, and so `from_hex`) uses the endomorphism tests of Scott's "A note on group membership tests for G1, G2 and GT on BLS pairing-friendly curves" in place of a multiplication by the group order.
+- `BLS::PointG1::MAX_BITS` and `BLS::PointG2::MAX_BITS` are gone; `BLS::ProjectivePoint::SCALAR_BITS` holds the width that matters.
+- `BLS.norm_p1` and `BLS.norm_p2`, which nothing used, are gone.
+- The `bigdecimal` dependency is gone.
+- Requires Ruby 3.3 or later, matching what is tested.
+- Depend on h2c 0.4.x, which no longer defines a top-level `BLS` module of its own.
+- `hash_to_curve` refuses an empty or non-string `dst:` with `BLS::Error` for both groups, as RFC 9380 section 3.1 requires, and anything the h2c gem raises for G1 arrives as `BLS::PointError` rather than `H2C::Error`.
+
+## [0.4.0] - 2026-08-10
+
+- Check that every parsed point lies in the prime-order subgroup.
+- Add the proof of possession scheme: `scheme:` on `sign`, `verify` and `verify_batch`, plus `pop_prove`, `pop_verify` and `fast_aggregate_verify`.
+- `verify_batch` handles repeated messages correctly and refuses them under `:basic`.
+- Verification returns false for the point at infinity instead of raising.
+- Validate G1 encodings as strictly as G2: infinity padding, flag and length consistency, reduced coordinates.
+- Validate hex input for points, messages and private keys instead of silently truncating or aliasing it.
+- `Field#invert` raises on zero instead of returning zero.
+- Fix `sgn0` to consult the second coordinate when the first is zero.
+- All exceptions descend from `BLS::Error`, with `BLS::PointError` and `BLS::PairingError` beneath it.
+- Add the bls12-381-tests and RFC 9380 test vectors. Document that nothing here is constant time.
+
+## [0.3.1] - 2026-04-24
+
+- Ruby 3.4 compatibility: depend on `bigdecimal` explicitly, follow the h2c gem's SSWU rename.
+
+## [0.3.0] - 2023-07-21
+
+- Support the compressed PointG2 format.
+- Fix the private key range check.
+
+## [0.2.2] - 2023-01-26
+
+- Add `BLS::Field#==` and `BLS::Field#to_s`.
+
+## [0.2.1] - 2023-01-16
+
+- Add argument validation and error message cleanup.
+
+## [0.2.0] - 2022-09-07
+
+- Add `BLS::PointG2.from_private_key`.
+
 ## [0.1.0] - 2021-03-29
 
 - Initial release

data/README.md

@@ -4,7 +4,7 @@ This library is a Ruby BLS12-381 implementation based on the JavaScript implemen
 In addition to that, it is possible to switch between public key and signature group (G1 and G2).
 
 Note: This library has passed the same tests as noble-bls12-381, but has not been audited to prove its safety.
-Please be careful when using this.
+Please be careful when using this, and read [Side channels](#side-channels) before signing with it.
 
 ## Installation
 
@@ -27,8 +27,8 @@ Or install it yourself as:
 ```ruby
 require 'bls'
 
-# Generate private key.
-private_key = SecureRandom.random_number(BLS::Curve::R - 1)
+# Generate private key: an integer in 1..(R - 1). Zero is not a key, so shift the range up.
+private_key = 1 + SecureRandom.random_number(BLS::Curve::R - 1)
 
 # Or you can use hex string.
 private_key = '67d53f170b908cabb9eb326c3c337762d59289a8fec79f7bc9254b584b73265c'
@@ -44,23 +44,17 @@ message = '64726e3da8'
 signature = BLS.sign(message, private_key)
 # signature is BLS::PointG2 object. You can get signature with hex format using #to_hex method.
 # If you want to use BLS::PointG1 signature, use BLS.sign(message, p, sig_type: :g1)
-signature.to_signature
+signature.to_hex(compressed: true)
 
 is_correct = BLS.verify(signature, message, public_key)
 => true
 
-# Sign 1 msg with 3 keys
 private_keys = [
   '18f020b98eb798752a50ed0563b079c125b0db5dd0b1060d1c1b47d4a193e1e4',
   'ed69a8c50cf8c9836be3b67c7eeff416612d45ba39a5c099d48fa668bf558c9c',
   '16ae669f3be7a2121e17d0c68c05a8f3d6bef21ec0f2315f1d7aec12484e4cf5'
 ]
 public_keys = private_keys.map { |p| BLS.get_public_key(p) }
-signatures2 = private_keys.map { |p| BLS.sign(message, p) }
-agg_public_keys2 = BLS.aggregate_public_keys(public_keys)
-agg_signatures2 = BLS.aggregate_signatures(signatures2)
-is_correct2 = BLS.verify(agg_signatures2, message, agg_public_keys2)
-=> true
 
 # Sign 3 msgs with 3 keys
 messages = %w[d2 0d98 05caf3]
@@ -68,12 +62,108 @@ signatures3 = private_keys.map.with_index { |p, i| BLS.sign(messages[i], p)}
 agg_signatures3 = BLS.aggregate_signatures(signatures3)
 is_correct3 = BLS.verify_batch(agg_signatures3, messages, public_keys)
 => true
+
+# Sign 1 msg with 3 keys.
+# This needs the proof of possession scheme: see the warning below.
+proofs = private_keys.map { |p| BLS.pop_prove(p) }
+public_keys.zip(proofs).each { |pubkey, proof| raise 'invalid key' unless BLS.pop_verify(pubkey, proof) }
+
+signatures2 = private_keys.map { |p| BLS.sign(message, p, scheme: :pop) }
+agg_signatures2 = BLS.aggregate_signatures(signatures2)
+is_correct2 = BLS.fast_aggregate_verify(agg_signatures2, message, public_keys)
+=> true
 ```
 
+## Signature schemes
+
+This library implements two of the schemes of
+[draft-irtf-cfrg-bls-signature](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-05),
+selected with the `scheme:` keyword of `BLS.sign` / `BLS.verify` / `BLS.verify_batch`.
+They use different domain separation tags, so a signature made under one never verifies
+under the other. The default is `:basic`, which is what earlier versions of this gem used.
+
+| scheme | aggregation |
+| --- | --- |
+| `:basic` (default) | `BLS.verify_batch`, **only when every message is distinct** |
+| `:pop` | the above with no such restriction, plus `BLS.fast_aggregate_verify` for many signatures over a single message |
+
+`BLS.verify_batch` returns `false` for a `:basic` aggregate that covers the same message
+twice, however well formed the signature is. Pass `scheme: :pop` to verify those.
+
+**Aggregating public keys is unsafe without proofs of possession.** Given a public key
+`pk_victim`, an attacker can register `pk_attacker = g * x - pk_victim` for an `x` they
+choose. The two keys aggregate to `g * x`, so the attacker alone can produce a signature
+that verifies against the aggregate, making it look like the victim signed. This is the
+rogue key attack, and it is why `:basic` supports no single-message aggregation at all.
+
+`BLS.pop_prove` closes the hole by signing a key with itself: producing a proof requires
+the private key, which the attacker does not have for `pk_attacker`. Call `BLS.pop_verify`
+on every public key **before** passing it to `BLS.aggregate_public_keys` or
+`BLS.fast_aggregate_verify` — neither of them can do it for you, since they never see the
+proofs.
+
+## Errors
+
+Everything this library raises about the data it was handed descends from `BLS::Error`, so
+one rescue covers a key that will not parse, a point outside the subgroup, a private key that
+is not hex, and a pairing that is not defined:
+
+```ruby
+begin
+  public_key = BLS::PointG1.from_hex(untrusted)
+rescue BLS::Error => e   # BLS::PointError here, and BLS::PairingError elsewhere
+  ...
+end
+```
+
+Passing the wrong type or the wrong number of coefficients is a mistake in the calling code
+rather than a fact about a key, and raises `ArgumentError` as it would anywhere else in Ruby.
+
+Verification does not raise over the keys and signatures it is given. `BLS.verify`,
+`BLS.verify_batch`, `BLS.fast_aggregate_verify` and `BLS.pop_verify` return `false` for any
+point they will not accept, including the point at infinity and an empty set of signers, so an
+untrusted key or signature cannot turn into an exception. Deserializing it with `from_hex`
+beforehand still raises, which is where a malformed encoding is caught. The message is
+different: it is the hex of a hash the caller computed, and one that is not hex, or has an odd
+number of digits, raises `BLS::PointError` from signing and verifying alike.
+
+## Threads
+
+Signing and verifying from several threads gives the right answers, but two caches are
+written without a lock and neither is worth sharing a point over.
+
+`calc_multiply_precomputes` builds its table over long enough that MRI switches threads part
+way through, so callers racing on one point all pass the "already has precomputes" check and
+each build their own. They build the same table, so the result stays correct; what you lose is
+the time and the memory of doing it several times over, and a guard that reads as protection
+while providing none. Build the table once, before the point goes anywhere else.
+
+`BLS.verify` memoises pairing coefficients onto the G2 point it is given, and onto
+`BLS::PointG2::BASE` when the public key is a G2 point. Racing callers recompute rather than
+corrupt, for the same reason: what is assigned is always a finished array.
+
+## Side channels
+
+**Nothing here is constant time, and signing is not safe against an attacker who can
+measure it.** `BLS.sign` and `BLS.get_public_key` multiply a curve point by the private
+key, and that multiplication leaks:
+
+* the scalar picks which precomputed point each window adds, so it decides which memory
+  gets touched, which is visible through the cache;
+* point addition returns early when an operand is the identity or the two are equal;
+* underneath it all, Ruby's bignum arithmetic and the `%` in `BLS::Fp` take time that
+  depends on their operands.
+
+A pure Ruby implementation cannot fix this: it has no control over how the interpreter
+lays out or times its integers. Treat this gem as suitable where the private key operation
+cannot be observed — verification of untrusted input is fine, since it touches no secret —
+and use a binding to a constant time library such as [blst](https://github.com/supranational/blst)
+where an attacker can watch the signer.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the BlS12-381 project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/bls12-381/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the BLS12-381 project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/azuchi/bls12-381/blob/main/CODE_OF_CONDUCT.md).

data/bls12-381.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'BLS12-381 implementation for Ruby.'
   spec.homepage      = 'https://github.com/azuchi/bls12-381'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.4.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.3.0')
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
@@ -27,8 +27,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   # Uncomment to register a new dependency of your gem
-  spec.add_dependency "h2c", ">= 0.2.1", "< 0.3"
-  spec.add_dependency "bigdecimal"
+  spec.add_dependency "h2c", "~> 0.4.0"
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake', '>= 12.3.3'

data/lib/bls/error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module BLS
+
+  # Base class for everything this library raises about the data it was given, so that
+  # `rescue BLS::Error` catches all of it.
+  #
+  # A wrong type or arity is a mistake in the calling code rather than a fact about a key or a
+  # point, and still raises ArgumentError, as it would anywhere else in Ruby.
+  class Error < StandardError; end
+
+  # A point that could not be parsed, is not on the curve, or is not in the prime-order
+  # subgroup.
+  class PointError < Error; end
+
+  # A pairing that was asked for where it is not defined.
+  class PairingError < Error; end
+end

data/lib/bls/field.rb

@@ -13,7 +13,15 @@ module BLS
       self.class.new(-value)
     end
 
+    # Multiplicative inverse.
+    # Zero has none, and the extended Euclid below returns 0 for it rather than failing, which
+    # is a wrong answer that propagates: ProjectivePoint#to_affine inverts z, so the point at
+    # infinity would come back as the affine coordinates (0, 0) instead of being refused.
+    # @return [BLS::Field] the inverse.
+    # @raise [BLS::Error] Occur when this element is zero.
     def invert
+      raise BLS::Error, 'Zero has no multiplicative inverse.' if zero?
+
       x0 = 1
       x1 = 0
       y0 = 0
@@ -37,7 +45,10 @@ module BLS
       self.class.new(value**2)
     end
 
+    # @raise [ArgumentError] Occur when +n+ is negative. Divide by the positive power instead.
     def pow(n)
+      raise ArgumentError, 'Exponent must not be negative.' if n.negative?
+
       v = value.pow(n, self.class.const_get(:ORDER))
       self.class.new(v)
     end
@@ -122,6 +133,8 @@ module BLS
   module FQP
 
     def ==(other)
+      return false unless other.is_a?(self.class)
+
       coeffs == other.coeffs
     end
 
@@ -149,7 +162,11 @@ module BLS
       self.class.new(coeffs.map(&:negate))
     end
 
+    # @raise [ArgumentError] Occur when +n+ is negative, which the loop below would otherwise
+    # answer with ONE as though it had been zero.
     def pow(n)
+      raise ArgumentError, 'Exponent must not be negative.' if n.negative?
+
       one = self.class.const_get(:ONE)
       return one if n.zero?
       return self if n == 1
@@ -248,7 +265,15 @@ module BLS
       Fp2.new([a * b, c * c1])
     end
 
+    # Square root, or nil when this element is not a square.
+    # Zero is answered up front. It is a square, its root being itself, and the division below
+    # would otherwise be asked for the inverse of zero. That used to yield zero and land here
+    # as a nil, which reads as "not a square" and is wrong for the one element that has
+    # exactly one root.
+    # @return [BLS::Fp2, nil]
     def sqrt
+      return self if zero?
+
       candidate = pow((Fp2::ORDER + 8) / 16)
       check = candidate.square / self
       r = ROOTS_OF_UNITY
@@ -700,12 +725,17 @@ module BLS
 
   
 
+  # sgn0 for GF(p^2), from RFC 9380 section 4.1.
+  # Combined with | and & rather than || and &&: sign_0 is 0 or 1, and 0 is truthy in Ruby,
+  # so a disjunction would always short circuit on it and x_1 would never be reached.
+  # @param [BLS::Fp2] x
+  # @return [Integer] 0 or 1.
   def sgn0(x)
     x0, x1 = x.values
     sign_0 = x0 % 2
-    zero_0 = x0 === 0
+    zero_0 = x0.zero? ? 1 : 0
     sign_1 = x1 % 2
-    sign_0 || (zero_0 && sign_1)
+    sign_0 | (zero_0 & sign_1)
   end
 
   def sqrt_div_fp2(u, v)

data/lib/bls/h2c.rb

@@ -3,26 +3,41 @@ module BLS
 
     LENGTH = 64
 
+    # Longest tag expand_message_xmd can carry as is; its length has to fit in one byte.
+    MAX_DST_LENGTH = 255
+    # Prefix under which a longer tag is hashed down to size, from RFC 9380 section 5.3.3.
+    OVERSIZE_DST_PREFIX = 'H2C-OVERSIZE-DST-'
+
     module_function
 
     # @param [String] message hash value with hex format.
     # @param [Integer] len_in_bytes length
+    # @param [String] dst Domain separation tag. Mixing tags across schemes breaks the
+    # domain separation the ciphersuites rely on, so it must always be passed explicitly.
+    # A tag longer than {MAX_DST_LENGTH} bytes is replaced by its hash, as RFC 9380 section
+    # 5.3.3 prescribes, so any length works and the result matches other implementations.
     # @return [Array[Integer]] byte array.
     # @raise BLS::Error
-    def expand_message_xmd(message, len_in_bytes)
-      b_in_bytes = BigDecimal(SHA256_DIGEST_SIZE)
+    def expand_message_xmd(message, len_in_bytes, dst)
+      raise BLS::Error, 'Domain separation tag must not be empty.' if dst.empty? # RFC 9380 section 3.1
+
+      dst = Digest::SHA256.digest(OVERSIZE_DST_PREFIX + dst) if dst.bytesize > MAX_DST_LENGTH
+      b_in_bytes = SHA256_DIGEST_SIZE
       r_in_bytes = b_in_bytes * 2
-      ell = (BigDecimal(len_in_bytes) / b_in_bytes).ceil
+      ell = (len_in_bytes + b_in_bytes - 1) / b_in_bytes
       raise BLS::Error, 'Invalid xmd length' if ell > 255
 
-      dst_prime = PointG2::DST_BASIC.bytes + BLS.i2osp(PointG2::DST_BASIC.bytesize, 1)
+      dst_prime = dst.bytes + BLS.i2osp(dst.bytesize, 1)
       z_pad = BLS.i2osp(0, r_in_bytes)
       l_i_b_str = BLS.i2osp(len_in_bytes, 2)
       b = Array.new(ell)
       payload = z_pad + [message].pack('H*').bytes + l_i_b_str + BLS.i2osp(0, 1) + dst_prime
       b_0 = Digest::SHA256.digest(payload.pack('C*'))
       b[0] = Digest::SHA256.digest((b_0.bytes + BLS.i2osp(1, 1) + dst_prime).pack('C*'))
-      (1..ell).each do |i|
+      # b[i] holds the RFC's b_(i + 1), so b_2 .. b_ell is ell - 1 more blocks. Running the
+      # loop to ell made one block too many: harmless after the truncation below, except that
+      # at ell == 255 its counter byte overflowed and the call failed at the RFC's own limit.
+      (1...ell).each do |i|
         args = BLS.bin_xor(b_0, b[i - 1]).bytes + BLS.i2osp(i + 1, 1) + dst_prime
         b[i] = Digest::SHA256.digest(args.pack('C*'))
       end
@@ -34,12 +49,13 @@ module BLS
 
       # Convert hash to Field.
       # @param [String] message hash value with hex format.
+      # @param [String] dst Domain separation tag of the ciphersuite in use.
       # @return [Array[Integer]] byte array.
-      def hash_to_field(message, random_oracle: true)
+      def hash_to_field(message, dst = PointG2::DST_BASIC, random_oracle: true)
         degree = 2
         count = random_oracle ? 2 : 1
         len_in_bytes = count * degree * LENGTH
-        pseudo_random_bytes = BLS::H2C.expand_message_xmd(message, len_in_bytes)
+        pseudo_random_bytes = BLS::H2C.expand_message_xmd(message, len_in_bytes, dst)
         u = Array.new(count)
         count.times do |i|
           e = Array.new(degree)
@@ -89,7 +105,7 @@ module BLS
       end
 
       # 3-isogeny map from E' to E
-      # Converts from Jacobi (xyz) to Projective (xyz) coordinates.
+      # Takes and returns projective (x, y, z) coordinates.
       def isogeny_map(x, y, z)
         mapped = Array.new(4, Fp2::ZERO)
         z_powers = [z, z**2, z**3]

data/lib/bls/math.rb

@@ -66,13 +66,33 @@ module BLS
   end
 
   # Normalize private key.
+  # A key at or above the group order is reduced rather than rejected, matching the reference
+  # implementation and the test vectors. Reducing raw entropy that way is slightly biased, so
+  # prefer drawing the key from 0 < k < Fr::ORDER to begin with.
   # @param [String|Integer] private_key a private key with hex or number.
   # @return [BLS::Fr] Normalized private key.
-  # @raise [BLS::Error] Occur when the private key is zero.
+  # @raise [BLS::Error] Occur when the private key is not a positive hex string or integer,
+  # or when it reduces to zero.
   def normalize_priv_key(private_key)
-    k = private_key.is_a?(String) ? private_key.to_i(16) : private_key
-    raise BLS::Error, "Private key must be 0 < private_key < #{Fr::ORDER}" if k <= 0
-    Fr.new(k)
+    k = case private_key
+        when String
+          # String#to_i stops at the first character it cannot read and returns what it has,
+          # so a mistyped or truncated key would otherwise turn into a different, much
+          # smaller one without any sign that it happened.
+          raise BLS::Error, 'Private key must be a hex string.' unless private_key.match?(/\A[0-9a-fA-F]+\z/)
+
+          private_key.to_i(16)
+        when Integer
+          private_key
+        else
+          raise BLS::Error, 'Private key must be Integer or String.'
+        end
+    raise BLS::Error, 'Private key must be positive.' unless k.positive?
+
+    key = Fr.new(k)
+    raise BLS::Error, "Private key must not be a multiple of #{Fr::ORDER}." if key.zero?
+
+    key
   end
 
   # Convert number to +byte_length+ bytes hex string.

data/lib/bls/pairing.rb

@@ -1,13 +1,14 @@
 module BLS
   module_function
 
-  class PairingError < StandardError; end
-
   # @param [BLS::PointG1] p
   # @param [BLS::PointG2] q
   # @param [Boolean] with_final_exp
   # @return [BLS::Fp12]
   # @raise [BLS::PairingError] Occur when p.zero? or q.zero?
+  # @raise [BLS::PointError] Occur when either point is off its curve or outside its
+  # prime-order subgroup. from_hex has already checked what it returns; this is for points
+  # built by hand, for which the pairing would otherwise be computed without complaint.
   # @raise [ArgumentError]
   def pairing(p, q, with_final_exp: true)
     raise ArgumentError, 'p should be BLS::PointG1 object' unless p.is_a?(BLS::PointG1)
@@ -16,8 +17,25 @@ module BLS
 
     p.validate!
     q.validate!
+    p.validate_group!
+    q.validate_group!
     looped = p.miller_loop(q)
     with_final_exp ? looped.final_exponentiate : looped
   end
 
+  # Pairing without the final exponentiation, using e(O, Q) = e(P, O) = 1 where {pairing}
+  # raises instead. Verification multiplies several of these together, so a degenerate key
+  # or signature has to fall out as a failed check rather than as an exception.
+  # @param [BLS::PointG1] p
+  # @param [BLS::PointG2] q
+  # @return [BLS::Fp12]
+  # @raise [ArgumentError]
+  def partial_pairing(p, q)
+    raise ArgumentError, 'p should be BLS::PointG1 object' unless p.is_a?(BLS::PointG1)
+    raise ArgumentError, 'q should be BLS::PointG2 object' unless q.is_a?(BLS::PointG2)
+    return Fp12::ONE if p.zero? || q.zero?
+
+    pairing(p, q, with_final_exp: false)
+  end
+
 end

data/lib/bls/point/g1.rb

@@ -1,45 +1,69 @@
 module BLS
   class PointG1 < BLS::ProjectivePoint
 
+    # Ciphersuite IDs of draft-irtf-cfrg-bls-signature section 4.3.
     DST_BASIC = 'BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_'
+    DST_POP = 'BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_POP_'
+    DST_POP_PROOF = 'BLS_POP_BLS12381G1_XMD:SHA-256_SSWU_RO_POP_'
 
     KEY_SIZE_COMPRESSED = 48
     KEY_SIZE_UNCOMPRESSED = 96
 
     BASE = PointG1.new(Fp.new(Curve::G_X), Fp.new(Curve::G_Y), Fp::ONE)
     ZERO = PointG1.new(Fp::ONE, Fp::ONE, Fp::ZERO)
-    MAX_BITS = Fp::MAX_BITS
 
     # Parse PointG1 from form hex.
     # @param [String] hex hex value of PointG1.
     # @return [PointG1]
-    # @raise [BLS::PointError] Occurs when hex length does not match, or point does not on G1.
+    # @raise [BLS::PointError] Occurs when hex length does not match, or point is not on G1.
     def self.from_hex(hex)
+      validate_hex!(hex)
       bytes = [hex].pack('H*')
-      point = case bytes.bytesize
-              when KEY_SIZE_COMPRESSED
-                compressed_value = hex.to_i(16)
-                b_flag = BLS.mod(compressed_value, POW_2_383) / POW_2_382
-                return ZERO if b_flag == 1
-
-                x = BLS.mod(compressed_value, POW_2_381)
-                full_y = BLS.mod(x**3 + Fp.new(Curve::B).value, Curve::P)
+      unless [KEY_SIZE_COMPRESSED, KEY_SIZE_UNCOMPRESSED].include?(bytes.bytesize)
+        raise PointError, 'Invalid point G1, expected 48 or 96 bytes.'
+      end
+
+      m_byte = bytes[0].unpack1('C') & 0xe0
+      if [0x20, 0x60, 0xe0].include?(m_byte)
+        raise PointError, "Invalid encoding flag: #{m_byte.to_s(16)}"
+      end
+
+      c_bit = m_byte & POINT_COMPRESSION_FLAG # compression flag
+      i_bit = m_byte & POINT_INFINITY_FLAG # infinity flag
+      s_bit = m_byte & POINT_Y_FLAG # y coordinate sign flag
+      bytes[0] = [bytes[0].unpack1('C') & 0x1f].pack('C') # set flag to 0
+
+      if i_bit == POINT_INFINITY_FLAG && bytes.unpack1('H*').to_i(16) > 0
+        raise PointError, 'Invalid point, infinity point should be all 0.'
+      end
+
+      point = if bytes.bytesize == KEY_SIZE_COMPRESSED && c_bit == POINT_COMPRESSION_FLAG # compressed format
+                return ZERO if i_bit == POINT_INFINITY_FLAG
+
+                x = bytes.unpack1('H*').to_i(16)
+                raise PointError, 'Invalid point G1, x must be less than the field order.' unless x < Curve::P
+
+                full_y = BLS.mod(x**3 + Curve::B, Curve::P)
                 y = BLS.pow_mod(full_y, (Curve::P + 1) / 4, Curve::P)
-                raise PointError, 'The given point is not on G1: y**2 = x**3 + b.' unless (BLS.pow_mod(y, 2, Curve::P) - full_y).zero?
+                raise PointError, 'The given point is not on G1: y**2 = x**3 + b.' unless BLS.pow_mod(y, 2, Curve::P) == full_y
 
-                a_flag = BLS.mod(compressed_value, POW_2_382) / POW_2_381
-                y = Curve::P - y unless ((y * 2) / Curve::P) == a_flag
+                y = Curve::P - y unless ((y * 2) / Curve::P) == (s_bit.zero? ? 0 : 1)
                 PointG1.new(Fp.new(x), Fp.new(y), Fp::ONE)
-              when KEY_SIZE_UNCOMPRESSED
-                return ZERO unless (bytes[0].unpack1('H*').to_i(16) & (1 << 6)).zero?
+              elsif bytes.bytesize == KEY_SIZE_UNCOMPRESSED && c_bit != POINT_COMPRESSION_FLAG # uncompressed format
+                return ZERO if i_bit == POINT_INFINITY_FLAG
 
                 x = bytes[0...PUBLIC_KEY_LENGTH].unpack1('H*').to_i(16)
                 y = bytes[PUBLIC_KEY_LENGTH..-1].unpack1('H*').to_i(16)
+                unless x < Curve::P && y < Curve::P
+                  raise PointError, 'Invalid point G1, coordinates must be less than the field order.'
+                end
+
                 PointG1.new(Fp.new(x), Fp.new(y), Fp::ONE)
               else
-                raise PointError, 'Invalid point G1, expected 48 or 96 bytes.'
+                raise PointError, 'Invalid point G1, compression flag does not match the encoded length.'
               end
       point.validate!
+      point.validate_group!
       point
     end
 
@@ -73,15 +97,38 @@ module BLS
 
     # Convert hash to PointG1
     # @param [String] message a hash with hex format.
+    # @param [Symbol] scheme signature scheme whose domain separation tag is used, :basic or :pop.
+    # @param [String] dst a domain separation tag to use instead of the scheme's, for a
+    # ciphersuite this library does not name, such as the ones the RFC 9380 vectors use.
     # @return [BLS::PointG1] point.
     # @raise [BLS::PointError]
-    def self.hash_to_curve(message)
-      raise PointError, 'expected hex string' unless message[/^[a-fA-F0-9]*$/]
+    def self.hash_to_curve(message, scheme: :basic, dst: nil)
+      validate_hex!(message)
 
-      h2c = ::H2C.get(::H2C::Suite::BLS12381G1_XMDSHA256_SSWU_RO_, PointG1::DST_BASIC)
+      h2c = ::H2C.get(::H2C::Suite::BLS12381G1_XMDSHA256_SSWU_RO_, resolve_dst(dst, scheme))
       p = h2c.digest([message].pack('H*'))
 
       PointG1.new(Fp.new(p.x), Fp.new(p.y), Fp::ONE)
+    rescue ::H2C::Error => e
+      # Whatever the h2c gem objects to, callers rescue it the way they rescue the rest.
+      raise PointError, e.message
+    end
+
+    # A primitive cube root of unity in Fp. (x, y) -> (BETA * x, y) is an endomorphism of E(Fp)
+    # that acts on G1 as multiplication by -z**2, z being the curve parameter. Of the two
+    # primitive roots, this is the one for which that holds; the other gives the inverse map.
+    ENDO_BETA = Fp.new(PSI2_C1).square
+
+    # Check whether this point belongs to G1, by the test of section 4 of
+    # https://eprint.iacr.org/2021/1130: a point of E(Fp) satisfies phi(P) == [-z**2]P exactly
+    # when it lies in G1. Two multiplications by the 64-bit z, with its six set bits, instead
+    # of one by the 255-bit r.
+    # @return [Boolean] true if this point is in G1.
+    def in_group?
+      return true if zero?
+
+      endo = PointG1.new(x * ENDO_BETA, y, z)
+      endo == multiply_unsafe(Curve::X).multiply_unsafe(Curve::X).negate
     end
 
     # Validate this point whether on curve over Fp.

data/lib/bls/point/g2.rb

@@ -3,12 +3,14 @@ module BLS
 
     attr_accessor :precomputes
 
+    # Ciphersuite IDs of draft-irtf-cfrg-bls-signature section 4.2.
     DST_BASIC = 'BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_'
+    DST_POP = 'BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_'
+    DST_POP_PROOF = 'BLS_POP_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_'
 
     KEY_SIZE_COMPRESSED = 96
     KEY_SIZE_UNCOMPRESSED = 192
 
-    MAX_BITS = Fp2::MAX_BITS
     BASE = PointG2.new(Fp2.new(Curve::G2_X), Fp2.new(Curve::G2_Y), Fp2::ONE)
     ZERO = PointG2.new(Fp2::ONE, Fp2::ONE, Fp2::ZERO)
 
@@ -18,7 +20,12 @@ module BLS
     # @return [BLS::PointG2] PointG2.
     # @raise [BLS::PointError]
     def self.from_hex(hex)
+      validate_hex!(hex)
       bytes = [hex].pack('H*')
+      unless [KEY_SIZE_COMPRESSED, KEY_SIZE_UNCOMPRESSED].include?(bytes.bytesize)
+        raise PointError, 'Invalid point G2, expected 96/192 bytes.'
+      end
+
       m_byte = bytes[0].unpack1('C')& 0xe0
       if [0x20, 0x60, 0xe0].include?(m_byte)
         raise PointError, "Invalid encoding flag: #{m_byte.to_s(16)}"
@@ -37,6 +44,11 @@ module BLS
                 return ZERO if i_bit == POINT_INFINITY_FLAG
                 x1 = bytes[0...PUBLIC_KEY_LENGTH].unpack1('H*').to_i(16)
                 x0 = bytes[PUBLIC_KEY_LENGTH...(2 * PUBLIC_KEY_LENGTH)].unpack1('H*').to_i(16)
+                # Fp.new reduces modulo P, so without this check x + P would decode as the same
+                # point under a second encoding. G1 refuses these too.
+                unless x0 < Curve::P && x1 < Curve::P
+                  raise PointError, 'Invalid point G2, coordinates must be less than the field order.'
+                end
                 x = Fp2.new([x0, x1])
                 right = x ** 3 + Fp2.new(Curve::B2)
                 y = right.sqrt
@@ -46,7 +58,11 @@ module BLS
                         else
                           (y.coeffs[1].value * 2) / Curve::P == 1 ? 1 : 0
                         end
-                y = s_bit > 0 && bit_y > 0 ? y : y.negate
+                # Flip to whichever root the encoding asked for. Written as a comparison, the
+                # way G1 does it, rather than as `s_bit > 0 && bit_y > 0 ? y : y.negate`:
+                # that form is only right because sqrt returns the root of sign 1, which it
+                # does not promise, and it would negate a root of sign 0 that wanted sign 0.
+                y = y.negate unless bit_y == (s_bit.zero? ? 0 : 1)
                 PointG2.new(x, y, Fp2::ONE)
               elsif bytes.bytesize == KEY_SIZE_UNCOMPRESSED && c_bit != POINT_COMPRESSION_FLAG # uncompressed format
                 return ZERO if i_bit == POINT_INFINITY_FLAG
@@ -54,11 +70,15 @@ module BLS
                 x0 = bytes[PUBLIC_KEY_LENGTH...(2 * PUBLIC_KEY_LENGTH)].unpack1('H*').to_i(16)
                 y1 = bytes[(2 * PUBLIC_KEY_LENGTH)...(3 * PUBLIC_KEY_LENGTH)].unpack1('H*').to_i(16)
                 y0 = bytes[(3 * PUBLIC_KEY_LENGTH)..-1].unpack1('H*').to_i(16)
+                unless [x0, x1, y0, y1].all? { |c| c < Curve::P }
+                  raise PointError, 'Invalid point G2, coordinates must be less than the field order.'
+                end
                 PointG2.new(Fp2.new([x0, x1]), Fp2.new([y0, y1]), Fp2::ONE)
               else
-                raise PointError, 'Invalid point G2, expected 96/192 bytes.'
+                raise PointError, 'Invalid point G2, compression flag does not match the encoded length.'
               end
       point.validate!
+      point.validate_group!
       point
     end
 
@@ -72,12 +92,15 @@ module BLS
 
     # Convert hash to PointG2
     # @param [String] message a hash with hex format.
+    # @param [Symbol] scheme signature scheme whose domain separation tag is used, :basic or :pop.
+    # @param [String] dst a domain separation tag to use instead of the scheme's, for a
+    # ciphersuite this library does not name, such as the ones the RFC 9380 vectors use.
     # @return [BLS::PointG2] point.
     # @raise [BLS::PointError]
-    def self.hash_to_curve(message)
-      raise PointError, 'expected hex string' unless message[/^[a-fA-F0-9]*$/]
+    def self.hash_to_curve(message, scheme: :basic, dst: nil)
+      validate_hex!(message)
 
-      u = BLS::H2C::G2.hash_to_field(message)
+      u = BLS::H2C::G2.hash_to_field(message, resolve_dst(dst, scheme))
       q0 = PointG2.new(*BLS::H2C::G2.isogeny_map(*BLS::H2C::G2.map_to_curve_sswu(u[0])))
       q1 = PointG2.new(*BLS::H2C::G2.isogeny_map(*BLS::H2C::G2.map_to_curve_sswu(u[1])))
       r = q0 + q1
@@ -124,6 +147,20 @@ module BLS
       to_hex(compressed: true)
     end
 
+    # Check whether this point belongs to G2, by the test of section 4 of
+    # https://eprint.iacr.org/2021/1130: psi, the untwist-Frobenius-twist endomorphism that
+    # {clear_cofactor} also uses, acts on G2 as multiplication by the curve parameter z, and a
+    # point of E'(Fp2) satisfies psi(P) == [z]P exactly when it lies in G2. z is negative for
+    # BLS12-381 and Curve::X holds its magnitude, hence the negate. One multiplication by a
+    # 64-bit scalar with six set bits instead of one by the 255-bit r.
+    # @return [Boolean] true if this point is in G2.
+    def in_group?
+      return true if zero?
+
+      psi = from_affine_tuple(BLS.psi(*to_affine))
+      psi == multiply_unsafe(Curve::X).negate
+    end
+
     def validate!
       b = Fp2.new(Curve::B2)
       return if zero?
@@ -137,6 +174,13 @@ module BLS
       self.precomputes = nil
     end
 
+    # The line coefficients {BLS.miller_loop} needs, worked out once and kept on the point.
+    #
+    # This memoises without a lock, so concurrent callers can each compute it. They compute
+    # the same coefficients and assign a finished array, so a reader sees one or the other and
+    # never a partial one; the cost is the repeated work. BLS.verify reaches this on
+    # PointG2::BASE, which is shared, whenever the public key is a G2 point.
+    # @return [Array]
     def pairing_precomputes
       return precomputes if precomputes
 

data/lib/bls/point.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'bigdecimal'
 require 'h2c'
 
 module BLS
@@ -13,11 +12,14 @@ module BLS
   autoload :PointG1, "bls/point/g1"
   autoload :PointG2, "bls/point/g2"
 
-  class PointError < StandardError; end
-
   # Abstract Point class that consist of projective coordinates.
   class ProjectivePoint
 
+    # Bits in the group order r. Every point this library hands out lies in the subgroup of
+    # that order, where [n]P == [n mod r]P, so this, not the size of the base field, is what
+    # a scalar multiplication has to cover.
+    SCALAR_BITS = Curve::R.bit_length
+
     attr_reader :x, :y, :z
     attr_accessor :m_precomputes
 
@@ -28,6 +30,56 @@ module BLS
       @m_precomputes = nil
     end
 
+    # Domain separation tag this point class uses for +scheme+.
+    # @param [Symbol] scheme :basic, :pop, or :pop_proof(the tag proofs of possession
+    # are signed under, kept separate from :pop so a proof cannot pass as a signature).
+    # @return [String] domain separation tag.
+    # @raise [BLS::Error] Occur when the scheme is unknown.
+    def self.dst(scheme)
+      case scheme
+      when :basic then const_get(:DST_BASIC)
+      when :pop then const_get(:DST_POP)
+      when :pop_proof then const_get(:DST_POP_PROOF)
+      else raise BLS::Error, "Unknown scheme: #{scheme.inspect}. Must be :basic or :pop."
+      end
+    end
+
+    # The tag {hash_to_curve} will use: the +dst+ given, or the one +scheme+ names.
+    # An empty tag is refused here, under BLS::Error, for both groups alike. RFC 9380 section
+    # 3.1 forbids it, and left to the layers below it would either go through unnoticed (G2)
+    # or surface as the h2c gem's own exception (G1), outside this library's hierarchy.
+    # @param [String, nil] dst explicit domain separation tag, if any.
+    # @param [Symbol] scheme signature scheme to take the tag from otherwise.
+    # @return [String] domain separation tag.
+    # @raise [BLS::Error] Occur when the tag is empty or not a string, or the scheme unknown.
+    def self.resolve_dst(dst, scheme)
+      return self.dst(scheme) if dst.nil?
+      raise BLS::Error, 'Domain separation tag must be a string.' unless dst.is_a?(String)
+      raise BLS::Error, 'Domain separation tag must not be empty.' if dst.empty?
+
+      dst
+    end
+
+    # Check that +hex+ is a whole number of bytes written in hex, for {from_hex} and
+    # {hash_to_curve}, which both unpack their argument with pack('H*').
+    #
+    # pack maps a character to a nibble by its low bits, so it reads '3', '#', 'J', 'Z', 'j'
+    # and 'z' all as 3 and never complains, and it pads an odd number of digits out to a whole
+    # byte. Left alone, that gives every point and every message a large family of spellings
+    # that all arrive at the same bytes. Applications tend to carry keys around as hex and
+    # compare, deduplicate and index them that way, so the aliases matter as much here as the
+    # non-canonical encodings do a layer down.
+    #
+    # \A..\z rather than ^..$ because those match at line boundaries in Ruby, which would let
+    # a newline carry a non-hex tail past the check.
+    # @param [String] hex a byte string in hex format.
+    # @raise [PointError] Occur when it is not an even length string of hex digits.
+    def self.validate_hex!(hex)
+      return if hex.is_a?(String) && hex.match?(/\A(?:[0-9a-fA-F]{2})*\z/)
+
+      raise PointError, 'expected hex string'
+    end
+
     def zero?
       z.zero?
     end
@@ -41,11 +93,13 @@ module BLS
       self.class.new(x, y, z)
     end
 
-    # Compare one point to another.
+    # Compare one point to another. A G1 point never equals a G2 point, nil, or anything
+    # else that is not a point of the same group, and says so with false rather than an
+    # exception, since Array#include?, uniq and the like call this on whatever they hold.
     # @param [ProjectivePoint] other another point.
     # @return [Boolean] whether same point or not.
     def ==(other)
-      raise PointError, "ProjectivePoint#==: this is #{self.class}, but other is #{other.class}" unless self.class == other.class
+      return false unless other.is_a?(self.class)
 
       (x * other.z) == (other.x * z) && (y * other.z) == (other.y * z)
     end
@@ -109,6 +163,10 @@ module BLS
     end
     alias - subtract
 
+    # Scalar multiplication by plain double-and-add, which skips the addition entirely on a
+    # zero bit and so takes a number of operations that tracks the scalar's Hamming weight.
+    # Only for scalars an observer already knows, such as the curve parameters. {multiply}
+    # hides that particular pattern, but is not constant time either.
     def multiply_unsafe(scalar)
       n = scalar.is_a?(Field) ? scalar.value : scalar
       raise PointError, 'Point#multiply: invalid scalar, expected positive integer' if n <= 0
@@ -123,11 +181,33 @@ module BLS
       p
     end
 
+    # Check whether this point belongs to the prime-order subgroup (G1 or G2).
+    # Being on the curve is not sufficient: E(Fp) and E'(Fp2) both contain points
+    # outside the order-r subgroup, and accepting them makes keys and signatures malleable.
+    # Since r**2 does not divide the group order, [r]P == O holds only for P in the subgroup.
+    # That is the definition and the reference the specs compare against; PointG1 and PointG2
+    # override it with an endomorphism check that reaches the same answer in a fraction of
+    # the time.
+    # @return [Boolean] true if this point is in the prime-order subgroup.
+    def in_group?
+      zero? || multiply_unsafe(Curve::R).zero?
+    end
+
+    # Validate that this point belongs to the prime-order subgroup.
+    # @raise [PointError] Occur when this point is not in the prime-order subgroup.
+    def validate_group!
+      raise PointError, 'Invalid point: not in prime-order subgroup' unless in_group?
+    end
+
     def to_affine(inv_z = z.invert)
       [x * inv_z, y * inv_z]
     end
 
+    # @raise [PointError] Occur when any of +points+ is the point at infinity, which has no
+    # affine representation.
     def to_affine_batch(points)
+      raise PointError, 'The point at infinity has no affine representation.' if points.any?(&:zero?)
+
       to_inv = gen_invert_batch(points.map(&:z))
       points.map.with_index { |p, i| p.to_affine(to_inv[i]) }
     end
@@ -136,21 +216,23 @@ module BLS
       new_point(xy[0], xy[1], x.class.const_get(:ONE))
     end
 
+    # Inverts a whole array for the price of one inversion plus a few multiplications each.
+    # Zero is refused rather than skipped: leaving it in place would hand the caller a zero
+    # where it asked for an inverse, and Field#invert refuses it for the same reason.
+    # @raise [BLS::Error] Occur when any element is zero.
     def gen_invert_batch(nums)
+      raise BLS::Error, 'Zero has no multiplicative inverse.' if nums.any?(&:zero?)
+
       len = nums.length
       scratch = Array.new(len)
       acc = x.class::ONE
       len.times do |i|
-        next if nums[i].zero?
-
         scratch[i] = acc
         acc *= nums[i]
       end
       acc = acc.invert
       len.times do |t|
         i = len - t - 1
-        next if nums[i].zero?
-
         tmp = acc * nums[i]
         nums[i] = acc * scratch[i]
         acc = tmp
@@ -158,18 +240,37 @@ module BLS
       nums
     end
 
-    # Constant time multiplication. Uses wNAF.
+    # Scalar multiplication using wNAF.
+    #
+    # This is NOT constant time, despite what {multiply_unsafe} implies by contrast. The
+    # number of additions follows the number of non-zero windows in the scalar, the point
+    # each one adds is read at an index derived from the scalar, and the additions themselves
+    # branch on whether an operand is the identity or the two are equal. Underneath, Ruby's
+    # bignum arithmetic and the modulo in Fp both run in time that depends on their operands.
+    # Anything the scalar decides is therefore visible to something watching timing or cache
+    # behaviour, which matters here because #sign and .from_private_key reach this with the
+    # private key. See the README.
+    #
+    # noble, which this follows, adds a throwaway point on every zero window so that each
+    # window costs one addition whatever its digit. That buys nothing here, where the
+    # arithmetic underneath is not constant time to begin with, so the zero windows are
+    # skipped and the work saved instead.
     def multiply(scalar)
       n = scalar.is_a?(Field) ? scalar.value : scalar
       raise PointError, 'Invalid scalar, expected positive integer' if n <= 0
-      raise PointError, "Scalar has more bits than maxBits, shouldn't happen" if n.bit_length > max_bits
 
-      wNAF(n).first
+      # Reduced modulo r so that wNAF has {SCALAR_BITS} bits to walk, whatever was passed in.
+      # The table used to be sized from the base field instead, 381 bits for G1 and 762 for
+      # G2, and every window past the scalar's top bit was a wasted addition.
+      n %= Curve::R
+      return zero if n.zero?
+
+      wNAF(n)
     end
     alias * multiply
 
     def precomputes_window(w)
-      windows = (BigDecimal(max_bits) / w).ceil
+      windows = window_count(w)
       window_size = 2**(w - 1)
       points = []
       p = self
@@ -185,14 +286,35 @@ module BLS
       points
     end
 
-    def max_bits
-      self.class.const_get(:MAX_BITS)
+    # Number of width-+w+ windows that {wNAF} walks and {precomputes_window} must cover.
+    #
+    # One bit more than the scalar has. A window whose digit comes out above 2**(w - 1) is
+    # recoded as a negative digit and carries 1 into the next window, and when the top
+    # window of the scalar does that, the carry needs a window of its own or it is dropped
+    # on the floor. With r's top five bits being 11100, a width of 5 hits this for about
+    # four scalars in ten.
+    # @param [Integer] w window width.
+    # @return [Integer] window count.
+    def window_count(w)
+      (SCALAR_BITS + w) / w
     end
 
     def normalize_z(points)
       to_affine_batch(points).map{ |p| from_affine_tuple(p) }
     end
 
+    # Build the window table that {multiply} then uses, trading memory for speed on a point
+    # that will be multiplied repeatedly, such as a generator.
+    #
+    # Call this once, before the point is shared between threads. The check below is not a
+    # lock: the table takes long enough to build that MRI will switch threads part way
+    # through, so several callers can pass the check together and each build their own, each
+    # paying the time and the memory. What they build is identical, so whichever assignment
+    # lands last is still correct and no half-built table is ever visible; the cost is the
+    # duplicated work, and a guard that reads as protection while providing none.
+    #
+    # @param [Integer] w window width.
+    # @raise [PointError] Occur when this point already has precomputes.
     def calc_multiply_precomputes(w)
       raise PointError, 'This point already has precomputes.' if m_precomputes
 
@@ -208,8 +330,7 @@ module BLS
     def wNAF(n)
       w, precomputes = m_precomputes || [1, precomputes_window(1)]
       p = zero
-      f = zero
-      windows = (BigDecimal(max_bits) / w).ceil
+      windows = window_count(w)
       window_size = 2**(w - 1)
       mask = (2**w - 1)
       max_number = 2**w
@@ -222,33 +343,23 @@ module BLS
           wbits -= max_number
           n += 1
         end
-        if wbits.zero?
-          f += (window % 2 ? precomputes[offset].negate : precomputes[offset])
-        else
-          cached = precomputes[offset + wbits.abs - 1]
-          p += (wbits.negative? ? cached.negate : cached)
-        end
+        next if wbits.zero?
+
+        cached = precomputes[offset + wbits.abs - 1]
+        p += (wbits.negative? ? cached.negate : cached)
       end
-      [p, f]
+      p
     end
   end
 
   module_function
 
-  def norm_p1(point)
-    point.is_a?(PointG1) ? point : PointG1.from_hex(point)
-  end
-
-  def norm_p2(point)
-    point.is_a?(PointG2) ? point : PointG2.from_hex(point)
-  end
-
-  def norm_p1h(point)
-    point.is_a?(PointG1) ? point : PointG1.hash_to_curve(point)
+  def norm_p1h(point, scheme: :basic)
+    point.is_a?(PointG1) ? point : PointG1.hash_to_curve(point, scheme: scheme)
   end
 
-  def norm_p2h(point)
-    point.is_a?(PointG2) ? point : PointG2.hash_to_curve(point)
+  def norm_p2h(point, scheme: :basic)
+    point.is_a?(PointG2) ? point : PointG2.hash_to_curve(point, scheme: scheme)
   end
 
 end

data/lib/bls/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BLS
-  VERSION = '0.3.1'
+  VERSION = '0.5.0'
 end

data/lib/bls.rb

@@ -2,6 +2,7 @@
 
 require 'digest'
 require 'bls/version'
+require 'bls/error' # defines the exception classes the files below raise
 require 'bls/math'
 require 'bls/curve'
 require 'bls/field'
@@ -11,8 +12,6 @@ require 'bls/pairing'
 
 module BLS
 
-  class Error < StandardError; end
-
   POW_2_381 = 2**381
   POW_2_382 = POW_2_381 * 2
   POW_2_383 = POW_2_382 * 2
@@ -28,13 +27,15 @@ module BLS
   # @param [Symbol] sig_type Signature type, :g1 or :g2.
   # If :g1 is specified, the signature is a point on G1 and the public key is a point on G2.
   # If :g2 is specified, the signature is a point on G2 and the public key is a point on G1.
+  # @param [Symbol] scheme Signature scheme, :basic or :pop. Signatures made under one scheme
+  # do not verify under the other, so signer and verifier must agree on it.
   # @return [PointG2] The signature point.
-  def sign(message, private_key, sig_type: :g2)
+  def sign(message, private_key, sig_type: :g2, scheme: :basic)
     msg_point = case sig_type
                 when :g1
-                  BLS.norm_p1h(message)
+                  BLS.norm_p1h(message, scheme: scheme)
                 when :g2
-                  BLS.norm_p2h(message)
+                  BLS.norm_p2h(message, scheme: scheme)
                 else
                   raise Error, 'sig_type must be :g1 or :g2.'
                 end
@@ -62,30 +63,42 @@ module BLS
   # @param [BLS::PointG1|BLS::PointG2] signature
   # @param [String] message Message digest(hash value with hex format) to be verified.
   # @param [BLS::PointG2|BLS::PointG1] public_key Public key with hex format or PointG1.
+  # @param [Symbol] scheme Signature scheme the signature was made under, :basic or :pop.
   # @return [Boolean] verification result.
-  def verify(signature, message, public_key)
+  def verify(signature, message, public_key, scheme: :basic)
     unless signature.is_a?(PointG1) && public_key.is_a?(PointG2) ||
       signature.is_a?(PointG2) && public_key.is_a?(PointG1)
       raise BLS::Error, 'Invalid signature or public key. If the public key is PointG1, the signature must be an element of Point::G2 or vice versa.'
     end
+    # KeyValidate of draft-irtf-cfrg-bls-signature section 2.5. The identity is not a public
+    # key anybody holds, and pairing it away would leave the identity signature verifying
+    # against every message.
+    return false if public_key.zero?
+
     g = public_key.is_a?(PointG1) ? PointG1::BASE : PointG2::BASE
     ephm = if public_key.is_a?(PointG1)
-             hm = BLS.norm_p2h(message)
-             BLS.pairing(public_key.negate, hm, with_final_exp: false)
+             hm = BLS.norm_p2h(message, scheme: scheme)
+             BLS.partial_pairing(public_key.negate, hm)
            else
-             hm = BLS.norm_p1h(message)
-             BLS.pairing(hm, public_key.negate, with_final_exp: false)
+             hm = BLS.norm_p1h(message, scheme: scheme)
+             BLS.partial_pairing(hm, public_key.negate)
            end
     egs = if public_key.is_a?(PointG1)
-            BLS.pairing(g, signature, with_final_exp: false)
+            BLS.partial_pairing(g, signature)
           else
-            BLS.pairing(signature, g, with_final_exp: false)
+            BLS.partial_pairing(signature, g)
           end
     exp = (egs * ephm).final_exponentiate
     exp == Fp12::ONE
   end
 
   # Aggregate multiple public keys.
+  #
+  # WARNING: the aggregate is only meaningful once every input key has been checked with
+  # {pop_verify}. Without that check an attacker who publishes pk_a = g * x - pk_victim
+  # can produce, on their own, a signature that verifies against the aggregate, making it
+  # look like the victim signed. See {fast_aggregate_verify}.
+  #
   # @param [Array[BLS::PointG1]|Array[BLS::PointG2]] public_keys the list of public keys.
   # @return [BLS::PointG1|BLS::PointG2] aggregated public key.
   def aggregate_public_keys(public_keys)
@@ -120,13 +133,20 @@ module BLS
   end
 
   # Verify aggregated signature.
+  #
+  # Under the :basic scheme the messages must all be distinct: repeating one is reported as
+  # an invalid signature, since that scheme has nothing but message distinctness to stop a
+  # rogue key from signing on another key's behalf. Use :pop, whose proofs of possession rule
+  # that out, to verify several signatures over the same message.
+  #
   # @param [BLS::PointG2|BLS::PointG1] signature aggregated signature(BLS::PointG2 or BLS::PointG1).
   # @param [Array[String]] messages the list of message.
   # @param [Array[BLS::PointG1]|Array[BLS::PointG2]] public_keys the list of public keys(BLS::PointG1 or BLS::PointG2).
+  # @param [Symbol] scheme Signature scheme the signatures were made under, :basic or :pop.
   # @return [Boolean] verification result.
-  def verify_batch(signature, messages, public_keys)
-    raise BLS::Error, 'Expected non-empty array.' if messages.empty?
+  def verify_batch(signature, messages, public_keys, scheme: :basic)
     raise BLS::Error, 'Public keys count should equal msg count.' unless messages.size == public_keys.size
+    return false if messages.empty? # nothing was signed, so nothing is verified
 
     sig_g2_flag = signature.is_a?(PointG2)
     public_keys.each do |public_key|
@@ -134,20 +154,70 @@ module BLS
         raise BLS::Error, "Public key must be #{sig_g2_flag ? 'PointG1' : 'PointG2'}"
       end
     end
+    return false if public_keys.any?(&:zero?) # KeyValidate, as in #verify
+
+    n_message = messages.map { |m| sig_g2_flag ? BLS.norm_p2h(m, scheme: scheme) : BLS.norm_p1h(m, scheme: scheme)}
 
-    n_message = messages.map { |m| sig_g2_flag ? BLS.norm_p2h(m) : BLS.norm_p1h(m)}
-    paired = []
+    # Keys that signed the same message are summed so that message is paired exactly once:
+    # e(P1, Q) * e(P2, Q) == e(P1 + P2, Q). Grouping on the serialized point rather than on
+    # the message keeps this independent of how equal messages happened to be spelled.
     zero = sig_g2_flag ? PointG1::ZERO : PointG2::ZERO
-    n_message.each do |message|
-      group_pubkey = n_message.each_with_index.inject(zero)do|group_pubkey, (sub_message, i)|
-        sub_message == message ? group_pubkey + public_keys[i] : group_pubkey
-      end
-      paired << (sig_g2_flag ? BLS.pairing(group_pubkey, message, with_final_exp: false) :
-                   BLS.pairing(message, group_pubkey, with_final_exp: false))
+    grouped = {}
+    n_message.each_with_index do |message, i|
+      group = (grouped[message.to_hex(compressed: true)] ||= [message, zero])
+      group[1] += public_keys[i]
+    end
+    return false if scheme == :basic && grouped.size < n_message.size
+
+    paired = grouped.each_value.map do |message, group_pubkey|
+      sig_g2_flag ? BLS.partial_pairing(group_pubkey, message) :
+        BLS.partial_pairing(message, group_pubkey)
     end
-    paired << (sig_g2_flag ? BLS.pairing(PointG1::BASE.negate, signature, with_final_exp: false) :
-                 BLS.pairing(signature, PointG2::BASE.negate, with_final_exp: false))
+    paired << (sig_g2_flag ? BLS.partial_pairing(PointG1::BASE.negate, signature) :
+                 BLS.partial_pairing(signature, PointG2::BASE.negate))
     product = paired.inject(Fp12::ONE) { |a, b| a * b }
     product.final_exponentiate == Fp12::ONE
   end
+
+  # Generate a proof of possession for +private_key+: a signature, under that key, over the
+  # public key it belongs to. Producing one requires knowing the private key, which is what
+  # makes aggregation safe against rogue key attacks.
+  # @param [Integer|String] private_key The private key. Integer or String(hex).
+  # @param [Symbol] key_type Public key type, :g1 or :g2. The proof lives in the other group.
+  # @return [BLS::PointG2|BLS::PointG1] proof of possession.
+  def pop_prove(private_key, key_type: :g1)
+    public_key = get_public_key(private_key, key_type: key_type)
+    msg = public_key.to_hex(compressed: true)
+    msg_point = public_key.is_a?(PointG1) ? BLS.norm_p2h(msg, scheme: :pop_proof) :
+                  BLS.norm_p1h(msg, scheme: :pop_proof)
+    msg_point * BLS.normalize_priv_key(private_key)
+  end
+
+  # Verify a proof of possession produced by {pop_prove}.
+  # @param [BLS::PointG1|BLS::PointG2] public_key the public key being proven.
+  # @param [BLS::PointG2|BLS::PointG1] proof proof of possession.
+  # @return [Boolean] verification result.
+  def pop_verify(public_key, proof)
+    verify(proof, public_key.to_hex(compressed: true), public_key, scheme: :pop_proof)
+  end
+
+  # Verify an aggregated signature over a single message signed by every key in +public_keys+.
+  #
+  # WARNING: every public key must have passed {pop_verify} first. This check cannot be done
+  # here because it needs each key's proof, and skipping it reopens the rogue key attack that
+  # the pop scheme exists to prevent.
+  #
+  # @param [BLS::PointG2|BLS::PointG1] signature aggregated signature.
+  # @param [String] message Message digest(hash value with hex format) to be verified.
+  # @param [Array[BLS::PointG1]|Array[BLS::PointG2]] public_keys the list of public keys.
+  # @return [Boolean] verification result.
+  def fast_aggregate_verify(signature, message, public_keys)
+    return false if public_keys.empty? # nothing signed, so nothing is verified
+    # KeyValidate every key, not just the aggregate. The identity adds nothing to the sum, so
+    # a set containing it would otherwise verify on the strength of the others while counting
+    # a key that nobody holds, and could hold, as one of the signers.
+    return false if public_keys.any?(&:zero?)
+
+    verify(signature, message, aggregate_public_keys(public_keys), scheme: :pop)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bls12-381
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Shigeyuki Azuchi
@@ -13,36 +13,16 @@ dependencies:
   name: h2c
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.1
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: 0.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.1
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '0.3'
-- !ruby/object:Gem::Dependency
-  name: bigdecimal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +73,7 @@ files:
 - bls12-381.gemspec
 - lib/bls.rb
 - lib/bls/curve.rb
+- lib/bls/error.rb
 - lib/bls/field.rb
 - lib/bls/h2c.rb
 - lib/bls/math.rb
@@ -114,7 +95,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="