secp256k1-native 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3721e2220de6d65f6bda10fe26a47bd2eaa248ba5d645caf70a0e40901720268
-  data.tar.gz: e07a7c79de6e4055581fd4a009dd48c375f7deb722bd2a18f5b99e9c444341ef
+  metadata.gz: e99016475f085f293dea746296947233bc59879e7e5b864da191ac9760ec665b
+  data.tar.gz: 409aac96468c5557951cb754a8bb0e9fd49e16b7526fdb31b22cb8441b2b2d85
 SHA512:
-  metadata.gz: a5b109ef38d0589630ac73eab3ff5b910e2592926fe949aea7c12c4b9285dc94242ebfb449075276666806c659c32e7366cd61e3f43bb3bbd6a12d848ec12330
-  data.tar.gz: 4298a51739c11a6a5d01231fcf9274f1bfcdd7a93518b2920c255b8361f10bdf25c5e0c85e2c080a11380c55f4382b6980cc7a90d0eaab6f2f06b518c64da91f
+  metadata.gz: 8fd3c3f89628724cfbad9866ba636c131350fcbf4977016d63eb4ec0c18568a037be17af63ff792981a49c74915942291384afc25989a097d31f6056f3fe4b0e
+  data.tar.gz: ac8290a66020b4ba4d5e0f4f77228bee25bf984eb517997b3178b4b51b165cf88a905c489bd429bc68a214d052bf56f412e27588ab07d434512a582c576fe47b

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [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/lib/secp256k1/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Secp256k1
-  VERSION = '0.15.0'
+  VERSION = '0.16.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.16.0
 platform: ruby
 authors:
 - Simon Bettison