secp256k1-native 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3721e2220de6d65f6bda10fe26a47bd2eaa248ba5d645caf70a0e40901720268
-  data.tar.gz: e07a7c79de6e4055581fd4a009dd48c375f7deb722bd2a18f5b99e9c444341ef
+  metadata.gz: b6a8b3524bbf944accbd5ee819c3623ce7495829d30b280fb29a905e43dcf52b
+  data.tar.gz: a0204b6cf5b4c37447d63e29425086320642cb881b9c107847a00111b4d07373
 SHA512:
-  metadata.gz: a5b109ef38d0589630ac73eab3ff5b910e2592926fe949aea7c12c4b9285dc94242ebfb449075276666806c659c32e7366cd61e3f43bb3bbd6a12d848ec12330
-  data.tar.gz: 4298a51739c11a6a5d01231fcf9274f1bfcdd7a93518b2920c255b8361f10bdf25c5e0c85e2c080a11380c55f4382b6980cc7a90d0eaab6f2f06b518c64da91f
+  metadata.gz: 7f0a0fd90e016a83ef50ce79f4d70c058524ae47d008992edb6250b12363ebf6c12397376da0ae6978592d9bf9a5ea05038765384f5379aba537503af9fc2b54
+  data.tar.gz: e22b4b04332c215353bfaf38f45eb03825fc9d1012a926e0c4da2369fbdc9c39bb305e3faecd69a9c476755f6c67872570d492c8531b93e0e9edaa6e7bd61872

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [0.17.0] - 2026-05-01
+
+### Added
+
+- Dudect-based constant-time verification harness (`rake timing:verify`) — empirical timing leakage detection using Welch's t-test for all constant-time C extension functions
+- Cryptographic development principles codified in CLAUDE.md — seven principles governing all development decisions
+- Property-based testing suite (field arithmetic, scalar arithmetic, point operations, cross-implementation parity)
+- GitHub Actions CI workflow for Ruby 2.7–3.4 matrix
+- Security findings disclosure process
+
+### Fixed
+
+- **Timing side-channel in `scalar_multiply_ct`** — `jp_add_internal` had early-return branches on infinity checks that leaked timing information about the secret scalar inside the Montgomery ladder (dudect t = -875). Made `jp_add_internal` fully branchless with mask-based conditional selection. Verified fix via dudect (t = 1.0)
+
+### Changed
+
+- Field arithmetic (`fred`, `fsub`, `fneg`, `fadd`) constant-time properties now empirically verified via dudect, not just code inspection
+
+## [0.16.0] - 2026-04-29
+
+### Breaking Changes
+
+- `Point#mul` is now constant-time (Montgomery ladder) by default, matching OpenSSL behaviour. The previous variable-time wNAF implementation is available as `Point#mul_vt`
+- `Point#mul` raises `InsecureOperationError` without the native C extension unless explicitly allowed via `SECP256K1_ALLOW_PURE_RUBY_CT=1` or `Secp256k1.allow_pure_ruby_ct!`
+
+### Added
+
+- `Point#mul_vt` for explicit variable-time scalar multiplication (public scalars only)
+- `Secp256k1.native?` to check whether the C extension is loaded
+- `Secp256k1.allow_pure_ruby_ct!` and `SECP256K1_ALLOW_PURE_RUBY_CT` env var for opting in to pure-Ruby constant-time operations
+- Evidence-based risk assessment documentation (`docs/risks.md`)
+- MkDocs site with GitHub Pages automation
+- YARD-generated API reference
+
+### Changed
+
+- `Point#mul_ct` is now a deprecated alias for `Point#mul`
+- Licence changed from Open BSV License to MIT
+- Documentation reorganised into focused documents (architecture, security, performance, design rationale)
+
 ## [0.15.0] - 2026-04-27
 
 ### Added

data/README.md

@@ -1,8 +1,10 @@
 # secp256k1-native
 
+> **Before using a custom cryptographic implementation, read [Evaluating the risks](https://sgbett.github.io/secp256k1-native/risks/) — it examines what the empirical evidence says about rolling your own crypto and where this gem sits in that landscape.**
+
 Pure native C secp256k1 implementation for Ruby (no libsecp256k1 dependency).
 
-Provides secp256k1 elliptic curve cryptography for Ruby — field arithmetic, scalar operations, Jacobian point arithmetic, and constant-time scalar multiplication — via an optional native C extension. The gem ships a pure-Ruby base layer that works out of the box on any Ruby 2.7+ platform, with the C extension as an optional accelerator (~22× speedup) that is silently skipped when unavailable.
+Provides secp256k1 elliptic curve cryptography for Ruby — field arithmetic, scalar operations, Jacobian point arithmetic, and constant-time scalar multiplication — via an optional native C extension. The gem ships a pure-Ruby base layer that works out of the box on any Ruby 2.7+ platform, with the C extension providing constant-time guarantees and ~22x acceleration when available.
 
 Used by the [bsv-ruby-sdk](https://github.com/sgbett/bsv-ruby-sdk) and suitable for any Ruby project requiring secp256k1 operations.
 
@@ -36,14 +38,14 @@ require 'secp256k1'
 # Generator point
 g = Secp256k1::Point.generator
 
-# Scalar multiplication (variable-time, for public scalars)
-scalar = 0xdeadbeef
-point = g.mul(scalar)
-puts point.x.to_s(16)
-
-# Constant-time scalar multiplication (for secret scalars)
+# Scalar multiplication (constant-time by default — safe for all scalars)
 secret = 0xcafebabe
-pubkey = g.mul_ct(secret)
+pubkey = g.mul(secret)
+puts pubkey.x.to_s(16)
+
+# Variable-time scalar multiplication (faster, for public scalars only)
+scalar = 0xdeadbeef
+point = g.mul_vt(scalar)
 
 # SEC1 encoding / decoding
 compressed = pubkey.to_octet_string(:compressed)    # 33 bytes
@@ -95,12 +97,12 @@ The wNAF loop and ECDSA/Schnorr logic remain in Ruby, calling native primitives
 
 ### Performance
 
-| Mode | Operations/sec (scalar multiplication) |
-|---|---|
-| Pure Ruby | ~100 |
-| Native C extension | ~2,277 |
+| Mode | Sign (ops/sec) | Verify (ops/sec) |
+|------|---------------|-----------------|
+| Pure Ruby | 100 | 97 |
+| C extension | 2,302 | 1,826 |
 
-The extension provides approximately 22× speedup for scalar multiplication — the dominant cost in signing, public key derivation, and Schnorr proof generation.
+The C extension provides ~23× speedup for signing and ~19× for verification — but performance is secondary to security. The primary purpose of the C extension is to provide **hardware-level constant-time guarantees** that Ruby's variable-width `Integer` internals cannot offer. Users handling secret key material should evaluate whether the pure-Ruby implementation is appropriate for their threat model. See [docs/performance.md](docs/performance.md) for detailed analysis.
 
 ## Building the native extension
 
@@ -116,7 +118,7 @@ bundle exec rake compile
 
 The compiled bundle is placed at `lib/secp256k1_native.bundle` (macOS) or `lib/secp256k1_native.so` (Linux).
 
-`extconf.rb` checks for `__uint128_t` availability at configure time. If the type is absent, a no-op Makefile is generated and the extension is silently skipped. At runtime, `secp256k1.rb` wraps the `require` in a `rescue LoadError` — if the bundle is absent, the pure-Ruby implementation is used without any error.
+`extconf.rb` checks for `__uint128_t` availability at configure time. If the type is absent, a no-op Makefile is generated and the extension is skipped. At runtime, `secp256k1.rb` wraps the `require` in a `rescue LoadError` — if the bundle is absent, the pure-Ruby implementation is used for public-scalar operations. Constant-time operations (`mul_ct`) will raise `InsecureOperationError` unless explicitly allowed via `SECP256K1_ALLOW_PURE_RUBY_CT=1` or `Secp256k1.allow_pure_ruby_ct!`.
 
 ## Running tests
 

data/ext/secp256k1_native/jacobian.c

@@ -24,9 +24,12 @@
  * ------------------------
  * jp_double: The Y=0 (point at infinity) check is handled branchlessly by
  *   computing the full result and masking to JP_INFINITY when Y is zero.
- * jp_add: Branches on pz==0 / qz==0 / h==0 operate on public data in all
- *   call paths (the wNAF accumulator starts at infinity, which is public).
- *   The field arithmetic within the main computation path is branchless.
+ * jp_add: Fully branchless.  All 18 field operations for the normal case
+ *   are computed unconditionally, along with an unconditional jp_double for
+ *   the h==0 (equal points) case.  Mask-based selects choose the correct
+ *   result (normal, double, infinity, or passthrough) without branching on
+ *   any input-dependent value.  This is essential for constant-time scalar
+ *   multiplication via the Montgomery ladder.
  * jp_neg: Branchless — delegates the zero-checking to fneg_internal.
  */
 
@@ -138,7 +141,7 @@ void jp_double_internal(uint256_t r[3], const uint256_t p[3])
 }
 
 /*
- * jp_add_internal — add two Jacobian points.
+ * jp_add_internal — add two Jacobian points (branchless).
  *
  * Formula (from hyperelliptic.org, "add-2007-bl"):
  *
@@ -153,27 +156,41 @@ void jp_double_internal(uint256_t r[3], const uint256_t p[3])
  *   Y3   = R·(V - X3) - S1·H3
  *   Z3   = H·Z1·Z2
  *
- * Special cases (handled with branches — all operate on public data):
- *   - pz == 0 (p is infinity)  → return q
- *   - qz == 0 (q is infinity)  → return p
- *   - h == 0, r == 0           → points are equal, call jp_double_internal(p)
- *   - h == 0, r != 0           → points are negatives of each other → infinity
- *
- * Matches the Ruby jp_add implementation exactly.
+ * Special cases (handled branchlessly via mask-based selects):
+ *   - pz == 0 (p is infinity)  → result = q
+ *   - qz == 0 (q is infinity)  → result = p
+ *   - h == 0, r == 0           → points are equal → jp_double(p)
+ *   - h == 0, r != 0           → points are negatives → infinity
+ *
+ * All field operations and the jp_double call are computed unconditionally.
+ * The correct result is chosen at the end via uint256_select, ensuring
+ * constant-time execution for the Montgomery ladder in scalar_multiply_ct.
+ *
+ * When h==0, the main path computes with h2=0, h3=0, z3=0 — well-defined
+ * field elements (no undefined behaviour), just mathematically meaningless.
+ * The mask-based selects override with the correct result.
+ *
+ * Selection order (later overrides earlier):
+ *   1. Start with normal addition result
+ *   2. If h==0 && r_val==0: select jp_double result (equal points)
+ *   3. If h==0 && r_val!=0: select infinity (negated points)
+ *   4. If qz==0: select p (q was infinity)
+ *   5. If pz==0: select q (p was infinity)
  */
 void jp_add_internal(uint256_t r[3], const uint256_t p[3], const uint256_t q[3])
 {
-    /* Handle point-at-infinity cases (pz == 0 or qz == 0).
-     * These branch on public data (Z coordinates are public in all call paths). */
-    if (uint256_is_zero(&p[2])) {
-        r[0] = q[0]; r[1] = q[1]; r[2] = q[2];
-        return;
-    }
-    if (uint256_is_zero(&q[2])) {
-        r[0] = p[0]; r[1] = p[1]; r[2] = p[2];
-        return;
-    }
-
+    /* Save copies of inputs for the final mask-based selects, since r may
+     * alias p or q (e.g. jp_add_internal(r1, r0, r1) in the Montgomery ladder).
+     * Writing the normal result into r[] would corrupt the source otherwise. */
+    uint256_t p_copy[3], q_copy[3];
+    memcpy(p_copy, p, sizeof(uint256_t) * 3);
+    memcpy(q_copy, q, sizeof(uint256_t) * 3);
+
+    /* 1. Capture input-dependent flags (evaluated once, used only in selects). */
+    uint64_t pz_zero = uint256_is_zero(&p[2]);
+    uint64_t qz_zero = uint256_is_zero(&q[2]);
+
+    /* 2. Compute all 18 field operations unconditionally. */
     uint256_t z1z1, z2z2;
     uint256_t u1, u2;
     uint256_t s1, s2;
@@ -199,21 +216,8 @@ void jp_add_internal(uint256_t r[3], const uint256_t p[3], const uint256_t q[3])
     fsub_internal(&h, &u2, &u1);
     fsub_internal(&r_val, &s2, &s1);
 
-    /* Handle the h == 0 special cases.
-     * h == 0 means the points have the same X (in affine).
-     * r == 0 additionally means the same Y → equal points → double.
-     * r != 0 means opposite Y → additive inverse → infinity. */
-    if (uint256_is_zero(&h)) {
-        if (uint256_is_zero(&r_val)) {
-            jp_double_internal(r, p);
-        } else {
-            r[0] = JP_INF_X;
-            r[1] = JP_INF_Y;
-            r[2] = JP_INF_Z;
-        }
-        return;
-    }
-
+    /* 3. Remaining field ops for the normal addition path.
+     *    When h==0 these produce h2=0, h3=0, z3=0 — valid field elements. */
     uint256_t h2, h3, v, x3, y3, z3;
 
     /* h2 = h²,  h3 = h * h2 */
@@ -241,9 +245,48 @@ void jp_add_internal(uint256_t r[3], const uint256_t p[3], const uint256_t q[3])
     fmul_internal(&tmp, &p[2], &q[2]);
     fmul_internal(&z3, &h, &tmp);
 
+    /* 4. Compute jp_double unconditionally for the h==0 && r_val==0 case.
+     *    Uses p_copy since r may alias p. */
+    uint256_t dbl[3];
+    jp_double_internal(dbl, p_copy);
+
+    /* 5. Capture remaining flags for mask-based selection. */
+    uint64_t h_zero = uint256_is_zero(&h);
+    uint64_t r_zero = uint256_is_zero(&r_val);
+
+    /* 6. Branchless result selection — order matters (later overrides earlier).
+     *
+     * Start with the normal addition result, then overlay special cases.
+     * Each uint256_select replaces r[i] only when the flag is non-zero. */
+
+    /* Start with normal addition result. */
     r[0] = x3;
     r[1] = y3;
     r[2] = z3;
+
+    /* If h==0 && r_val==0: points are equal → use jp_double result. */
+    uint64_t select_dbl = h_zero & r_zero;
+    uint256_select(&r[0], &r[0], &dbl[0], select_dbl);
+    uint256_select(&r[1], &r[1], &dbl[1], select_dbl);
+    uint256_select(&r[2], &r[2], &dbl[2], select_dbl);
+
+    /* If h==0 && r_val!=0: points are negatives → result is infinity. */
+    uint64_t select_inf = h_zero & (~r_zero & 1);
+    uint256_select(&r[0], &r[0], &JP_INF_X, select_inf);
+    uint256_select(&r[1], &r[1], &JP_INF_Y, select_inf);
+    uint256_select(&r[2], &r[2], &JP_INF_Z, select_inf);
+
+    /* If qz==0: q was infinity → result is p.
+     * Uses p_copy since r may alias p. */
+    uint256_select(&r[0], &r[0], &p_copy[0], qz_zero);
+    uint256_select(&r[1], &r[1], &p_copy[1], qz_zero);
+    uint256_select(&r[2], &r[2], &p_copy[2], qz_zero);
+
+    /* If pz==0: p was infinity → result is q.
+     * Uses q_copy since r may alias q. */
+    uint256_select(&r[0], &r[0], &q_copy[0], pz_zero);
+    uint256_select(&r[1], &r[1], &q_copy[1], pz_zero);
+    uint256_select(&r[2], &r[2], &q_copy[2], pz_zero);
 }
 
 /*
@@ -399,11 +442,10 @@ void scalar_multiply_ct_internal(uint256_t r[3], const uint256_t *k, const uint2
  * Constant-time scalar multiplication using the Montgomery ladder.
  *
  * Computes k × (px, py) entirely in C with no per-iteration Ruby dispatch.
- * The ladder loop is branchless with respect to the scalar bits (via cswap).
- * Note: jp_add_internal still branches on infinity/collision edge cases,
- * so full constant-time depends on the point operations being hardened
- * separately.  The k==0 early return is on a non-secret value (k==0 is
- * never a valid private key or nonce).
+ * The ladder loop is branchless with respect to the scalar bits (via cswap),
+ * and jp_add_internal is fully branchless (mask-based selects for all
+ * input-dependent special cases).  The k==0 early return is on a non-secret
+ * value (k==0 is never a valid private key or nonce).
  *
  * @param k  [Integer] scalar (must be in [0, N))
  * @param px [Integer] affine x-coordinate of the base point

data/ext/secp256k1_native/secp256k1_native.h

@@ -103,6 +103,21 @@ void scalar_inv_internal(uint256_t *r, const uint256_t *a);
 /* Registration helper — called from Init_secp256k1_native. */
 void register_scalar_methods(VALUE mod);
 
+/* -----------------------------------------------------------------------
+ * Branchless selection helper
+ * ----------------------------------------------------------------------- */
+
+/* Branchless conditional select: if flag is non-zero, *r = *b; else *r = *a.
+ * Constant-time: no branch on flag. */
+static inline void uint256_select(uint256_t *r, const uint256_t *a,
+                                   const uint256_t *b, uint64_t flag) {
+    uint64_t mask = -(uint64_t)(flag != 0);
+    r->d[0] = (a->d[0] & ~mask) | (b->d[0] & mask);
+    r->d[1] = (a->d[1] & ~mask) | (b->d[1] & mask);
+    r->d[2] = (a->d[2] & ~mask) | (b->d[2] & mask);
+    r->d[3] = (a->d[3] & ~mask) | (b->d[3] & mask);
+}
+
 /* -----------------------------------------------------------------------
  * Jacobian point operations — internal functions declared here so that
  * future modules (e.g. a scalar multiply module) can call them directly

data/lib/secp256k1/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Secp256k1
-  VERSION = '0.15.0'
+  VERSION = '0.17.0'
 end

data/lib/secp256k1.rb

@@ -19,6 +19,32 @@ require_relative 'secp256k1/version'
 # All field operations work on plain Ruby +Integer+ values (arbitrary
 # precision, C-backed in MRI). No external gems required.
 module Secp256k1
+  # Raised when a constant-time operation is attempted without the native
+  # C extension loaded. The pure-Ruby implementation cannot guarantee
+  # constant-time execution due to interpreter-introduced timing variability.
+  class InsecureOperationError < SecurityError; end
+
+  # Whether the native C extension is loaded and active.
+  #
+  # @return [Boolean]
+  def self.native?
+    @native == true
+  end
+
+  # Explicitly allow constant-time operations in pure-Ruby mode.
+  # Call this only after evaluating the risks documented in docs/risks.md.
+  def self.allow_pure_ruby_ct!
+    @allow_pure_ruby_ct = true
+  end
+
+  # @api private
+  def self.pure_ruby_ct_allowed?
+    @allow_pure_ruby_ct || ENV.key?('SECP256K1_ALLOW_PURE_RUBY_CT')
+  end
+
+  @native = false
+  @allow_pure_ruby_ct = false
+
   # The secp256k1 field prime: p = 2^256 - 2^32 - 977
   P = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F
 
@@ -510,41 +536,58 @@ module Secp256k1
       end
     end
 
-    # Scalar multiplication: self * scalar (variable-time, wNAF).
+    # Scalar multiplication: self * scalar (constant-time, Montgomery ladder).
+    #
+    # Processes all 256 bits unconditionally so execution time does not
+    # depend on the scalar value. Safe for both secret and public scalars.
+    # This is the default because the safe path should be the easy path.
     #
-    # Suitable for public scalars only (e.g. signature verification).
-    # For secret-scalar paths use {#mul_ct}.
+    # For performance-critical public-scalar paths (e.g. batch verification)
+    # where constant-time is unnecessary, use {#mul_vt}.
+    #
+    # Raises {InsecureOperationError} if the native C extension is not loaded,
+    # unless explicitly allowed via {Secp256k1.allow_pure_ruby_ct!} or the
+    # +SECP256K1_ALLOW_PURE_RUBY_CT+ environment variable.
     #
     # @param scalar [Integer] the scalar multiplier
     # @return [Point] the resulting point
     def mul(scalar)
+      unless Secp256k1.native? || Secp256k1.pure_ruby_ct_allowed?
+        raise Secp256k1::InsecureOperationError,
+              'mul requires the native C extension for constant-time guarantees. ' \
+              'Set SECP256K1_ALLOW_PURE_RUBY_CT=1 or call Secp256k1.allow_pure_ruby_ct! to override.'
+      end
+
       return self.class.infinity if scalar.zero? || infinity?
 
       scalar %= N
       return self.class.infinity if scalar.zero?
 
-      jp = Secp256k1.scalar_multiply_wnaf(scalar, @x, @y)
+      jp = Secp256k1.scalar_multiply_ct(scalar, @x, @y)
       affine = Secp256k1.jp_to_affine(jp)
       return self.class.infinity if affine.nil?
 
       self.class.new(affine[0], affine[1])
     end
 
-    # Constant-time scalar multiplication: self * scalar (Montgomery ladder).
+    # @deprecated Use {#mul} instead. Alias retained for backward compatibility.
+    alias mul_ct mul
+
+    # Variable-time scalar multiplication: self * scalar (wNAF).
     #
-    # Processes all 256 bits unconditionally so execution time does not
-    # depend on the scalar value. Use this for secret-scalar paths:
-    # key generation, signing, and ECDH shared-secret derivation.
+    # Faster than {#mul} but leaks timing information about the scalar.
+    # Use only when the scalar is public (e.g. signature verification,
+    # computing known generator multiples). Never use with secret scalars.
     #
-    # @param scalar [Integer] the secret scalar multiplier
+    # @param scalar [Integer] the public scalar multiplier
     # @return [Point] the resulting point
-    def mul_ct(scalar)
+    def mul_vt(scalar)
       return self.class.infinity if scalar.zero? || infinity?
 
       scalar %= N
       return self.class.infinity if scalar.zero?
 
-      jp = Secp256k1.scalar_multiply_ct(scalar, @x, @y)
+      jp = Secp256k1.scalar_multiply_wnaf(scalar, @x, @y)
       affine = Secp256k1.jp_to_affine(jp)
       return self.class.infinity if affine.nil?
 
@@ -619,8 +662,13 @@ module Secp256k1
        jp_double jp_add jp_neg scalar_multiply_ct].each do |m|
       singleton_class.define_method(m, Secp256k1Native.method(m).to_proc)
     end
+
+    @native = true
   rescue LoadError
-    # Extension not compiled — pure-Ruby fallback, no action needed.
+    # Extension not compiled — pure-Ruby fallback.
+    warn '[secp256k1-native] Native C extension not loaded — falling back to pure Ruby. ' \
+         'Constant-time operations (mul_ct) will raise unless explicitly allowed. ' \
+         'See: https://sgbett.github.io/secp256k1-native/risks/'
   end
 end
 # rubocop:enable Naming/MethodParameterName, Metrics/ModuleLength

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: secp256k1-native
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Simon Bettison