jwt-pq 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc80be78087261982368d78df297e89720290aa2c1252ed7b3b1f44298dd4856
-  data.tar.gz: f4c95127b8f0aab465029c1eedff1e0ef37c6e1342348f3286bc396e26ef6961
+  metadata.gz: d662c64af196cc33ed4b288a641442317fe49881eef85bfadc2385c0bee7e63f
+  data.tar.gz: 599a753241ae95a168461d1a7f61b2a2b2147da13f1456479758873657fb18f5
 SHA512:
-  metadata.gz: 3498399528c54d624c93ca00f1c6a884cb6db6591dd861cc26409aa58502a8ecf1ae1bd6901c7fb5b8d1ebe44cd5462661757b299dc8f7127100b60d9153d5ed
-  data.tar.gz: 22a25bf0c7f3562f226a88832dba44ee164964328dcf2c2841a0c6ea286a585bd7f85c5237d5356d6272fc1ff3ef1ca3cf63f5b4057e91ef8895a22a2d75ff3b
+  metadata.gz: c360bb8b3b5a8fdad530e3cba2f6d3630999d635669d85e5ac57854f746bbf8250559073d258ca2aa95f0f443208aded8c90b68a15f75f58a00370963fa5c943
+  data.tar.gz: e57d739e3567413f845a685caf55305d7704120fee29adf31ab09cbb0a85cbc2b6c0713ad4e85db73c65c1238d323ab04ab5e079adef06f2918a2114fb06aa96

data/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-19
+
+### Added
+
+- Hybrid-sign throughput benchmark at `bench/hybrid_sign_throughput.rb`
+- Hybrid-verify throughput benchmark at `bench/hybrid_verify_throughput.rb`
+- Parameterized `bench/sign_throughput.rb` and `bench/verify_throughput.rb` via `ALG` env var — previously hardcoded to `ML-DSA-65`, now supports all three security levels
+- PEM key fixtures for ML-DSA-44 and ML-DSA-87 under `bench/fixtures/`
+- `bench/generate_fixtures.rb` to regenerate bench fixtures idempotently
+- Cross-implementation interop CI against `dilithium-py` (independent pure-Python ML-DSA / FIPS 204 implementation) — runs on push, PR, and weekly
+
+### Changed
+
+- **Hybrid EdDSA+ML-DSA-65 sign throughput: +12.1%** (5200 → 5831 sigs/s on Ruby 3.4.6 + liboqs 0.15.0). Inline type-check in `HybridEdDsa#sign` (+1.6%) plus cached frozen header hash and precomputed `ml_dsa_algorithm` at init (+10.4%) — `#header` is called once per `JWT.encode`, so eliminating the per-call Hash allocation and `String#sub` compounds noticeably.
+- **Hybrid EdDSA+ML-DSA-65 verify throughput: +2.3%** (4812 → 4923 verifies/s). Inline type-check in `HybridEdDsa#verify`, mirroring the sign-side pattern.
+- `bench/` directory no longer packaged into the published gem (smaller install footprint).
+
+### Benchmarks
+
+Throughput on Ruby 3.4.6, macOS x86_64, liboqs 0.15.0 (benchmark-ips, 2s warmup + 5s measurement):
+
+| Algorithm  |      Sign |     Verify |
+|------------|----------:|-----------:|
+| ML-DSA-44  |  9678 ops/s  | 12650 ops/s |
+| ML-DSA-65  |  6236 ops/s  |  8567 ops/s |
+| ML-DSA-87  |  3591 ops/s  |  6510 ops/s |
+
+## [0.3.0] - 2026-04-19
+
+### Added
+
+- Sign-throughput benchmark at `bench/sign_throughput.rb` with a fixed PEM key fixture (`bench/fixtures/ml_dsa_65_sk.pem`), driven by `benchmark-ips`
+- Verify-throughput benchmark at `bench/verify_throughput.rb`
+- NIST ACVP sigVer KAT tests at `spec/jwt/pq/kat_spec.rb` — external interface, pure ML-DSA, empty context; covers ML-DSA-44, ML-DSA-65, and ML-DSA-87 with both passing and known-bad signatures as a canonical correctness gate
+- `JWT::PQ::MlDsa#sign_with_sk_buffer` and `#verify_with_pk_buffer` — fast paths that accept pre-populated FFI buffers. The existing bytes-in `#sign` / `#verify` APIs are unchanged
+
+### Changed
+
+- **ML-DSA signing throughput: +2.6%** (from 6676 to 6849 sigs/s on Ruby 3.4.6 + liboqs 0.15.0 for ML-DSA-65). Class-level cache of the `OQS_SIG` handle per algorithm avoids `OQS_SIG_new`/`OQS_SIG_free` per call; per-`Key` memoization of the secret-key FFI buffer avoids a 4032-byte allocation + copy per sign
+- **ML-DSA verification throughput: +19.4%** (from 7995 to 9548 verifies/s on the same setup for ML-DSA-65). Class-level cache of the `OQS_SIG` handle for verify; per-`Key` memoization of the public-key FFI buffer; inlined type-check in the JWA verify entry point. `Key#verify` now reaches 93% of the raw `OQS_SIG_verify` ceiling; remaining overhead lives inside `ruby-jwt`
+- `Key#destroy!` now also zeroes the cached secret-key FFI buffer (`@sk_buffer`) in addition to `@private_key`, preserving the secure-erase contract after the buffer memoization
+
+### Dependencies
+
+- Add `benchmark-ips ~> 2.14` as a development/test dependency (powers the bench harnesses)
+- Bump `ruby/setup-ruby` from 1.299.0 to 1.301.0 (#2)
+
 ## [0.2.0] - 2026-04-06
 
 ### Added
@@ -56,6 +103,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Optional dependency on jwt-eddsa / ed25519
 - Error classes: `LiboqsError`, `KeyError`, `SignatureError`, `MissingDependencyError`
 
-[Unreleased]: https://github.com/marcelopazzo/jwt-pq/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/marcelopazzo/jwt-pq/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/marcelopazzo/jwt-pq/releases/tag/v0.1.0

data/Gemfile

@@ -5,6 +5,7 @@ source "https://rubygems.org"
 gemspec
 
 group :development, :test do
+  gem "benchmark-ips", "~> 2.14"
   gem "rake"
   gem "rspec", "~> 3.13"
   gem "rubocop", "~> 1.75"

data/README.md

@@ -2,6 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/jwt-pq.svg)](https://rubygems.org/gems/jwt-pq)
 [![CI](https://github.com/marcelopazzo/jwt-pq/actions/workflows/ci.yml/badge.svg)](https://github.com/marcelopazzo/jwt-pq/actions/workflows/ci.yml)
+[![Cross-interop](https://github.com/marcelopazzo/jwt-pq/actions/workflows/interop.yml/badge.svg)](https://github.com/marcelopazzo/jwt-pq/actions/workflows/interop.yml)
 [![codecov](https://codecov.io/gh/marcelopazzo/jwt-pq/graph/badge.svg)](https://codecov.io/gh/marcelopazzo/jwt-pq)
 
 Post-quantum JWT signatures for Ruby. Adds **ML-DSA** (FIPS 204) support to the [ruby-jwt](https://github.com/jwt/ruby-jwt) ecosystem, with an optional **hybrid EdDSA + ML-DSA** mode.

data/jwt-pq.gemspec

@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
 
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
-      f.start_with?("spec/", "vendor/", ".github/") ||
+      f.start_with?("spec/", "vendor/", ".github/", "bench/") ||
         f.match?(/\A(?:\.git|\.rspec|\.rubocop|jwt-pq-plan)/)
     end
   end

data/lib/jwt/pq/algorithms/hybrid_eddsa.rb

@@ -17,24 +17,36 @@ module JWT
 
         def initialize(alg)
           @alg = alg
+          @ml_dsa_algorithm = alg.sub("EdDSA+", "")
+          @header = { "alg" => alg, "pq_alg" => @ml_dsa_algorithm }.freeze
         end
 
         def header(*)
-          { "alg" => alg, "pq_alg" => ml_dsa_algorithm }
+          @header
         end
 
         def sign(data:, signing_key:)
-          key = resolve_signing_key(signing_key)
+          unless signing_key.is_a?(JWT::PQ::HybridKey)
+            raise_sign_error!(
+              "Expected a JWT::PQ::HybridKey, got #{signing_key.class}. " \
+              "Use JWT::PQ::HybridKey.generate to create a hybrid key."
+            )
+          end
+          raise_sign_error!("Both Ed25519 and ML-DSA private keys required") unless signing_key.private?
 
-          ed_sig = key.ed25519_signing_key.sign(data)
-          ml_sig = key.ml_dsa_key.sign(data)
+          ed_sig = signing_key.ed25519_signing_key.sign(data)
+          ml_sig = signing_key.ml_dsa_key.sign(data)
 
           # Concatenate: Ed25519 (64 bytes) || ML-DSA (variable)
           ed_sig + ml_sig
         end
 
         def verify(data:, signature:, verification_key:)
-          key = resolve_verification_key(verification_key)
+          unless verification_key.is_a?(JWT::PQ::HybridKey)
+            raise_verify_error!(
+              "Expected a JWT::PQ::HybridKey, got #{verification_key.class}."
+            )
+          end
 
           return false if signature.bytesize <= ED25519_SIG_SIZE
 
@@ -42,13 +54,13 @@ module JWT
           ml_sig = signature.byteslice(ED25519_SIG_SIZE..)
 
           ed_valid = begin
-            key.ed25519_verify_key.verify(ed_sig, data)
+            verification_key.ed25519_verify_key.verify(ed_sig, data)
             true
           rescue Ed25519::VerifyError
             false
           end
 
-          ml_valid = key.ml_dsa_key.verify(data, ml_sig)
+          ml_valid = verification_key.ml_dsa_key.verify(data, ml_sig)
 
           ed_valid && ml_valid
         rescue JWT::PQ::Error
@@ -57,9 +69,7 @@ module JWT
 
         private
 
-        def ml_dsa_algorithm
-          alg.sub("EdDSA+", "")
-        end
+        attr_reader :ml_dsa_algorithm
 
         def resolve_signing_key(key)
           case key

data/lib/jwt/pq/algorithms/ml_dsa.rb

@@ -20,8 +20,13 @@ module JWT
         end
 
         def verify(data:, signature:, verification_key:)
-          key = resolve_verification_key(verification_key)
-          key.verify(data, signature)
+          unless verification_key.is_a?(JWT::PQ::Key)
+            raise_verify_error!(
+              "Expected a JWT::PQ::Key, got #{verification_key.class}. " \
+              "Use JWT::PQ::Key.generate(:#{alg_symbol}) to create a key."
+            )
+          end
+          verification_key.verify(data, signature)
         rescue JWT::PQ::Error
           false
         end

data/lib/jwt/pq/key.rb

@@ -6,7 +6,7 @@ module JWT
   module PQ
     # Represents an ML-DSA keypair (public + optional private key).
     # Used as the signing/verification key for JWT operations.
-    class Key
+    class Key # rubocop:disable Metrics/ClassLength
       ALGORITHM_ALIASES = {
         ml_dsa_44: "ML-DSA-44",
         ml_dsa_65: "ML-DSA-65",
@@ -50,12 +50,12 @@ module JWT
       def sign(data)
         raise KeyError, "Private key not available — cannot sign" unless @private_key
 
-        @ml_dsa.sign(data, @private_key)
+        @ml_dsa.sign_with_sk_buffer(data, sk_buffer)
       end
 
       # Verify a signature using the public key.
       def verify(data, signature)
-        @ml_dsa.verify(data, signature, @public_key)
+        @ml_dsa.verify_with_pk_buffer(data, signature, pk_buffer)
       end
 
       # Whether this key can be used for signing.
@@ -70,6 +70,8 @@ module JWT
           @private_key.replace("\0" * @private_key.bytesize)
           @private_key = nil
         end
+        @sk_buffer&.clear
+        @sk_buffer = nil
         true
       end
 
@@ -153,6 +155,14 @@ module JWT
 
       private
 
+      def sk_buffer
+        @sk_buffer ||= FFI::MemoryPointer.new(:uint8, @private_key.bytesize).put_bytes(0, @private_key)
+      end
+
+      def pk_buffer
+        @pk_buffer ||= FFI::MemoryPointer.new(:uint8, @public_key.bytesize).put_bytes(0, @public_key)
+      end
+
       def resolve_algorithm(algorithm)
         self.class.send(:resolve_algorithm, algorithm)
       end

data/lib/jwt/pq/ml_dsa.rb

@@ -11,6 +11,34 @@ module JWT
         "ML-DSA-87" => { public_key: 2592, secret_key: 4896, signature: 4627, nist_level: 5 }
       }.freeze
 
+      @sign_handles = {}
+      @sign_handles_mutex = Mutex.new
+
+      def self.sign_handle(algorithm)
+        @sign_handles[algorithm] || @sign_handles_mutex.synchronize do
+          @sign_handles[algorithm] ||= begin
+            h = LibOQS.OQS_SIG_new(algorithm)
+            raise LiboqsError, "Failed to initialize #{algorithm}" if h.null?
+
+            h
+          end
+        end
+      end
+
+      @verify_handles = {}
+      @verify_handles_mutex = Mutex.new
+
+      def self.verify_handle(algorithm)
+        @verify_handles[algorithm] || @verify_handles_mutex.synchronize do
+          @verify_handles[algorithm] ||= begin
+            h = LibOQS.OQS_SIG_new(algorithm)
+            raise LiboqsError, "Failed to initialize #{algorithm}" if h.null?
+
+            h
+          end
+        end
+      end
+
       attr_reader :algorithm
 
       def initialize(algorithm)
@@ -48,24 +76,28 @@ module JWT
       def sign(message, secret_key)
         validate_key_size!(secret_key, :secret_key)
 
-        sig = LibOQS.OQS_SIG_new(@algorithm)
-        raise LiboqsError, "Failed to initialize #{@algorithm}" if sig.null?
+        sk_buf = FFI::MemoryPointer.new(:uint8, secret_key.bytesize)
+        sk_buf.put_bytes(0, secret_key)
+        sign_with_sk_buffer(message, sk_buf)
+      ensure
+        sk_buf&.clear
+      end
 
+      # Faster sign path: takes a pre-populated FFI::MemoryPointer holding the
+      # secret key. Caller is responsible for buffer lifecycle (allocation,
+      # zeroing). Used by JWT::PQ::Key to avoid re-allocating+copying the
+      # secret key on every sign call.
+      def sign_with_sk_buffer(message, sk_buf)
+        sig = self.class.sign_handle(@algorithm)
         sig_buf = FFI::MemoryPointer.new(:uint8, @sizes[:signature])
         sig_len = FFI::MemoryPointer.new(:size_t)
         msg_buf = FFI::MemoryPointer.from_string(message)
-        sk_buf = FFI::MemoryPointer.new(:uint8, secret_key.bytesize)
-        sk_buf.put_bytes(0, secret_key)
 
         status = LibOQS.OQS_SIG_sign(sig, sig_buf, sig_len,
                                      msg_buf, message.bytesize, sk_buf)
         raise SignatureError, "Signing failed for #{@algorithm}" unless status == LibOQS::OQS_SUCCESS
 
-        actual_len = sig_len.read(:size_t)
-        sig_buf.read_bytes(actual_len)
-      ensure
-        sk_buf&.clear
-        LibOQS.OQS_SIG_free(sig) if sig && !sig.null?
+        sig_buf.read_bytes(sig_len.read(:size_t))
       end
 
       # Verify a signature against a message and public key.
@@ -73,20 +105,24 @@ module JWT
       def verify(message, signature, public_key)
         validate_key_size!(public_key, :public_key)
 
-        sig = LibOQS.OQS_SIG_new(@algorithm)
-        raise LiboqsError, "Failed to initialize #{@algorithm}" if sig.null?
+        pk_buf = FFI::MemoryPointer.new(:uint8, public_key.bytesize)
+        pk_buf.put_bytes(0, public_key)
+        verify_with_pk_buffer(message, signature, pk_buf)
+      end
 
+      # Faster verify path: takes a pre-populated FFI::MemoryPointer holding
+      # the public key. Caller is responsible for buffer lifecycle. Used by
+      # JWT::PQ::Key to avoid re-allocating+copying the public key on every
+      # verify call.
+      def verify_with_pk_buffer(message, signature, pk_buf)
+        sig = self.class.verify_handle(@algorithm)
         msg_buf = FFI::MemoryPointer.from_string(message)
         sig_buf = FFI::MemoryPointer.new(:uint8, signature.bytesize)
         sig_buf.put_bytes(0, signature)
-        pk_buf = FFI::MemoryPointer.new(:uint8, public_key.bytesize)
-        pk_buf.put_bytes(0, public_key)
 
         status = LibOQS.OQS_SIG_verify(sig, msg_buf, message.bytesize,
                                        sig_buf, signature.bytesize, pk_buf)
         status == LibOQS::OQS_SUCCESS
-      ensure
-        LibOQS.OQS_SIG_free(sig) if sig && !sig.null?
       end
 
       # Key sizes for this algorithm

data/lib/jwt/pq/version.rb

@@ -2,6 +2,6 @@
 
 module JWT
   module PQ
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jwt-pq
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Marcelo Almeida