mldsa_gh 0.1.0

data/ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/symmetric.h

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) The mldsa-native project authors
+ * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+ */
+#ifndef MLD_SYMMETRIC_H
+#define MLD_SYMMETRIC_H
+
+#include "cbmc.h"
+#include "common.h"
+
+#include MLD_FIPS202_HEADER_FILE
+#if !defined(MLD_CONFIG_SERIAL_FIPS202_ONLY)
+#include MLD_FIPS202X4_HEADER_FILE
+#endif
+
+#define MLD_STREAM128_BLOCKBYTES SHAKE128_RATE
+#define MLD_STREAM256_BLOCKBYTES SHAKE256_RATE
+
+#define mld_xof256_ctx mld_shake256ctx
+#define mld_xof256_init(CTX) mld_shake256_init(CTX)
+
+#define mld_xof256_absorb_once(CTX, IN, INBYTES) \
+  do                                             \
+  {                                              \
+    mld_shake256_absorb(CTX, IN, INBYTES);       \
+    mld_shake256_finalize(CTX);                  \
+  } while (0)
+
+
+#define mld_xof256_release(CTX) mld_shake256_release(CTX)
+#define mld_xof256_squeezeblocks(OUT, OUTBLOCKS, STATE) \
+  mld_shake256_squeeze(OUT, (OUTBLOCKS) * SHAKE256_RATE, STATE)
+
+#define mld_xof128_ctx mld_shake128ctx
+#define mld_xof128_init(CTX) mld_shake128_init(CTX)
+
+#define mld_xof128_absorb_once(CTX, IN, INBYTES) \
+  do                                             \
+  {                                              \
+    mld_shake128_absorb(CTX, IN, INBYTES);       \
+    mld_shake128_finalize(CTX);                  \
+  } while (0)
+
+#define mld_xof128_release(CTX) mld_shake128_release(CTX)
+#define mld_xof128_squeezeblocks(OUT, OUTBLOCKS, STATE) \
+  mld_shake128_squeeze(OUT, (OUTBLOCKS) * SHAKE128_RATE, STATE)
+
+#define mld_xof256_x4_ctx mld_shake256x4ctx
+#define mld_xof256_x4_init(CTX) mld_shake256x4_init((CTX))
+#define mld_xof256_x4_absorb(CTX, IN, INBYTES)                          \
+  mld_shake256x4_absorb_once((CTX), (IN)[0], (IN)[1], (IN)[2], (IN)[3], \
+                             (INBYTES))
+#define mld_xof256_x4_squeezeblocks(BUF, NBLOCKS, CTX)                 \
+  mld_shake256x4_squeezeblocks((BUF)[0], (BUF)[1], (BUF)[2], (BUF)[3], \
+                               (NBLOCKS), (CTX))
+#define mld_xof256_x4_release(CTX) mld_shake256x4_release((CTX))
+
+#define mld_xof128_x4_ctx mld_shake128x4ctx
+#define mld_xof128_x4_init(CTX) mld_shake128x4_init((CTX))
+#define mld_xof128_x4_absorb(CTX, IN, INBYTES)                          \
+  mld_shake128x4_absorb_once((CTX), (IN)[0], (IN)[1], (IN)[2], (IN)[3], \
+                             (INBYTES))
+#define mld_xof128_x4_squeezeblocks(BUF, NBLOCKS, CTX)                 \
+  mld_shake128x4_squeezeblocks((BUF)[0], (BUF)[1], (BUF)[2], (BUF)[3], \
+                               (NBLOCKS), (CTX))
+#define mld_xof128_x4_release(CTX) mld_shake128x4_release((CTX))
+
+#endif /* !MLD_SYMMETRIC_H */

data/ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/sys.h

@@ -0,0 +1,327 @@
+/*
+ * Copyright (c) The mlkem-native project authors
+ * Copyright (c) The mldsa-native project authors
+ * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+ */
+
+#ifndef MLD_SYS_H
+#define MLD_SYS_H
+
+#if !defined(MLD_CONFIG_NO_ASM) && (defined(__GNUC__) || defined(__clang__))
+#define MLD_HAVE_INLINE_ASM
+#endif
+
+/* Try to find endianness, if not forced through CFLAGS already */
+#if !defined(MLD_SYS_LITTLE_ENDIAN) && !defined(MLD_SYS_BIG_ENDIAN)
+#if defined(__BYTE_ORDER__)
+#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+#define MLD_SYS_LITTLE_ENDIAN
+#elif __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
+#define MLD_SYS_BIG_ENDIAN
+#else
+#error "__BYTE_ORDER__ defined, but don't recognize value."
+#endif
+#endif /* __BYTE_ORDER__ */
+
+/* MSVC does not define __BYTE_ORDER__. However, MSVC only supports
+ * little endian x86, x86_64, and AArch64. It is, hence, safe to assume
+ * little endian. */
+#if defined(_MSC_VER) && (defined(_M_X64) || defined(_M_AMD64) || \
+                          defined(_M_IX86) || defined(_M_ARM64))
+#define MLD_SYS_LITTLE_ENDIAN
+#endif
+
+#endif /* !MLD_SYS_LITTLE_ENDIAN && !MLD_SYS_BIG_ENDIAN */
+
+/* Check if we're running on an AArch64 little endian system. _M_ARM64 is set by
+ * MSVC. */
+#if defined(__AARCH64EL__) || defined(_M_ARM64)
+#define MLD_SYS_AARCH64
+#endif
+
+/* Check if the AArch64 compilation target supports NEON (Advanced SIMD).
+ *
+ * Some compilers also define __ARM_NEON__, but __ARM_NEON is the most reliable
+ * signal. Specifically, clang on Apple appears to keep __ARM_NEON__ set even if
+ * -march=armv8-a+nosimd is set.
+ *
+ * gcc 4.8 -- the first gcc version introducing Neon support -- sets neither
+ * __ARM_NEON nor __ARM_NEON__; in fact, there is no preprocessor signal that
+ * Neon is enabled. If you use gcc 4.8 and need Neon, you should set
+ * MLD_SYS_AARCH64_NEON manually. gcc 4.9 onwards do set __ARM_NEON.
+ */
+#if defined(MLD_SYS_AARCH64) && defined(__ARM_NEON)
+#define MLD_SYS_AARCH64_NEON
+#endif
+
+/* Check if we're running on an AArch64 big endian system. */
+#if defined(__AARCH64EB__)
+#define MLD_SYS_AARCH64_EB
+#endif
+
+/* Check if we're running on an Armv8.1-M system with MVE */
+#if defined(__ARM_ARCH_8_1M_MAIN__) || defined(__ARM_FEATURE_MVE)
+#define MLD_SYS_ARMV81M_MVE
+#endif
+
+/* Check if we're running on an x86_64 system. */
+#if defined(__x86_64__) || defined(_M_X64) || defined(_M_AMD64)
+#define MLD_SYS_X86_64
+#if defined(__AVX2__)
+#define MLD_SYS_X86_64_AVX2
+#endif
+#endif /* __x86_64__ || _M_X64 || _M_AMD64 */
+
+#if defined(MLD_SYS_LITTLE_ENDIAN) && defined(__powerpc64__)
+#define MLD_SYS_PPC64LE
+#endif
+
+#if defined(__riscv) && defined(__riscv_xlen) && __riscv_xlen == 64
+#define MLD_SYS_RISCV64
+#endif
+
+#if defined(MLD_SYS_RISCV64) && defined(__riscv_vector) && \
+    defined(__riscv_v_intrinsic)
+#define MLD_SYS_RISCV64_RVV
+#endif
+
+#if defined(__riscv) && defined(__riscv_xlen) && __riscv_xlen == 32
+#define MLD_SYS_RISCV32
+#endif
+
+#if defined(_WIN64) || defined(_WIN32)
+#define MLD_SYS_WINDOWS
+#endif
+
+#if defined(__linux__)
+#define MLD_SYS_LINUX
+#endif
+
+#if defined(__APPLE__)
+#define MLD_SYS_APPLE
+#endif
+
+/* If MLD_FORCE_AARCH64 is set, assert that we're indeed on an AArch64 system.
+ */
+#if defined(MLD_FORCE_AARCH64) && !defined(MLD_SYS_AARCH64)
+#error "MLD_FORCE_AARCH64 is set, but we don't seem to be on an AArch64 system."
+#endif
+
+/* If MLD_FORCE_AARCH64_EB is set, assert that we're indeed on a big endian
+ * AArch64 system. */
+#if defined(MLD_FORCE_AARCH64_EB) && !defined(MLD_SYS_AARCH64_EB)
+#error \
+    "MLD_FORCE_AARCH64_EB is set, but we don't seem to be on an AArch64 system."
+#endif
+
+/* If MLD_FORCE_X86_64 is set, assert that we're indeed on an X86_64 system. */
+#if defined(MLD_FORCE_X86_64) && !defined(MLD_SYS_X86_64)
+#error "MLD_FORCE_X86_64 is set, but we don't seem to be on an X86_64 system."
+#endif
+
+#if defined(MLD_FORCE_PPC64LE) && !defined(MLD_SYS_PPC64LE)
+#error "MLD_FORCE_PPC64LE is set, but we don't seem to be on a PPC64LE system."
+#endif
+
+#if defined(MLD_FORCE_RISCV64) && !defined(MLD_SYS_RISCV64)
+#error "MLD_FORCE_RISCV64 is set, but we don't seem to be on a RISCV64 system."
+#endif
+
+#if defined(MLD_FORCE_RISCV32) && !defined(MLD_SYS_RISCV32)
+#error "MLD_FORCE_RISCV32 is set, but we don't seem to be on a RISCV32 system."
+#endif
+
+/*
+ * MLD_INLINE: Hint for inlining.
+ * - MSVC: __inline
+ * - C99+: inline
+ * - GCC/Clang C90: __attribute__((unused)) to silence warnings
+ * - Other C90: empty
+ */
+#if !defined(MLD_INLINE)
+#if defined(_MSC_VER)
+#define MLD_INLINE __inline
+#elif defined(inline) || \
+    (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L)
+#define MLD_INLINE inline
+#elif defined(__GNUC__) || defined(__clang__)
+#define MLD_INLINE __attribute__((unused))
+#else
+#define MLD_INLINE
+#endif
+#endif /* !MLD_INLINE */
+
+/*
+ * MLD_ALWAYS_INLINE: Force inlining.
+ * - MSVC: __forceinline
+ * - GCC/Clang C99+: MLD_INLINE __attribute__((always_inline))
+ * - Other: MLD_INLINE (no forced inlining)
+ */
+#if !defined(MLD_ALWAYS_INLINE)
+#if defined(_MSC_VER)
+#define MLD_ALWAYS_INLINE __forceinline
+#elif (defined(__GNUC__) || defined(__clang__)) && \
+    (defined(inline) ||                            \
+     (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L))
+#define MLD_ALWAYS_INLINE MLD_INLINE __attribute__((always_inline))
+#else
+#define MLD_ALWAYS_INLINE MLD_INLINE
+#endif
+#endif /* !MLD_ALWAYS_INLINE */
+
+/*
+ * MLD_NOINLINE: Prevent inlining.
+ * - MSVC: __declspec(noinline)
+ * - GCC/Clang: __attribute__((noinline))
+ * - Other: empty
+ */
+#if !defined(MLD_NOINLINE)
+#if defined(_MSC_VER)
+#define MLD_NOINLINE __declspec(noinline)
+#elif defined(__GNUC__) || defined(__clang__)
+#define MLD_NOINLINE __attribute__((noinline))
+#else
+#define MLD_NOINLINE
+#endif
+#endif /* !MLD_NOINLINE */
+
+#ifndef MLD_STATIC_TESTABLE
+#define MLD_STATIC_TESTABLE static
+#endif
+
+/*
+ * C90 does not have the restrict compiler directive yet.
+ * We don't use it in C90 builds.
+ */
+#if !defined(restrict)
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
+#define MLD_RESTRICT restrict
+#else
+#define MLD_RESTRICT
+#endif
+
+#else /* !restrict */
+
+#define MLD_RESTRICT restrict
+#endif /* restrict */
+
+#define MLD_DEFAULT_ALIGN 32
+#define MLD_ALIGN_UP(N) \
+  ((((N) + (MLD_DEFAULT_ALIGN - 1)) / MLD_DEFAULT_ALIGN) * MLD_DEFAULT_ALIGN)
+#if defined(__GNUC__)
+#define MLD_ALIGN __attribute__((aligned(MLD_DEFAULT_ALIGN)))
+#elif defined(_MSC_VER)
+#define MLD_ALIGN __declspec(align(MLD_DEFAULT_ALIGN))
+#else
+#define MLD_ALIGN /* No known support for alignment constraints */
+#endif
+
+
+/* New X86_64 CPUs support control-flow protection using the CET instructions.
+ * When enabled (through -fcf-protection=), all compilation units (including
+ * empty ones) need to support CET for this to work.
+ * For assembly, this means that source files need to signal support for
+ * CET by setting the appropriate note.gnu.property section.
+ * This can be achieved by including the <cet.h> header in all assembly file.
+ * This file also provides the _CET_ENDBR macro which needs to be placed at
+ * every potential target of an indirect branch.
+ * If CET is enabled _CET_ENDBR maps to the endbr64 instruction, otherwise
+ * it is empty.
+ * In case the compiler does not support CET (e.g., <gcc8, <clang11),
+ * the __CET__ macro is not set and we default to nothing.
+ * Note that we only issue _CET_ENDBR instructions through the MLD_ASM_FN_SYMBOL
+ * macro as the global symbols are the only possible targets of indirect
+ * branches in our code.
+ */
+#if defined(MLD_SYS_X86_64)
+#if defined(__CET__)
+#include <cet.h>
+#define MLD_CET_ENDBR _CET_ENDBR
+#else
+#define MLD_CET_ENDBR
+#endif
+#endif /* MLD_SYS_X86_64 */
+
+#if defined(MLD_CONFIG_CT_TESTING_ENABLED) && !defined(__ASSEMBLER__)
+#include <valgrind/memcheck.h>
+#define MLD_CT_TESTING_SECRET(ptr, len) \
+  VALGRIND_MAKE_MEM_UNDEFINED((ptr), (len))
+#define MLD_CT_TESTING_DECLASSIFY(ptr, len) \
+  VALGRIND_MAKE_MEM_DEFINED((ptr), (len))
+#else /* MLD_CONFIG_CT_TESTING_ENABLED && !__ASSEMBLER__ */
+#define MLD_CT_TESTING_SECRET(ptr, len) \
+  do                                    \
+  {                                     \
+  } while (0)
+#define MLD_CT_TESTING_DECLASSIFY(ptr, len) \
+  do                                        \
+  {                                         \
+  } while (0)
+#endif /* !(MLD_CONFIG_CT_TESTING_ENABLED && !__ASSEMBLER__) */
+
+#if defined(__GNUC__) || defined(__clang__)
+#define MLD_MUST_CHECK_RETURN_VALUE __attribute__((warn_unused_result))
+#else
+#define MLD_MUST_CHECK_RETURN_VALUE
+#endif
+
+/* The x86_64 assembly backend uses the SysV calling convention. On Windows,
+ * where the Microsoft x64 calling convention is the default, it can still be
+ * used with compilers that allow choosing the calling convention per
+ * function: GCC and Clang support __attribute__((sysv_abi)), which makes
+ * calls to the annotated function follow the SysV calling convention.
+ *
+ * MLD_SYSV_ABI_SUPPORTED signals that the toolchain can call SysV assembly
+ * routines; the x86_64 assembly backend is only enabled if it is defined.
+ * MLD_SYSV_ABI is the attribute carried by declarations of x86_64 assembly
+ * routines. Both macros can be set externally for toolchains offering an
+ * equivalent mechanism that is not recognized here. */
+#if defined(MLD_SYS_X86_64) && !defined(MLD_SYSV_ABI_SUPPORTED)
+#if !defined(MLD_SYS_WINDOWS) || defined(__GNUC__) || defined(__clang__)
+#define MLD_SYSV_ABI_SUPPORTED
+#endif
+#endif
+
+#if !defined(MLD_SYSV_ABI)
+#if defined(MLD_SYS_WINDOWS) && defined(MLD_SYSV_ABI_SUPPORTED)
+#define MLD_SYSV_ABI __attribute__((sysv_abi))
+#else
+#define MLD_SYSV_ABI
+#endif
+#endif /* !MLD_SYSV_ABI */
+
+#if !defined(__ASSEMBLER__)
+/* System capability enumeration */
+typedef enum
+{
+  /* x86_64 */
+  MLD_SYS_CAP_X86_64_AVX2,
+  /* AArch64 */
+  MLD_SYS_CAP_AARCH64_NEON,
+  MLD_SYS_CAP_AARCH64_SHA3,
+  /* Armv8.1-M */
+  MLD_SYS_CAP_ARMV81M_MVE
+} mld_sys_cap;
+
+#if !defined(MLD_CONFIG_CUSTOM_CAPABILITY_FUNC)
+#include "cbmc.h"
+
+MLD_MUST_CHECK_RETURN_VALUE
+static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap)
+__contract__(
+  ensures(return_value == 0 || return_value == 1)
+)
+{
+  /* By default, we rely on compile-time feature detection/specification:
+   * If a feature is enabled at compile-time, we assume it is supported by
+   * the host that the resulting library/binary will be built on.
+   * If this assumption is not true, you MUST overwrite this function.
+   * See the documentation of MLD_CONFIG_CUSTOM_CAPABILITY_FUNC in
+   * mldsa_native_config.h for more information. */
+  (void)cap;
+  return 1;
+}
+#endif /* !MLD_CONFIG_CUSTOM_CAPABILITY_FUNC */
+#endif /* !__ASSEMBLER__ */
+
+#endif /* !MLD_SYS_H */

data/ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/zetas.inc

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) The mldsa-native project authors
+ * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+ */
+
+/*
+ * WARNING: This file is auto-generated from scripts/autogen
+ *          in the mldsa-native repository.
+ *          Do not modify it directly.
+ */
+
+
+/*
+ * Table of zeta values used in the reference NTT and inverse NTT.
+ * See autogen for details.
+ */
+static const int32_t mld_zetas[MLDSA_N] = {
+    0,        25847,    -2608894, -518909,  237124,   -777960,  -876248,
+    466468,   1826347,  2353451,  -359251,  -2091905, 3119733,  -2884855,
+    3111497,  2680103,  2725464,  1024112,  -1079900, 3585928,  -549488,
+    -1119584, 2619752,  -2108549, -2118186, -3859737, -1399561, -3277672,
+    1757237,  -19422,   4010497,  280005,   2706023,  95776,    3077325,
+    3530437,  -1661693, -3592148, -2537516, 3915439,  -3861115, -3043716,
+    3574422,  -2867647, 3539968,  -300467,  2348700,  -539299,  -1699267,
+    -1643818, 3505694,  -3821735, 3507263,  -2140649, -1600420, 3699596,
+    811944,   531354,   954230,   3881043,  3900724,  -2556880, 2071892,
+    -2797779, -3930395, -1528703, -3677745, -3041255, -1452451, 3475950,
+    2176455,  -1585221, -1257611, 1939314,  -4083598, -1000202, -3190144,
+    -3157330, -3632928, 126922,   3412210,  -983419,  2147896,  2715295,
+    -2967645, -3693493, -411027,  -2477047, -671102,  -1228525, -22981,
+    -1308169, -381987,  1349076,  1852771,  -1430430, -3343383, 264944,
+    508951,   3097992,  44288,    -1100098, 904516,   3958618,  -3724342,
+    -8578,    1653064,  -3249728, 2389356,  -210977,  759969,   -1316856,
+    189548,   -3553272, 3159746,  -1851402, -2409325, -177440,  1315589,
+    1341330,  1285669,  -1584928, -812732,  -1439742, -3019102, -3881060,
+    -3628969, 3839961,  2091667,  3407706,  2316500,  3817976,  -3342478,
+    2244091,  -2446433, -3562462, 266997,   2434439,  -1235728, 3513181,
+    -3520352, -3759364, -1197226, -3193378, 900702,   1859098,  909542,
+    819034,   495491,   -1613174, -43260,   -522500,  -655327,  -3122442,
+    2031748,  3207046,  -3556995, -525098,  -768622,  -3595838, 342297,
+    286988,   -2437823, 4108315,  3437287,  -3342277, 1735879,  203044,
+    2842341,  2691481,  -2590150, 1265009,  4055324,  1247620,  2486353,
+    1595974,  -3767016, 1250494,  2635921,  -3548272, -2994039, 1869119,
+    1903435,  -1050970, -1333058, 1237275,  -3318210, -1430225, -451100,
+    1312455,  3306115,  -1962642, -1279661, 1917081,  -2546312, -1374803,
+    1500165,  777191,   2235880,  3406031,  -542412,  -2831860, -1671176,
+    -1846953, -2584293, -3724270, 594136,   -3776993, -2013608, 2432395,
+    2454455,  -164721,  1957272,  3369112,  185531,   -1207385, -3183426,
+    162844,   1616392,  3014001,  810149,   1652634,  -3694233, -1799107,
+    -3038916, 3523897,  3866901,  269760,   2213111,  -975884,  1717735,
+    472078,   -426683,  1723600,  -1803090, 1910376,  -1667432, -1104333,
+    -260646,  -3833893, -2939036, -2235985, -420899,  -2286327, 183443,
+    -976891,  1612842,  -3545687, -554416,  3919660,  -48306,   -1362209,
+    3937738,  1400424,  -846154,  1976782,
+};

data/lib/mldsa/parameter_set.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module MLDSA
+  # ML-DSA parameter set metadata.
+  class ParameterSet
+    # @return [Integer] mldsa-native numeric identifier
+    attr_reader :identifier
+
+    # @return [Integer] private seed size in bytes
+    attr_reader :seed_size
+
+    # @return [Integer] expanded private key size in bytes
+    attr_reader :private_key_size
+
+    # @return [Integer] public key size in bytes
+    attr_reader :public_key_size
+
+    # @return [Integer] signature size in bytes
+    attr_reader :signature_size
+
+    # @return [Integer] external message representative size in bytes
+    attr_reader :mu_size
+
+    # @return [Integer] hedging randomness size in bytes
+    attr_reader :random_size
+
+    # @api private
+    def initialize(identifier:, private_key_size:, public_key_size:, signature_size:)
+      @identifier = identifier
+      @seed_size = MLDSA::SEED_SIZE
+      @private_key_size = private_key_size
+      @public_key_size = public_key_size
+      @signature_size = signature_size
+      @mu_size = MLDSA::MU_SIZE
+      @random_size = MLDSA::RANDOM_SIZE
+    end
+
+    # Compare parameter sets by their metadata.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) &&
+        identifier == other.identifier &&
+        seed_size == other.seed_size &&
+        private_key_size == other.private_key_size &&
+        public_key_size == other.public_key_size &&
+        signature_size == other.signature_size &&
+        mu_size == other.mu_size &&
+        random_size == other.random_size
+    end
+
+    # @see #==
+    def eql?(other)
+      self == other
+    end
+
+    # @return [Integer]
+    def hash
+      [
+        self.class,
+        identifier,
+        seed_size,
+        private_key_size,
+        public_key_size,
+        signature_size,
+        mu_size,
+        random_size
+      ].hash
+    end
+
+    # @return [String]
+    def to_s
+      "ML-DSA-#{identifier}"
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class}:#{object_id} #{self}>"
+    end
+  end
+end

data/lib/mldsa/signing_key.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module MLDSA
+  # Private key for producing ML-DSA signatures.
+  class SigningKey
+    # @return [MLDSA::VerifyKey] public key corresponding to this signing key
+    attr_reader :verify_key
+
+    # @return [MLDSA::ParameterSet] ML-DSA parameter set for this key
+    attr_reader :parameter_set
+
+    # Generate a random ML-DSA signing key for the given parameter set.
+    #
+    # @param parameter_set [MLDSA::ParameterSet] one of {MLDSA::ML_DSA_44}, {MLDSA::ML_DSA_65}, or {MLDSA::ML_DSA_87}
+    # @return [MLDSA::SigningKey]
+    # @raise [ArgumentError] if the parameter set is not supported
+    def self.generate(parameter_set)
+      parameter_set = MLDSA.validate_parameter_set(parameter_set)
+      new SecureRandom.random_bytes(parameter_set.seed_size), parameter_set
+    end
+
+    # Import a signing key from an expanded private key.
+    #
+    # The private seed is not recoverable from keys imported this way.
+    #
+    # @param private_key [String] serialized expanded private key bytes
+    # @param parameter_set [MLDSA::ParameterSet] one of {MLDSA::ML_DSA_44}, {MLDSA::ML_DSA_65}, or {MLDSA::ML_DSA_87}
+    # @return [MLDSA::SigningKey]
+    # @raise [ArgumentError] if the parameter set is unsupported, the key has the wrong size, or the key is invalid
+    # @raise [TypeError] if private_key is not a String
+    def self.from_private_key(private_key, parameter_set)
+      parameter_set = MLDSA.validate_parameter_set(parameter_set)
+      MLDSA.validate_bytes(private_key, parameter_set.private_key_size, "private key")
+      private_key = MLDSA.copy_bytes(private_key)
+
+      public_key = Native.public_key_from_private_key(parameter_set.identifier, private_key)
+      new_from_private_key(private_key, public_key, parameter_set)
+    end
+
+    # Import a signing key from a private seed.
+    #
+    # @param seed [String] {MLDSA::SEED_SIZE}-byte private seed
+    # @param parameter_set [MLDSA::ParameterSet] one of {MLDSA::ML_DSA_44}, {MLDSA::ML_DSA_65}, or {MLDSA::ML_DSA_87}
+    # @param public_key [String, nil] optional public key expected to match the seed
+    # @raise [ArgumentError] if the parameter set is unsupported, seed has the wrong size, public_key has the wrong size, or public_key does not match the seed
+    # @raise [TypeError] if seed or public_key is not a String
+    def initialize(seed, parameter_set, public_key: nil)
+      parameter_set = MLDSA.validate_parameter_set(parameter_set)
+      MLDSA.validate_bytes(seed, parameter_set.seed_size, "private seed")
+      MLDSA.validate_bytes(public_key, parameter_set.public_key_size, "public key") if public_key
+
+      @parameter_set = parameter_set
+      @seed = MLDSA.copy_bytes(seed)
+      private_key, derived_public_key = Native.keypair_from_seed(parameter_set.identifier, @seed)
+
+      raise ArgumentError, "public key does not match private seed" if public_key && public_key != derived_public_key
+
+      @private_key = MLDSA.copy_bytes(private_key)
+      @verify_key = VerifyKey.new(derived_public_key, parameter_set)
+    end
+
+    # Export the private seed.
+    #
+    # @return [String] mutable copy of the private seed
+    # @raise [MLDSA::SeedUnavailableError] if this key was imported from an expanded private key
+    def seed
+      return @seed.dup if @seed
+
+      raise SeedUnavailableError, "private seed is unavailable for keys imported from a private key"
+    end
+
+    # @see #seed
+    alias private_seed seed
+
+    # Export the expanded private key.
+    #
+    # @return [String] mutable copy of the expanded private key
+    def private_key
+      @private_key.dup
+    end
+
+    # Sign a message using hedged ML-DSA.
+    #
+    # @param message [String] message to sign
+    # @param context [String] optional application context, at most 255 bytes
+    # @return [String] signature bytes
+    # @raise [ArgumentError] if context is too large
+    # @raise [TypeError] if context is not a String
+    def sign(message, context: "")
+      MLDSA.validate_context(context)
+      Native.sign(parameter_set.identifier, @private_key, message, context, SecureRandom.random_bytes(parameter_set.random_size))
+    end
+
+    # Sign a precomputed external message representative.
+    #
+    # This method does not compute `mu`; callers must provide the exact
+    # {MLDSA::MU_SIZE}-byte value.
+    #
+    # @param mu [String] precomputed external message representative
+    # @return [String] signature bytes
+    # @raise [ArgumentError] if mu has the wrong size
+    # @raise [TypeError] if mu is not a String
+    def sign_mu(mu)
+      MLDSA.validate_bytes(mu, parameter_set.mu_size, "mu")
+      Native.sign_mu(parameter_set.identifier, @private_key, mu, SecureRandom.random_bytes(parameter_set.random_size))
+    end
+
+    # Export the expanded private key.
+    #
+    # @return [String] mutable copy of the expanded private key
+    def private_key_bytes
+      private_key
+    end
+
+    # @see #private_key_bytes
+    alias to_private_key private_key_bytes
+
+    # Export the private seed.
+    #
+    # @return [String] mutable copy of the private seed
+    # @raise [MLDSA::SeedUnavailableError] if this key was imported from an expanded private key
+    def to_bytes
+      seed
+    end
+
+    # Redacted string representation.
+    #
+    # @return [String]
+    def to_s
+      "#<#{self.class}:#{object_id} parameter_set=#{parameter_set}>"
+    end
+
+    # @see #to_s
+    alias inspect to_s
+
+    # @api private
+    def self.new_from_private_key(private_key, public_key, parameter_set)
+      allocate.tap do |key|
+        key.instance_variable_set(:@parameter_set, parameter_set)
+        key.instance_variable_set(:@seed, nil)
+        key.instance_variable_set(:@private_key, MLDSA.copy_bytes(private_key))
+        key.instance_variable_set(:@verify_key, VerifyKey.new(public_key, parameter_set))
+      end
+    end
+    private_class_method :new_from_private_key
+  end
+end