kpqc 0.1.0

data/ext/kpqc/randombytes.c

@@ -0,0 +1,107 @@
+/* SPDX-License-Identifier: MIT */
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+#if defined(KPQC_TEST_ENTROPY)
+#include <ruby.h>
+
+static VALUE kpqc_entropy_callback = Qnil;
+static ID kpqc_call;
+
+static VALUE kpqc_set_randombytes(VALUE self, VALUE callback) {
+    (void)self;
+    if (!rb_respond_to(callback, kpqc_call)) {
+        rb_raise(rb_eTypeError, "entropy provider must respond to call");
+    }
+    kpqc_entropy_callback = callback;
+    return callback;
+}
+
+static VALUE kpqc_reset_randombytes(VALUE self) {
+    (void)self;
+    kpqc_entropy_callback = Qnil;
+    return Qnil;
+}
+
+void kpqc_randombytes_test_init(VALUE algorithm) {
+    kpqc_call = rb_intern("call");
+    rb_global_variable(&kpqc_entropy_callback);
+    rb_define_singleton_method(
+        algorithm, "__set_randombytes", kpqc_set_randombytes, 1);
+    rb_define_singleton_method(
+        algorithm, "__reset_randombytes", kpqc_reset_randombytes, 0);
+}
+#endif
+
+#if defined(_WIN32)
+#include <limits.h>
+#include <windows.h>
+#include <bcrypt.h>
+#elif defined(__APPLE__) || defined(__FreeBSD__) || defined(__OpenBSD__) || \
+    defined(__NetBSD__) || defined(__DragonFly__)
+#include <stdlib.h>
+#elif defined(__linux__) || defined(__ANDROID__)
+#include <errno.h>
+#include <sys/random.h>
+#else
+#error "kpqc currently supports operating-system entropy on Windows, Linux, Android, macOS, and BSD"
+#endif
+
+static int kpqc_fill_random(uint8_t *output, size_t length) {
+#if defined(KPQC_TEST_ENTROPY)
+    if (kpqc_entropy_callback != Qnil) {
+        VALUE entropy = rb_funcall(
+            kpqc_entropy_callback, kpqc_call, 1, SIZET2NUM(length));
+        if (!RB_TYPE_P(entropy, T_STRING)) {
+            rb_raise(rb_eTypeError, "entropy provider must return a String");
+        }
+        if ((size_t)RSTRING_LEN(entropy) != length) {
+            rb_raise(rb_eRuntimeError,
+                     "entropy provider returned %ld bytes, expected %lu",
+                     RSTRING_LEN(entropy), (unsigned long)length);
+        }
+        memcpy(output, RSTRING_PTR(entropy), length);
+        return 0;
+    }
+#endif
+#if defined(_WIN32)
+    while (length != 0) {
+        ULONG chunk = length > (size_t)ULONG_MAX ? ULONG_MAX : (ULONG)length;
+        if (BCryptGenRandom(NULL, output, chunk,
+                            BCRYPT_USE_SYSTEM_PREFERRED_RNG) != 0) {
+            return -1;
+        }
+        output += chunk;
+        length -= chunk;
+    }
+    return 0;
+#elif defined(__APPLE__) || defined(__FreeBSD__) || defined(__OpenBSD__) || \
+    defined(__NetBSD__) || defined(__DragonFly__)
+    arc4random_buf(output, length);
+    return 0;
+#else
+    while (length != 0) {
+        ssize_t count = getrandom(output, length, 0);
+        if (count < 0) {
+            if (errno == EINTR) continue;
+            return -1;
+        }
+        if (count == 0) return -1;
+        output += (size_t)count;
+        length -= (size_t)count;
+    }
+    return 0;
+#endif
+}
+
+#if defined(KPQC_AIMER)
+int randombytes(unsigned char *output, unsigned long long length) {
+    if (length > (unsigned long long)SIZE_MAX) return -1;
+    return kpqc_fill_random(output, (size_t)length);
+}
+#else
+int randombytes(uint8_t *output, size_t length) {
+    return kpqc_fill_random(output, length);
+}
+#endif

data/ext/kpqc/smaugt128/extconf.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+require_relative "../extconf_helper"
+KpqCBuild.smaugt("smaugt128", 0)
+

data/ext/kpqc/smaugt192/extconf.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+require_relative "../extconf_helper"
+KpqCBuild.smaugt("smaugt192", 1)
+

data/ext/kpqc/smaugt256/extconf.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+require_relative "../extconf_helper"
+KpqCBuild.smaugt("smaugt256", 2)
+

data/ext/kpqc/timer/extconf.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+require_relative "../extconf_helper"
+KpqCBuild.smaugt("timer", 3)
+

data/kpqc.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/kpqc/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "kpqc"
+  spec.version = KpqC::VERSION
+  spec.authors = ["osuolfou"]
+  spec.email = ["osuolfou@naver.com"]
+
+  spec.summary = "Ruby APIs for AIMer, HAETAE, NTRU+, and SMAUG-T."
+  spec.description =
+    "Synchronous Ruby bindings for the bundled AIMer and HAETAE signature " \
+    "schemes and NTRU+ and SMAUG-T key-encapsulation mechanisms."
+  spec.homepage = "https://github.com/osuolfou/kpqc-rb"
+  spec.license = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "ext/**/*.{rb,c,h}",
+    "vendor/**/*.{c,h,json}",
+    "vendor/**/LICENSE",
+    "test/**/*.{rb,mjs,rsp}",
+    "Gemfile",
+    "kpqc.gemspec",
+    "Rakefile",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ]
+  spec.require_paths = ["lib"]
+  spec.extensions = Dir["ext/kpqc/*/extconf.rb"].sort
+
+  spec.add_development_dependency "rake", ">= 12.3"
+  spec.add_development_dependency "minitest", ">= 5.10"
+end

data/lib/kpqc/aimer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "api"
+
+module KpqC
+  # AIMer signature parameter sets.
+  module Aimer
+    AIMER128F = SignatureAlgorithm.new(
+      "aimer-128f", SignatureSizes.new(32, 48, 5_888), "aimer128f"
+    )
+    AIMER128S = SignatureAlgorithm.new(
+      "aimer-128s", SignatureSizes.new(32, 48, 4_160), "aimer128s"
+    )
+    AIMER192F = SignatureAlgorithm.new(
+      "aimer-192f", SignatureSizes.new(48, 72, 13_056), "aimer192f"
+    )
+    AIMER192S = SignatureAlgorithm.new(
+      "aimer-192s", SignatureSizes.new(48, 72, 9_120), "aimer192s"
+    )
+    AIMER256F = SignatureAlgorithm.new(
+      "aimer-256f", SignatureSizes.new(64, 96, 25_120), "aimer256f"
+    )
+    AIMER256S = SignatureAlgorithm.new(
+      "aimer-256s", SignatureSizes.new(64, 96, 17_056), "aimer256s"
+    )
+    private_constant :AIMER128F, :AIMER128S, :AIMER192F, :AIMER192S,
+                     :AIMER256F, :AIMER256S
+
+    class << self
+      def aimer128f; AIMER128F; end
+      def aimer128s; AIMER128S; end
+      def aimer192f; AIMER192F; end
+      def aimer192s; AIMER192S; end
+      def aimer256f; AIMER256F; end
+      def aimer256s; AIMER256S; end
+    end
+  end
+end

data/lib/kpqc/api.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "types"
+
+module KpqC
+  # An error reported by a bundled cryptographic core.
+  class Error < StandardError
+  end
+
+  EMPTY_CONTEXT = "".b.freeze
+  private_constant :EMPTY_CONTEXT
+
+  module AlgorithmSupport
+    def generate_key_pair
+      KeyPair.new(*native.keygen)
+    end
+
+    def inspect
+      "#<#{self.class} id=#{id.inspect} sizes=#{sizes.inspect}>"
+    end
+
+    def to_s
+      id
+    end
+
+    private
+
+    def initialize_algorithm(id, sizes, native_name)
+      @id = id.freeze
+      @sizes = sizes
+      @native_name = native_name.freeze
+      @native_constant = native_name.sub(/\A([a-z])/) do
+        Regexp.last_match(1).upcase
+      end.freeze
+    end
+
+    def native
+      require_native_extension
+      Native.const_get(@native_constant, false)
+    end
+
+    def require_native_extension
+      require "kpqc/#{@native_name}_native"
+    rescue LoadError => installed_error
+      begin
+        require "#{@native_name}_native"
+      rescue LoadError
+        raise installed_error
+      end
+    end
+
+    def require_string(label, value)
+      return value if value.is_a?(String)
+
+      raise TypeError, "#{label} must be a String"
+    end
+
+    def require_size(label, value, expected)
+      require_string(label, value)
+      return value if value.bytesize == expected
+
+      raise ArgumentError,
+            "#{label} must be #{expected} bytes, received #{value.bytesize}"
+    end
+
+    def require_context(context)
+      require_string("context", context)
+      return context if context.bytesize <= 255
+
+      raise ArgumentError,
+            "context cannot exceed 255 bytes, received #{context.bytesize}"
+    end
+  end
+  private_constant :AlgorithmSupport
+
+  # A signature algorithm and parameter set.
+  class SignatureAlgorithm
+    include AlgorithmSupport
+
+    attr_reader :id, :sizes
+
+    def initialize(id, sizes, native_name)
+      initialize_algorithm(id, sizes, native_name)
+      freeze
+    end
+
+    def sign(message, secret_key, context: EMPTY_CONTEXT)
+      require_string("message", message)
+      require_size("secret_key", secret_key, sizes.secret_key)
+      require_context(context)
+      native.sign(message, secret_key, context)
+    end
+
+    def verify(message, signature, public_key, context: EMPTY_CONTEXT)
+      require_string("message", message)
+      require_string("signature", signature)
+      require_size("public_key", public_key, sizes.public_key)
+      require_context(context)
+      return false unless signature.bytesize == sizes.signature
+
+      native.verify(message, signature, public_key, context)
+    end
+
+  end
+
+  # A key-encapsulation algorithm and parameter set.
+  class KeyEncapsulationAlgorithm
+    include AlgorithmSupport
+
+    attr_reader :id, :sizes
+
+    def initialize(id, sizes, native_name)
+      initialize_algorithm(id, sizes, native_name)
+      freeze
+    end
+
+    def encapsulate(public_key)
+      require_size("public_key", public_key, sizes.public_key)
+      EncapsulatedSecret.new(*native.encapsulate(public_key))
+    end
+
+    def decapsulate(ciphertext, secret_key)
+      require_size("ciphertext", ciphertext, sizes.ciphertext)
+      require_size("secret_key", secret_key, sizes.secret_key)
+      native.decapsulate(ciphertext, secret_key)
+    end
+
+  end
+end

data/lib/kpqc/haetae.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "api"
+
+module KpqC
+  # HAETAE signature parameter sets.
+  module Haetae
+    HAETAE2 = SignatureAlgorithm.new(
+      "haetae-mode2", SignatureSizes.new(992, 1_408, 1_474), "haetae2"
+    )
+    HAETAE3 = SignatureAlgorithm.new(
+      "haetae-mode3", SignatureSizes.new(1_472, 2_112, 2_349), "haetae3"
+    )
+    HAETAE5 = SignatureAlgorithm.new(
+      "haetae-mode5", SignatureSizes.new(2_080, 2_752, 2_948), "haetae5"
+    )
+    private_constant :HAETAE2, :HAETAE3, :HAETAE5
+
+    class << self
+      def haetae2; HAETAE2; end
+      def haetae3; HAETAE3; end
+      def haetae5; HAETAE5; end
+    end
+  end
+end

data/lib/kpqc/ntruplus.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "api"
+
+module KpqC
+  # NTRU+ key-encapsulation parameter sets.
+  module NtruPlus
+    NTRUPLUS768 = KeyEncapsulationAlgorithm.new(
+      "NTRU+768", KemSizes.new(1_152, 2_336, 1_152, 32), "ntruplus768"
+    )
+    NTRUPLUS864 = KeyEncapsulationAlgorithm.new(
+      "NTRU+864", KemSizes.new(1_296, 2_624, 1_296, 32), "ntruplus864"
+    )
+    NTRUPLUS1152 = KeyEncapsulationAlgorithm.new(
+      "NTRU+1152", KemSizes.new(1_728, 3_488, 1_728, 32), "ntruplus1152"
+    )
+    private_constant :NTRUPLUS768, :NTRUPLUS864, :NTRUPLUS1152
+
+    class << self
+      def ntruplus768; NTRUPLUS768; end
+      def ntruplus864; NTRUPLUS864; end
+      def ntruplus1152; NTRUPLUS1152; end
+    end
+  end
+end

data/lib/kpqc/smaugt.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "api"
+
+module KpqC
+  # SMAUG-T and TiMER key-encapsulation parameter sets.
+  module SmaugT
+    SMAUGT128 = KeyEncapsulationAlgorithm.new(
+      "SMAUG-T128", KemSizes.new(672, 832, 672, 32), "smaugt128"
+    )
+    SMAUGT192 = KeyEncapsulationAlgorithm.new(
+      "SMAUG-T192", KemSizes.new(1_088, 1_312, 992, 32), "smaugt192"
+    )
+    SMAUGT256 = KeyEncapsulationAlgorithm.new(
+      "SMAUG-T256", KemSizes.new(1_440, 1_728, 1_376, 32), "smaugt256"
+    )
+    TIMER = KeyEncapsulationAlgorithm.new(
+      "TiMER", KemSizes.new(672, 832, 608, 32), "timer"
+    )
+    private_constant :SMAUGT128, :SMAUGT192, :SMAUGT256, :TIMER
+
+    class << self
+      def smaugt128; SMAUGT128; end
+      def smaugt192; SMAUGT192; end
+      def smaugt256; SMAUGT256; end
+      def timer; TIMER; end
+    end
+  end
+end

data/lib/kpqc/types.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module KpqC
+  # A generated public and secret key pair.
+  class KeyPair
+    attr_reader :public_key, :secret_key
+
+    def initialize(public_key, secret_key)
+      @public_key = public_key
+      @secret_key = secret_key
+    end
+
+    # Wipe the secret key in place on a best-effort basis.
+    def clear!
+      KpqC.send(:wipe!, @secret_key)
+      self
+    end
+
+    def inspect
+      "#<#{self.class} public_key=#{@public_key.bytesize} bytes secret_key=[REDACTED]>"
+    end
+
+    alias to_s inspect
+  end
+
+  # The result of a key-encapsulation operation.
+  class EncapsulatedSecret
+    attr_reader :ciphertext, :shared_secret
+
+    def initialize(ciphertext, shared_secret)
+      @ciphertext = ciphertext
+      @shared_secret = shared_secret
+    end
+
+    # Wipe the shared secret in place on a best-effort basis.
+    def clear!
+      KpqC.send(:wipe!, @shared_secret)
+      self
+    end
+
+    def inspect
+      "#<#{self.class} ciphertext=#{@ciphertext.bytesize} bytes shared_secret=[REDACTED]>"
+    end
+
+    alias to_s inspect
+  end
+
+  # Byte sizes for a signature parameter set.
+  class SignatureSizes
+    attr_reader :public_key, :secret_key, :signature
+
+    def initialize(public_key, secret_key, signature)
+      @public_key = public_key
+      @secret_key = secret_key
+      @signature = signature
+      freeze
+    end
+
+    def ==(other)
+      other.is_a?(SignatureSizes) &&
+        [public_key, secret_key, signature] ==
+          [other.public_key, other.secret_key, other.signature]
+    end
+
+    alias eql? ==
+
+    def hash
+      [self.class, public_key, secret_key, signature].hash
+    end
+  end
+
+  # Byte sizes for a key-encapsulation parameter set.
+  class KemSizes
+    attr_reader :public_key, :secret_key, :ciphertext, :shared_secret
+
+    def initialize(public_key, secret_key, ciphertext, shared_secret)
+      @public_key = public_key
+      @secret_key = secret_key
+      @ciphertext = ciphertext
+      @shared_secret = shared_secret
+      freeze
+    end
+
+    def ==(other)
+      other.is_a?(KemSizes) &&
+        [public_key, secret_key, ciphertext, shared_secret] ==
+          [other.public_key, other.secret_key, other.ciphertext,
+           other.shared_secret]
+    end
+
+    alias eql? ==
+
+    def hash
+      [self.class, public_key, secret_key, ciphertext, shared_secret].hash
+    end
+  end
+
+  def self.wipe!(value)
+    value.bytesize.times { |index| value.setbyte(index, 0) }
+  end
+  private_class_method :wipe!
+end
+

data/lib/kpqc/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module KpqC
+  VERSION = "0.1.0"
+end
+

data/lib/kpqc.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "kpqc/version"
+require_relative "kpqc/aimer"
+require_relative "kpqc/haetae"
+require_relative "kpqc/ntruplus"
+require_relative "kpqc/smaugt"
+
+# Synchronous Ruby APIs for the KpqC post-quantum cryptographic schemes.
+module KpqC
+  class << self
+    def aimer128f; Aimer.aimer128f; end
+    def aimer128s; Aimer.aimer128s; end
+    def aimer192f; Aimer.aimer192f; end
+    def aimer192s; Aimer.aimer192s; end
+    def aimer256f; Aimer.aimer256f; end
+    def aimer256s; Aimer.aimer256s; end
+
+    def haetae2; Haetae.haetae2; end
+    def haetae3; Haetae.haetae3; end
+    def haetae5; Haetae.haetae5; end
+
+    def ntruplus768; NtruPlus.ntruplus768; end
+    def ntruplus864; NtruPlus.ntruplus864; end
+    def ntruplus1152; NtruPlus.ntruplus1152; end
+
+    def smaugt128; SmaugT.smaugt128; end
+    def smaugt192; SmaugT.smaugt192; end
+    def smaugt256; SmaugT.smaugt256; end
+    def timer; SmaugT.timer; end
+  end
+end
+

data/test/algorithm_test.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class SignatureAlgorithmTest < Minitest::Test
+  def test_all_parameter_sets_round_trip_and_reject_changes
+    SIGNATURE_ALGORITHMS.each do |algorithm|
+      keys = algorithm.generate_key_pair
+      other = algorithm.generate_key_pair
+
+      assert_equal algorithm.sizes.public_key, keys.public_key.bytesize,
+                   algorithm.id
+      assert_equal algorithm.sizes.secret_key, keys.secret_key.bytesize,
+                   algorithm.id
+      refute_equal keys.public_key, other.public_key, algorithm.id
+
+      [["test\x00\xff".b, "domain".b], ["".b, "".b],
+       ["boundary".b, "x".b * 255]].each do |message, context|
+        signature = algorithm.sign(message, keys.secret_key, context: context)
+        assert_instance_of String, signature
+        assert_equal algorithm.sizes.signature, signature.bytesize
+        assert algorithm.verify(
+          message, signature, keys.public_key, context: context
+        ), algorithm.id
+        refute algorithm.verify(
+          message + "!", signature, keys.public_key, context: context
+        ), algorithm.id
+        refute algorithm.verify(
+          message, altered(signature), keys.public_key, context: context
+        ), algorithm.id
+        refute algorithm.verify(
+          message, signature, other.public_key, context: context
+        ), algorithm.id
+        refute algorithm.verify(
+          message, signature, keys.public_key, context: "wrong".b
+        ), algorithm.id
+      end
+
+      refute algorithm.verify("".b, "".b, keys.public_key), algorithm.id
+      assert_raises(ArgumentError) do
+        algorithm.sign("".b, keys.secret_key, context: "x".b * 256)
+      end
+      assert_raises(TypeError) { algorithm.sign(:text, keys.secret_key) }
+      assert_raises(ArgumentError) do
+        algorithm.sign("".b, keys.secret_key.byteslice(1..-1))
+      end
+      assert_raises(ArgumentError) do
+        algorithm.verify("".b, "".b, keys.public_key.byteslice(1..-1))
+      end
+    ensure
+      keys.clear! if keys
+      other.clear! if other
+    end
+  end
+end
+
+class KeyEncapsulationAlgorithmTest < Minitest::Test
+  def test_all_parameter_sets_round_trip_and_reject_changes
+    KEM_ALGORITHMS.each do |algorithm|
+      keys = algorithm.generate_key_pair
+      first = algorithm.encapsulate(keys.public_key)
+      second = algorithm.encapsulate(keys.public_key)
+
+      assert_equal algorithm.sizes.public_key, keys.public_key.bytesize,
+                   algorithm.id
+      assert_equal algorithm.sizes.secret_key, keys.secret_key.bytesize,
+                   algorithm.id
+      assert_equal algorithm.sizes.ciphertext, first.ciphertext.bytesize,
+                   algorithm.id
+      assert_equal algorithm.sizes.shared_secret, first.shared_secret.bytesize,
+                   algorithm.id
+      assert_equal first.shared_secret,
+                   algorithm.decapsulate(first.ciphertext, keys.secret_key),
+                   algorithm.id
+      refute_equal first.ciphertext, second.ciphertext, algorithm.id
+      refute_equal first.shared_secret, second.shared_secret, algorithm.id
+
+      if algorithm.id.start_with?("NTRU+")
+        assert_raises(KpqC::Error) do
+          algorithm.decapsulate(altered(first.ciphertext), keys.secret_key)
+        end
+      else
+        replacement = algorithm.decapsulate(
+          altered(first.ciphertext), keys.secret_key
+        )
+        assert_equal algorithm.sizes.shared_secret, replacement.bytesize
+        refute_equal first.shared_secret, replacement
+      end
+
+      assert_raises(ArgumentError) do
+        algorithm.encapsulate(keys.public_key.byteslice(1..-1))
+      end
+      assert_raises(TypeError) { algorithm.encapsulate([]) }
+      assert_raises(ArgumentError) do
+        algorithm.decapsulate(
+          first.ciphertext.byteslice(1..-1), keys.secret_key
+        )
+      end
+      assert_raises(ArgumentError) do
+        algorithm.decapsulate(
+          first.ciphertext, keys.secret_key.byteslice(1..-1)
+        )
+      end
+    ensure
+      keys.clear! if keys
+      first.clear! if first
+      second.clear! if second
+    end
+  end
+end
+