pq_crypto 0.6.0 → 0.6.1

data/lib/pq_crypto/kem.rb

@@ -158,7 +158,7 @@ module PQCrypto
 
       def initialize(algorithm, bytes)
         @algorithm = algorithm
-        @bytes = String(bytes).b
+        @bytes = Internal.binary_string(bytes)
         validate_length!
       end
 
@@ -196,7 +196,7 @@ module PQCrypto
 
       def ==(other)
         return false unless other.is_a?(PublicKey) && other.algorithm == algorithm
-        PQCrypto.__send__(:native_ct_equals, other.send(:bytes_for_native), @bytes)
+        Internal.constant_time_equal?(other.send(:bytes_for_native), @bytes)
       end
 
       alias eql? ==
@@ -226,14 +226,14 @@ module PQCrypto
 
       def initialize(algorithm, bytes, seed: nil)
         @algorithm = algorithm
-        @bytes = String(bytes).b
-        @seed = seed.nil? ? nil : String(seed).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 = String(seed).b
+        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
@@ -253,37 +253,15 @@ module PQCrypto
       end
 
       def to_pkcs8_der(format: :expanded, passphrase: nil, iterations: PKCS8::ENCRYPTED_PKCS8_DEFAULT_ITERATIONS)
-        case format
-        when :expanded
-          PKCS8.encode_der(@algorithm, @bytes, format: :expanded, passphrase: passphrase, iterations: iterations)
-        when :seed
-          ensure_seed_available!(format)
-          PKCS8.encode_der(@algorithm, @seed, format: :seed, passphrase: passphrase, iterations: iterations)
-        when :both
-          ensure_seed_available!(format)
-          PKCS8.encode_der(@algorithm, [@seed, @bytes], format: :both, passphrase: passphrase, iterations: iterations)
-        else
-          raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
-        end
+        PKCS8.encode_der(@algorithm, pkcs8_material(format), format: format, passphrase: passphrase, iterations: iterations)
       end
 
       def to_pkcs8_pem(format: :expanded, passphrase: nil, iterations: PKCS8::ENCRYPTED_PKCS8_DEFAULT_ITERATIONS)
-        case format
-        when :expanded
-          PKCS8.encode_pem(@algorithm, @bytes, format: :expanded, passphrase: passphrase, iterations: iterations)
-        when :seed
-          ensure_seed_available!(format)
-          PKCS8.encode_pem(@algorithm, @seed, format: :seed, passphrase: passphrase, iterations: iterations)
-        when :both
-          ensure_seed_available!(format)
-          PKCS8.encode_pem(@algorithm, [@seed, @bytes], format: :both, passphrase: passphrase, iterations: iterations)
-        else
-          raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
-        end
+        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
@@ -296,7 +274,7 @@ module PQCrypto
 
       def ==(other)
         return false unless other.is_a?(SecretKey) && other.algorithm == algorithm
-        PQCrypto.__send__(:native_ct_equals, other.send(:bytes_for_native), @bytes)
+        Internal.constant_time_equal?(other.send(:bytes_for_native), @bytes)
       end
 
       alias eql? ==
@@ -320,8 +298,23 @@ module PQCrypto
         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::PRIVATE_KEY_CHOICES.fetch(@algorithm).fetch(:seed_bytes)
+        expected = PKCS8::PrivateKeyChoice.seed_bytes(@algorithm)
         raise InvalidKeyError, "Invalid KEM seed length" unless @seed.bytesize == expected
       end
 
@@ -336,8 +329,8 @@ module PQCrypto
       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/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