pq_crypto 0.5.3 → 0.6.1

data/lib/pq_crypto/pkcs8.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
-require "openssl"
-
 module PQCrypto
   module PKCS8
     PEM_LABEL = "PRIVATE KEY"
     PEM_BEGIN = "-----BEGIN #{PEM_LABEL}-----"
     PEM_END = "-----END #{PEM_LABEL}-----"
+    ENCRYPTED_PEM_LABEL = "ENCRYPTED PRIVATE KEY"
+    ENCRYPTED_PEM_BEGIN = "-----BEGIN #{ENCRYPTED_PEM_LABEL}-----"
+    ENCRYPTED_PEM_END = "-----END #{ENCRYPTED_PEM_LABEL}-----"
     ML_KEM_SEED_BYTES = 64
     ML_DSA_SEED_BYTES = 32
+    ENCRYPTED_PKCS8_DEFAULT_ITERATIONS = 200_000
 
     @allow_ml_dsa_seed_format = false
 
@@ -48,340 +50,95 @@ module PQCrypto
     class << self
       attr_accessor :allow_ml_dsa_seed_format
 
-      def encode_der(algorithm_symbol, secret_material, format:)
-        entry = AlgorithmRegistry.fetch(algorithm_symbol)
-        validate_secret_key_algorithm!(algorithm_symbol, entry)
-        ensure_format_supported!(algorithm_symbol, format)
-
-        choice_der = case format
-                     when :seed
-                       encode_seed_choice(secret_material, algorithm_symbol)
-                     when :expanded
-                       encode_expanded_key_choice(secret_material, algorithm_symbol)
-                     when :both
-                       encode_both_choice(secret_material, algorithm_symbol)
-                     else
-                       raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
-                     end
-
-        OpenSSL::ASN1::Sequence.new([
-          OpenSSL::ASN1::Integer.new(0),
-          OpenSSL::ASN1::Sequence.new([
-            OpenSSL::ASN1::ObjectId.new(AlgorithmRegistry.standard_oid(algorithm_symbol)),
-          ]),
-          OpenSSL::ASN1::OctetString.new(choice_der),
-        ]).to_der.b
-      rescue OpenSSL::ASN1::ASN1Error => e
-        raise SerializationError, e.message
-      end
-
-      def encode_pem(algorithm_symbol, secret_material, format:)
-        der = encode_der(algorithm_symbol, secret_material, format: format)
-        body = encode_base64(der).scan(/.{1,64}/).join("\n")
-        "#{PEM_BEGIN}\n#{body}\n#{PEM_END}\n"
-      end
-
-      def decode_der(der)
-        input = String(der).b
-        outer = decode_asn1(input)
-        raise SerializationError, "PKCS#8 DER contains trailing data" unless outer.to_der.b == input
-        raise SerializationError, "PKCS#8 must be an ASN.1 SEQUENCE" unless outer.is_a?(OpenSSL::ASN1::Sequence)
-        raise SerializationError, "PKCS#8 OneAsymmetricKey must contain exactly 3 elements" unless outer.value.size == 3
-
-        version, algorithm_identifier, private_key = outer.value
-        decode_version(version)
-        algorithm = decode_algorithm_identifier(algorithm_identifier)
+      def encode_der(algorithm, secret_material, format:, passphrase: nil, iterations: ENCRYPTED_PKCS8_DEFAULT_ITERATIONS)
         entry = AlgorithmRegistry.fetch(algorithm)
-        validate_secret_key_algorithm!(algorithm, entry)
+        PrivateKeyChoice.validate_secret_key_algorithm!(algorithm, entry)
 
-        unless private_key.is_a?(OpenSSL::ASN1::OctetString)
-          raise SerializationError, "PKCS#8 privateKey must be an OCTET STRING"
-        end
-
-        decode_private_key_choice(algorithm, String(private_key.value).b)
-      end
+        choice_der = PrivateKeyChoice.encode(algorithm, secret_material, format)
+        der = private_key_info_to_der(algorithm, choice_der)
+        return der if passphrase.nil?
 
-      def decode_pem(pem)
-        der = der_from_pem(pem)
-        decode_der(der)
-      end
-
-      private
-
-      def decode_asn1(der)
-        OpenSSL::ASN1.decode(der)
-      rescue OpenSSL::ASN1::ASN1Error => e
+        encrypt_der(der, passphrase: passphrase, iterations: iterations)
+      rescue ArgumentError => e
         raise SerializationError, e.message
+      ensure
+        Internal.safe_wipe(choice_der) if defined?(choice_der)
+        Internal.safe_wipe(der) if passphrase && defined?(der)
       end
 
-      def decode_version(value)
-        raise SerializationError, "PKCS#8 version must be an INTEGER" unless value.is_a?(OpenSSL::ASN1::Integer)
-
-        version = value.value.respond_to?(:to_i) ? value.value.to_i : value.value
-        raise SerializationError, "PKCS#8 version must be 0" unless version == 0
-      end
-
-      def decode_algorithm_identifier(value)
-        unless value.is_a?(OpenSSL::ASN1::Sequence)
-          raise SerializationError, "PKCS#8 algorithm must be an AlgorithmIdentifier SEQUENCE"
-        end
-        unless value.value.size == 1
-          raise SerializationError, "PKCS#8 AlgorithmIdentifier parameters must be absent"
-        end
-
-        oid = value.value.first
-        raise SerializationError, "PKCS#8 AlgorithmIdentifier must contain an OBJECT IDENTIFIER" unless oid.is_a?(OpenSSL::ASN1::ObjectId)
-
-        algorithm = AlgorithmRegistry.by_standard_oid(oid.oid)
-        raise SerializationError, "Unsupported PKCS#8 algorithm OID: #{oid.oid}" if algorithm.nil?
-
-        algorithm
-      end
-
-      def decode_private_key_choice(algorithm, choice_der)
-        tag = choice_der.getbyte(0)
-        raise SerializationError, "PKCS#8 privateKey CHOICE is empty" if tag.nil?
-
-        case tag
-        when 0x80
-          ensure_format_supported!(algorithm, :seed)
-          decode_seed_choice(algorithm, choice_der)
-        when 0x04
-          ensure_format_supported!(algorithm, :expanded)
-          decode_expanded_key(algorithm, choice_der)
-        when 0x30
-          ensure_format_supported!(algorithm, :both)
-          decode_both_choice(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 decode_seed_choice(algorithm, choice_der)
-        seed = decode_tlv_value(choice_der, expected_tag: 0x80, label: "seed")
-        validate_seed_length!(algorithm, seed)
-
-        [algorithm, :seed, seed]
+      def encode_pem(algorithm, secret_material, format:, passphrase: nil, iterations: ENCRYPTED_PKCS8_DEFAULT_ITERATIONS)
+        der = encode_der(algorithm, secret_material, format: format, passphrase: passphrase, iterations: iterations)
+        pkcs8_native { PQCrypto.__send__(:native_pkcs8_der_to_pem, der, !passphrase.nil?) }
       end
 
-      def decode_expanded_key(algorithm, choice_der)
-        expanded = decode_asn1(choice_der)
-        unless expanded.to_der.b == choice_der
-          raise SerializationError, "PKCS#8 expandedKey contains trailing data"
-        end
-        unless expanded.is_a?(OpenSSL::ASN1::OctetString)
-          raise SerializationError, "PKCS#8 expandedKey must be an OCTET STRING"
-        end
-
-        bytes = String(expanded.value).b
-        validate_expanded_key_length!(algorithm, bytes)
-
-        [algorithm, :expanded, bytes]
-      end
-
-      def decode_both_choice(algorithm, choice_der)
-        both = decode_asn1(choice_der)
-        raise SerializationError, "PKCS#8 both contains trailing data" unless both.to_der.b == choice_der
-        raise SerializationError, "PKCS#8 both must be a SEQUENCE" unless both.is_a?(OpenSSL::ASN1::Sequence)
-        raise SerializationError, "PKCS#8 both must contain exactly 2 elements" unless both.value.size == 2
-
-        seed, expanded = both.value
-        raise SerializationError, "PKCS#8 both seed must be an OCTET STRING" unless seed.is_a?(OpenSSL::ASN1::OctetString)
-        unless expanded.is_a?(OpenSSL::ASN1::OctetString)
-          raise SerializationError, "PKCS#8 both expandedKey must be an OCTET STRING"
-        end
-
-        seed_bytes = String(seed.value).b
-        expanded_bytes = String(expanded.value).b
-        validate_seed_length!(algorithm, seed_bytes)
-        validate_expanded_key_length!(algorithm, expanded_bytes)
-        verify_both_consistency!(algorithm, seed_bytes, expanded_bytes)
-
-        [algorithm, :both, [seed_bytes, expanded_bytes]]
-      end
-
-      def encode_seed_choice(secret_material, algorithm)
-        seed = String(secret_material).b
-        validate_seed_length!(algorithm, seed)
-
-        encode_tlv(0x80, seed)
-      end
+      def decode_der(der, passphrase: nil)
+        input = Internal.binary_string(der)
+        return decode_encrypted_der(input, passphrase: passphrase) if encrypted_der?(input)
 
-      def encode_expanded_key_choice(secret_material, algorithm)
-        bytes = String(secret_material).b
-        validate_expanded_key_length!(algorithm, bytes)
+        oid, choice_der = private_key_info_from_der(input)
+        algorithm = AlgorithmRegistry.by_standard_oid(oid)
+        raise SerializationError, "Unsupported PKCS#8 algorithm OID: #{oid}" if algorithm.nil?
 
-        OpenSSL::ASN1::OctetString.new(bytes).to_der.b
+        entry = AlgorithmRegistry.fetch(algorithm)
+        PrivateKeyChoice.validate_secret_key_algorithm!(algorithm, entry)
+        PrivateKeyChoice.decode(algorithm, Internal.binary_string(choice_der))
+      rescue ArgumentError => e
+        raise SerializationError, e.message
+      ensure
+        Internal.safe_wipe(choice_der) if defined?(choice_der)
       end
 
-      def encode_both_choice(secret_material, algorithm)
-        unless secret_material.is_a?(Array) && secret_material.size == 2
-          raise SerializationError, "PKCS#8 both format requires [seed, expandedKey]"
+      def decode_pem(pem, passphrase: nil)
+        _encrypted, der = pkcs8_native { PQCrypto.__send__(:native_pkcs8_pem_to_der, String(pem)) }
+        begin
+          decode_der(der, passphrase: passphrase)
+        ensure
+          Internal.safe_wipe(der)
         end
-
-        seed, expanded = secret_material
-        seed_bytes = String(seed).b
-        expanded_bytes = String(expanded).b
-        validate_seed_length!(algorithm, seed_bytes)
-        validate_expanded_key_length!(algorithm, expanded_bytes)
-
-        OpenSSL::ASN1::Sequence.new([
-          OpenSSL::ASN1::OctetString.new(seed_bytes),
-          OpenSSL::ASN1::OctetString.new(expanded_bytes),
-        ]).to_der.b
-      end
-
-      def verify_both_consistency!(algorithm, seed, expanded)
-        native_method = {
-          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,
-        }[algorithm]
-        return if native_method.nil?
-
-        _public_key, expected_expanded = PQCrypto.__send__(native_method, seed)
-        return if PQCrypto.__send__(:native_ct_equals, expected_expanded, expanded)
-
-        message = if ml_dsa_algorithm?(algorithm)
-                    "seed/expandedKey inconsistency in ML-DSA PKCS#8 'both' encoding (RFC 9881 §6)"
-                  else
-                    "seed/expandedKey inconsistency in PKCS#8 'both' encoding (RFC 9935 §8)"
-                  end
-        raise SerializationError, message
-      end
-
-      def validate_seed_length!(algorithm, seed)
-        expected = choice_profile(algorithm).fetch(:seed_bytes)
-        return if seed.bytesize == expected
-
-        raise SerializationError,
-              "Invalid #{algorithm.inspect} seed private key length: expected #{expected}, got #{seed.bytesize}"
       end
 
-      def validate_expanded_key_length!(algorithm, expanded)
-        expected = choice_profile(algorithm).fetch(:expanded_bytes)
-        return if expanded.bytesize == expected
-
-        raise SerializationError,
-              "Invalid #{algorithm.inspect} expanded private key length: expected #{expected}, got #{expanded.bytesize}"
-      end
-
-      def validate_secret_key_algorithm!(algorithm_symbol, entry)
-        return if PRIVATE_KEY_CHOICES.key?(algorithm_symbol) && %i[ml_kem ml_dsa].include?(entry.fetch(:family))
-
-        raise SerializationError, "PKCS#8 private key codec is not supported for #{algorithm_symbol.inspect}"
-      end
+      private
 
-      def choice_profile(algorithm)
-        PRIVATE_KEY_CHOICES.fetch(algorithm) do
-          raise SerializationError, "PKCS#8 private key codec is not supported for #{algorithm.inspect}"
+      def private_key_info_to_der(algorithm, choice_der)
+        pkcs8_native do
+          PQCrypto.__send__(:native_pkcs8_private_key_info_to_der,
+                            AlgorithmRegistry.standard_oid(algorithm), choice_der)
         end
       end
 
-      def ensure_format_supported!(algorithm, format)
-        if ml_dsa_algorithm?(algorithm) && %i[seed both].include?(format) && !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
-
-        profile = choice_profile(algorithm)
-        return if profile.fetch(:supported_formats).include?(format)
-
-        raise SerializationError, "Unsupported PKCS#8 private key format for #{algorithm.inspect}: #{format.inspect}"
+      def private_key_info_from_der(der)
+        pkcs8_native { PQCrypto.__send__(:native_pkcs8_private_key_info_from_der, der) }
       end
 
-      def ml_dsa_algorithm?(algorithm)
-        %i[ml_dsa_44 ml_dsa_65 ml_dsa_87].include?(algorithm)
+      def encrypted_der?(der)
+        pkcs8_native { PQCrypto.__send__(:native_pkcs8_encrypted_der?, der) }
       end
 
-      def encode_tlv(tag, value)
-        tag.chr.b + encode_der_length(value.bytesize) + value
-      end
+      def encrypt_der(der, passphrase:, iterations:)
+        iterations = Integer(iterations)
+        raise SerializationError, "Encrypted PKCS#8 iterations must be positive" unless iterations.positive?
 
-      def decode_tlv_value(der, expected_tag:, label:)
-        tag = der.getbyte(0)
-        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_der_length(der, 1)
-        value_offset = 1 + length_bytes
-        value_end = value_offset + length
-        raise SerializationError, "PKCS#8 #{label} length exceeds available data" if value_end > der.bytesize
-        raise SerializationError, "PKCS#8 #{label} contains trailing data" unless value_end == der.bytesize
-
-        der.byteslice(value_offset, length).b
+        pkcs8_native { PQCrypto.__send__(:native_pkcs8_encrypt_der, der, String(passphrase), iterations) }
       end
 
-      def encode_der_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_der_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
+      def decode_encrypted_der(der, passphrase:)
+        raise SerializationError, "Encrypted PKCS#8 requires passphrase" if passphrase.nil?
 
-        if length < 0x80 || (length_octets > 1 && der.getbyte(offset + 1).zero?)
-          raise SerializationError, "PKCS#8 DER length is not minimally encoded"
+        plain_der = pkcs8_native { PQCrypto.__send__(:native_pkcs8_decrypt_der, der, String(passphrase)) }
+        begin
+          decode_der(plain_der)
+        ensure
+          Internal.safe_wipe(plain_der)
         end
-
-        [length, 1 + length_octets]
-      end
-
-      def encode_base64(bytes)
-        [String(bytes).b].pack("m0")
       end
 
-      def decode_base64(body)
-        compact = body.gsub(/[\r\n]/, "")
-        unless compact.match?(/\A(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?\z/)
-          raise SerializationError, "Invalid PKCS#8 PEM: invalid base64"
-        end
-
-        compact.unpack1("m0").b
-      rescue ArgumentError => e
+      def pkcs8_native
+        yield
+      rescue SerializationError
+        raise
+      rescue PQCrypto::Error => e
         raise SerializationError, e.message
       end
-
-      def der_from_pem(pem)
-        text = String(pem)
-        match = text.match(/\A#{Regexp.escape(PEM_BEGIN)}\r?\n(?<body>[A-Za-z0-9+\/=\r\n]+)\r?\n#{Regexp.escape(PEM_END)}[ \t\r\n]*\z/)
-        raise SerializationError, "Invalid PKCS#8 PEM: expected #{PEM_LABEL.inspect} label" unless match
-
-        body = match[:body]
-        raise SerializationError, "Invalid PKCS#8 PEM: embedded NUL in body" if body.include?("\0")
-
-        decode_base64(body)
-      end
     end
   end
 end

data/lib/pq_crypto/serialization.rb

@@ -21,63 +21,53 @@ module PQCrypto
       end
 
       def public_key_to_pqc_container_der(algorithm, bytes)
-        PQCrypto.__send__(:native_public_key_to_pqc_container_der, String(algorithm), String(bytes).b)
-      rescue ArgumentError, PQCrypto::Error => e
-        raise SerializationError, e.message
+        dump(:native_public_key_to_pqc_container_der, algorithm, bytes)
       end
 
       def public_key_to_pqc_container_pem(algorithm, bytes)
-        PQCrypto.__send__(:native_public_key_to_pqc_container_pem, String(algorithm), String(bytes).b)
-      rescue ArgumentError, PQCrypto::Error => e
-        raise SerializationError, e.message
+        dump(:native_public_key_to_pqc_container_pem, algorithm, bytes)
       end
 
       def secret_key_to_pqc_container_der(algorithm, bytes)
-        PQCrypto.__send__(:native_secret_key_to_pqc_container_der, String(algorithm), String(bytes).b)
-      rescue ArgumentError, PQCrypto::Error => e
-        raise SerializationError, e.message
+        dump(:native_secret_key_to_pqc_container_der, algorithm, bytes)
       end
 
       def secret_key_to_pqc_container_pem(algorithm, bytes)
-        PQCrypto.__send__(:native_secret_key_to_pqc_container_pem, String(algorithm), String(bytes).b)
-      rescue ArgumentError, PQCrypto::Error => e
-        raise SerializationError, e.message
+        dump(:native_secret_key_to_pqc_container_pem, algorithm, bytes)
       end
 
       def public_key_from_pqc_container_der(expected_algorithm, der)
-        algorithm, bytes = PQCrypto.__send__(:native_public_key_from_pqc_container_der, String(der).b)
-        validate_algorithm_expectation!(expected_algorithm, algorithm)
-        [algorithm, bytes]
-      rescue ArgumentError, PQCrypto::Error => e
-        raise SerializationError, e.message
+        load(:native_public_key_from_pqc_container_der, expected_algorithm, der)
       end
 
       def public_key_from_pqc_container_pem(expected_algorithm, pem)
-        algorithm, bytes = PQCrypto.__send__(:native_public_key_from_pqc_container_pem, String(pem).b)
-        validate_algorithm_expectation!(expected_algorithm, algorithm)
-        [algorithm, bytes]
-      rescue ArgumentError, PQCrypto::Error => e
-        raise SerializationError, e.message
+        load(:native_public_key_from_pqc_container_pem, expected_algorithm, pem)
       end
 
       def secret_key_from_pqc_container_der(expected_algorithm, der)
-        algorithm, bytes = PQCrypto.__send__(:native_secret_key_from_pqc_container_der, String(der).b)
-        validate_algorithm_expectation!(expected_algorithm, algorithm)
-        [algorithm, bytes]
+        load(:native_secret_key_from_pqc_container_der, expected_algorithm, der)
+      end
+
+      def secret_key_from_pqc_container_pem(expected_algorithm, pem)
+        load(:native_secret_key_from_pqc_container_pem, expected_algorithm, pem)
+      end
+
+      private
+
+      def dump(native_method, algorithm, bytes)
+        PQCrypto.__send__(native_method, String(algorithm), Internal.binary_string(bytes))
       rescue ArgumentError, PQCrypto::Error => e
         raise SerializationError, e.message
       end
 
-      def secret_key_from_pqc_container_pem(expected_algorithm, pem)
-        algorithm, bytes = PQCrypto.__send__(:native_secret_key_from_pqc_container_pem, String(pem).b)
+      def load(native_method, expected_algorithm, source)
+        algorithm, bytes = PQCrypto.__send__(native_method, Internal.binary_string(source))
         validate_algorithm_expectation!(expected_algorithm, algorithm)
         [algorithm, bytes]
       rescue ArgumentError, PQCrypto::Error => e
         raise SerializationError, e.message
       end
 
-      private
-
       def validate_algorithm_expectation!(expected_algorithm, actual_algorithm)
         return if expected_algorithm.nil? || expected_algorithm == actual_algorithm