kzg 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a95b1996252d6a12eedace4b4bf2e156be72dbe9cb2326668b5de7f02b555918
-  data.tar.gz: bebbb85f562586fe286476b1dbac10117749474cf19f769cbe812972ba76d0c9
+  metadata.gz: ed4f0b47a0f3f5b5de96f7cd6a931aa979b6ebc84e48eaf7c696755f7caf990f
+  data.tar.gz: ae70fe07a4eb798b08669d0f891b9a83bf0d48f27311d859623ae3b3eaf9fa0c
 SHA512:
-  metadata.gz: aff0458dda59c813ee4ccc0651568b3ac5623352bffd7bca2db66304bdfc61e003121b9fbb482e072693ace781914634e83dc56d2c1287146d61f7f964bb7697
-  data.tar.gz: 4c5f4acebe7964631c93d979521c068d457d0c9256ed06488a44dc8c9859f216eeccbbdd0ac59e981ce90a90e3ebafe80d005c8690fd171d33270d0b737292ac
+  metadata.gz: 3b8a04dadb5dc5260debcff77a7b2982f15434e7f3c610189430d53abee3b8d6ac0be2ee0c46b5f7bda7bda52e1551e62e862decc4fa258491d3596301b0d853
+  data.tar.gz: 3ca8ab11a1f10b9644c1580ea2b3fbf0714f33ffb5e8460e85155c59ae8ede6f49c1a50ec11dcbc1b45ab2de90e4718a3f4483adb53db1a1d91273f1e7de6c2c

data/.github/workflows/main.yml

@@ -9,10 +9,9 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - '3.1'
-          - '3.2'
           - '3.3'
           - '3.4'
+          - '4.0'
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-11
+
+### Added
+
+- `KZG.decode_field_element`, which reads the canonical 32 byte big endian encoding of a
+  field element and refuses everything else. `BLS::Fr` reduces modulo the group order, which
+  is right for an element built in memory and wrong for one arriving as bytes: it would
+  otherwise leave `1` and `1 + BLS::Curve::R` as two spellings of a single claim, either of
+  which verifies against the other's proof. This is the scalar counterpart of
+  `BLS::PointG1.from_hex`.
+- The EIP-4844 reference vectors for `verify_kzg_proof` are run against
+  `KZG::Setting#valid_proof?`, which verifies with the same pairing equation.
+
+### Changed
+
+- Require bls12-381 0.4.0, whose `from_hex` refuses a point outside the prime-order subgroup
+  and a non-canonical encoding of one.
+- `KZG::Setting#valid_proof?` and `#valid_multi_proof?` answer `false` where they used to
+  raise, so that untrusted input cannot turn into an exception: for a proof or a commitment
+  at infinity, outside the prime-order subgroup, or of the wrong type, and for an `x` that
+  repeats, that does not pair up with `y`, or that the setup is too small to open. They also
+  check the subgroup themselves, which only `from_hex` did before and only for callers that
+  deserialize from hex.
+- `KZG::Commitment` commits the zero polynomial to the point at infinity rather than to
+  `nil`, which `#compute_proof` returns for a constant polynomial.
+- `KZG::Setting.new`, `KZG::Commitment.new`, `KZG::Polynomial#div` and `#multiply` raise
+  `KZG::Error` for arguments that used to fail later as arithmetic on a nil.
+- `KZG.setup_params` raises `KZG::Error` for an `n` below 2, which built a setting that could
+  verify nothing, and for a secret that is a multiple of the group order.
+
 ## [0.1.0] - 2021-04-11
 
 - Initial release

data/README.md

@@ -95,6 +95,35 @@ y = [55, 9217, 280483]
 setting.valid_multi_proof?(commitment.value, multi_proof, x, y)
 ```
 
+#### Untrusted input
+
+`valid_proof?` and `valid_multi_proof?` answer `false` for anything they will not accept, so
+a commitment or a proof that arrives over the wire cannot turn into an exception. Both check
+that the points they are given are in the prime-order subgroup, which being on the curve does
+not imply and which proofs are forgeable without.
+
+What they cannot check is how `x` and `y` were spelled, because they never see it. `BLS::Fr`
+reduces modulo the group order, which is what makes `-6` and `r - 6` one element, and also
+what leaves `1` and `1 + BLS::Curve::R` as two encodings of a single claim: a proof for
+either verifies against the other. Decode field elements that arrive as bytes with
+`KZG.decode_field_element`, which refuses everything but the canonical 32 byte big endian
+form, in the same way `BLS::PointG1.from_hex` refuses a non-canonical point:
+
+```ruby
+x = KZG.decode_field_element(x_hex) # 32 bytes, big endian, no 0x prefix
+y = KZG.decode_field_element(y_hex) # raises KZG::Error if x_hex is not canonical
+commitment = BLS::PointG1.from_hex(commitment_hex)
+proof = BLS::PointG1.from_hex(proof_hex)
+
+setting.valid_proof?(commitment, proof, x, y)
+```
+
+The [EIP-4844 reference vectors for `verify_kzg_proof`][eip4844-vectors] are run against
+`valid_proof?` in the specs; that function verifies with the same pairing equation and reads
+nothing from the trusted setup but `[s]_2.`
+
+[eip4844-vectors]: https://github.com/ethereum/c-kzg-4844/tree/main/tests/verify_kzg_proof/kzg-mainnet
+
 ### Use as vector commitment
 
 When used as a Vector commitment, the value to be committed is encoded in a polynomial expression as the evaluated value of the polynomial.
@@ -117,3 +146,25 @@ proof = commitment.compute_proof(3)
 # verify
 setting.valid_proof?(commitment.value, proof, 3, 9)
 ```
+
+## Side channels
+
+**Committing is not safe against an attacker who can measure it.** A commitment multiplies a
+setup point by each coefficient of the polynomial, and those coefficients are the very thing
+the commitment hides — the vector above among them. The multiplication underneath is
+[not constant time][bls-side-channels]: the scalar decides which precomputed point each
+window adds and so which memory is touched, point addition returns early on the identity, and
+Ruby's bignum arithmetic takes time that depends on its operands.
+
+A pure Ruby implementation cannot fix this, and neither can the library underneath. Treat
+committing as suitable where it cannot be observed. Verifying is fine either way, since it
+touches nothing secret.
+
+[bls-side-channels]: https://github.com/azuchi/bls12-381#side-channels
+
+## Threads
+
+Verifying from several threads gives the right answers. `valid_proof?` pairs against
+`BLS::PointG2::BASE`, which memoises its pairing coefficients on first use without a lock, so
+racing callers can each compute them; what is assigned is always a finished array, so the
+cost is the repeated work rather than a wrong result.

data/kzg.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
 
   # Uncomment to register a new dependency of your gem
   spec.add_dependency 'bigdecimal'
-  spec.add_dependency 'bls12-381', '~> 0.3.0'
+  spec.add_dependency 'bls12-381', '~> 0.4.0'
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/kzg/commitment.rb

@@ -8,9 +8,22 @@ module KZG
     # Create commitment
     # @param [KZG::Setting] setting
     # @param [KZG::Polynomial] polynomial
+    # @raise [KZG::Error] Occur when the polynomial has more coefficients than the setup has
+    # points to commit them with.
     def initialize(setting, polynomial)
+      # Checked here rather than only in from_coeffs, which is not the only way in: the
+      # verification path builds its interpolation straight through new, and a coefficient
+      # with no point to meet is otherwise a nil that fails as arithmetic.
+      if polynomial.coeffs.length > setting.g1_points.length
+        raise KZG::Error,
+              "coeffs length is greater than the number of secret parameters."
+      end
+
       @setting = setting
       @polynomial = polynomial
+      # Seeded with the point at infinity so that the zero polynomial commits to it rather
+      # than to nil. compute_proof reaches here with an empty quotient whenever the
+      # polynomial is a constant, and that proof goes on to a pairing.
       @value =
         polynomial
           .coeffs
@@ -19,17 +32,14 @@ module KZG
             c = c.is_a?(BLS::Fr) ? c : BLS::Fr.new(c)
             c.value.zero? ? BLS::PointG1::ZERO : setting.g1_points[i] * c
           end
-          .inject(&:+)
+          .inject(BLS::PointG1::ZERO, &:+)
     end
 
     # Create commitment using coefficients.
     # @param [KZG::Setting] setting
     # @param [Array(Integer | BLS::Fr)] coeffs Coefficients of polynomial equation.
+    # @raise [KZG::Error] Occur when there are more coefficients than setup points, as in new.
     def self.from_coeffs(setting, coeffs)
-      if coeffs.length > setting.g1_points.length
-        raise KZG::Error,
-              "coeffs length is greater than the number of secret parameters."
-      end
       Commitment.new(setting, KZG::Polynomial.new(coeffs))
     end
 

data/lib/kzg/polynomial.rb

@@ -12,13 +12,27 @@ module KZG
     end
 
     # Create polynomial using lagrange interpolation using (x, y) list.
-    # @param [Array(Integer)] x The array of x coordinate.
-    # @param [Array(Integer)] y The array of y coordinate.
+    # @param [Array(Integer)] x The array of x coordinate. Must not contain the same value
+    # twice: no polynomial passes through two different y at one x, and one that repeats an
+    # (x, y) pair is under-determined either way.
+    # @param [Array(Integer)] y The array of y coordinate. Must be as long as +x+.
     # @return [KZG::Polynomial]
+    # @raise [KZG::Error] Occur when x contains a duplicate value, or x and y differ in
+    # length.
     def self.lagrange_interpolate(x, y)
       n = x.length
+      unless n == y.length
+        raise KZG::Error, "x and y must have the same length."
+      end
+
       x = x.map { |i| i.is_a?(BLS::Fr) ? i : BLS::Fr.new(i) }
       y = y.map { |i| i.is_a?(BLS::Fr) ? i : BLS::Fr.new(i) }
+      # The product below runs over the differences between x[i] and every other x, so a
+      # repeat makes it zero and the division by it undefined. Caught here rather than left
+      # to BLS::Fr#invert so that it reads as the input error it is.
+      if x.map(&:value).uniq.length < n
+        raise KZG::Error, "x contains duplicate value."
+      end
       coeffs = Array.new(n, BLS::Fr::ZERO)
       n.times do |i|
         prod = BLS::Fr::ONE
@@ -40,7 +54,10 @@ module KZG
     # Create polynomial from array of x coordinate like f(x) = (x - x0)(x - x1)...(x - xn)
     # @param [Array(Integer)] x An array of x coordinate.
     # @return [KZG::Polynomial]
+    # @raise [KZG::Error] Occur when x is empty, which names no roots to build from.
     def self.zero_poly(x)
+      raise KZG::Error, "x must not be empty." if x.empty?
+
       poleis =
         x.map { |v| Polynomial.new([BLS::Fr.new(v).negate, BLS::Fr::ONE]) }
       poleis[1..].inject(poleis.first) { |result, poly| result * poly }
@@ -96,6 +113,11 @@ module KZG
       unless other.is_a?(Polynomial)
         raise ArgumentError, "multiply target must be Polynomial"
       end
+      # An empty coefficient list is the zero polynomial, and zero times anything is zero.
+      # Left to the loop below, an empty operand sizes the result at -1 when both are empty,
+      # and otherwise leaves it a row of nils, since the inner loop never runs to fill them.
+      return Polynomial.new([]) if coeffs.empty? || other.coeffs.empty?
+
       new_coeffs = Array.new(coeffs.length + other.coeffs.length - 1)
       coeffs.each.with_index do |a, i|
         other.coeffs.each.with_index do |b, j|
@@ -111,10 +133,18 @@ module KZG
     # @param [KZG::Polynomial] other Other polynomial
     # @return [KZG::Polynomial] Divided polynomial
     # @return ArgumentError
+    # @raise [KZG::Error] Occur when +other+ has no non-zero leading coefficient to divide by.
     def div(other)
       unless other.is_a?(Polynomial)
         raise ArgumentError, "divide target must be Polynomial"
       end
+      # The long division below divides by this coefficient once per step. Zero has no
+      # inverse, and an empty divisor has no coefficient at all; neither denominator names a
+      # polynomial of any degree, so refuse both here rather than reach BLS::Fr#invert.
+      if other.coeffs.empty? || other.coeffs.last.value.zero?
+        raise KZG::Error, "divisor must have a non-zero leading coefficient."
+      end
+
       a = coeffs.dup
       a_pos = a.length - 1
       b_pos = other.coeffs.length - 1

data/lib/kzg/setting.rb

@@ -6,21 +6,33 @@ module KZG
     attr_reader :g1_points, :g2_points
 
     # @param [Array(BLS::PointG1)] g1_points
-    # @param [Array(BLS::PointG2)] g2_points
+    # @param [Array(BLS::PointG2)] g2_points at least [1]_2 and [s]_2, the two a proof is
+    # checked against.
+    # @raise [KZG::Error] Occur when either array holds something other than the points of
+    # its group, or when g2_points is too short to verify with.
     def initialize(g1_points, g2_points)
       raise KZG::Error, "g1_points must be array." unless g1_points.is_a?(Array)
+      raise KZG::Error, "g2_points must be array." unless g2_points.is_a?(Array)
       unless g1_points.all? { |g| g.is_a?(BLS::PointG1) }
         raise KZG::Error, "All elements of g1_points must be BLS::PointG1."
       end
       unless g2_points.all? { |g| g.is_a?(BLS::PointG2) }
         raise KZG::Error, "All elements of g2_points must be BLS::PointG2."
       end
+      # valid_proof? reads g2_points[1], so a setting short of it can verify nothing. Refused
+      # here rather than at verification time, where it is a nil that has travelled some way
+      # from the setup that omitted it.
+      if g2_points.length < 2
+        raise KZG::Error, "g2_points must have at least 2 elements."
+      end
 
       @g1_points = g1_points
       @g2_points = g2_points
     end
 
     def ==(other)
+      return false unless other.is_a?(Setting)
+
       g1_points == other.g1_points && g2_points == other.g2_points
     end
 
@@ -29,20 +41,22 @@ module KZG
     # @param [BLS::PointG1] proof
     # @param [Integer|BLS::Fr] x
     # @param [Integer|BLS::Fr] y
+    # @return [Boolean] verification result.
     def valid_proof?(commit_point, proof, x, y)
+      return false unless g1_element?(commit_point) && g1_element?(proof)
+
       x = x.is_a?(BLS::Fr) ? x : BLS::Fr.new(x)
       y = y.is_a?(BLS::Fr) ? y : BLS::Fr.new(y)
       xg2 = x.value.zero? ? BLS::PointG2::ZERO : BLS::PointG2::BASE * x
       yg = y.value.zero? ? BLS::PointG1::ZERO : BLS::PointG1::BASE * y
 
       # e([commitment - y]^(-1), [1]) * e([proof],  [s - x]) = 1
-      lhs =
-        BLS.pairing(
-          (commit_point - yg).negate,
-          BLS::PointG2::BASE,
-          with_final_exp: false
-        )
-      rhs = BLS.pairing(proof, g2_points[1] - xg2, with_final_exp: false)
+      # partial_pairing rather than pairing: a proof at infinity, or a commitment that
+      # cancels with [y], is a degenerate input a verifier can be handed and has to come out
+      # as false rather than as a BLS::PairingError. e(O, Q) = e(P, O) = 1 leaves the
+      # equation above intact.
+      lhs = BLS.partial_pairing((commit_point - yg).negate, BLS::PointG2::BASE)
+      rhs = BLS.partial_pairing(proof, g2_points[1] - xg2)
       exp = (lhs * rhs).final_exponentiate
       exp == BLS::Fp12::ONE
     end
@@ -52,21 +66,36 @@ module KZG
     # @param [BLS::PointG1] proof
     # @param [Array(Integer|BLS::Fr)] x
     # @param [Array(Integer|BLS::Fr)] y
+    # @return [Boolean] verification result. A claim this method cannot interpolate through
+    # is a claim that does not verify, so a malformed x/y is false rather than an exception.
     def valid_multi_proof?(commit_point, proof, x, y)
+      return false unless g1_element?(commit_point) && g1_element?(proof)
+      # Nothing is claimed over an empty set of points, and a y that does not pair up with an
+      # x leaves the interpolation below indexing past the end of it.
+      return false if x.empty? || x.length != y.length
+      # Both commitments below take one setup point per coefficient, and z(x) is of degree
+      # x.length, so it needs one G2 point more than there are x. A claim larger than that is
+      # one this setting cannot weigh, rather than one it has weighed and rejected, but it
+      # reaches here from whoever is being verified and so cannot raise either.
+      if x.length > g1_points.length || x.length >= g2_points.length
+        return false
+      end
+
       x = x.map { |v| v.is_a?(BLS::Fr) ? v.value : v }
       y = y.map { |v| v.is_a?(BLS::Fr) ? v.value : v }
+      # Interpolation through a repeated x is undefined, and lagrange_interpolate raises on
+      # it. The x here comes from whoever the proof is being verified for, so a repeat has to
+      # be reported as a failed proof instead of letting the exception escape. Compared after
+      # reduction, since x and x + BLS::Curve::R are the same field element.
+      return false if x.map { |v| BLS::Fr.new(v).value }.uniq.length < x.length
+
       # compute i(x)
       i_poly = Polynomial.lagrange_interpolate(x, y)
       # compute z(x)
       z_poly = Polynomial.zero_poly(x)
       # e([commitment - interpolation_polynomial(s)]^(-1), [1]) * e([proof],  [s^n - x^n]) = 1
       is = Commitment.new(self, i_poly).value
-      lhs =
-        BLS.pairing(
-          (commit_point - is).negate,
-          BLS::PointG2::BASE,
-          with_final_exp: false
-        )
+      lhs = BLS.partial_pairing((commit_point - is).negate, BLS::PointG2::BASE)
       z_commit =
         z_poly
           .coeffs
@@ -74,10 +103,35 @@ module KZG
           .with_index do |c, i|
             c.value.zero? ? BLS::PointG2::ZERO : g2_points[i] * c
           end
-          .inject(&:+)
-      rhs = BLS.pairing(proof, z_commit, with_final_exp: false)
+          .inject(BLS::PointG2::ZERO, &:+)
+      rhs = BLS.partial_pairing(proof, z_commit)
       exp = (lhs * rhs).final_exponentiate
       exp == BLS::Fp12::ONE
     end
+
+    private
+
+    # Whether +point+ is an element of G1, rather than merely a point on the curve over Fp.
+    #
+    # The subgroup check is what carries weight here. E(Fp) is bigger than the prime-order
+    # subgroup by the cofactor, and a point taken from the rest of it makes the pairing
+    # bilinear over a group the soundness argument never covered, which is what lets forged
+    # proofs through. BLS::PointG1.from_hex runs this check as of bls12-381 0.4.0, but only
+    # for callers that deserialize their points from hex; a commitment or a proof reaching
+    # this class by any other route has never been checked.
+    #
+    # The curve check has to come first: multiplying a point that satisfies no curve equation
+    # is meaningless, and its result landing on infinity would pass the subgroup check on an
+    # input that is not a point at all.
+    # @param [Object] point
+    # @return [Boolean]
+    def g1_element?(point)
+      return false unless point.is_a?(BLS::PointG1)
+
+      point.validate! # raises unless on the curve over Fp
+      point.in_group?
+    rescue BLS::PointError
+      false
+    end
   end
 end

data/lib/kzg/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KZG
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/kzg.rb

@@ -12,18 +12,65 @@ module KZG
   autoload :Polynomial, "kzg/polynomial"
   autoload :Commitment, "kzg/commitment"
 
+  # Size of the canonical encoding of a field element, as used by EIP-4844 and its test
+  # vectors: 32 bytes, big endian.
+  FIELD_ELEMENT_BYTE_SIZE = 32
+  FIELD_ELEMENT_HEX =
+    /\A(?:[0-9a-fA-F]{2}){#{FIELD_ELEMENT_BYTE_SIZE}}\z/.freeze
+
   module_function
 
+  # Decode a field element from its canonical representation.
+  #
+  # BLS::Fr.new reduces whatever it is handed modulo the group order. That is the right
+  # answer for an element built in memory, where -6 and r - 6 are two ways of writing one
+  # element, and the wrong one for an element arriving as bytes: it leaves 1 and r + 1 as two
+  # spellings of a single claim, and a proof for either verifies against the other. Anything
+  # that deduplicates, indexes or compares by the encoding then sees two claims where there
+  # is one.
+  #
+  # This is the scalar counterpart of BLS::PointG1.from_hex, which refuses a non-canonical
+  # point for the same reason. Together they cover both halves of the wire format; neither
+  # KZG::Setting#valid_proof? nor BLS::Fr can, since neither is handed the encoding.
+  #
+  # @param [String] hex a field element, 32 bytes big endian in hex, with no 0x prefix.
+  # @return [BLS::Fr] the decoded field element.
+  # @raise [KZG::Error] Occur when +hex+ is not 32 bytes of hex digits, or encodes a value at
+  # or above the group order.
+  def decode_field_element(hex)
+    unless hex.is_a?(String) && hex.match?(FIELD_ELEMENT_HEX)
+      raise KZG::Error,
+            "Field element must be #{FIELD_ELEMENT_BYTE_SIZE} bytes in hex."
+    end
+
+    value = hex.to_i(16)
+    unless value < BLS::Curve::R
+      raise KZG::Error, "Field element must be less than the group order."
+    end
+
+    BLS::Fr.new(value)
+  end
+
   # Setup elements of elliptic curve from +secret+.
   # Note: Since the random secret must not be known to anyone,
   # this Trusted Setup usually needs to be performed using an MPC or similar.
   # @param [Integer] secret random secret.
-  # @param [Integer] n number of parameters.
+  # @param [Integer] n number of parameters. At least 2, since a setting needs [1]_2 and
+  # [s]_2 to check a proof against.
   # @return [KZG::Setting]
+  # @raise [KZG::Error] Occur when n is below 2, or when the secret reduces to zero.
   def setup_params(secret, n)
+    raise KZG::Error, "n must be 2 or more." unless n.is_a?(Integer) && n >= 2
+
+    s = BLS::Fr.new(secret)
+    # A secret of zero, or any multiple of the group order, leaves every point above [s^0] at
+    # infinity: a setup that commits to nothing but the constant term.
+    if s.zero?
+      raise KZG::Error, "secret must not be a multiple of the group order."
+    end
+
     s1 = Array.new(n)
     s2 = Array.new(n)
-    s = BLS::Fr.new(secret)
     s_pow = BLS::Fr::ONE
     n.times do |i|
       s1[i] = BLS::PointG1::BASE * s_pow

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kzg
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - azuchi
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement