ml_dsa 0.1.0

data/ext/ml_dsa/ml_dsa_impl_template.h

@@ -0,0 +1,35 @@
+/*
+ * ml_dsa_impl_template.h — Parametric amalgamation template.
+ *
+ * Single source of truth for which PQClean .c files are included per
+ * parameter set.  Each ml_dsa_NN_impl.c defines ML_DSA_PS to its
+ * parameter set code (44, 65, or 87) and includes this template.
+ *
+ * Including .c files causes GCC/Clang to resolve their quoted includes
+ * (e.g. #include "params.h") relative to the directory of the included
+ * file, so each variant picks up its own params.h automatically.
+ * fips202.h and randombytes.h are resolved via -I$(srcdir) (ext/ml_dsa/).
+ *
+ * To add a new PQClean source file, add it ONCE here — all three
+ * parameter sets pick it up automatically.
+ */
+
+#ifndef ML_DSA_PS
+#  error "ML_DSA_PS must be defined before including ml_dsa_impl_template.h"
+#endif
+
+/* Token-paste helpers to build paths like ml-dsa-44/clean/ntt.c */
+#define ML_DSA_PASTE2(a, b) a ## b
+#define ML_DSA_PASTE(a, b) ML_DSA_PASTE2(a, b)
+#define ML_DSA_PATH(file) ML_DSA_STRINGIFY(ml-dsa-ML_DSA_PS/clean/file)
+#define ML_DSA_STRINGIFY(x) ML_DSA_STRINGIFY2(x)
+#define ML_DSA_STRINGIFY2(x) #x
+
+#include ML_DSA_PATH(ntt.c)
+#include ML_DSA_PATH(packing.c)
+#include ML_DSA_PATH(poly.c)
+#include ML_DSA_PATH(polyvec.c)
+#include ML_DSA_PATH(reduce.c)
+#include ML_DSA_PATH(rounding.c)
+#include ML_DSA_PATH(symmetric-shake.c)
+#include ML_DSA_PATH(sign.c)

data/ext/ml_dsa/ml_dsa_internal.h

@@ -0,0 +1,188 @@
+/*
+ * ml_dsa_internal.h — Shared declarations for the ML-DSA C extension.
+ *
+ * This header provides the minimal interface consumed by ml_dsa_ext.c
+ * and the parametric impl template files (ml_dsa_NN_impl.c).  It contains:
+ *   - Standard and Ruby includes
+ *   - C11 atomics compatibility macros
+ *   - PQClean api.h includes (ifdef-guarded by parameter set)
+ *   - Constants and named boundary-array positions
+ *   - Dispatch table typedef
+ *   - TypedData struct definitions for PublicKey and SecretKey
+ *
+ * Design decisions:
+ *
+ *   Why no Signer/Verifier streaming classes?
+ *     True incremental ML-DSA signing would require splitting PQClean's
+ *     sign/verify at the SHAKE-256 mu-computation boundary — a fragile
+ *     change that breaks on every PQClean update.  The former Ruby
+ *     Signer/Verifier classes buffered the full message anyway, providing
+ *     an illusion of streaming without actual streaming.  Removed in
+ *     favor of direct sk.sign / pk.verify calls.
+ *
+ *   Why batch-only C layer (no single-op sign/verify in C)?
+ *     The batch sign/verify C paths already handle single items.  Having
+ *     separate single-op C functions duplicated ~190 lines of nogvl
+ *     structs, callbacks, body/ensure pairs.  Now sk.sign and pk.verify
+ *     are Ruby methods that call sign_many/verify_many with a single-
+ *     element array.  The overhead (one Ruby Array + one SignRequest/
+ *     VerifyRequest) is negligible vs. the ~50us crypto operation.
+ *
+ *   Why ParameterSet in Ruby, not C?
+ *     ParameterSet is a value object with Comparable, inspect, to_s —
+ *     features that are trivial in Ruby but would require 100+ lines of
+ *     boilerplate in C.  The C layer passes integer codes (44/65/87)
+ *     through the boundary.  The build_param_data array-of-arrays bridges
+ *     C constants into Ruby with no per-call overhead (runs once at
+ *     require time).
+ *
+ *   Why no code generator for the dispatch table?
+ *     ML-DSA has exactly 3 parameter sets (44, 65, 87), standardized by
+ *     NIST FIPS 204.  This set will not change.  A code generator would
+ *     add build complexity for a table that has 3 entries.
+ *
+ *   Why context is a plain string (not a Context class)?
+ *     FIPS 204 defines context as 0..255 bytes — that's a string with a
+ *     length check.  A wrapper class adds API surface without adding
+ *     invariants beyond what the primitive can express.
+ *
+ *   rb_ensure pattern:
+ *     Every GVL-released crypto operation follows this structure:
+ *       1. Allocate buffers in body (covered by ensure on OOM)
+ *       2. Pin Ruby strings with rb_str_new_frozen before GVL drop
+ *       3. Call rb_thread_call_without_gvl
+ *       4. Build result objects
+ *       5. Place RB_GC_GUARD at END of body (not in ensure!)
+ *       6. Ensure function: secure_zero + free all allocations
+ *     CRITICAL: RB_GC_GUARD must live on the body's stack frame, not
+ *     in ensure, because ensure may execute after body's locals are gone.
+ */
+
+#ifndef ML_DSA_INTERNAL_H
+#define ML_DSA_INTERNAL_H
+
+/* Must precede <string.h> so memset_s is declared when available. */
+#define __STDC_WANT_LIB_EXT1__ 1
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <ruby/st.h>
+#include <ruby/encoding.h>
+#include <string.h>
+#include <stdint.h>
+#include <stdarg.h>
+
+/* C11 atomics for thread-safe wipe flag.  MSVC < 2022 lacks stdatomic.h,
+ * so we fall back to volatile int + compiler barriers on that platform. */
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L && !defined(__STDC_NO_ATOMICS__)
+#  include <stdatomic.h>
+#  define ML_DSA_ATOMIC _Atomic
+#  define ML_DSA_ATOMIC_LOAD(p) atomic_load_explicit((p), memory_order_acquire)
+#  define ML_DSA_ATOMIC_STORE(p, v) atomic_store_explicit((p), (v), memory_order_release)
+#else
+#  define ML_DSA_ATOMIC volatile
+#  define ML_DSA_ATOMIC_LOAD(p) (*(p))
+#  define ML_DSA_ATOMIC_STORE(p, v) (*(p) = (v))
+#endif
+
+#ifdef ML_DSA_ENABLE_44
+#  include "ml-dsa-44/clean/api.h"
+#endif
+#ifdef ML_DSA_ENABLE_65
+#  include "ml-dsa-65/clean/api.h"
+#endif
+#ifdef ML_DSA_ENABLE_87
+#  include "ml-dsa-87/clean/api.h"
+#endif
+
+#include "randombytes.h"
+
+/* ------------------------------------------------------------------ */
+/* Constants                                                           */
+/* ------------------------------------------------------------------ */
+
+#define ML_DSA_RNDBYTES   32
+#define ML_DSA_SEED_BYTES 32
+
+/* Named positions for the flat Ruby->C boundary arrays.
+ * sign_many: [sk, message, ctx_or_nil, deterministic_or_nil, rnd_or_nil]
+ * verify_many: [pk, message, signature, ctx_or_nil] */
+#define SIGN_OP_SK   0
+#define SIGN_OP_MSG  1
+#define SIGN_OP_CTX  2
+#define SIGN_OP_DET  3
+#define SIGN_OP_RND  4   /* optional pre-generated rnd bytes from pluggable RNG */
+
+#define VERIFY_OP_PK   0
+#define VERIFY_OP_MSG  1
+#define VERIFY_OP_SIG  2
+#define VERIFY_OP_CTX  3
+
+#ifdef ML_DSA_ENABLE_87
+#  define ML_DSA_MAX_PK_BYTES  PQCLEAN_MLDSA87_CLEAN_CRYPTO_PUBLICKEYBYTES
+#  define ML_DSA_MAX_SK_BYTES  PQCLEAN_MLDSA87_CLEAN_CRYPTO_SECRETKEYBYTES
+#  define ML_DSA_MAX_SIG_BYTES PQCLEAN_MLDSA87_CLEAN_CRYPTO_BYTES
+#elif defined(ML_DSA_ENABLE_65)
+#  define ML_DSA_MAX_PK_BYTES  PQCLEAN_MLDSA65_CLEAN_CRYPTO_PUBLICKEYBYTES
+#  define ML_DSA_MAX_SK_BYTES  PQCLEAN_MLDSA65_CLEAN_CRYPTO_SECRETKEYBYTES
+#  define ML_DSA_MAX_SIG_BYTES PQCLEAN_MLDSA65_CLEAN_CRYPTO_BYTES
+#else
+#  define ML_DSA_MAX_PK_BYTES  PQCLEAN_MLDSA44_CLEAN_CRYPTO_PUBLICKEYBYTES
+#  define ML_DSA_MAX_SK_BYTES  PQCLEAN_MLDSA44_CLEAN_CRYPTO_SECRETKEYBYTES
+#  define ML_DSA_MAX_SIG_BYTES PQCLEAN_MLDSA44_CLEAN_CRYPTO_BYTES
+#endif
+
+/* Convenience macro — wraps rb_ensure with the cast boilerplate. */
+#define ML_DSA_ENSURE(body, ensure, state) \
+    rb_ensure((body), (VALUE)(state), (ensure), (VALUE)(state))
+
+/* ------------------------------------------------------------------ */
+/* Dispatch table                                                      */
+/* ------------------------------------------------------------------ */
+
+typedef int (*keygen_fn_t)(uint8_t *, uint8_t *, const uint8_t *);
+typedef int (*sign_fn_t)(uint8_t *, size_t *,
+                         const uint8_t *, size_t,
+                         const uint8_t *, size_t,
+                         const uint8_t *,
+                         const uint8_t *);   /* rnd_in */
+typedef int (*verify_fn_t)(const uint8_t *, size_t,
+                           const uint8_t *, size_t,
+                           const uint8_t *, size_t,
+                           const uint8_t *);
+
+typedef struct {
+    int              ps;
+    int              security_level;
+    keygen_fn_t      keygen_fn;
+    sign_fn_t        sign_fn;
+    verify_fn_t      verify_fn;
+    size_t           pk_len;
+    size_t           sk_len;
+    size_t           sig_len;
+} ml_dsa_impl_t;
+
+extern const ml_dsa_impl_t ML_DSA_IMPLS[];
+extern const size_t ML_DSA_IMPL_COUNT;
+
+/* ------------------------------------------------------------------ */
+/* TypedData structures                                                */
+/* ------------------------------------------------------------------ */
+
+typedef struct {
+    size_t   len;
+    int      ps_code;
+    VALUE    fingerprint;  /* cached SHA-256 hex prefix, Qnil until computed */
+    uint8_t  bytes[];   /* flexible array member — allocated inline */
+} ml_dsa_pk_t;
+
+typedef struct {
+    size_t          len;
+    int             ps_code;
+    ML_DSA_ATOMIC int wiped;  /* non-zero after wipe! — atomic for thread safety */
+    int             has_seed; /* non-zero if seed[] contains the keygen seed */
+    uint8_t         seed[ML_DSA_SEED_BYTES]; /* keygen seed (zeroed if !has_seed) */
+    uint8_t         bytes[];  /* flexible array member — allocated inline */
+} ml_dsa_sk_t;
+
+#endif /* ML_DSA_INTERNAL_H */

data/ext/ml_dsa/randombytes.c

@@ -0,0 +1,48 @@
+/*
+ * randombytes.c — OS-backed CSPRNG.
+ *
+ * Replaces PQClean's common/randombytes.c.  All randomness for keygen
+ * and signing is generated before the GVL drop and passed explicitly
+ * to the PQClean functions (seed_in for keygen, rnd_in for signing).
+ * This file is only used for OS CSPRNG calls made while holding the GVL.
+ */
+
+#include "randombytes.h"
+
+#if defined(_WIN32)
+# include <windows.h>
+# include <bcrypt.h>
+# pragma comment(lib, "bcrypt.lib")
+#elif defined(__APPLE__) || defined(__FreeBSD__) || defined(__OpenBSD__) || defined(__NetBSD__)
+# include <stdlib.h>   /* arc4random_buf */
+#else
+# include <errno.h>
+# include <sys/random.h>  /* getrandom(2), Linux >= 3.17 */
+#endif
+
+void randombytes(uint8_t *x, size_t xlen)
+{
+#if defined(_WIN32)
+    /* BCryptGenRandom takes ULONG; guard against truncation on 64-bit. */
+    if (xlen > (size_t)ULONG_MAX) abort();
+    NTSTATUS status = BCryptGenRandom(NULL, x, (ULONG)xlen,
+                                      BCRYPT_USE_SYSTEM_PREFERRED_RNG);
+    if (!BCRYPT_SUCCESS(status)) abort();
+
+#elif defined(__APPLE__) || defined(__FreeBSD__) || defined(__OpenBSD__) || defined(__NetBSD__)
+    arc4random_buf(x, xlen);
+
+#else
+    /* Linux: loop on EINTR; getrandom never returns partial reads for <= 256 bytes */
+    while (xlen > 0) {
+        ssize_t ret = getrandom(x, xlen, 0);
+        if (ret < 0) {
+            if (errno == EINTR) continue;
+            /* getrandom failure is fatal — caller cannot continue safely */
+            __builtin_trap();
+        }
+        x    += (size_t)ret;
+        xlen -= (size_t)ret;
+    }
+#endif
+}

data/ext/ml_dsa/randombytes.h

@@ -0,0 +1,15 @@
+#ifndef ML_DSA_RANDOMBYTES_H
+#define ML_DSA_RANDOMBYTES_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+/*
+ * Generate xlen random bytes into x using the OS CSPRNG:
+ *   - Linux:        getrandom(2)
+ *   - macOS/BSD:    arc4random_buf(3)
+ *   - Windows:      BCryptGenRandom
+ */
+void randombytes(uint8_t *x, size_t xlen);
+
+#endif /* ML_DSA_RANDOMBYTES_H */

data/lib/ml_dsa/batch_builder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MlDsa
+  # Collects sign or verify operations for batch execution.
+  # Obtained via {MlDsa.batch}. Do not mix sign and verify in one batch.
+  class BatchBuilder
+    def initialize
+      @ops = []
+      @mode = nil
+    end
+
+    # Add a sign operation to the batch.
+    # @param sk [SecretKey]
+    # @param message [String]
+    # @param context [String, nil] FIPS 204 context (0..255 bytes)
+    # @param deterministic [Boolean] use deterministic signing
+    # @return [self] for chaining
+    def sign(sk:, message:, context: nil, deterministic: false)
+      check_mode!(:sign)
+      @ops << SignRequest.new(sk: sk, message: message,
+        context: context, deterministic: deterministic)
+      self
+    end
+
+    # Add a verify operation to the batch.
+    # @param pk [PublicKey]
+    # @param message [String]
+    # @param signature [String]
+    # @param context [String, nil] FIPS 204 context (0..255 bytes)
+    # @return [self] for chaining
+    def verify(pk:, message:, signature:, context: nil)
+      check_mode!(:verify)
+      @ops << VerifyRequest.new(pk: pk, message: message,
+        signature: signature, context: context)
+      self
+    end
+
+    # @api private
+    def execute(config: MlDsa.config, yield_every: Internal::DEFAULT_YIELD_EVERY)
+      return [] if @ops.empty?
+      if @mode == :sign
+        MlDsa.sign_many(@ops, config: config, yield_every: yield_every)
+      else
+        MlDsa.verify_many(@ops, config: config, yield_every: yield_every)
+      end
+    end
+
+    private
+
+    def check_mode!(mode)
+      if @mode && @mode != mode
+        raise ArgumentError, "cannot mix sign and verify in the same batch"
+      end
+      @mode = mode
+    end
+  end
+end

data/lib/ml_dsa/config.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module MlDsa
+  # Thread-safe configuration holder for instrumentation subscribers
+  # and pluggable RNG.  Each Ractor or test context can have its own
+  # Config instance.
+  #
+  # @example Custom config for testing
+  #   cfg = MlDsa::Config.new
+  #   cfg.random_source = proc { |n| "\x42" * n }
+  #   pk, sk = MlDsa.keygen(MlDsa::ML_DSA_65, config: cfg)
+  class Config
+    def initialize
+      @subscribers = []
+      @mutex = Mutex.new
+      @random_source = nil
+    end
+
+    # Subscribe to instrumentation events. The block receives a frozen Hash
+    # with keys +:operation+, +:param_set+, +:count+, and +:duration_ns+.
+    #
+    # @yield [Hash] event payload
+    # @return [Proc] the subscriber (pass to {.unsubscribe} to remove)
+    def subscribe(&block)
+      raise ArgumentError, "subscribe requires a block" unless block
+      @mutex.synchronize { @subscribers << block }
+      block
+    end
+
+    # Remove a previously registered subscriber.
+    # @param subscriber [Proc] the block returned by {#subscribe}
+    # @return [Proc, nil] the removed subscriber, or nil if not found
+    def unsubscribe(subscriber)
+      @mutex.synchronize { @subscribers.delete(subscriber) }
+    end
+
+    # @return [Proc, nil] the current random source, or nil for OS CSPRNG
+    attr_reader :random_source
+
+    # Set a custom random source. The proc must accept a single Integer
+    # argument (byte count) and return a binary String of that length.
+    #
+    # @param source [Proc, nil]
+    def random_source=(source)
+      if source && !source.respond_to?(:call)
+        raise TypeError, "random_source must respond to :call or be nil"
+      end
+      @random_source = source
+    end
+
+    # @api private — fire event to all subscribers
+    def notify(operation, param_set, count, duration_ns)
+      # In non-main Ractors, skip instrumentation to avoid isolation errors
+      if defined?(Ractor) && Ractor.respond_to?(:main?) && !Ractor.main?
+        return nil
+      end
+      subs = @mutex.synchronize { @subscribers.dup }
+      return if subs.empty?
+      event = {
+        operation: operation,
+        param_set: param_set,
+        count: count,
+        duration_ns: duration_ns
+      }.freeze
+      subs.each { |s| s.call(event) }
+      nil
+    end
+  end
+end

data/lib/ml_dsa/internal.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module MlDsa
+  # Nested module with private_constant so that MlDsa::Internal is
+  # accessible inside this gem but invisible to external callers.
+  module Internal
+    # Named positions for the flat Ruby→C boundary arrays.
+    # Must match SIGN_OP_* / VERIFY_OP_* macros in ml_dsa_internal.h.
+    SIGN_OP_SK = 0
+    SIGN_OP_MSG = 1
+    SIGN_OP_CTX = 2
+    SIGN_OP_DET = 3
+    SIGN_OP_RND = 4   # optional pre-generated rnd bytes (pluggable RNG)
+
+    VERIFY_OP_PK = 0
+    VERIFY_OP_MSG = 1
+    VERIFY_OP_SIG = 2
+    VERIFY_OP_CTX = 3
+
+    RND_BYTES = 32
+
+    # Default number of items between cooperative yields to the fiber
+    # scheduler during batch normalization loops.  Zero means no yielding.
+    DEFAULT_YIELD_EVERY = 0
+
+    # Yield to the fiber scheduler if one is active and yield_every > 0.
+    # Called inside normalization loops to allow other fibers to run
+    # during large batch preparations.
+    def self.maybe_yield(i, yield_every)
+      return unless yield_every > 0 && ((i + 1) % yield_every).zero?
+      scheduler = Fiber.scheduler
+      return unless scheduler
+      scheduler.yield
+    rescue NoMethodError
+      # Fiber.scheduler or scheduler.yield not available (Ruby < 3.1)
+      nil
+    end
+
+    # Raise MlDsa::Error::Deserialization with structured metadata.
+    def self.raise_deser(format_str, position, reason, message)
+      err = MlDsa::Error::Deserialization.new(message)
+      err.instance_variable_set(:@format, format_str)
+      err.instance_variable_set(:@position, position)
+      err.instance_variable_set(:@reason, reason.to_sym)
+      raise err
+    end
+
+    # Look up the ParameterSet for a given code (44, 65, or 87).
+    def self.param_set_for_code(code)
+      MlDsa.const_get("ML_DSA_#{code}")
+    end
+
+    # Validate and return a ParameterSet.
+    def self.resolve_ps(ps)
+      case ps
+      when ParameterSet then ps
+      else
+        raise TypeError,
+          "param_set must be a MlDsa::ParameterSet " \
+          "(ML_DSA_44, ML_DSA_65, or ML_DSA_87), got #{ps.class}"
+      end
+    end
+
+    # Validate a hex string and decode to binary bytes.
+    def self.decode_hex(hex)
+      raise TypeError, "hex must be a String, got #{hex.class}" unless hex.is_a?(String)
+      raise ArgumentError, "hex string must not be empty" if hex.empty?
+      unless hex.match?(/\A[0-9a-fA-F]+\z/) && hex.length.even?
+        raise ArgumentError,
+          "hex must contain only hexadecimal characters and have even length"
+      end
+      [hex].pack("H*")
+    end
+  end
+  private_constant :Internal
+end

data/lib/ml_dsa/key_pair.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module MlDsa
+  # Holds a matched public/secret key pair returned by {MlDsa.keygen}.
+  # Supports destructuring: +pk, sk = MlDsa.keygen(...)+.
+  class KeyPair
+    # @return [PublicKey]
+    attr_reader :public_key
+    # @return [SecretKey]
+    attr_reader :secret_key
+
+    def initialize(public_key, secret_key)
+      @public_key = public_key
+      @secret_key = secret_key
+      freeze
+    end
+
+    # Support destructuring: +pk, sk = keygen(...)+.
+    # @return [Array(PublicKey, SecretKey)]
+    def to_ary
+      [public_key, secret_key]
+    end
+
+    alias_method :to_a, :to_ary
+    alias_method :deconstruct, :to_ary
+
+    # @return [ParameterSet]
+    def param_set
+      public_key.param_set
+    end
+
+    # @return [String]
+    def inspect
+      "#<MlDsa::KeyPair #{param_set.name}>"
+    end
+
+    alias_method :to_s, :inspect
+  end
+end

data/lib/ml_dsa/parameter_set.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module MlDsa
+  # Encapsulates a concrete ML-DSA parameter set (44, 65, or 87).
+  #
+  # Obtain instances via the +ML_DSA_44+, +ML_DSA_65+, +ML_DSA_87+ constants;
+  # do not call +new+ directly.  Supports +Comparable+ ordering by security
+  # level: +ML_DSA_44 < ML_DSA_65 < ML_DSA_87+.
+  class ParameterSet
+    include Comparable
+
+    # @return [String] human-readable name, e.g. +"ML-DSA-44"+
+    attr_reader :name
+    # @return [Integer] numeric code (44, 65, or 87)
+    attr_reader :code
+    # @return [Integer] NIST security level (2, 3, or 5)
+    attr_reader :security_level
+    # @return [Integer] public key size in bytes
+    attr_reader :public_key_bytes
+    # @return [Integer] secret key size in bytes
+    attr_reader :secret_key_bytes
+    # @return [Integer] signature size in bytes
+    attr_reader :signature_bytes
+
+    def initialize(name, code, security_level, pk, sk, sig)
+      @name = name.freeze
+      @code = code
+      @security_level = security_level
+      @public_key_bytes = pk
+      @secret_key_bytes = sk
+      @signature_bytes = sig
+      freeze
+    end
+
+    def <=>(other)
+      return nil unless other.is_a?(ParameterSet)
+      @security_level <=> other.security_level
+    end
+
+    def to_s
+      @name
+    end
+
+    def inspect
+      "#<MlDsa::ParameterSet #{@name}>"
+    end
+
+    private_class_method :new
+  end
+
+  # Build ParameterSet constants from C extension data — no raw integer
+  # constants are exposed in the public API.
+  # Each row is [code, security_level, pk_bytes, sk_bytes, sig_bytes].
+  _param_data.each do |code, security_level, pk_bytes, sk_bytes, sig_bytes|
+    name = "ML-DSA-#{code}"
+    const_name = "ML_DSA_#{code}"
+    ps = ParameterSet.send(:new,
+      name, code, security_level, pk_bytes, sk_bytes, sig_bytes)
+    const_set(const_name, ps)
+  end
+
+  # OIDs assigned by NIST for ML-DSA parameter sets (FIPS 204).
+  ML_DSA_OIDS = {
+    44 => "2.16.840.1.101.3.4.3.17",
+    65 => "2.16.840.1.101.3.4.3.18",
+    87 => "2.16.840.1.101.3.4.3.19"
+  }.freeze
+
+  ML_DSA_OID_TO_CODE = ML_DSA_OIDS.invert.freeze
+
+  # O(1) lookup tables for param_set_for_signature_size / param_set_for_pk_size
+  PARAM_SET_BY_SIG_SIZE = constants.filter_map { |c|
+    ps = const_get(c)
+    [ps.signature_bytes, ps] if ps.is_a?(ParameterSet)
+  }.to_h.freeze
+  private_constant :PARAM_SET_BY_SIG_SIZE
+
+  PARAM_SET_BY_PK_SIZE = constants.filter_map { |c|
+    ps = const_get(c)
+    [ps.public_key_bytes, ps] if ps.is_a?(ParameterSet)
+  }.to_h.freeze
+  private_constant :PARAM_SET_BY_PK_SIZE
+
+  PARAM_SET_BY_SK_SIZE = constants.filter_map { |c|
+    ps = const_get(c)
+    [ps.secret_key_bytes, ps] if ps.is_a?(ParameterSet)
+  }.to_h.freeze
+  private_constant :PARAM_SET_BY_SK_SIZE
+end