bls12-381 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2660bb6049da204d945d3d40a6bf06f26ed1c041794d959ea9b0662b725a1b8b
-  data.tar.gz: ad30c4cc593a729823bd51d05a1bdecc68566ed0e5b100cd31dc8130bf6e1353
+  metadata.gz: 1398ff4737e7cc35aee61178bb064235e4f5765ec18a69511681c9389c1384a5
+  data.tar.gz: f6f386f4681e0cb3a3c642a0d5fa2e061fc9c96b4034c019cdf0e510020e059a
 SHA512:
-  metadata.gz: eab97d8693ad91b412a1f7c8dd362b0b82c241e96c220ba686e79208c0828b3cd27303ecc8fa68ae51e18ca1f596d87bceff9b35ab009795e438784b8cab66a6
-  data.tar.gz: f1672d9beb73fa230f0d1bfe1b2ef56955599ed79d46ebd9a98cf344f593f705e6a63351dd87c7e65b8de25867705e915ae3f04d8e047ab9bd01741219dd5345
+  metadata.gz: 7589e44db5a83ae84615cfbad287d7c36c3eb223186e3b0552755ef36ceff516b8fcf40a1f11fec534344d48db49f4277be8fdbb82eb16e5f972854334732818
+  data.tar.gz: b0d5fb49ba941dec4fe7e3eb892cc08036e10505bf6cc6e01f429cf3874219092aaffb530bd54e96ba48c7ce01aa59cd4774871c81d05b72282e76f3a78757be

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
 
@@ -49,18 +49,12 @@ signature.to_signature
 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,8 +62,102 @@ 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 never raises over the data it is given. `BLS.verify`, `BLS.verify_batch`,
+`BLS.fast_aggregate_verify` and `BLS.pop_verify` return `false` for anything they will not
+accept, including the point at infinity and an empty set of signers, so untrusted input cannot
+turn into an exception. Deserializing that input with `from_hex` beforehand still raises, which
+is where a malformed encoding is caught.
+
+## 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).

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
@@ -248,7 +256,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 +716,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

@@ -7,15 +7,17 @@ module BLS
 
     # @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.
     # @return [Array[Integer]] byte array.
     # @raise BLS::Error
-    def expand_message_xmd(message, len_in_bytes)
+    def expand_message_xmd(message, len_in_bytes, dst)
       b_in_bytes = BigDecimal(SHA256_DIGEST_SIZE)
       r_in_bytes = b_in_bytes * 2
       ell = (BigDecimal(len_in_bytes) / b_in_bytes).ceil
       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)
@@ -34,12 +36,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)

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,8 +1,6 @@
 module BLS
   module_function
 
-  class PairingError < StandardError; end
-
   # @param [BLS::PointG1] p
   # @param [BLS::PointG2] q
   # @param [Boolean] with_final_exp
@@ -20,4 +18,19 @@ module BLS
     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,7 +1,10 @@
 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
@@ -13,33 +16,55 @@ module BLS
     # 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,12 +98,15 @@ 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_, dst || self.dst(scheme))
       p = h2c.digest([message].pack('H*'))
 
       PointG1.new(Fp.new(p.x), Fp.new(p.y), Fp::ONE)

data/lib/bls/point/g2.rb

@@ -3,7 +3,10 @@ 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
@@ -18,7 +21,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)}"
@@ -46,7 +54,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
@@ -56,9 +68,10 @@ module BLS
                 y0 = bytes[(3 * PUBLIC_KEY_LENGTH)..-1].unpack1('H*').to_i(16)
                 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 +85,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, dst || self.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
@@ -137,6 +153,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

@@ -13,8 +13,6 @@ 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
 
@@ -28,6 +26,40 @@ 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
+
+    # 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
@@ -109,6 +141,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 +159,30 @@ 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.
+    # @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 +191,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,7 +215,15 @@ 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. wNAF
+    # gives every window an addition, but the point it 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.
     def multiply(scalar)
       n = scalar.is_a?(Field) ? scalar.value : scalar
       raise PointError, 'Invalid scalar, expected positive integer' if n <= 0
@@ -193,6 +258,18 @@ module BLS
       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
 
@@ -243,12 +320,12 @@ module BLS
     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.4.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.4.0
 platform: ruby
 authors:
 - Shigeyuki Azuchi
@@ -93,6 +93,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