mldsa_gh 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aed3bb631447f2cdb28c472cf08605aafb240a19a8833e0a4e5f66a1b39946d6
+  data.tar.gz: 1cb8657a920600ba10ac0baa7ca92ceeb3ce9db6adeefca3de3ddadef5aa968c
+SHA512:
+  metadata.gz: 0152a68f82bf5446a7b67d828f01f971dce522b512858cc5dc46e4d3e78be75c818dce581a118ce5e0f3b8279f0cd8658f8253a6452953ade62a48f7d041493e
+  data.tar.gz: c4aefcae2c3bb5055b0f7348c30eec5f96613f668db704ed2eaabf5c062205e6192e1db8b1211279c5644cceffd2fa376edf4dcc85cbdc448f1615799c6198ae

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vcsjones
+
+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,88 @@
+# ML-DSA GitHub
+
+Ruby bindings for ML-DSA using the vendored `mldsa-native`.
+
+## Usage
+
+```ruby
+require "mldsa_gh"
+
+signing_key = MLDSA::SigningKey.generate(MLDSA::ML_DSA_65)
+signature = signing_key.sign("message", context: "example")
+
+verify_key = signing_key.verify_key
+verify_key.verify(signature, "message", context: "example")
+```
+
+Import a private seed, private key, or public key:
+
+```ruby
+signing_key = MLDSA::SigningKey.new(seed, MLDSA::ML_DSA_44)
+signing_key = MLDSA::SigningKey.from_private_key(private_key, MLDSA::ML_DSA_44)
+verify_key = MLDSA::VerifyKey.new(public_key, MLDSA::ML_DSA_44)
+```
+
+Parameter sets are objects describing an ML-DSA parameter set and sizes:
+
+```ruby
+MLDSA::ML_DSA_44.public_key_size   # => 1312
+MLDSA::ML_DSA_44.private_key_size  # => 2560
+MLDSA::ML_DSA_44.signature_size    # => 2420
+```
+
+## External Mu
+
+ML-DSA signs in "pure" mode by default. That means callers provide the message bytes directly, rather than providing
+a pre-hash or externally computed message representative. mldsa-native still computes ML-DSA's internal message
+representative while signing. Pure mode is useful to avoid pre-hashing misuse, but it means the signer must have the
+entire message available to pass into the signing operation. This can make signing large inputs, such as files, difficult
+when buffering the full input in memory is not feasible.
+
+ML-DSA has an "external mu" mode where the message representative is computed externally and then passed to signing.
+This is similar to signing a digest in that the signing API receives a fixed-size value, but `mu` is not simply
+`SHAKE256(message)`, and external mu is not the same as HashML-DSA.
+
+External mu requires using the SHAKE-256 sponge function. It is defined as
+
+```
+SHAKE256(SHAKE256(public_key_bytes, 64) || 0x00 || context_size_byte || context || message, 64)
+```
+
+One way to compute `mu` is with the `sha3` gem. This example shows computing the mu for "helloworld", however
+broken up in to two operations.
+
+```ruby
+require "sha3"
+
+context = "example"
+message1 = "hello"
+message2 = "world"
+verify_key = signing_key.verify_key
+
+tr_hasher = SHA3::Digest::SHAKE_256.new
+tr_hasher << verify_key.to_bytes
+tr = tr_hasher.squeeze(64)
+
+mu_hasher = SHA3::Digest::SHAKE_256.new
+mu_hasher << tr
+mu_hasher << "\x00"
+mu_hasher << context.bytesize.chr # ML-DSA does not permit a context larger than 255 bytes.
+mu_hasher << context
+mu_hasher << message1
+mu_hasher << message2
+mu = mu_hasher.squeeze(signing_key.parameter_set.mu_size)
+
+# Sign 'helloworld' based on creating it from external mu.
+signature = signing_key.sign_mu(mu)
+
+# Verify it against 'helloworld' with our context to show that mu verifies against pure ML-DSA.
+verify_key.verify(signature, message1 + message2, context: context)
+
+# Or verify it against the externally computed mu
+verify_key.verify_mu(signature, mu)
+```
+
+## Comparison with `ruby/openssl`
+
+Ruby's `openssl` gem can also offer ML-DSA from OpenSSL. However, this requires OpenSSL 3.5 or later, which is fairly new
+and only starting to appear in very recent Linux distributions.

data/ext/mldsa_gh_native/extconf.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+$warnflags = ""
+$CFLAGS << " -O3 -std=c99"
+
+extension_dir = File.expand_path(__dir__)
+vendor_mldsa_dir = File.join(extension_dir, "vendor", "mldsa-native", "mldsa")
+
+$INCFLAGS << " -I#{vendor_mldsa_dir} -I#{extension_dir}"
+$srcs = ["mldsa_gh_native.c", "mldsa_gh_native_all.c"]
+
+create_makefile "mldsa_gh_native"

data/ext/mldsa_gh_native/mldsa_gh_native.c

@@ -0,0 +1,222 @@
+#if defined(__clang__)
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdefault-const-init-field-unsafe"
+#endif
+#include "ruby.h"
+#if defined(__clang__)
+#pragma clang diagnostic pop
+#endif
+
+#include <stdint.h>
+#include <string.h>
+
+#include "mldsa_gh_native_all.h"
+
+typedef int (*mldsa_keypair_from_seed_func)(uint8_t *, uint8_t *, const uint8_t *);
+typedef int (*mldsa_public_key_from_private_key_func)(uint8_t *, const uint8_t *);
+typedef int (*mldsa_sign_internal_func)(uint8_t *, const uint8_t *, size_t, const uint8_t *, size_t, const uint8_t *,
+                                        const uint8_t *, int);
+typedef int (*mldsa_verify_func)(const uint8_t *, const uint8_t *, size_t, const uint8_t *, size_t, const uint8_t *);
+typedef int (*mldsa_verify_mu_func)(const uint8_t *, const uint8_t *, const uint8_t *);
+typedef size_t (*mldsa_prepare_domain_separation_prefix_func)(uint8_t *, const uint8_t *, size_t, const uint8_t *, size_t, int);
+
+typedef struct {
+    int parameter_set;
+    size_t private_key_size;
+    size_t public_key_size;
+    size_t signature_size;
+    mldsa_keypair_from_seed_func keypair_from_seed;
+    mldsa_public_key_from_private_key_func public_key_from_private_key;
+    mldsa_sign_internal_func sign_internal;
+    mldsa_verify_func verify;
+    mldsa_verify_mu_func verify_mu;
+    mldsa_prepare_domain_separation_prefix_func prepare_domain_separation_prefix;
+} mldsa_parameter_set;
+
+static VALUE mMLDSA = Qnil;
+static VALUE mMLDSA_Native = Qnil;
+static const mldsa_parameter_set parameter_sets[] = {
+    {44, MLDSA44_SECRETKEYBYTES, MLDSA44_PUBLICKEYBYTES, MLDSA44_BYTES,
+     mldsa_gh44_keypair_internal, mldsa_gh44_pk_from_sk, mldsa_gh44_signature_internal,
+     mldsa_gh44_verify, mldsa_gh44_verify_extmu, mldsa_gh44_prepare_domain_separation_prefix},
+    {65, MLDSA65_SECRETKEYBYTES, MLDSA65_PUBLICKEYBYTES, MLDSA65_BYTES,
+     mldsa_gh65_keypair_internal, mldsa_gh65_pk_from_sk, mldsa_gh65_signature_internal,
+     mldsa_gh65_verify, mldsa_gh65_verify_extmu, mldsa_gh65_prepare_domain_separation_prefix},
+    {87, MLDSA87_SECRETKEYBYTES, MLDSA87_PUBLICKEYBYTES, MLDSA87_BYTES,
+     mldsa_gh87_keypair_internal, mldsa_gh87_pk_from_sk, mldsa_gh87_signature_internal,
+     mldsa_gh87_verify, mldsa_gh87_verify_extmu, mldsa_gh87_prepare_domain_separation_prefix}
+};
+
+static const mldsa_parameter_set *get_parameter_set(VALUE parameter_set)
+{
+    int requested = NUM2INT(parameter_set);
+    size_t i;
+
+    for (i = 0; i < sizeof(parameter_sets) / sizeof(parameter_sets[0]); i++) {
+        if (parameter_sets[i].parameter_set == requested) {
+            return &parameter_sets[i];
+        }
+    }
+
+    rb_raise(rb_eArgError, "expected parameter set 44, 65, or 87, got %d", requested);
+}
+
+static VALUE ensure_string_size(VALUE value, size_t expected_size, const char *name)
+{
+    StringValue(value);
+
+    if ((size_t)RSTRING_LEN(value) != expected_size) {
+        rb_raise(rb_eArgError, "expected %zu-byte %s, got %ld", expected_size, name, RSTRING_LEN(value));
+    }
+
+    return value;
+}
+
+static VALUE mMLDSA_Native_keypair_from_seed(VALUE self, VALUE parameter_set, VALUE seed)
+{
+    const mldsa_parameter_set *params = get_parameter_set(parameter_set);
+    VALUE private_key;
+    VALUE public_key;
+
+    (void)self;
+    seed = ensure_string_size(seed, MLDSA_SEEDBYTES, "private seed");
+
+    private_key = rb_str_new(NULL, (long)params->private_key_size);
+    public_key = rb_str_new(NULL, (long)params->public_key_size);
+
+    if (params->keypair_from_seed((uint8_t *)RSTRING_PTR(public_key), (uint8_t *)RSTRING_PTR(private_key),
+                                  (const uint8_t *)RSTRING_PTR(seed)) != 0) {
+        rb_raise(rb_eRuntimeError, "ML-DSA key generation failed");
+    }
+
+    return rb_ary_new_from_args(2, private_key, public_key);
+}
+
+static VALUE mMLDSA_Native_public_key_from_private_key(VALUE self, VALUE parameter_set, VALUE private_key)
+{
+    const mldsa_parameter_set *params = get_parameter_set(parameter_set);
+    VALUE public_key;
+
+    (void)self;
+    private_key = ensure_string_size(private_key, params->private_key_size, "private key");
+
+    public_key = rb_str_new(NULL, (long)params->public_key_size);
+
+    if (params->public_key_from_private_key((uint8_t *)RSTRING_PTR(public_key),
+                                            (const uint8_t *)RSTRING_PTR(private_key)) != 0) {
+        rb_raise(rb_eArgError, "invalid private key");
+    }
+
+    return public_key;
+}
+
+static VALUE mMLDSA_Native_sign(VALUE self, VALUE parameter_set, VALUE private_key, VALUE message, VALUE context,
+                                         VALUE randomness)
+{
+    const mldsa_parameter_set *params = get_parameter_set(parameter_set);
+    uint8_t pre[MLD_DOMAIN_SEPARATION_MAX_BYTES];
+    size_t prelen;
+    size_t context_length;
+    VALUE signature;
+
+    (void)self;
+    private_key = ensure_string_size(private_key, params->private_key_size, "private key");
+    randomness = ensure_string_size(randomness, MLDSA_RNDBYTES, "randomness");
+    StringValue(message);
+    StringValue(context);
+    context_length = (size_t)RSTRING_LEN(context);
+
+    /* mldsa-native's public randomized signing API obtains hedging randomness
+     * by calling mld_randombytes(). We generate that randomness in Ruby before
+     * entering native code instead, so native signing never calls back into Ruby
+     * while holding RSTRING_PTR values. signature_internal lets us provide that
+     * randomness explicitly, but it also requires us to provide mldsa-native's
+     * pure ML-DSA domain-separation prefix. */
+    prelen = params->prepare_domain_separation_prefix(
+        pre, NULL, 0, (const uint8_t *)RSTRING_PTR(context), context_length, MLD_PREHASH_NONE);
+    if (prelen == 0) {
+        rb_raise(rb_eArgError, "expected context to be at most 255 bytes, got %ld", RSTRING_LEN(context));
+    }
+
+    signature = rb_str_new(NULL, (long)params->signature_size);
+
+    if (params->sign_internal((uint8_t *)RSTRING_PTR(signature), (const uint8_t *)RSTRING_PTR(message),
+                              (size_t)RSTRING_LEN(message), pre, prelen, (const uint8_t *)RSTRING_PTR(randomness),
+                              (const uint8_t *)RSTRING_PTR(private_key), 0) != 0) {
+        rb_raise(rb_eRuntimeError, "ML-DSA signing failed");
+    }
+
+    return signature;
+}
+
+static VALUE mMLDSA_Native_verify(VALUE self, VALUE parameter_set, VALUE public_key, VALUE signature,
+                                           VALUE message, VALUE context)
+{
+    const mldsa_parameter_set *params = get_parameter_set(parameter_set);
+    int result;
+
+    (void)self;
+    public_key = ensure_string_size(public_key, params->public_key_size, "public key");
+    signature = ensure_string_size(signature, params->signature_size, "signature");
+    StringValue(message);
+    StringValue(context);
+
+    result = params->verify((const uint8_t *)RSTRING_PTR(signature), (const uint8_t *)RSTRING_PTR(message),
+                            (size_t)RSTRING_LEN(message),
+                            (const uint8_t *)RSTRING_PTR(context), (size_t)RSTRING_LEN(context),
+                            (const uint8_t *)RSTRING_PTR(public_key));
+
+    return result == 0 ? Qtrue : Qfalse;
+}
+
+static VALUE mMLDSA_Native_sign_mu(VALUE self, VALUE parameter_set, VALUE private_key, VALUE mu, VALUE randomness)
+{
+    const mldsa_parameter_set *params = get_parameter_set(parameter_set);
+    VALUE signature;
+
+    (void)self;
+    private_key = ensure_string_size(private_key, params->private_key_size, "private key");
+    mu = ensure_string_size(mu, MLDSA_CRHBYTES, "mu");
+    randomness = ensure_string_size(randomness, MLDSA_RNDBYTES, "randomness");
+
+    signature = rb_str_new(NULL, (long)params->signature_size);
+
+    if (params->sign_internal((uint8_t *)RSTRING_PTR(signature), (const uint8_t *)RSTRING_PTR(mu),
+                              (size_t)RSTRING_LEN(mu), NULL, 0, (const uint8_t *)RSTRING_PTR(randomness),
+                              (const uint8_t *)RSTRING_PTR(private_key), 1) != 0) {
+        rb_raise(rb_eRuntimeError, "ML-DSA external-mu signing failed");
+    }
+
+    return signature;
+}
+
+static VALUE mMLDSA_Native_verify_mu(VALUE self, VALUE parameter_set, VALUE public_key, VALUE signature, VALUE mu)
+{
+    const mldsa_parameter_set *params = get_parameter_set(parameter_set);
+    int result;
+
+    (void)self;
+    public_key = ensure_string_size(public_key, params->public_key_size, "public key");
+    signature = ensure_string_size(signature, params->signature_size, "signature");
+    mu = ensure_string_size(mu, MLDSA_CRHBYTES, "mu");
+
+    result = params->verify_mu((const uint8_t *)RSTRING_PTR(signature), (const uint8_t *)RSTRING_PTR(mu),
+                               (const uint8_t *)RSTRING_PTR(public_key));
+
+    return result == 0 ? Qtrue : Qfalse;
+}
+
+void Init_mldsa_gh_native(void)
+{
+    mMLDSA = rb_define_module("MLDSA");
+    mMLDSA_Native = rb_define_module_under(mMLDSA, "Native");
+    rb_define_singleton_method(mMLDSA_Native, "keypair_from_seed",
+                               mMLDSA_Native_keypair_from_seed, 2);
+    rb_define_singleton_method(mMLDSA_Native, "public_key_from_private_key",
+                               mMLDSA_Native_public_key_from_private_key, 2);
+    rb_define_singleton_method(mMLDSA_Native, "sign", mMLDSA_Native_sign, 5);
+    rb_define_singleton_method(mMLDSA_Native, "verify", mMLDSA_Native_verify, 5);
+    rb_define_singleton_method(mMLDSA_Native, "sign_mu", mMLDSA_Native_sign_mu, 4);
+    rb_define_singleton_method(mMLDSA_Native, "verify_mu", mMLDSA_Native_verify_mu, 4);
+
+}

data/ext/mldsa_gh_native/mldsa_gh_native_all.c

@@ -0,0 +1,24 @@
+#define MLD_CONFIG_NAMESPACE_PREFIX mldsa_gh
+#define MLD_CONFIG_MULTILEVEL_BUILD
+#define MLD_CONFIG_NO_RANDOMIZED_API
+
+#define MLD_CONFIG_MULTILEVEL_WITH_SHARED
+#define MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS
+#define MLD_CONFIG_PARAMETER_SET 44
+#include "vendor/mldsa-native/mldsa/mldsa_native.c"
+#undef MLD_CONFIG_PARAMETER_SET
+#undef MLD_CONFIG_MULTILEVEL_WITH_SHARED
+
+#define MLD_CONFIG_MULTILEVEL_NO_SHARED
+#define MLD_CONFIG_PARAMETER_SET 65
+#include "vendor/mldsa-native/mldsa/mldsa_native.c"
+#undef MLD_CONFIG_PARAMETER_SET
+#undef MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS
+
+#define MLD_CONFIG_PARAMETER_SET 87
+#include "vendor/mldsa-native/mldsa/mldsa_native.c"
+#undef MLD_CONFIG_PARAMETER_SET
+#undef MLD_CONFIG_MULTILEVEL_NO_SHARED
+#undef MLD_CONFIG_NO_RANDOMIZED_API
+#undef MLD_CONFIG_MULTILEVEL_BUILD
+#undef MLD_CONFIG_NAMESPACE_PREFIX

data/ext/mldsa_gh_native/mldsa_gh_native_all.h

@@ -0,0 +1,26 @@
+#ifndef RUBY_MLDSA_GH_NATIVE_ALL_H
+#define RUBY_MLDSA_GH_NATIVE_ALL_H
+
+#define MLD_CONFIG_NAMESPACE_PREFIX mldsa_gh
+#define MLD_CONFIG_MULTILEVEL_BUILD
+#define MLD_CONFIG_NO_RANDOMIZED_API
+
+#define MLD_CONFIG_PARAMETER_SET 44
+#include "mldsa_native.h"
+#undef MLD_CONFIG_PARAMETER_SET
+#undef MLD_H
+
+#define MLD_CONFIG_PARAMETER_SET 65
+#include "mldsa_native.h"
+#undef MLD_CONFIG_PARAMETER_SET
+#undef MLD_H
+
+#define MLD_CONFIG_PARAMETER_SET 87
+#include "mldsa_native.h"
+#undef MLD_CONFIG_PARAMETER_SET
+#undef MLD_CONFIG_NO_RANDOMIZED_API
+#undef MLD_CONFIG_MULTILEVEL_BUILD
+#undef MLD_CONFIG_NAMESPACE_PREFIX
+#undef MLD_H
+
+#endif

data/ext/mldsa_gh_native/vendor/mldsa-native/BUILDING.md

@@ -0,0 +1,108 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Building mldsa-native
+
+### Prerequisites
+
+To build **mldsa-native**, you need `make` and a C90 compiler. To use the test scripts, you need Python3 (>= 3.7).
+
+### By hand
+
+See [mldsa](mldsa).
+
+### Using `make`
+
+You can build and test **mldsa-native** as follows:
+
+```bash
+make test       # With native code backend (if available)
+make OPT=0 test # With C backend
+```
+
+To merely build test components, use the following `make` targets:
+
+```bash
+make func
+make kat
+make acvp
+```
+
+To run them, add `run_`:
+
+```bash
+make run_func
+make run_kat
+make run_acvp
+```
+
+The resulting binaries can be found in `test/build` (their full path is printed by `make`).
+
+For benchmarking, specify the cycle counting method. Currently, **mldsa-native** is supporting NO, PERF, PMU, and MAC:
+* `NO` means that no cycle counting will be used; this can be used to confirm that benchmarks compile fine.
+* `PERF` uses the `perf` kernel module for cycle counting. Does not work on Apple platforms.
+* `PMU` uses direct PMU access if available. On AArch64, this may require you to load a kernel module first, see [here](https://github.com/mupq/pqax?tab=readme-ov-file#enable-access-to-performance-counters). Does not work on Apple platforms.
+* `MAC` is `perf`-based and works on some Apple platforms, at least Apple M1.
+
+```
+# CYCLES has to be one of PERF, PMU, MAC, NO
+sudo make run_bench CYCLES=PERF
+sudo make run_bench_components CYCLES=PERF
+```
+
+### Using `tests` script
+
+For convenience, you can also use the [`./scripts/tests`](scripts/tests) script as a wrapper around `make`. For
+example,
+
+```bash
+./scripts/tests func
+```
+
+will compile and run functionality tests. Similarly,
+
+```bash
+./scripts/tests bench -c PERF -r
+```
+
+will compile and run benchmarks, using PERF for cycle counting (`-c PERF`) and running as root (`-r`).
+
+For detailed information on how to use the script, please refer to
+`./scripts/tests --help`.
+
+### Windows
+
+You can also build **mldsa-native** on Windows using `nmake` and an MSVC compiler.
+
+To build and run the tests, use the following `nmake` target:
+```powershell
+nmake /f .\Makefile.Microsoft_nmake quickcheck
+```
+
+This runs the functional, RNG-failure, allocation, ACVP, KAT and Wycheproof tests. The assembly backends are not yet
+supported on Windows, so the tests are built for the C backend only.
+
+# Checking the proofs
+
+## CBMC
+
+### Prerequisites
+
+To run the CBMC proofs, you need specific versions of CBMC and the underlying solvers, e.g. as specified in our `nix` environment; see [nix/cbmc](nix/cbmc/).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to setup and use `nix`.
+
+### Running the CBMC proofs
+
+Once you are in the `nix` shell or have all tools setup by hand, use `./scripts/tests cbmc` (or just `tests cbmc` in the `nix` shell) to re-check the CBMC proofs.
+See `tests cbmc --help` for details on the command line options, and [proofs/cbmc](proofs/cbmc) for more details on the CBMC proofs in general.
+
+## HOL-Light
+
+### Prerequisites
+
+To run the HOL-Light proofs, you need recent versions of HOL-Light and s2n-bignum, e.g. as specified in our `nix` environment; see [nix/s2n_bignum](nix/s2n_bignum) and [nix/hol_light](nix/hol_light).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to setup and use `nix`.
+
+### Running the HOL-Light proofs
+
+Once you are in the `nix` shell or have all tools setup by hand, use `./scripts/tests hol_light` (or just `tests hol_light` in the `nix` shell) to re-check the HOL-Light proofs. Note that depending on the function, they will take a long time. See `tests hol_light --help` for details on the command line options, and [proofs/hol_light](proofs/hol_light) for more details on the HOL-Light proofs in general.
+