pq_crypto 0.5.3 → 0.6.1

data/ext/pqcrypto/pqcrypto_secure.h

@@ -95,17 +95,17 @@ int pq_mldsa_keypair_from_seed(uint8_t *public_key, uint8_t *secret_key,
 int pq_mldsa87_keypair_from_seed(uint8_t *public_key, uint8_t *secret_key,
                                   const uint8_t *seed32);
 int pq_sign(uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len,
-            const uint8_t *secret_key);
+            const uint8_t *ctx, size_t ctx_len, const uint8_t *secret_key);
 int pq_mldsa44_sign(uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len,
-                    const uint8_t *secret_key);
+                    const uint8_t *ctx, size_t ctx_len, const uint8_t *secret_key);
 int pq_mldsa87_sign(uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len,
-                    const uint8_t *secret_key);
+                    const uint8_t *ctx, size_t ctx_len, const uint8_t *secret_key);
 int pq_verify(const uint8_t *signature, size_t signature_len, const uint8_t *message,
-              size_t message_len, const uint8_t *public_key);
+              size_t message_len, const uint8_t *ctx, size_t ctx_len, const uint8_t *public_key);
 int pq_mldsa44_verify(const uint8_t *signature, size_t signature_len, const uint8_t *message,
-                      size_t message_len, const uint8_t *public_key);
+                      size_t message_len, const uint8_t *ctx, size_t ctx_len, const uint8_t *public_key);
 int pq_mldsa87_verify(const uint8_t *signature, size_t signature_len, const uint8_t *message,
-                      size_t message_len, const uint8_t *public_key);
+                      size_t message_len, const uint8_t *ctx, size_t ctx_len, const uint8_t *public_key);
 
 int pq_public_key_to_pqc_container_der(uint8_t **output, size_t *output_len,
                                        const uint8_t *public_key,
@@ -132,6 +132,26 @@ int pq_secret_key_from_pqc_container_pem(char **algorithm_out, uint8_t **key_out
                                           size_t *key_len_out, const char *input,
                                           size_t input_len);
 
+int pq_pkcs8_private_key_info_to_der(uint8_t **output, size_t *output_len,
+                                     const char *oid_text, const uint8_t *private_key,
+                                     size_t private_key_len);
+int pq_pkcs8_private_key_info_from_der(char **oid_text_out, uint8_t **private_key_out,
+                                       size_t *private_key_len_out, const uint8_t *input,
+                                       size_t input_len);
+int pq_pkcs8_encrypt_private_key_info_der(uint8_t **output, size_t *output_len,
+                                          const uint8_t *plain_der, size_t plain_der_len,
+                                          const char *passphrase, size_t passphrase_len,
+                                          int iterations);
+int pq_pkcs8_decrypt_private_key_info_der(uint8_t **output, size_t *output_len,
+                                          const uint8_t *encrypted_der,
+                                          size_t encrypted_der_len, const char *passphrase,
+                                          size_t passphrase_len);
+int pq_pkcs8_der_is_encrypted_private_key_info(const uint8_t *input, size_t input_len);
+int pq_pkcs8_der_to_pem(char **output, size_t *output_len, const uint8_t *der, size_t der_len,
+                        int encrypted);
+int pq_pkcs8_pem_to_der(uint8_t **der_out, size_t *der_len_out, int *encrypted_out,
+                        const char *input, size_t input_len);
+
 int pq_testing_mlkem_keypair_from_seed(uint8_t *public_key, uint8_t *secret_key,
                                        const uint8_t *seed, size_t seed_len);
 int pq_testing_mlkem512_keypair_from_seed(uint8_t *public_key, uint8_t *secret_key,
@@ -189,13 +209,18 @@ const char *pq_version(void);
 #define PQ_MLDSA_MUBYTES        64
 #define PQ_MLDSA_TRBYTES        64
 
-int pq_mldsa_extract_tr_from_secret_key(uint8_t *tr_out, const uint8_t *secret_key);
-int pq_mldsa_compute_tr_from_public_key(uint8_t *tr_out, const uint8_t *public_key);
+int pq_mldsa_extract_tr_from_secret_key(uint8_t *tr_out, const uint8_t *secret_key,
+                                        size_t public_key_len,
+                                        int (*pk_from_sk)(uint8_t *, const uint8_t *));
+int pq_mldsa_compute_tr_from_public_key(uint8_t *tr_out, const uint8_t *public_key,
+                                        size_t public_key_len);
 
 int pq_sign_mu(uint8_t *signature, size_t *signature_len,
-               const uint8_t *mu, const uint8_t *secret_key);
+               const uint8_t *mu, const uint8_t *secret_key,
+               int (*signature_extmu)(uint8_t *, size_t *, const uint8_t *, const uint8_t *));
 int pq_verify_mu(const uint8_t *signature, size_t signature_len,
-                 const uint8_t *mu, const uint8_t *public_key);
+                 const uint8_t *mu, const uint8_t *public_key, size_t expected_signature_len,
+                 int (*verify_extmu)(const uint8_t *, size_t, const uint8_t *, const uint8_t *));
 void *pq_mu_builder_new(void);
 int pq_mu_builder_init(void *state, const uint8_t *tr,
                        const uint8_t *ctx, size_t ctxlen);

data/ext/pqcrypto/pqcrypto_version.h

@@ -2,6 +2,6 @@
 #ifndef PQCRYPTO_VERSION_H
 #define PQCRYPTO_VERSION_H
 
-#define PQCRYPTO_VERSION "0.5.3"
+#define PQCRYPTO_VERSION "0.6.1"
 
 #endif

data/lib/pq_crypto/hybrid_kem.rb

@@ -79,12 +79,13 @@ module PQCrypto
 
     class SecretKey < KEM::SecretKey
       def decapsulate(ciphertext)
-        PQCrypto.__send__(:native_hybrid_kem_decapsulate_expanded_object, String(ciphertext).b, expanded_key_for_native)
+        PQCrypto.__send__(:native_hybrid_kem_decapsulate_expanded_object, Internal.binary_string(ciphertext), expanded_key_for_native)
       rescue ArgumentError => e
         raise InvalidCiphertextError, e.message
       end
 
       def wipe!
+        PQCrypto.__send__(:native_hybrid_kem_expanded_secret_key_wipe, @expanded_key) if @expanded_key
         @expanded_key = nil
         super
       end

data/lib/pq_crypto/internal.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module Internal
+    module_function
+
+    def binary_string(value)
+      String(value).b
+    end
+
+    def safe_wipe(value)
+      return unless value.is_a?(String) && !value.frozen?
+
+      PQCrypto.secure_wipe(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def constant_time_equal?(left, right)
+      PQCrypto.__send__(:native_ct_equals, left, right)
+    end
+  end
+end

data/lib/pq_crypto/kem.rb

@@ -44,6 +44,10 @@ module PQCrypto
         SecretKey.new(resolve_algorithm!(algorithm), bytes)
       end
 
+      def secret_key_from_seed(algorithm, seed)
+        SecretKey.from_seed(resolve_algorithm!(algorithm), seed)
+      end
+
       def public_key_from_pqc_container_der(der, algorithm = nil)
         resolved_algorithm, bytes = Serialization.public_key_from_pqc_container_der(algorithm, der)
         PublicKey.new(resolve_algorithm!(resolved_algorithm), bytes)
@@ -64,12 +68,12 @@ module PQCrypto
         SecretKey.new(resolve_algorithm!(resolved_algorithm), bytes)
       end
 
-      def secret_key_from_pkcs8_der(der)
-        secret_key_from_decoded_pkcs8(*PKCS8.decode_der(der))
+      def secret_key_from_pkcs8_der(der, passphrase: nil)
+        secret_key_from_decoded_pkcs8(*PKCS8.decode_der(der, passphrase: passphrase))
       end
 
-      def secret_key_from_pkcs8_pem(pem)
-        secret_key_from_decoded_pkcs8(*PKCS8.decode_pem(pem))
+      def secret_key_from_pkcs8_pem(pem, passphrase: nil)
+        secret_key_from_decoded_pkcs8(*PKCS8.decode_pem(pem, passphrase: passphrase))
       end
 
       def public_key_from_spki_der(der, algorithm: nil)
@@ -101,20 +105,20 @@ module PQCrypto
       end
 
       def secret_key_from_decoded_pkcs8(algorithm, format, material)
-        secret_material = case format
-                          when :seed
-                            _public_key, expanded = PQCrypto.__send__(native_method_for(algorithm, :keypair_from_seed), material)
-                            expanded
-                          when :both
-                            _seed, expanded = material
-                            expanded
-                          when :expanded
-                            material
-                          else
-                            raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
-                          end
-
-        SecretKey.new(resolve_algorithm!(algorithm), secret_material)
+        algorithm = resolve_algorithm!(algorithm)
+
+        case format
+        when :seed
+          _public_key, expanded = PQCrypto.__send__(native_method_for(algorithm, :keypair_from_seed), material)
+          SecretKey.new(algorithm, expanded, seed: material)
+        when :both
+          seed, expanded = material
+          SecretKey.new(algorithm, expanded, seed: seed)
+        when :expanded
+          SecretKey.new(algorithm, material)
+        else
+          raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
+        end
       end
 
       def native_method_for(algorithm, operation)
@@ -154,7 +158,7 @@ module PQCrypto
 
       def initialize(algorithm, bytes)
         @algorithm = algorithm
-        @bytes = String(bytes).b
+        @bytes = Internal.binary_string(bytes)
         validate_length!
       end
 
@@ -192,7 +196,7 @@ module PQCrypto
 
       def ==(other)
         return false unless other.is_a?(PublicKey) && other.algorithm == algorithm
-        PQCrypto.__send__(:native_ct_equals, other.to_bytes, @bytes)
+        Internal.constant_time_equal?(other.send(:bytes_for_native), @bytes)
       end
 
       alias eql? ==
@@ -207,6 +211,10 @@ module PQCrypto
 
       private
 
+      def bytes_for_native
+        @bytes
+      end
+
       def validate_length!
         expected = KEM.details(@algorithm).fetch(:public_key_bytes)
         raise InvalidKeyError, "Invalid KEM public key length" unless @bytes.bytesize == expected
@@ -216,10 +224,20 @@ module PQCrypto
     class SecretKey
       attr_reader :algorithm
 
-      def initialize(algorithm, bytes)
+      def initialize(algorithm, bytes, seed: nil)
         @algorithm = algorithm
-        @bytes = String(bytes).b
+        @bytes = Internal.binary_string(bytes)
+        @seed = seed.nil? ? nil : Internal.binary_string(seed)
         validate_length!
+        validate_seed_length! if @seed
+      end
+
+      def self.from_seed(algorithm, seed)
+        seed_bytes = Internal.binary_string(seed)
+        _public_key, expanded = PQCrypto.__send__(KEM.send(:native_method_for, algorithm, :keypair_from_seed), seed_bytes)
+        new(algorithm, expanded, seed: seed_bytes)
+      rescue ArgumentError => e
+        raise InvalidKeyError, e.message
       end
 
       def to_bytes
@@ -234,42 +252,29 @@ module PQCrypto
         Serialization.secret_key_to_pqc_container_pem(@algorithm, @bytes)
       end
 
-      def to_pkcs8_der(format: :expanded)
-        case format
-        when :expanded
-          PKCS8.encode_der(@algorithm, @bytes, format: :expanded)
-        when :seed, :both
-          raise SerializationError, "PKCS#8 #{format.inspect} export from KEM::SecretKey requires original seed material"
-        else
-          raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
-        end
+      def to_pkcs8_der(format: :expanded, passphrase: nil, iterations: PKCS8::ENCRYPTED_PKCS8_DEFAULT_ITERATIONS)
+        PKCS8.encode_der(@algorithm, pkcs8_material(format), format: format, passphrase: passphrase, iterations: iterations)
       end
 
-      def to_pkcs8_pem(format: :expanded)
-        case format
-        when :expanded
-          PKCS8.encode_pem(@algorithm, @bytes, format: :expanded)
-        when :seed, :both
-          raise SerializationError, "PKCS#8 #{format.inspect} export from KEM::SecretKey requires original seed material"
-        else
-          raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
-        end
+      def to_pkcs8_pem(format: :expanded, passphrase: nil, iterations: PKCS8::ENCRYPTED_PKCS8_DEFAULT_ITERATIONS)
+        PKCS8.encode_pem(@algorithm, pkcs8_material(format), format: format, passphrase: passphrase, iterations: iterations)
       end
 
       def decapsulate(ciphertext)
-        PQCrypto.__send__(KEM.send(:native_method_for, @algorithm, :decapsulate), String(ciphertext).b, @bytes)
+        PQCrypto.__send__(KEM.send(:native_method_for, @algorithm, :decapsulate), Internal.binary_string(ciphertext), @bytes)
       rescue ArgumentError => e
         raise InvalidCiphertextError, e.message
       end
 
       def wipe!
         PQCrypto.secure_wipe(@bytes)
+        PQCrypto.secure_wipe(@seed) if @seed
         self
       end
 
       def ==(other)
         return false unless other.is_a?(SecretKey) && other.algorithm == algorithm
-        PQCrypto.__send__(:native_ct_equals, other.to_bytes, @bytes)
+        Internal.constant_time_equal?(other.send(:bytes_for_native), @bytes)
       end
 
       alias eql? ==
@@ -284,18 +289,48 @@ module PQCrypto
 
       private
 
+      def bytes_for_native
+        @bytes
+      end
+
       def validate_length!
         expected = KEM.details(@algorithm).fetch(:secret_key_bytes)
         raise InvalidKeyError, "Invalid KEM secret key length" unless @bytes.bytesize == expected
       end
+
+      def pkcs8_material(format)
+        case format
+        when :expanded
+          @bytes
+        when :seed
+          ensure_seed_available!(format)
+          @seed
+        when :both
+          ensure_seed_available!(format)
+          [@seed, @bytes]
+        else
+          raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
+        end
+      end
+
+      def validate_seed_length!
+        expected = PKCS8::PrivateKeyChoice.seed_bytes(@algorithm)
+        raise InvalidKeyError, "Invalid KEM seed length" unless @seed.bytesize == expected
+      end
+
+      def ensure_seed_available!(format)
+        return if @seed
+
+        raise SerializationError, "PKCS#8 #{format.inspect} export from KEM::SecretKey requires original seed material"
+      end
     end
 
     class EncapsulationResult
       attr_reader :ciphertext, :shared_secret
 
       def initialize(ciphertext, shared_secret)
-        @ciphertext = String(ciphertext).b
-        @shared_secret = String(shared_secret).b
+        @ciphertext = Internal.binary_string(ciphertext)
+        @shared_secret = Internal.binary_string(shared_secret)
       end
 
       def inspect

data/lib/pq_crypto/key.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module Key
+    class << self
+      def generate(algorithm)
+        algorithm = resolve_algorithm!(algorithm)
+        case AlgorithmRegistry.fetch(algorithm).fetch(:family)
+        when :ml_kem
+          KEM.generate(algorithm)
+        when :ml_dsa
+          Signature.generate(algorithm)
+        when :ml_kem_hybrid
+          HybridKEM.generate(algorithm)
+        else
+          raise UnsupportedAlgorithmError, "Unsupported key generation algorithm: #{algorithm.inspect}"
+        end
+      end
+
+      def from_pem(pem, passphrase: nil)
+        text = String(pem)
+        if text.include?(SPKI::PEM_BEGIN)
+          public_key_from_spki_pem(text)
+        elsif text.include?(PKCS8::PEM_BEGIN) || text.include?(PKCS8::ENCRYPTED_PEM_BEGIN)
+          secret_key_from_pkcs8_pem(text, passphrase: passphrase)
+        else
+          raise SerializationError, "Unsupported PEM label for PQCrypto::Key.from_pem"
+        end
+      end
+
+      def from_der(der, passphrase: nil)
+        public_key_from_spki_der(der)
+      rescue SerializationError => spki_error
+        begin
+          secret_key_from_pkcs8_der(der, passphrase: passphrase)
+        rescue SerializationError => pkcs8_error
+          raise SerializationError,
+                "Unable to decode DER as SPKI or PKCS#8 (SPKI: #{spki_error.message}; PKCS#8: #{pkcs8_error.message})"
+        end
+      end
+
+      private
+
+      def resolve_algorithm!(algorithm)
+        AlgorithmRegistry.fetch(algorithm)
+        algorithm
+      end
+
+      def public_key_from_spki_pem(pem)
+        algorithm, bytes = SPKI.decode_pem(pem)
+        public_key_from_algorithm_and_bytes(algorithm, bytes)
+      end
+
+      def public_key_from_spki_der(der)
+        algorithm, bytes = SPKI.decode_der(der)
+        public_key_from_algorithm_and_bytes(algorithm, bytes)
+      end
+
+      def secret_key_from_pkcs8_pem(pem, passphrase: nil)
+        secret_key_from_decoded_pkcs8(*PKCS8.decode_pem(pem, passphrase: passphrase))
+      end
+
+      def secret_key_from_pkcs8_der(der, passphrase: nil)
+        secret_key_from_decoded_pkcs8(*PKCS8.decode_der(der, passphrase: passphrase))
+      end
+
+      def secret_key_from_decoded_pkcs8(algorithm, format, material)
+        case AlgorithmRegistry.fetch(algorithm).fetch(:family)
+        when :ml_kem
+          KEM.send(:secret_key_from_decoded_pkcs8, algorithm, format, material)
+        when :ml_dsa
+          Signature.send(:secret_key_from_decoded_pkcs8, algorithm, format, material)
+        else
+          raise SerializationError, "PKCS#8 private key codec is not supported for #{algorithm.inspect}"
+        end
+      end
+
+      def public_key_from_algorithm_and_bytes(algorithm, bytes)
+        case AlgorithmRegistry.fetch(algorithm).fetch(:family)
+        when :ml_kem
+          KEM::PublicKey.new(algorithm, bytes)
+        when :ml_dsa
+          Signature::PublicKey.new(algorithm, bytes)
+        else
+          raise SerializationError, "SPKI public key codec is not supported for #{algorithm.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/pq_crypto/pkcs8/der.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module PKCS8
+    module DER
+      module_function
+
+      def encode_tlv(tag, value)
+        tag.chr.b + encode_length(value.bytesize) + value
+      end
+
+      def decode_tlv(der, offset, expected_tag:, label:)
+        tag = der.getbyte(offset)
+        raise SerializationError, "PKCS#8 #{label} is missing" if tag.nil?
+        unless tag == expected_tag
+          raise SerializationError, "PKCS#8 #{label} has unexpected tag: 0x#{tag.to_s(16).rjust(2, '0')}"
+        end
+
+        length, length_bytes = decode_length(der, offset + 1)
+        value_offset = offset + 1 + length_bytes
+        value_end = value_offset + length
+        raise SerializationError, "PKCS#8 #{label} length exceeds available data" if value_end > der.bytesize
+
+        [tag, der.byteslice(value_offset, length).b, value_end]
+      end
+
+      def encode_length(length)
+        raise SerializationError, "Invalid DER length" if length.negative?
+        return length.chr.b if length < 0x80
+
+        encoded = []
+        remaining = length
+        until remaining.zero?
+          encoded.unshift(remaining & 0xff)
+          remaining >>= 8
+        end
+
+        (0x80 | encoded.length).chr.b + encoded.pack("C*").b
+      end
+
+      def decode_length(der, offset)
+        first = der.getbyte(offset)
+        raise SerializationError, "PKCS#8 DER length is missing" if first.nil?
+
+        return [first, 1] if first < 0x80
+
+        length_octets = first & 0x7f
+        raise SerializationError, "PKCS#8 DER indefinite length is not allowed" if length_octets.zero?
+        raise SerializationError, "PKCS#8 DER length is too large" if length_octets > 4
+        if offset + 1 + length_octets > der.bytesize
+          raise SerializationError, "PKCS#8 DER length exceeds available data"
+        end
+
+        length = 0
+        length_octets.times do |i|
+          byte = der.getbyte(offset + 1 + i)
+          length = (length << 8) | byte
+        end
+
+        if length < 0x80 || (length_octets > 1 && der.getbyte(offset + 1).zero?)
+          raise SerializationError, "PKCS#8 DER length is not minimally encoded"
+        end
+
+        [length, 1 + length_octets]
+      end
+    end
+  end
+end

data/lib/pq_crypto/pkcs8/private_key_choice.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module PKCS8
+    module PrivateKeyChoice
+      SEED_TAG = 0x80
+      EXPANDED_TAG = 0x04
+      BOTH_TAG = 0x30
+
+      KEYPAIR_FROM_SEED_METHODS = {
+        ml_kem_512: :native_ml_kem_512_keypair_from_seed,
+        ml_kem_768: :native_ml_kem_keypair_from_seed,
+        ml_kem_1024: :native_ml_kem_1024_keypair_from_seed,
+        ml_dsa_44: :native_ml_dsa_44_keypair_from_seed,
+        ml_dsa_65: :native_ml_dsa_keypair_from_seed,
+        ml_dsa_87: :native_ml_dsa_87_keypair_from_seed,
+      }.freeze
+
+      module_function
+
+      def encode(algorithm, secret_material, format)
+        ensure_format_supported!(algorithm, format)
+
+        case format
+        when :seed
+          encode_seed(algorithm, secret_material)
+        when :expanded
+          encode_expanded(algorithm, secret_material)
+        when :both
+          encode_both(algorithm, secret_material)
+        else
+          raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
+        end
+      end
+
+      def decode(algorithm, choice_der)
+        tag = choice_der.getbyte(0)
+        raise SerializationError, "PKCS#8 privateKey CHOICE is empty" if tag.nil?
+
+        case tag
+        when SEED_TAG
+          ensure_format_supported!(algorithm, :seed)
+          decode_seed(algorithm, choice_der)
+        when EXPANDED_TAG
+          ensure_format_supported!(algorithm, :expanded)
+          decode_expanded(algorithm, choice_der)
+        when BOTH_TAG
+          ensure_format_supported!(algorithm, :both)
+          decode_both(algorithm, choice_der)
+        else
+          raise SerializationError,
+                "Unsupported PKCS#8 #{algorithm.inspect} private key CHOICE tag: 0x#{tag.to_s(16).rjust(2, '0')}"
+        end
+      end
+
+      def validate_secret_key_algorithm!(algorithm, entry)
+        return if PKCS8::PRIVATE_KEY_CHOICES.key?(algorithm) && %i[ml_kem ml_dsa].include?(entry.fetch(:family))
+
+        raise SerializationError, "PKCS#8 private key codec is not supported for #{algorithm.inspect}"
+      end
+
+      def ensure_format_supported!(algorithm, format)
+        if ml_dsa_algorithm?(algorithm) && %i[seed both].include?(format) && !PKCS8.allow_ml_dsa_seed_format
+          raise SerializationError,
+                "ML-DSA seed-format PKCS#8 is opt-in; set PQCrypto::PKCS8.allow_ml_dsa_seed_format = true to enable (see SECURITY.md for caveats)"
+        end
+
+        return if profile(algorithm).fetch(:supported_formats).include?(format)
+
+        raise SerializationError, "Unsupported PKCS#8 private key format for #{algorithm.inspect}: #{format.inspect}"
+      end
+
+      def seed_bytes(algorithm)
+        profile(algorithm).fetch(:seed_bytes)
+      end
+
+      def expanded_bytes(algorithm)
+        profile(algorithm).fetch(:expanded_bytes)
+      end
+
+      def ml_dsa_algorithm?(algorithm)
+        %i[ml_dsa_44 ml_dsa_65 ml_dsa_87].include?(algorithm)
+      end
+
+      def profile(algorithm)
+        PKCS8::PRIVATE_KEY_CHOICES.fetch(algorithm) do
+          raise SerializationError, "PKCS#8 private key codec is not supported for #{algorithm.inspect}"
+        end
+      end
+
+      def validate_seed_length!(algorithm, seed)
+        expected = seed_bytes(algorithm)
+        return if seed.bytesize == expected
+
+        raise SerializationError,
+              "Invalid #{algorithm.inspect} seed private key length: expected #{expected}, got #{seed.bytesize}"
+      end
+
+      def validate_expanded_length!(algorithm, expanded)
+        expected = expanded_bytes(algorithm)
+        return if expanded.bytesize == expected
+
+        raise SerializationError,
+              "Invalid #{algorithm.inspect} expanded private key length: expected #{expected}, got #{expanded.bytesize}"
+      end
+
+      def decode_seed(algorithm, choice_der)
+        _tag, seed, next_offset = DER.decode_tlv(choice_der, 0, expected_tag: SEED_TAG, label: "seed")
+        raise SerializationError, "PKCS#8 seed contains trailing data" unless next_offset == choice_der.bytesize
+
+        validate_seed_length!(algorithm, seed)
+        [algorithm, :seed, seed]
+      end
+
+      def decode_expanded(algorithm, choice_der)
+        _tag, bytes, next_offset = DER.decode_tlv(choice_der, 0, expected_tag: EXPANDED_TAG, label: "expandedKey")
+        raise SerializationError, "PKCS#8 expandedKey contains trailing data" unless next_offset == choice_der.bytesize
+
+        validate_expanded_length!(algorithm, bytes)
+        [algorithm, :expanded, bytes]
+      end
+
+      def decode_both(algorithm, choice_der)
+        _tag, body, next_offset = DER.decode_tlv(choice_der, 0, expected_tag: BOTH_TAG, label: "both")
+        raise SerializationError, "PKCS#8 both contains trailing data" unless next_offset == choice_der.bytesize
+
+        _seed_tag, seed_bytes, offset = DER.decode_tlv(body, 0, expected_tag: EXPANDED_TAG, label: "both seed")
+        _expanded_tag, expanded_bytes, offset = DER.decode_tlv(body, offset, expected_tag: EXPANDED_TAG, label: "both expandedKey")
+        raise SerializationError, "PKCS#8 both must contain exactly 2 elements" unless offset == body.bytesize
+
+        validate_seed_length!(algorithm, seed_bytes)
+        validate_expanded_length!(algorithm, expanded_bytes)
+        verify_both_consistency!(algorithm, seed_bytes, expanded_bytes)
+
+        [algorithm, :both, [seed_bytes, expanded_bytes]]
+      end
+
+      def encode_seed(algorithm, secret_material)
+        seed = Internal.binary_string(secret_material)
+        validate_seed_length!(algorithm, seed)
+
+        DER.encode_tlv(SEED_TAG, seed)
+      end
+
+      def encode_expanded(algorithm, secret_material)
+        bytes = Internal.binary_string(secret_material)
+        validate_expanded_length!(algorithm, bytes)
+
+        DER.encode_tlv(EXPANDED_TAG, bytes)
+      end
+
+      def encode_both(algorithm, secret_material)
+        unless secret_material.is_a?(Array) && secret_material.size == 2
+          raise SerializationError, "PKCS#8 both format requires [seed, expandedKey]"
+        end
+
+        seed, expanded = secret_material
+        seed_bytes = Internal.binary_string(seed)
+        expanded_bytes = Internal.binary_string(expanded)
+        validate_seed_length!(algorithm, seed_bytes)
+        validate_expanded_length!(algorithm, expanded_bytes)
+
+        body = DER.encode_tlv(EXPANDED_TAG, seed_bytes) + DER.encode_tlv(EXPANDED_TAG, expanded_bytes)
+        DER.encode_tlv(BOTH_TAG, body)
+      end
+
+      def verify_both_consistency!(algorithm, seed, expanded)
+        native_method = KEYPAIR_FROM_SEED_METHODS.fetch(algorithm, nil)
+        return if native_method.nil?
+
+        _public_key, expected_expanded = PQCrypto.__send__(native_method, seed)
+        return if Internal.constant_time_equal?(expected_expanded, expanded)
+
+        raise SerializationError, consistency_error_message(algorithm)
+      ensure
+        Internal.safe_wipe(expected_expanded) if defined?(expected_expanded)
+      end
+
+      def consistency_error_message(algorithm)
+        return "seed/expandedKey inconsistency in ML-DSA PKCS#8 'both' encoding (RFC 9881 §6)" if ml_dsa_algorithm?(algorithm)
+
+        "seed/expandedKey inconsistency in PKCS#8 'both' encoding (RFC 9935 §8)"
+      end
+    end
+  end
+end