ml_dsa 0.1.0

data/lib/ml_dsa.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require_relative "ml_dsa/version"
+require "ml_dsa/ml_dsa_ext"
+require "pqc_asn1"
+
+require_relative "ml_dsa/config"
+require_relative "ml_dsa/parameter_set"
+require_relative "ml_dsa/internal"
+require_relative "ml_dsa/requests"
+require_relative "ml_dsa/key_pair"
+require_relative "ml_dsa/public_key"
+require_relative "ml_dsa/secret_key"
+require_relative "ml_dsa/batch_builder"
+
+module MlDsa
+  # Seed size (bytes) for deterministic key generation.
+  SEED_BYTES = 32
+
+  # The default global Config instance.
+  # @return [Config]
+  def self.config
+    @config
+  end
+
+  @config = Config.new
+
+  # -----------------------------------------------------------------------
+  # Convenience delegators — keep the existing top-level API working
+  # -----------------------------------------------------------------------
+
+  # Subscribe to instrumentation events on the default config.
+  # @see Config#subscribe
+  def self.subscribe(&block)
+    @config.subscribe(&block)
+  end
+
+  # Remove a subscriber from the default config.
+  # @see Config#unsubscribe
+  def self.unsubscribe(subscriber)
+    @config.unsubscribe(subscriber)
+  end
+
+  # @return [Proc, nil] the current random source on the default config
+  def self.random_source
+    @config.random_source
+  end
+
+  # Set the random source on the default config.
+  # @param source [Proc, nil]
+  def self.random_source=(source)
+    @config.random_source = source
+  end
+
+  # -----------------------------------------------------------------------
+  # Module-level API
+  # -----------------------------------------------------------------------
+
+  class << self
+    # Generate a key pair for the given parameter set.
+    #
+    # @param param_set [ParameterSet] ML_DSA_44, ML_DSA_65, or ML_DSA_87
+    # @param seed [String, nil] optional 32-byte seed for deterministic keygen
+    # @param config [Config] configuration (default: MlDsa.config)
+    # @return [KeyPair] frozen key pair (supports destructuring: +pk, sk = keygen(...)+)
+    # @raise [TypeError] if param_set is not a ParameterSet
+    # @raise [ArgumentError] if seed is not exactly 32 bytes
+    def keygen(param_set, seed: nil, config: nil)
+      cfg = config || @config
+      ps = Internal.resolve_ps(param_set)
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+      if seed
+        raise TypeError, "seed must be a String" unless seed.is_a?(String)
+        seed_bin = seed.b
+        raise ArgumentError, "seed must be exactly 32 bytes, got #{seed_bin.bytesize}" unless seed_bin.bytesize == 32
+        pk, sk = _keygen_seed(ps.code, seed_bin)
+      elsif cfg.random_source
+        # Pluggable RNG: generate a seed and use deterministic keygen
+        rng_seed = cfg.random_source.call(SEED_BYTES)
+        unless rng_seed.is_a?(String) && rng_seed.bytesize == SEED_BYTES
+          raise ArgumentError,
+            "random_source must return #{SEED_BYTES} bytes, " \
+            "got #{rng_seed.is_a?(String) ? rng_seed.bytesize : rng_seed.class}"
+        end
+        pk, sk = _keygen_seed(ps.code, rng_seed.b)
+      else
+        pk, sk = _keygen(ps.code)
+      end
+      now = Time.now.freeze
+      pk.instance_variable_set(:@created_at, now)
+      sk.instance_variable_set(:@created_at, now)
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - t0
+      cfg.notify(:keygen, ps, 1, duration)
+      KeyPair.new(pk, sk)
+    end
+
+    # Sign multiple messages in a single GVL drop.
+    #
+    # @param operations [Array<SignRequest>]
+    # @param config [Config] configuration (default: MlDsa.config)
+    # @param yield_every [Integer] yield to the fiber scheduler every N items
+    #   during the normalization loop (0 = never, default)
+    # @return [Array<String>] frozen array of frozen binary signature strings
+    def sign_many(operations, config: nil, yield_every: Internal::DEFAULT_YIELD_EVERY)
+      cfg = config || @config
+      unless operations.is_a?(Array)
+        raise TypeError, "operations must be an Array, got #{operations.class}"
+      end
+      return [].freeze if operations.empty?
+      ops = operations.each_with_index.map do |op, i|
+        Internal.maybe_yield(i, yield_every)
+        normalize_sign_op(op, i, cfg)
+      end
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+      result = _sign_many(ops)
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - t0
+      ps = operations.first&.sk&.param_set
+      cfg.notify(:sign, ps, operations.size, duration)
+      result
+    end
+
+    # Verify multiple signatures in a single GVL drop.
+    #
+    # Returns {Result} objects with per-item details: +.ok?+ indicates
+    # success, +.reason+ distinguishes wrong-size signatures from
+    # cryptographic verification failures.
+    #
+    # @param operations [Array<VerifyRequest>]
+    # @param config [Config] configuration (default: MlDsa.config)
+    # @param yield_every [Integer] yield to the fiber scheduler every N items
+    #   during the normalization loop (0 = never, default)
+    # @return [Array<Result>] frozen array of Result objects
+    def verify_many(operations, config: nil, yield_every: Internal::DEFAULT_YIELD_EVERY)
+      cfg = config || @config
+      unless operations.is_a?(Array)
+        raise TypeError, "operations must be an Array, got #{operations.class}"
+      end
+      return [].freeze if operations.empty?
+      # Pre-check signature sizes to distinguish size errors from crypto failures
+      size_ok = operations.map do |op|
+        Internal.resolve_ps(op.pk.param_set)
+        op.signature.bytesize == op.pk.param_set.signature_bytes
+      end
+      ops = operations.each_with_index.map do |op, i|
+        Internal.maybe_yield(i, yield_every)
+        normalize_verify_op(op, i)
+      end
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+      bools = _verify_many(ops)
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - t0
+      ps = operations.first&.pk&.param_set
+      cfg.notify(:verify, ps, operations.size, duration)
+      results = operations.each_with_index.map do |op, i|
+        if bools[i]
+          Result.new(value: true, ok: true, reason: nil)
+        elsif !size_ok[i]
+          expected = op.pk.param_set.signature_bytes
+          Result.new(value: false, ok: false,
+            reason: "wrong_signature_size: expected #{expected}, got #{op.signature.bytesize}")
+        else
+          Result.new(value: false, ok: false, reason: "verification_failed")
+        end
+      end
+      results.freeze
+    end
+
+    # Unified batch builder — collects sign/verify ops and executes them
+    # in a single GVL drop.
+    #
+    # @example Batch signing
+    #   sigs = MlDsa.batch { |b| b.sign(sk: sk, message: msg) }
+    #
+    # @example Batch verification
+    #   results = MlDsa.batch { |b| b.verify(pk: pk, message: msg, signature: sig) }
+    #
+    # @yield [BatchBuilder]
+    # @return [Array<String>] for sign batches, [Array<Result>] for verify batches
+    # @raise [ArgumentError] if the batch mixes sign and verify operations
+    def batch(config: nil, yield_every: Internal::DEFAULT_YIELD_EVERY)
+      cfg = config || @config
+      builder = BatchBuilder.new
+      yield builder
+      builder.execute(config: cfg, yield_every: yield_every)
+    end
+
+    private
+
+    # Returns a flat 5-element array [sk, message, ctx, det, rnd_or_nil].
+    # Flat arrays avoid per-item Hash allocation in the Ruby→C boundary.
+    # Position constants are in Internal::SIGN_OP_*.
+    def normalize_sign_op(op, idx, cfg)
+      unless op.is_a?(SignRequest)
+        raise TypeError,
+          "sign_many: item #{idx} must be a SignRequest, got #{op.class}"
+      end
+      op.validate!
+      rnd = nil
+      rng = cfg.random_source
+      if !op.deterministic && rng
+        rnd = rng.call(Internal::RND_BYTES)
+        unless rnd.is_a?(String) && rnd.bytesize == Internal::RND_BYTES
+          raise ArgumentError,
+            "random_source must return #{Internal::RND_BYTES} bytes, " \
+            "got #{rnd.is_a?(String) ? rnd.bytesize : rnd.class}"
+        end
+      end
+      [op.sk, op.message, op.context, op.deterministic, rnd]
+    end
+
+    # Returns a flat 4-element array [pk, message, signature, ctx_or_nil].
+    # Position constants are in Internal::VERIFY_OP_*.
+    def normalize_verify_op(op, idx)
+      unless op.is_a?(VerifyRequest)
+        raise TypeError,
+          "verify_many: item #{idx} must be a VerifyRequest, got #{op.class}"
+      end
+      op.validate!
+      [op.pk, op.message, op.signature, op.context]
+    end
+
+    # Look up the ParameterSet whose signature size matches +n+ bytes.
+    # @param n [Integer] signature byte count
+    # @return [ParameterSet]
+    # @raise [ArgumentError] if no parameter set matches
+    def param_set_for_signature_size(n)
+      ps = PARAM_SET_BY_SIG_SIZE[n]
+      return ps if ps
+      raise ArgumentError, "no ML-DSA parameter set has #{n}-byte signatures"
+    end
+
+    # Look up the ParameterSet whose public key size matches +n+ bytes.
+    # @param n [Integer] public key byte count
+    # @return [ParameterSet]
+    # @raise [ArgumentError] if no parameter set matches
+    def param_set_for_pk_size(n)
+      ps = PARAM_SET_BY_PK_SIZE[n]
+      return ps if ps
+      raise ArgumentError, "no ML-DSA parameter set has #{n}-byte public keys"
+    end
+  end
+end
+
+# PQC umbrella namespace for post-quantum cryptographic algorithms.
+#
+# Currently only ML-DSA is implemented; future algorithms (ML-KEM,
+# SLH-DSA, etc.) can register here for unified discovery.
+#
+# @example
+#   PQC.algorithms              # => { ml_dsa: MlDsa }
+#   PQC.algorithm(:ml_dsa)      # => MlDsa
+#   PQC::MlDsa == ::MlDsa       # => true
+module PQC
+  @registry = {}
+
+  # Register a PQC algorithm module under a symbolic name.
+  # @param name [Symbol]
+  # @param mod [Module]
+  def self.register(name, mod)
+    @registry[name.to_sym] = mod
+  end
+
+  # List all registered PQC algorithms.
+  # @return [Hash{Symbol => Module}]
+  def self.algorithms
+    @registry.dup
+  end
+
+  # Look up a registered algorithm by name.
+  # @param name [Symbol]
+  # @return [Module, nil]
+  def self.algorithm(name)
+    @registry[name.to_sym]
+  end
+
+  MlDsa = ::MlDsa
+  register(:ml_dsa, ::MlDsa)
+end

data/patches/README.md

@@ -0,0 +1,55 @@
+# PQClean Patches
+
+This directory tracks every modification made to vendored PQClean sources
+under `ext/ml_dsa/ml-dsa-{44,65,87}/`.
+
+## Why we patch
+
+FIPS 204 §3 allows both **hedged** signing (randomised `rnd`) and
+**deterministic** signing (`rnd = 0^{32}`).  The upstream PQClean
+`crypto_sign_signature_ctx` function generates `rnd` internally via
+`randombytes`.  That couples the randomness source to the signing function and
+makes deterministic testing impossible without mocking.
+
+Our patch adds an explicit `const uint8_t *rnd_in` parameter so that:
+
+* The **caller** (i.e. `ml_dsa_ext.c`) controls whether signing is hedged or
+  deterministic.
+* The C implementation stays free of any Ruby-level state.
+* Deterministic KAT vectors can be reproduced without patching `randombytes`.
+
+## Files modified
+
+For each of `ml-dsa-44`, `ml-dsa-65`, `ml-dsa-87`:
+
+| File | Change |
+|------|--------|
+| `clean/api.h` | Added `const uint8_t *rnd_in` as last argument to `crypto_sign_signature_ctx` |
+| `clean/sign.h` | Same declaration change |
+| `clean/sign.c` | Implementation: replaced internal `randombytes(rnd, RNDBYTES)` call with `memcpy(rnd, rnd_in, RNDBYTES)` |
+
+## Applying the patch
+
+```sh
+patch -p1 < patches/pqclean-explicit-rnd.patch
+```
+
+Run from the repository root.  After applying, recompile with:
+
+```sh
+bundle exec rake compile
+```
+
+## Verifying the patch matches vendored sources
+
+```sh
+bundle exec rake pqclean:verify
+```
+
+This task diffs the three `sign.c` / `sign.h` / `api.h` files against the
+patch to confirm no untracked drift has occurred.
+
+## PQClean upstream commit
+
+Vendored from PQClean commit `main` as of initial gem creation.  No other
+changes were made to the PQClean sources.

data/patches/pqclean-explicit-rnd.patch

@@ -0,0 +1,64 @@
+From: ml_dsa gem maintainers
+Subject: [PATCH] Add explicit parameters to PQClean keygen and signing
+
+Two patches applied to all three parameter set variants (44, 65, 87):
+
+1. crypto_sign_keypair: add `const uint8_t *seed_in` parameter.
+   Replaces the internal `randombytes(seedbuf, SEEDBYTES)` call with
+   `memcpy(seedbuf, seed_in, SEEDBYTES)`.  The caller generates the
+   seed (from OS CSPRNG, pluggable RNG, or user-provided) and passes
+   it explicitly.  This eliminates the need for thread-local seed
+   override hacks in randombytes.c.
+
+2. crypto_sign_signature_ctx: add `const uint8_t *rnd_in` parameter.
+   Replaces the internal `randombytes(rnd, RNDBYTES)` call with
+   `memcpy(rnd, rnd_in, RNDBYTES)`.  The caller passes OS-random bytes
+   for hedged signing or zeroes for deterministic signing (FIPS 204 S3).
+
+Applied to: ml-dsa-44/clean, ml-dsa-65/clean, ml-dsa-87/clean
+Each variant receives identical structural changes; only the symbol
+prefix (PQCLEAN_MLDSA44_CLEAN, etc.) differs.
+
+---
+ ext/ml_dsa/ml-dsa-{44,65,87}/clean/api.h  |  keygen + sign declarations
+ ext/ml_dsa/ml-dsa-{44,65,87}/clean/sign.h |  keygen + sign declarations
+ ext/ml_dsa/ml-dsa-{44,65,87}/clean/sign.c |  keygen + sign implementations
+
+For each variant (shown for ml-dsa-44, identical for 65/87):
+
+--- a/ext/ml_dsa/ml-dsa-44/clean/api.h
++++ b/ext/ml_dsa/ml-dsa-44/clean/api.h
+@@ keygen declaration
+-int PQCLEAN_MLDSA44_CLEAN_crypto_sign_keypair(uint8_t *pk, uint8_t *sk);
++int PQCLEAN_MLDSA44_CLEAN_crypto_sign_keypair(uint8_t *pk, uint8_t *sk,
++        const uint8_t *seed_in);
+
+@@ sign_signature_ctx declaration
+ int PQCLEAN_MLDSA44_CLEAN_crypto_sign_signature_ctx(uint8_t *sig, size_t *siglen,
+         const uint8_t *m, size_t mlen,
+         const uint8_t *ctx, size_t ctxlen,
+-        const uint8_t *sk);
++        const uint8_t *sk,
++        const uint8_t *rnd_in);
+
+--- a/ext/ml_dsa/ml-dsa-44/clean/sign.c
++++ b/ext/ml_dsa/ml-dsa-44/clean/sign.c
+@@ keygen implementation
+-int PQCLEAN_MLDSA44_CLEAN_crypto_sign_keypair(uint8_t *pk, uint8_t *sk) {
++int PQCLEAN_MLDSA44_CLEAN_crypto_sign_keypair(uint8_t *pk, uint8_t *sk,
++        const uint8_t *seed_in) {
+     /* ... */
+-    randombytes(seedbuf, SEEDBYTES);
++    /* Caller provides the seed: OS-random for normal keygen,
++     * or a user-supplied seed for deterministic keygen. */
++    memcpy(seedbuf, seed_in, SEEDBYTES);
+
+@@ sign_signature_ctx implementation
+-        const uint8_t *sk) {
++        const uint8_t *sk,
++        const uint8_t *rnd_in) {
+     /* ... */
+-    randombytes(rnd, RNDBYTES);
++    /* rnd_in is provided by the caller: OS-random for hedged signing,
++     * or 0^RNDBYTES for deterministic signing (FIPS 204 S3). */
++    memcpy(rnd, rnd_in, RNDBYTES);

data/sig/ml_dsa.rbs

@@ -0,0 +1,178 @@
+module MlDsa
+  VERSION: String
+  SEED_BYTES: Integer
+
+  ML_DSA_44: ParameterSet
+  ML_DSA_65: ParameterSet
+  ML_DSA_87: ParameterSet
+
+  ML_DSA_OIDS: Hash[Integer, String]
+  ML_DSA_OID_TO_CODE: Hash[String, Integer]
+
+  PARAM_SET_BY_PK_SIZE: Hash[Integer, ParameterSet]
+  PARAM_SET_BY_SK_SIZE: Hash[Integer, ParameterSet]
+  PARAM_SET_BY_SIG_SIZE: Hash[Integer, ParameterSet]
+
+  def self.config: () -> Config
+
+  def self.subscribe: () { (Hash[Symbol, untyped]) -> void } -> Proc
+  def self.unsubscribe: (Proc subscriber) -> Proc?
+  def self.random_source: () -> Proc?
+  def self.random_source=: (Proc? source) -> Proc?
+
+  def self.keygen: (ParameterSet param_set, ?seed: String?, ?config: Config?) -> KeyPair
+
+  def self.sign_many: (Array[SignRequest] operations, ?config: Config?, ?yield_every: Integer) -> Array[String]
+
+  def self.verify_many: (Array[VerifyRequest] operations, ?config: Config?, ?yield_every: Integer) -> Array[Result]
+
+  def self.batch: (?config: Config?, ?yield_every: Integer) { (BatchBuilder) -> void } -> (Array[String] | Array[Result])
+
+  class Config
+    def initialize: () -> void
+    def subscribe: () { (Hash[Symbol, untyped]) -> void } -> Proc
+    def unsubscribe: (Proc subscriber) -> Proc?
+    attr_reader random_source: Proc?
+    def random_source=: (Proc? source) -> void
+    def notify: (Symbol operation, ParameterSet? param_set, Integer count, Integer duration_ns) -> nil
+  end
+
+  class ParameterSet
+    include Comparable
+
+    attr_reader name: String
+    attr_reader code: Integer
+    attr_reader security_level: Integer
+    attr_reader public_key_bytes: Integer
+    attr_reader secret_key_bytes: Integer
+    attr_reader signature_bytes: Integer
+
+    def <=>: (ParameterSet other) -> Integer?
+    def to_s: () -> String
+    def inspect: () -> String
+  end
+
+  class KeyPair
+    attr_reader public_key: PublicKey
+    attr_reader secret_key: SecretKey
+
+    def to_ary: () -> [PublicKey, SecretKey]
+    def to_a: () -> [PublicKey, SecretKey]
+    def deconstruct: () -> [PublicKey, SecretKey]
+    def param_set: () -> ParameterSet
+    def inspect: () -> String
+    def to_s: () -> String
+  end
+
+  class PublicKey
+    def param_set: () -> ParameterSet
+    def bytesize: () -> Integer
+    def to_bytes: () -> String
+    def to_hex: () -> String
+    def fingerprint: () -> String
+    def to_der: () -> String
+    def to_pem: () -> String
+    def verify: (String message, String signature, ?context: String) -> bool
+    def to_s: () -> String
+    def inspect: () -> String
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+
+    attr_reader created_at: Time?
+    attr_reader key_usage: Symbol?
+    def key_usage=: (Symbol? value) -> Symbol?
+
+    def self.from_bytes: (String bytes, ?ParameterSet? param_set) -> PublicKey
+    def self.from_hex: (String hex, ?ParameterSet? param_set) -> PublicKey
+    def self.from_der: (String der) -> PublicKey
+    def self.from_pem: (String pem) -> PublicKey
+  end
+
+  class SecretKey
+    def param_set: () -> ParameterSet
+    def public_key: () -> PublicKey?
+    def seed: () -> String?
+    def bytesize: () -> Integer
+    def with_bytes: [T] () { (String) -> T } -> T
+    def wipe!: () -> nil
+    def sign: (String message, ?deterministic: bool, ?context: String) -> String
+    def to_der: () -> String
+    def to_pem: () -> String
+    def to_s: () -> String
+    def inspect: () -> String
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+
+    attr_reader created_at: Time?
+    attr_reader key_usage: Symbol?
+    def key_usage=: (Symbol? value) -> Symbol?
+
+    def self.from_bytes: (String bytes, ?ParameterSet? param_set) -> SecretKey
+    def self.from_hex: (String hex, ?ParameterSet? param_set) -> SecretKey
+    def self.from_der: (String der) -> SecretKey
+    def self.from_pem: (String pem) -> SecretKey
+    def self.from_seed: (String seed, ParameterSet param_set) -> SecretKey
+  end
+
+  class SignRequest
+    attr_accessor sk: SecretKey
+    attr_accessor message: String
+    attr_accessor context: String?
+    attr_accessor deterministic: bool?
+
+    def initialize: (?sk: SecretKey, ?message: String, ?context: String?, ?deterministic: bool?) -> void
+    def validate!: () -> self
+  end
+
+  class VerifyRequest
+    attr_accessor pk: PublicKey
+    attr_accessor message: String
+    attr_accessor signature: String
+    attr_accessor context: String?
+
+    def initialize: (?pk: PublicKey, ?message: String, ?signature: String, ?context: String?) -> void
+    def validate!: () -> self
+  end
+
+  class Result
+    attr_reader value: bool
+    attr_reader ok: bool
+    attr_reader reason: String?
+
+    def initialize: (?value: bool, ?ok: bool, ?reason: String?) -> void
+    def ok?: () -> bool
+    def inspect: () -> String
+    def to_s: () -> String
+  end
+
+  class BatchBuilder
+    def sign: (sk: SecretKey, message: String, ?context: String?, ?deterministic: bool) -> self
+    def verify: (pk: PublicKey, message: String, signature: String, ?context: String?) -> self
+    def execute: (?config: Config, ?yield_every: Integer) -> (Array[String] | Array[Result])
+  end
+
+  class Error < StandardError
+    def reason: () -> String?
+  end
+
+  class Error::KeyGeneration < Error
+  end
+
+  class Error::Signing < Error
+  end
+
+  class Error::Deserialization < Error
+    def format: () -> String?
+    def position: () -> Integer?
+  end
+end
+
+module PQC
+  MlDsa: Module
+
+  def self.register: (Symbol name, Module mod) -> void
+  def self.algorithms: () -> Hash[Symbol, Module]
+  def self.algorithm: (Symbol name) -> Module?
+end