Add post-quantum cryptography (PQC) support to SSLConfig

Gemfile

@@ -4,4 +4,4 @@ gemspec
 
 gem "rake"
 gem "test-unit"
-gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
+gem "test-unit-ruby-core"

lib/drb/ssl.rb

@@ -25,19 +25,25 @@ class SSLConfig
       #
       # See DRb::DRbSSLSocket::SSLConfig.new for more details
       DEFAULT = {
-        :SSLCertificate       => nil,
-        :SSLPrivateKey        => nil,
-        :SSLClientCA          => nil,
-        :SSLCACertificatePath => nil,
-        :SSLCACertificateFile => nil,
-        :SSLTmpDhCallback     => nil,
-        :SSLVerifyMode        => ::OpenSSL::SSL::VERIFY_NONE,
-        :SSLVerifyDepth       => nil,
-        :SSLVerifyCallback    => nil,   # custom verification
-        :SSLCertificateStore  => nil,
+        :SSLCertificates              => nil,
+        :SSLCertificate               => nil,
+        :SSLPrivateKey                => nil,
+        :SSLPrivateKeyAlgorithms      => ["RSA"],
+        :SSLClientCA                  => nil,
+        :SSLCACertificatePath         => nil,
+        :SSLCACertificateFile         => nil,
+        :SSLSignatureAlgorithms       => nil,
+        :SSLClientSignatureAlgorithms => nil,
+        :SSLGroups                    => nil,
+        :SSLTmpDhCallback             => nil,
+        :SSLVerifyMode                => ::OpenSSL::SSL::VERIFY_NONE,
+        :SSLVerifyDepth               => nil,
+        :SSLVerifyCallback            => nil,   # custom verification
+        :SSLCertificateStore          => nil,
         # Must specify if you use auto generated certificate.
-        :SSLCertName          => nil,   # e.g. [["CN","fqdn.example.com"]]
-        :SSLCertComment       => "Generated by Ruby/OpenSSL"
+        # e.g. [["CN", "fqdn.example.com"]]
+        :SSLCertName                  => nil,
+        :SSLCertComment               => "Generated by Ruby/OpenSSL"
       }
 
       # Create a new DRb::DRbSSLSocket::SSLConfig instance
@@ -51,13 +57,29 @@ class SSLConfig
       #
       # From +config+ Hash:
       #
+      # :SSLCertificates ::
+      #   An Array of [certificate, private_key] pairs. Each element
+      #   is an Array of an OpenSSL::X509::Certificate and its
+      #   corresponding private key.  This option is prioritized over
+      #   :SSLCertificate and :SSLPrivateKey.  See
+      #   OpenSSL::SSL::SSLContext#add_certificate
+      #
       # :SSLCertificate ::
       #   An instance of OpenSSL::X509::Certificate.  If this is not provided,
       #   then a generic X509 is generated, with a correspond :SSLPrivateKey
       #
       # :SSLPrivateKey ::
-      #   A private key instance, like OpenSSL::PKey::RSA.  This key must be
-      #   the key that signed the :SSLCertificate
+      #   A private key instance, like OpenSSL::PKey::RSA for RSA
+      #   and OpenSSL::PKey::PKey for ML-DSA-44, ML-DSA-65,
+      #   ML-DSA-87.  This key must be the key that signed the
+      #   :SSLCertificate
+      #
+      # :SSLPrivateKeyAlgorithms ::
+      #   An Array of private key algorithms used to generate
+      #   certificates when :SSLCertificates, :SSLCertificate and
+      #   :SSLPrivateKey are not provided. Supported algorithms are
+      #   RSA, ML-DSA-44, ML-DSA-65, and ML-DSA-87.
+      #   Defaults to ["RSA"]
       #
       # :SSLClientCA ::
       #   An OpenSSL::X509::Certificate, or Array of certificates that will
@@ -70,6 +92,15 @@ class SSLConfig
       # :SSLCACertificateFile ::
       #   A path to a CA certificate file, in PEM format.
       #
+      # :SSLSignatureAlgorithms ::
+      #   Signature algorithms.  See OpenSSL::SSL::SSLContext#sigalgs=
+      #
+      # :SSLClientSignatureAlgorithms ::
+      #   Client signature algorithms.  See OpenSSL::SSL::SSLContext#client_sigalgs=
+      #
+      # :SSLGroups ::
+      #   Key exchange groups.  See OpenSSL::SSL::SSLContext#groups=
+      #
       # :SSLTmpDhCallback ::
       #   A DH callback. See OpenSSL::SSL::SSLContext.tmp_dh_callback
       #
@@ -133,10 +164,14 @@ class SSLConfig
       #   c.setup_certificate
       #
       def initialize(config)
-        @config  = config
-        @cert    = config[:SSLCertificate]
-        @pkey    = config[:SSLPrivateKey]
-        @ssl_ctx = nil
+        @config   = config
+        @certs = if config.key?(:SSLCertificates)
+                   config[:SSLCertificates]
+                 elsif config[:SSLCertificate] && config[:SSLPrivateKey]
+                   [[config[:SSLCertificate], config[:SSLPrivateKey]]]
+                 end
+        @pkey_algs = self[:SSLPrivateKeyAlgorithms]
+        @ssl_ctx  = nil
       end
 
       # A convenience method to access the values like a Hash
@@ -162,25 +197,81 @@ def accept(tcp)
         ssl
       end
 
-      # Ensures that :SSLCertificate and :SSLPrivateKey have been provided
-      # or that a new certificate is generated with the other parameters
-      # provided.
+      # Ensures that :SSLCertificates or :SSLCertificate and
+      # :SSLPrivateKey have been provided, or that new certificates
+      # are generated with the other parameters provided.
       def setup_certificate
-        if @cert && @pkey
+        if @certs
           return
         end
 
-        rsa = OpenSSL::PKey::RSA.new(2048)
+        @certs = @pkey_algs.map { |pkey_alg| setup_certificate_one(pkey_alg) }
+      end
+
+      # Establish the OpenSSL::SSL::SSLContext with the configuration
+      # parameters provided.
+      def setup_ssl_context
+        ctx = ::OpenSSL::SSL::SSLContext.new
+        @certs&.each do |cert, pkey|
+          ctx.add_certificate(cert, pkey)
+        end
+        ctx.min_version     = self[:SSLMinVersion]
+        ctx.max_version     = self[:SSLMaxVersion]
+        ctx.client_ca       = self[:SSLClientCA]
+        ctx.ca_path         = self[:SSLCACertificatePath]
+        ctx.ca_file         = self[:SSLCACertificateFile]
+        if self[:SSLSignatureAlgorithms]
+          ctx.sigalgs = self[:SSLSignatureAlgorithms]
+        end
+        if self[:SSLClientSignatureAlgorithms]
+          ctx.client_sigalgs = self[:SSLClientSignatureAlgorithms]
+        end
+        if self[:SSLGroups]
+          ctx.groups = self[:SSLGroups]
+        end
+        ctx.tmp_dh_callback = self[:SSLTmpDhCallback]
+        ctx.verify_mode     = self[:SSLVerifyMode]
+        ctx.verify_depth    = self[:SSLVerifyDepth]
+        ctx.verify_callback = self[:SSLVerifyCallback]
+        ctx.cert_store      = self[:SSLCertificateStore]
+        @ssl_ctx = ctx
+      end
+
+      private
 
+      def setup_certificate_one(pkey_alg)
         cert = OpenSSL::X509::Certificate.new
+
+        case pkey_alg
+        when "RSA"
+          pkey = OpenSSL::PKey::RSA.new(2048)
+          cert.public_key = pkey
+          digest = "SHA256"
+        when "ML-DSA-44", "ML-DSA-65", "ML-DSA-87"
+          # OpenSSL >= 3.5.0 support ML-DSA. OpenSSL::PKey.generate_key raises
+          # OpenSSL::PKey::PKeyError if ML-DSA algorithm is not supported.
+          # https://openssl-library.org/post/2025-04-08-openssl-35-final-release/
+          pkey = OpenSSL::PKey.generate_key(pkey_alg)
+          # OpenSSL::PKey::PKey#public_to_der was added in openssl gem 2.2.0.
+          # https://github.com/ruby/openssl/blob/v2.2.0/History.md?plain=1#L72-L75
+          cert.public_key = OpenSSL::PKey.read(pkey.public_to_der)
+          # OpenSSL::X509::Certificate#sign doesn't accept explicit digest
+          # algorithm, in ML-DSA because ML-DSA has a built-in digest.
+          digest = nil
+        else
+          raise(ArgumentError,
+                "#{pkey_alg} algorithm not found. "\
+                "RSA, ML-DSA-44, ML-DSA-65, and ML-DSA-87 "\
+                "algorithms are supported")
+        end
+
         cert.version = 2 # This means v3
         cert.serial = 0
         name = OpenSSL::X509::Name.new(self[:SSLCertName])
         cert.subject = name
         cert.issuer = name
         cert.not_before = Time.now
         cert.not_after = Time.now + (365*24*60*60)
-        cert.public_key = rsa.public_key
 
         ef = OpenSSL::X509::ExtensionFactory.new(nil,cert)
         cert.extensions = [
@@ -192,29 +283,9 @@ def setup_certificate
         if comment = self[:SSLCertComment]
           cert.add_extension(ef.create_extension("nsComment", comment))
         end
-        cert.sign(rsa, "SHA256")
-
-        @cert = cert
-        @pkey = rsa
-      end
+        cert.sign(pkey, digest)
 
-      # Establish the OpenSSL::SSL::SSLContext with the configuration
-      # parameters provided.
-      def setup_ssl_context
-        ctx = ::OpenSSL::SSL::SSLContext.new
-        ctx.cert            = @cert
-        ctx.key             = @pkey
-        ctx.min_version     = self[:SSLMinVersion]
-        ctx.max_version     = self[:SSLMaxVersion]
-        ctx.client_ca       = self[:SSLClientCA]
-        ctx.ca_path         = self[:SSLCACertificatePath]
-        ctx.ca_file         = self[:SSLCACertificateFile]
-        ctx.tmp_dh_callback = self[:SSLTmpDhCallback]
-        ctx.verify_mode     = self[:SSLVerifyMode]
-        ctx.verify_depth    = self[:SSLVerifyDepth]
-        ctx.verify_callback = self[:SSLVerifyCallback]
-        ctx.cert_store      = self[:SSLCertificateStore]
-        @ssl_ctx = ctx
+        [cert, pkey]
       end
     end
 

test/drb/drbtest.rb

@@ -4,6 +4,7 @@
 require 'drb/drb'
 require 'drb/extservm'
 require 'timeout'
+require_relative 'drbtest_utils'
 
 module DRbTests
 
@@ -393,4 +394,75 @@ def test_07_break_18
 
 end
 
+# A PQC support module
+# Inspired by ruby/rubygems omit_unless_support_pqc
+module DRbPQC
+  # PQC algorithms ML-KEM and ML-DSA require OpenSSL >= 3.5.
+  # https://openssl-library.org/post/2025-04-08-openssl-35-final-release/
+  # Ruby OpenSSL >= 4.0 has useful methods in PQC use cases.
+  # https://github.com/ruby/openssl/blob/v4.0.0/History.md?plain=1#L25-L35
+  # And fixed the following bug related to PQC.
+  # https://github.com/ruby/openssl/pull/898
+  # However, we don't check OpenSSL and Ruby OpenSSL versions here
+  # for a flexible check for other SSL libraries such as LibreSSL and AWS-LC.
+  def omit_unless_support_pqc
+    # Even with a new enough OpenSSL, the runtime may keep PQC groups and
+    # signature algorithms out of its default negotiation lists (for example
+    # RHEL's system-wide crypto policies). The PQC server forces both, while
+    # the gem fetcher connects with the default client configuration, so a
+    # real loopback handshake is the only reliable way to tell whether this
+    # environment can negotiate PQC at all.
+    unless support_pqc_handshake?
+      omit 'OpenSSL or Ruby OpenSSL is too old to support PQC, '\
+           'or PQC handshake is not available in this OpenSSL configuration'
+    end
+  end
+
+  # Probe an actual PQC handshake between a forced-PQC server and a
+  # default-configured client, mirroring what the integration tests exercise.
+  # Memoized so the probe runs at most once per process.
+  def support_pqc_handshake?
+    return @support_pqc_handshake unless @support_pqc_handshake.nil?
+
+    @support_pqc_handshake = probe_pqc_handshake
+  end
+
+  def probe_pqc_handshake
+    server = TCPServer.new('127.0.0.1', 0)
+    ctx = OpenSSL::SSL::SSLContext.new
+    cert = Fixtures.read_cert('mldsa65_server.crt')
+    pkey = Fixtures.read_pkey('mldsa65_server.key')
+    ctx.add_certificate(cert, pkey)
+
+    # ctx.groups (OpenSSL::SSL::SSLContext#groups) requires Ruby OpenSSL >= 4.0.
+    return nil unless ctx.respond_to?(:groups=)
+
+    ctx.groups = 'X25519MLKEM768'
+    ssl_server = OpenSSL::SSL::SSLServer.new(server, ctx)
+
+    port = server.addr[1]
+    server_thread = Thread.new do
+      client = ssl_server.accept
+      client.close
+    rescue OpenSSL::OpenSSLError
+      nil
+    end
+
+    client_ctx = OpenSSL::SSL::SSLContext.new
+    client_ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE
+    socket = TCPSocket.new('127.0.0.1', port)
+    ssl = OpenSSL::SSL::SSLSocket.new(socket, client_ctx)
+    ssl.connect
+    ssl.close
+    true
+  rescue OpenSSL::PKey::PKeyError, OpenSSL::OpenSSLError, SystemCallError
+    false
+  ensure
+    server_thread&.join(5)
+    server_thread&.kill if server_thread&.alive?
+    ssl_server&.close
+    server&.close
+  end
+end
+
 end

test/drb/drbtest_utils.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: false
+
+# This file does not require test/unit unlike drbtest.rb because it can
+# be loaded by child processes (ut_*.rb) where
+# test-unit's at_exit autorunner would cause errors.
+
+require 'openssl'
+
+module DRbTests
+
+module Fixtures
+  module_function
+
+  def file_path(name)
+    File.join(__dir__, 'fixtures', name)
+  end
+
+  def read_file(name)
+    @file_cache ||= {}
+    @file_cache[name] ||= File.read(file_path(name))
+  end
+
+  # Raises OpenSSL::PKey::PKeyError when reading an ML-DSA-65 key file
+  # with old OpenSSL versions.
+  def read_pkey(name)
+    OpenSSL::PKey.read(read_file(name))
+  end
+
+  def read_cert(name)
+    OpenSSL::X509::Certificate.new(read_file(name))
+  end
+end
+
+end