mldsa_gh 0.1.0

data/lib/mldsa/verify_key.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module MLDSA
+  # Public key for verifying ML-DSA signatures.
+  class VerifyKey
+    # @return [MLDSA::ParameterSet] ML-DSA parameter set for this key
+    attr_reader :parameter_set
+
+    # Import a public verification key.
+    #
+    # @param key [String] serialized public key bytes
+    # @param parameter_set [MLDSA::ParameterSet] one of {MLDSA::ML_DSA_44}, {MLDSA::ML_DSA_65}, or {MLDSA::ML_DSA_87}
+    # @raise [ArgumentError] if the parameter set is unsupported or the key has the wrong size
+    # @raise [TypeError] if key is not a String
+    def initialize(key, parameter_set)
+      parameter_set = MLDSA.validate_parameter_set(parameter_set)
+      MLDSA.validate_bytes(key, parameter_set.public_key_size, "public key")
+
+      @parameter_set = parameter_set
+      @key_bytes = MLDSA.copy_bytes(key)
+    end
+
+    # Verify a signature over a message and optional context.
+    #
+    # @param signature [String] signature bytes
+    # @param message [String] signed message
+    # @param context [String] optional application context, at most 255 bytes
+    # @return [true] when verification succeeds
+    # @raise [MLDSA::VerifyError] if verification fails
+    # @raise [ArgumentError] if signature has the wrong size or context is too large
+    # @raise [TypeError] if context is not a String
+    def verify(signature, message, context: "")
+      MLDSA.validate_context(context)
+      MLDSA.validate_bytes(signature, parameter_set.signature_size, "signature")
+
+      return true if Native.verify(parameter_set.identifier, @key_bytes, signature, message, context)
+
+      raise VerifyError, "signature verification failed!"
+    end
+
+    # Verify a signature over a precomputed external message representative.
+    #
+    # @param signature [String] signature bytes
+    # @param mu [String] precomputed external message representative
+    # @return [true] when verification succeeds
+    # @raise [MLDSA::VerifyError] if verification fails
+    # @raise [ArgumentError] if signature or mu has the wrong size
+    # @raise [TypeError] if mu is not a String
+    def verify_mu(signature, mu)
+      MLDSA.validate_bytes(signature, parameter_set.signature_size, "signature")
+      MLDSA.validate_bytes(mu, parameter_set.mu_size, "mu")
+
+      return true if Native.verify_mu(parameter_set.identifier, @key_bytes, signature, mu)
+
+      raise VerifyError, "signature verification failed!"
+    end
+
+    # Export the public key.
+    #
+    # @return [String] mutable copy of the public key bytes
+    def to_bytes
+      @key_bytes.dup
+    end
+
+    # String representation containing the public key bytes as hex.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class}:#{@key_bytes.unpack1('H*')}>"
+    end
+  end
+end

data/lib/mldsa/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MLDSA
+  # Gem version.
+  # @return [String]
+  VERSION = "0.1.0"
+end

data/lib/mldsa_gh.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "mldsa/version"
+require "mldsa/parameter_set"
+require "mldsa/signing_key"
+require "mldsa/verify_key"
+
+# Ruby bindings for ML-DSA-44, ML-DSA-65, and ML-DSA-87.
+module MLDSA
+  module_function
+
+  # Size of an ML-DSA private seed in bytes.
+  # @return [Integer]
+  SEED_SIZE = 32
+
+  # Size of the hedging randomness supplied to mldsa-native in bytes.
+  # @return [Integer]
+  RANDOM_SIZE = 32
+
+  # Size of an external message representative `mu` in bytes.
+  # @return [Integer]
+  MU_SIZE = 64
+
+  # ML-DSA-44 parameter set.
+  # @return [MLDSA::ParameterSet]
+  ML_DSA_44 = ParameterSet.new(
+    identifier: 44,
+    private_key_size: 2560,
+    public_key_size: 1312,
+    signature_size: 2420
+  ).freeze
+
+  # ML-DSA-65 parameter set.
+  # @return [MLDSA::ParameterSet]
+  ML_DSA_65 = ParameterSet.new(
+    identifier: 65,
+    private_key_size: 4032,
+    public_key_size: 1952,
+    signature_size: 3309
+  ).freeze
+
+  # ML-DSA-87 parameter set.
+  # @return [MLDSA::ParameterSet]
+  ML_DSA_87 = ParameterSet.new(
+    identifier: 87,
+    private_key_size: 4896,
+    public_key_size: 2592,
+    signature_size: 4627
+  ).freeze
+  ParameterSet.private_class_method :new
+
+  # Supported ML-DSA parameter sets.
+  # @return [Array<MLDSA::ParameterSet>]
+  PARAMETER_SETS = [ML_DSA_44, ML_DSA_65, ML_DSA_87].freeze
+
+  # Raised when a signature fails verification.
+  VerifyError = Class.new(StandardError)
+
+  # Raised when requesting a private seed from a key imported without one.
+  SeedUnavailableError = Class.new(StandardError)
+
+  require "mldsa_gh_native"
+  private_constant :Native
+
+  # @api private
+  def validate_parameter_set(parameter_set)
+    return parameter_set if PARAMETER_SETS.include?(parameter_set)
+
+    raise ArgumentError, "expected parameter set MLDSA::ML_DSA_44, MLDSA::ML_DSA_65, or MLDSA::ML_DSA_87, got #{parameter_set.inspect}"
+  end
+
+  # @api private
+  def validate_bytes(value, size, name)
+    raise TypeError, "expected String, got #{value.class}" unless value.is_a?(String)
+    return true if value.bytesize == size
+
+    raise ArgumentError, "expected #{size}-byte #{name}, got #{value.bytesize}"
+  end
+
+  # @api private
+  def validate_context(context)
+    raise TypeError, "expected String, got #{context.class}" unless context.is_a?(String)
+    return true if context.bytesize <= 255
+
+    raise ArgumentError, "expected context to be at most 255 bytes, got #{context.bytesize}"
+  end
+
+  # @api private
+  def copy_bytes(value)
+    value.dup.freeze
+  end
+end

metadata

@@ -0,0 +1,225 @@
+--- !ruby/object:Gem::Specification
+name: mldsa_gh
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- vcsjones
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: Ruby bindings for ML-DSA-44, ML-DSA-65, and ML-DSA-87 using mldsa-native.
+executables: []
+extensions:
+- ext/mldsa_gh_native/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- ext/mldsa_gh_native/extconf.rb
+- ext/mldsa_gh_native/mldsa_gh_native.c
+- ext/mldsa_gh_native/mldsa_gh_native_all.c
+- ext/mldsa_gh_native/mldsa_gh_native_all.h
+- ext/mldsa_gh_native/vendor/mldsa-native/BUILDING.md
+- ext/mldsa_gh_native/vendor/mldsa-native/LICENSE
+- ext/mldsa_gh_native/vendor/mldsa-native/README.md
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/README.md
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/mldsa_native.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/mldsa_native.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/mldsa_native_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/mldsa_native_config.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/cbmc.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/common.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/context.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/ct.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/ct.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/debug.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/debug.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/fips202.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/fips202.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/fips202x4.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/fips202x4.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/keccakf1600.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/keccakf1600.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/auto.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/src/fips202_native_aarch64.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/src/keccak_f1600_x1_scalar_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/src/keccak_f1600_x1_v84a_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/src/keccak_f1600_x2_v84a_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/src/keccak_f1600_x4_v8a_scalar_hybrid_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/src/keccak_f1600_x4_v8a_v84a_scalar_hybrid_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/src/keccakf1600_round_constants.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/x1_scalar.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/x1_v84a.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/x2_v84a.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/x4_v8a_scalar.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/aarch64/x4_v8a_v84a_scalar.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/api.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/armv81m/README.md
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/armv81m/mve.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/armv81m/src/fips202_native_armv81m.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/armv81m/src/keccak_f1600_x4_mve.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/armv81m/src/keccak_f1600_x4_mve.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/armv81m/src/keccak_f1600_x4_state_extract_bytes_mve.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/armv81m/src/keccak_f1600_x4_state_xor_bytes_mve.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/armv81m/src/keccakf1600_round_constants.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/auto.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/x86_64/keccak_f1600_x4_avx2.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/x86_64/src/fips202_native_x86_64.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/x86_64/src/keccak_f1600_x4_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/fips202/native/x86_64/src/keccakf1600_constants.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/meta.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/aarch64_zetas.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/arith_native_aarch64.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_intt_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_ntt_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_pointwise_montgomery_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_poly_caddq_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_poly_chknorm_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_poly_decompose_32_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_poly_decompose_88_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_poly_use_hint_32_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_poly_use_hint_88_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_polyvecl_pointwise_acc_montgomery_l4_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_polyvecl_pointwise_acc_montgomery_l5_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_polyvecl_pointwise_acc_montgomery_l7_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_polyz_unpack_17_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_polyz_unpack_19_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_rej_uniform_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_rej_uniform_eta2_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/mldsa_rej_uniform_eta4_aarch64_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/polyz_unpack_table.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/rej_uniform_eta_table.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/aarch64/src/rej_uniform_table.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/api.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/meta.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/meta.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/arith_native_x86_64.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/consts.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/consts.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_intt_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_ntt_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_nttunpack_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_pointwise_acc_l4_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_pointwise_acc_l5_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_pointwise_acc_l7_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_pointwise_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_poly_caddq_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_poly_chknorm_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_poly_decompose_32_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_poly_decompose_88_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_poly_use_hint_32_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_poly_use_hint_88_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_polyz_unpack_17_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_polyz_unpack_19_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_rej_uniform_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_rej_uniform_eta2_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/mldsa_rej_uniform_eta4_avx2_asm.S
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/native/x86_64/src/rej_uniform_table.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/packing.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/packing.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/params.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/poly.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/poly.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/poly_kl.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/poly_kl.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/polyvec.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/polyvec.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/polyvec_lazy.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/polyvec_lazy.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/randombytes.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/reduce.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/rounding.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/sign.c
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/sign.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/symmetric.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/sys.h
+- ext/mldsa_gh_native/vendor/mldsa-native/mldsa/src/zetas.inc
+- lib/mldsa/parameter_set.rb
+- lib/mldsa/signing_key.rb
+- lib/mldsa/verify_key.rb
+- lib/mldsa/version.rb
+- lib/mldsa_gh.rb
+homepage: https://github.com/github/mldsa_gh
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Ruby bindings for ML-DSA
+test_files: []