ml_dsa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a532543c1f2654a5ee484919c2700a3f46731ee63033fd1ad59b8bd3873fe9fe
+  data.tar.gz: 449a09788a28127d8bb17aa98046131db5e7854021f206b8210cd7f95f4c9d0f
+SHA512:
+  metadata.gz: c399d7e930247d10232805993dac0a5911f7e8d07b21e7b8dcb3bcba22675be366adfcd694f2da130340532c1d7975f9c505f902fad44b7eefa88c91b3ed265a
+  data.tar.gz: c2eb08be27b1582834b6f5e54f610beeca61ec52b727bcdcbf3ac6b1ed76b2fb94dd6e12dc39e07099053bf76ca536025426cabbab7f76d969b641203170ee1e

data/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-18
+
+Initial release implementing NIST FIPS 204 ML-DSA (Module-Lattice-Based
+Digital Signature Algorithm) as a Ruby C extension.
+
+### Features
+
+#### Core cryptography
+- Three parameter sets: ML-DSA-44 (NIST Level 2), ML-DSA-65 (Level 3),
+  ML-DSA-87 (Level 5), backed by vendored PQClean clean C implementation.
+- `MlDsa.keygen(param_set)` — key pair generation with optional `seed:`
+  for deterministic keygen from a 32-byte seed.
+- `SecretKey#sign(message, deterministic:, context:)` — hedged (randomized,
+  default) and deterministic signing with optional FIPS 204 context strings.
+- `PublicKey#verify(message, signature, context:)` — signature verification.
+- Batch operations: `MlDsa.sign_many` / `MlDsa.verify_many` execute
+  multiple operations in a single GVL release for thread concurrency.
+- `MlDsa.batch { |b| ... }` — block-based batch builder that collects
+  sign or verify operations and executes them together.
+- `verify_many` returns `Array[Result]` with per-item `.ok?` and `.reason`
+  (distinguishes `wrong_signature_size` from `verification_failed`).
+- Build-time parameter set selection: `--with-ml-dsa-params=44,65` to
+  compile only a subset (reduces binary size).
+
+#### Key management
+- `SecretKey#public_key` — returns the associated `PublicKey` from keygen
+  (nil for deserialized keys).
+- `SecretKey.from_seed(seed, param_set)` — reconstruct from a 32-byte seed
+  with `public_key` attached automatically.
+- `SecretKey#seed` — access the keygen seed for compact storage (nil if not
+  created from a seed). Securely zeroed on `wipe!` and GC.
+- `PublicKey#fingerprint` — SHA-256 prefix (32 hex chars) for identification
+  in logs and UIs.
+- `PublicKey#created_at` / `SecretKey#created_at` — timestamp set at
+  construction for audit trails and key rotation policies.
+- `PublicKey#key_usage=` / `SecretKey#key_usage=` — optional `Symbol`
+  metadata for application-defined usage labels.
+
+#### Serialization
+- Raw bytes: `to_bytes` / `from_bytes` with auto-detection of parameter set
+  from byte length.
+- Hex: `to_hex` / `from_hex` with auto-detection.
+- DER: `to_der` / `from_der` — SubjectPublicKeyInfo for public keys,
+  PKCS#8 / OneAsymmetricKey for secret keys (OIDs per FIPS 204).
+- PEM: `to_pem` / `from_pem` — PEM-armored DER.
+- DER/PEM handled by the [`pqc_asn1`](https://github.com/msuliq/pqc_asn1)
+  gem with no OpenSSL dependency. Secret key DER intermediates are held in
+  `PqcAsn1::SecureBuffer` (mmap-protected, securely zeroed).
+
+#### Secret key hygiene
+- Key bytes live in C-managed memory, securely zeroed on GC.
+- `SecretKey#with_bytes { |buf| ... }` — controlled access with automatic
+  wipe on block exit (even on exception).
+- `SecretKey#wipe!` — explicit zeroing; subsequent operations raise
+  `MlDsa::Error`.
+- Memory locking: `mlock` prevents secret key pages from swapping to disk.
+- No `SecretKey#to_bytes` or `#to_hex` — prevents accidental key leakage
+  into logs, exception messages, or long-lived Ruby Strings.
+- `dup` / `clone` and `Marshal.dump` raise `TypeError` on both key classes.
+
+#### Configuration and instrumentation
+- `MlDsa::Config` — encapsulates mutable state (subscribers, RNG). All
+  operations accept optional `config:` for per-Ractor or per-test contexts.
+- `MlDsa.subscribe { |event| ... }` — audit logging hooks with
+  `:operation`, `:param_set`, `:count`, `:duration_ns`. No key material
+  exposed.
+- `MlDsa.random_source=` — pluggable RNG for testing or HSM integration.
+  Keygen uses it to generate a seed; signing uses it for the rnd nonce.
+- `yield_every:` keyword on batch operations for cooperative fiber
+  scheduling in async servers.
+
+#### Concurrency
+- GVL release: all crypto operations run without the Global VM Lock.
+- `PublicKey` is Ractor-shareable (`RUBY_TYPED_FROZEN_SHAREABLE`, Ruby 3.0+).
+- Thread-safe wipe detection via C11 `_Atomic` with acquire/release semantics.
+- Ractor-compatible instrumentation (silently no-op in non-main Ractors).
+
+#### PQC namespace
+- `PQC::MlDsa` alias with `PQC.register` / `PQC.algorithms` /
+  `PQC.algorithm(:name)` registry for future multi-algorithm discovery.
+
+#### Error handling
+- `MlDsa::Error` base class with subclasses `Error::KeyGeneration`,
+  `Error::Signing`, `Error::Deserialization`.
+- Deserialization errors include `format`, `position`, and `reason` metadata.
+- `ParameterSet` includes `Comparable` for sorting and comparison.
+
+### Security
+- Secure zeroing: `SecureZeroMemory` (Windows), `explicit_bzero`
+  (Linux/BSD/macOS), `memset_s` (C11), or volatile fallback with compiler
+  fence.
+- Constant-time secret key comparison via XOR-accumulate with compiler fence.
+- Platform-appropriate CSPRNG: `getrandom(2)` (Linux), `arc4random_buf`
+  (macOS/BSD), `BCryptGenRandom` (Windows).
+- `-fvisibility=hidden` prevents PQClean symbols from clashing with other gems.
+- Process-salted hashing for `#hash` method.
+- Heap buffers freed via `rb_ensure` — no leak on exceptions.

data/LICENSE

@@ -0,0 +1,14 @@
+Copyright 2026 Suleyman Musayev
+
+This project is dual-licensed. You may use, distribute, and modify it under
+the terms of either:
+
+  * the MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT), or
+  * the Apache License, Version 2.0 (LICENSE-APACHE or
+    http://www.apache.org/licenses/LICENSE-2.0)
+
+at your option.
+
+Unless you explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in this project by you, as defined in the Apache-2.0 license,
+shall be dual-licensed as above, without any additional terms or conditions.

data/LICENSE-APACHE

@@ -0,0 +1,185 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or a Contribution
+      incorporated within the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this License
+      for that Work shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text file
+          distributed as part of the Derivative Works; within the Source
+          form or documentation, if provided along with the Derivative
+          Works; or, within a display generated by the Derivative Works,
+          if and wherever such third-party notices normally appear. The
+          contents of the NOTICE file are for informational purposes only
+          and do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, reproduce, modify,
+      prepare Derivative Works of, publicly display, publicly perform,
+      sublicense, and distribute those modifications and additional rights
+      as a separate license, provided Your use, reproduction, modification,
+      preparation of Derivative Works, distribution, and other activities
+      remain in full compliance with the terms of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Suleyman Musayev
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleyman Musayev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,234 @@
+# ml_dsa
+
+Ruby C extension for **ML-DSA** (NIST FIPS 204), the post-quantum digital
+signature algorithm formerly known as CRYSTALS-Dilithium.
+
+Bundles the [PQClean](https://github.com/PQClean/PQClean) clean C
+implementation for all three standardized parameter sets:
+
+| Parameter Set | NIST Security Level | Public Key | Secret Key | Signature |
+|---------------|---------------------|------------|------------|-----------|
+| ML-DSA-44     | 2                   | 1,312 B    | 2,560 B    | 2,420 B   |
+| ML-DSA-65     | 3                   | 1,952 B    | 4,032 B    | 3,309 B   |
+| ML-DSA-87     | 5                   | 2,592 B    | 4,896 B    | 4,627 B   |
+
+## Installation
+
+```ruby
+gem "ml_dsa"
+```
+
+```sh
+gem install ml_dsa
+```
+
+Compile only a subset of parameter sets to reduce binary size:
+
+```sh
+gem install ml_dsa -- --with-ml-dsa-params=44,65
+bundle config build.ml_dsa --with-ml-dsa-params=65
+```
+
+### Requirements
+
+- Ruby >= 2.7.2
+- C11-compatible compiler (GCC, Clang, MSVC)
+- Linux, macOS (Intel + ARM), or Windows
+- No OpenSSL dependency
+
+## Usage
+
+### Key generation
+
+```ruby
+require "ml_dsa"
+
+pk, sk = MlDsa.keygen(MlDsa::ML_DSA_65)
+```
+
+Deterministic keygen from a 32-byte seed:
+
+```ruby
+seed = SecureRandom.random_bytes(32)
+pk, sk = MlDsa.keygen(MlDsa::ML_DSA_65, seed: seed)
+```
+
+### Signing and verification
+
+```ruby
+message = "Hello, post-quantum world!"
+
+signature = sk.sign(message)                          # hedged (randomized)
+signature = sk.sign(message, deterministic: true)     # deterministic
+signature = sk.sign(message, context: "app-v1")       # with FIPS 204 context
+
+pk.verify(message, signature)                         # => true
+pk.verify(message, signature, context: "app-v1")      # => true
+```
+
+### Batch operations
+
+Sign or verify multiple messages in a single GVL release:
+
+```ruby
+signatures = MlDsa.sign_many([
+  MlDsa::SignRequest.new(sk: sk, message: "msg1"),
+  MlDsa::SignRequest.new(sk: sk, message: "msg2"),
+])
+
+results = MlDsa.verify_many([
+  MlDsa::VerifyRequest.new(pk: pk, message: "msg1", signature: signatures[0]),
+  MlDsa::VerifyRequest.new(pk: pk, message: "msg2", signature: signatures[1]),
+])
+
+results.each do |r|
+  puts r.ok? ? "valid" : "failed: #{r.reason}"
+end
+```
+
+Block-based batch builder:
+
+```ruby
+sigs = MlDsa.batch { |b|
+  b.sign(sk: sk, message: "msg1")
+  b.sign(sk: sk, message: "msg2")
+}
+```
+
+### Serialization
+
+```ruby
+# Raw bytes — param_set auto-detected from byte size
+pk2 = MlDsa::PublicKey.from_bytes(pk.to_bytes)
+
+# Hex — param_set auto-detected from byte size
+pk3 = MlDsa::PublicKey.from_hex(pk.to_hex)
+
+# DER (SubjectPublicKeyInfo / PKCS#8) — param_set auto-detected from OID
+pk4 = MlDsa::PublicKey.from_der(pk.to_der)
+sk2 = MlDsa::SecretKey.from_der(sk.to_der)
+
+# PEM
+pk5 = MlDsa::PublicKey.from_pem(pk.to_pem)
+sk3 = MlDsa::SecretKey.from_pem(sk.to_pem)
+
+# Seed-only compact storage (32 bytes instead of full key)
+sk4 = MlDsa::SecretKey.from_seed(seed, MlDsa::ML_DSA_65)
+```
+
+### Key management
+
+```ruby
+# Secret keys from keygen/from_seed carry the associated public key
+sk.public_key == pk  # => true
+sk.seed              # => 32-byte seed (nil if not created from seed)
+
+# Keys deserialized from bytes/DER/PEM have no associated public key
+MlDsa::SecretKey.from_der(sk.to_der).public_key  # => nil
+
+# Fingerprint for logs and UIs (SHA-256 prefix, 32 hex chars)
+pk.fingerprint  # => "a3b1c9f0e2d4..."
+
+# Timestamps and metadata
+pk.created_at           # => Time
+sk.key_usage = :signing # application-defined label
+```
+
+### Secret key hygiene
+
+Secret keys live in C-managed memory with `mlock` (prevents swap) and
+`secure_zero` on GC. There is no `to_bytes` or `to_hex` on secret keys.
+
+```ruby
+# Controlled access — buffer is wiped on block exit, even on exception
+sk.with_bytes do |buf|
+  # buf is a temporary binary String
+end
+
+# Explicit wipe — subsequent operations raise MlDsa::Error
+sk.wipe!
+```
+
+### Pluggable RNG
+
+```ruby
+MlDsa.random_source = proc { |n| "\x42" * n }  # for testing / HSM
+MlDsa.random_source = nil                       # restore OS CSPRNG
+```
+
+### Instrumentation
+
+```ruby
+subscriber = MlDsa.subscribe do |event|
+  logger.info "#{event[:operation]} #{event[:param_set].name} " \
+              "count=#{event[:count]} duration=#{event[:duration_ns]}ns"
+end
+
+MlDsa.unsubscribe(subscriber)
+```
+
+Isolated configuration for per-Ractor or per-test contexts:
+
+```ruby
+cfg = MlDsa::Config.new
+cfg.random_source = proc { |n| SecureRandom.random_bytes(n) }
+pk, sk = MlDsa.keygen(MlDsa::ML_DSA_65, config: cfg)
+```
+
+### PQC namespace
+
+```ruby
+PQC::MlDsa == MlDsa       # => true
+PQC.algorithms             # => { ml_dsa: MlDsa }
+PQC.algorithm(:ml_dsa)     # => MlDsa
+```
+
+## Error handling
+
+```ruby
+begin
+  MlDsa::PublicKey.from_der(bad_data)
+rescue MlDsa::Error::Deserialization => e
+  e.message   # => "invalid DER: ..."
+  e.format    # => "DER"
+  e.position  # => 12
+  e.reason    # => :unknown_oid
+end
+```
+
+- `MlDsa::Error` — base class
+  - `MlDsa::Error::KeyGeneration`
+  - `MlDsa::Error::Signing`
+  - `MlDsa::Error::Deserialization` — includes `format`, `position`, `reason`
+
+## Security
+
+| Property | Implementation |
+|----------|---------------|
+| Secure zeroing | `SecureZeroMemory` / `explicit_bzero` / `memset_s` / volatile fallback |
+| Constant-time comparison | XOR-accumulate with compiler fence for secret key equality |
+| Memory locking | `mlock` prevents secret key pages from swapping to disk |
+| Thread-safe wipe | C11 `_Atomic` with acquire/release semantics |
+| GVL release | All crypto runs without the Global VM Lock |
+| Ractor safety | `PublicKey` is Ractor-shareable (`RUBY_TYPED_FROZEN_SHAREABLE`) |
+| Symbol isolation | `-fvisibility=hidden` prevents PQClean symbol clashes |
+| No OpenSSL | DER/PEM via [`pqc_asn1`](https://github.com/msuliq/pqc_asn1) gem |
+
+## Development
+
+```sh
+bundle install
+bundle exec rake compile
+bundle exec rake test
+bundle exec rake bench            # benchmarks (requires benchmark-ips)
+bundle exec rake yard             # API docs
+bundle exec standardrb            # Ruby lint
+bundle exec rake lint:c           # C static analysis (requires cppcheck)
+bundle exec rake pqclean:verify   # verify vendored PQClean patches
+bundle exec rake generate:impl    # regenerate amalgamation files
+```
+
+## License
+
+Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE),
+at your option.

data/ext/ml_dsa/extconf.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+# Allow selecting which parameter sets to compile at build time.
+# Defaults to all three. To compile only a subset:
+#   gem install ml_dsa -- --with-ml-dsa-params=65
+#   bundle config build.ml_dsa --with-ml-dsa-params=44,65
+params_config = with_config("ml-dsa-params", "44,65,87").to_s
+enabled = params_config
+  .split(",")
+  .filter_map { |s| Integer(s.strip) rescue nil } # standard:disable Style/RescueModifier
+  .select { |n| [44, 65, 87].include?(n) }
+  .uniq
+
+if enabled.empty?
+  abort "No valid ML-DSA parameter sets. " \
+        "Use --with-ml-dsa-params=44,65,87 (any non-empty subset)."
+end
+
+# Pass compile-time flags for each enabled parameter set
+enabled.each { |ps| $CFLAGS << " -DML_DSA_ENABLE_#{ps}" }
+
+# Compile only the impl files for enabled parameter sets;
+# fips202.c and randombytes.c are always needed.
+$srcs = %w[ml_dsa_ext.c fips202.c randombytes.c]
+enabled.each { |ps| $srcs << "ml_dsa_#{ps}_impl.c" }
+
+# -std=c11 for C11 features; -I$(srcdir) is added automatically by mkmf,
+# making fips202.h and randombytes.h visible to amalgamation impl files.
+# -fvisibility=hidden prevents PQClean helper symbols (shake256, poly_ntt,
+# etc.) from leaking into the process symbol table and conflicting with
+# other gems that bundle different versions of the same libraries.
+$CFLAGS << " -O2 -Wall -Wextra -Wshadow -std=c11"
+$CFLAGS << " -fvisibility=hidden" if try_cflags("-fvisibility=hidden")
+
+# Probe for platform-appropriate secure zeroing
+have_func("explicit_bzero", ["string.h"])
+have_func("memset_s", ["string.h"])
+
+# Probe for mlock (prevent secret key pages from being swapped to disk)
+have_func("mlock", ["sys/mman.h"])
+
+# Probe for Ractor safety API (Ruby 3.0+)
+have_func("rb_ext_ractor_safe", ["ruby.h"])
+
+create_makefile("ml_dsa/ml_dsa_ext")