pq_crypto 0.1.0

data/lib/pq_crypto/hybrid_kem.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module HybridKEM
+    CANONICAL_ALGORITHM = :ml_kem_768_x25519_hkdf_sha256
+
+    DETAILS = {
+      CANONICAL_ALGORITHM => {
+        name: CANONICAL_ALGORITHM,
+        family: Serialization.algorithm_to_family(CANONICAL_ALGORITHM),
+        oid: Serialization.algorithm_to_oid(CANONICAL_ALGORITHM),
+        public_key_bytes: HYBRID_KEM_PUBLIC_KEY_BYTES,
+        secret_key_bytes: HYBRID_KEM_SECRET_KEY_BYTES,
+        ciphertext_bytes: HYBRID_KEM_CIPHERTEXT_BYTES,
+        shared_secret_bytes: HYBRID_KEM_SHARED_SECRET_BYTES,
+        description: "Hybrid KEM: ML-KEM-768 + X25519 combined via transcript-bound HKDF-SHA256.",
+      }.freeze,
+    }.freeze
+
+    class << self
+      def generate(algorithm = CANONICAL_ALGORITHM)
+        algorithm = resolve_algorithm!(algorithm)
+        public_key, secret_key = PQCrypto.__send__(:native_hybrid_kem_keypair)
+        Keypair.new(PublicKey.new(algorithm, public_key), SecretKey.new(algorithm, secret_key))
+      end
+
+      def public_key_from_bytes(algorithm, bytes)
+        PublicKey.new(resolve_algorithm!(algorithm), bytes)
+      end
+
+      def secret_key_from_bytes(algorithm, bytes)
+        SecretKey.new(resolve_algorithm!(algorithm), bytes)
+      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)
+      end
+
+      def public_key_from_pqc_container_pem(pem, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.public_key_from_pqc_container_pem(algorithm, pem)
+        PublicKey.new(resolve_algorithm!(resolved_algorithm), bytes)
+      end
+
+      def secret_key_from_pqc_container_der(der, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.secret_key_from_pqc_container_der(algorithm, der)
+        SecretKey.new(resolve_algorithm!(resolved_algorithm), bytes)
+      end
+
+      def secret_key_from_pqc_container_pem(pem, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.secret_key_from_pqc_container_pem(algorithm, pem)
+        SecretKey.new(resolve_algorithm!(resolved_algorithm), bytes)
+      end
+
+      def details(algorithm)
+        DETAILS.fetch(resolve_algorithm!(algorithm)).dup
+      end
+
+      def supported
+        DETAILS.keys.dup
+      end
+
+      private
+
+      def resolve_algorithm!(algorithm)
+        return algorithm if DETAILS.key?(algorithm)
+
+        raise UnsupportedAlgorithmError, "Unsupported hybrid KEM algorithm: #{algorithm.inspect}"
+      end
+    end
+
+    class Keypair < KEM::Keypair; end
+    class EncapsulationResult < KEM::EncapsulationResult; end
+
+    class PublicKey < KEM::PublicKey
+      def encapsulate
+        ciphertext, shared_secret = PQCrypto.__send__(:native_hybrid_kem_encapsulate, @bytes)
+        EncapsulationResult.new(ciphertext, shared_secret)
+      rescue ArgumentError => e
+        raise InvalidKeyError, e.message
+      end
+
+      private
+
+      def validate_length!
+        expected = HybridKEM.details(@algorithm).fetch(:public_key_bytes)
+        raise InvalidKeyError, "Invalid hybrid KEM public key length" unless @bytes.bytesize == expected
+      end
+    end
+
+    class SecretKey < KEM::SecretKey
+      def decapsulate(ciphertext)
+        PQCrypto.__send__(:native_hybrid_kem_decapsulate, String(ciphertext).b, @bytes)
+      rescue ArgumentError => e
+        raise InvalidCiphertextError, e.message
+      end
+
+      private
+
+      def validate_length!
+        expected = HybridKEM.details(@algorithm).fetch(:secret_key_bytes)
+        raise InvalidKeyError, "Invalid hybrid KEM secret key length" unless @bytes.bytesize == expected
+      end
+    end
+  end
+end

data/lib/pq_crypto/kem.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module KEM
+    CANONICAL_ALGORITHM = :ml_kem_768
+
+    DETAILS = {
+      CANONICAL_ALGORITHM => {
+        name: CANONICAL_ALGORITHM,
+        family: Serialization.algorithm_to_family(CANONICAL_ALGORITHM),
+        oid: Serialization.algorithm_to_oid(CANONICAL_ALGORITHM),
+        public_key_bytes: ML_KEM_PUBLIC_KEY_BYTES,
+        secret_key_bytes: ML_KEM_SECRET_KEY_BYTES,
+        ciphertext_bytes: ML_KEM_CIPHERTEXT_BYTES,
+        shared_secret_bytes: ML_KEM_SHARED_SECRET_BYTES,
+        description: "Pure ML-KEM-768 primitive (FIPS 203).",
+      }.freeze,
+    }.freeze
+
+    class << self
+      def generate(algorithm = CANONICAL_ALGORITHM)
+        algorithm = resolve_algorithm!(algorithm)
+        public_key, secret_key = PQCrypto.__send__(:native_ml_kem_keypair)
+        Keypair.new(PublicKey.new(algorithm, public_key), SecretKey.new(algorithm, secret_key))
+      end
+
+      def public_key_from_bytes(algorithm, bytes)
+        PublicKey.new(resolve_algorithm!(algorithm), bytes)
+      end
+
+      def secret_key_from_bytes(algorithm, bytes)
+        SecretKey.new(resolve_algorithm!(algorithm), bytes)
+      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)
+      end
+
+      def public_key_from_pqc_container_pem(pem, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.public_key_from_pqc_container_pem(algorithm, pem)
+        PublicKey.new(resolve_algorithm!(resolved_algorithm), bytes)
+      end
+
+      def secret_key_from_pqc_container_der(der, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.secret_key_from_pqc_container_der(algorithm, der)
+        SecretKey.new(resolve_algorithm!(resolved_algorithm), bytes)
+      end
+
+      def secret_key_from_pqc_container_pem(pem, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.secret_key_from_pqc_container_pem(algorithm, pem)
+        SecretKey.new(resolve_algorithm!(resolved_algorithm), bytes)
+      end
+
+      def details(algorithm)
+        DETAILS.fetch(resolve_algorithm!(algorithm)).dup
+      end
+
+      def supported
+        DETAILS.keys.dup
+      end
+
+      private
+
+      def resolve_algorithm!(algorithm)
+        return algorithm if DETAILS.key?(algorithm)
+
+        raise UnsupportedAlgorithmError, "Unsupported KEM algorithm: #{algorithm.inspect}"
+      end
+    end
+
+    class Keypair
+      attr_reader :public_key, :secret_key
+
+      def initialize(public_key, secret_key)
+        @public_key = public_key
+        @secret_key = secret_key
+
+        unless @public_key.algorithm == @secret_key.algorithm
+          raise InvalidKeyError, "KEM keypair algorithms do not match"
+        end
+      end
+
+      def algorithm
+        @public_key.algorithm
+      end
+    end
+
+    class PublicKey
+      attr_reader :algorithm
+
+      def initialize(algorithm, bytes)
+        @algorithm = algorithm
+        @bytes = String(bytes).b
+        validate_length!
+      end
+
+      def to_bytes
+        @bytes.dup
+      end
+
+      def to_pqc_container_der
+        Serialization.public_key_to_pqc_container_der(@algorithm, @bytes)
+      end
+
+      def to_pqc_container_pem
+        Serialization.public_key_to_pqc_container_pem(@algorithm, @bytes)
+      end
+
+      def encapsulate
+        ciphertext, shared_secret = PQCrypto.__send__(:native_ml_kem_encapsulate, @bytes)
+        EncapsulationResult.new(ciphertext, shared_secret)
+      rescue ArgumentError => e
+        raise InvalidKeyError, e.message
+      end
+
+      def encapsulate_to_bytes
+        result = encapsulate
+        [result.ciphertext, result.shared_secret]
+      end
+
+      def ==(other)
+        other.is_a?(PublicKey) && other.algorithm == algorithm && other.to_bytes == @bytes
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, algorithm, @bytes].hash
+      end
+
+      private
+
+      def validate_length!
+        expected = KEM.details(@algorithm).fetch(:public_key_bytes)
+        raise InvalidKeyError, "Invalid KEM public key length" unless @bytes.bytesize == expected
+      end
+    end
+
+    class SecretKey
+      attr_reader :algorithm
+
+      def initialize(algorithm, bytes)
+        @algorithm = algorithm
+        @bytes = String(bytes).b
+        validate_length!
+      end
+
+      def to_bytes
+        @bytes.dup
+      end
+
+      def to_pqc_container_der
+        Serialization.secret_key_to_pqc_container_der(@algorithm, @bytes)
+      end
+
+      def to_pqc_container_pem
+        Serialization.secret_key_to_pqc_container_pem(@algorithm, @bytes)
+      end
+
+      def decapsulate(ciphertext)
+        PQCrypto.__send__(:native_ml_kem_decapsulate, String(ciphertext).b, @bytes)
+      rescue ArgumentError => e
+        raise InvalidCiphertextError, e.message
+      end
+
+      def wipe!
+        PQCrypto.secure_wipe(@bytes)
+        self
+      end
+
+      def ==(other)
+        other.is_a?(SecretKey) && other.algorithm == algorithm && other.to_bytes == @bytes
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, algorithm, @bytes].hash
+      end
+
+      private
+
+      def validate_length!
+        expected = KEM.details(@algorithm).fetch(:secret_key_bytes)
+        raise InvalidKeyError, "Invalid KEM secret key length" unless @bytes.bytesize == expected
+      end
+    end
+
+    class EncapsulationResult
+      attr_reader :ciphertext, :shared_secret
+
+      def initialize(ciphertext, shared_secret)
+        @ciphertext = String(ciphertext).b
+        @shared_secret = String(shared_secret).b
+      end
+    end
+  end
+end

data/lib/pq_crypto/serialization.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module Serialization
+    ALGORITHM_METADATA = {
+      ml_kem_768: {
+        family: :ml_kem,
+        oid: "2.25.186599352125448088867056807454444238446",
+      }.freeze,
+      ml_kem_768_x25519_hkdf_sha256: {
+        family: :ml_kem_hybrid,
+        oid: "2.25.260242945110721168101139140490528778800",
+      }.freeze,
+      ml_dsa_65: {
+        family: :ml_dsa,
+        oid: "2.25.305232938483772195555080795650659207792",
+      }.freeze,
+    }.freeze
+
+    class << self
+      def algorithm_metadata(algorithm)
+        metadata = ALGORITHM_METADATA[algorithm]
+        raise SerializationError, "Unsupported serialization algorithm: #{algorithm.inspect}" unless metadata
+
+        metadata
+      end
+
+      def algorithm_to_oid(algorithm)
+        algorithm_metadata(algorithm).fetch(:oid)
+      end
+
+      def algorithm_to_family(algorithm)
+        algorithm_metadata(algorithm).fetch(:family)
+      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
+      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
+      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
+      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
+      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
+      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
+      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]
+      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)
+        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
+
+        raise SerializationError,
+              "Expected #{expected_algorithm.inspect}, got #{actual_algorithm.inspect} (serialized key algorithm mismatch)"
+      end
+    end
+  end
+end

data/lib/pq_crypto/signature.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module Signature
+    CANONICAL_ALGORITHM = :ml_dsa_65
+
+    DETAILS = {
+      CANONICAL_ALGORITHM => {
+        name: CANONICAL_ALGORITHM,
+        family: Serialization.algorithm_to_family(CANONICAL_ALGORITHM),
+        oid: Serialization.algorithm_to_oid(CANONICAL_ALGORITHM),
+        public_key_bytes: SIGN_PUBLIC_KEY_BYTES,
+        secret_key_bytes: SIGN_SECRET_KEY_BYTES,
+        signature_bytes: SIGN_BYTES,
+        description: "ML-DSA-65 signature primitive (FIPS 204).",
+      }.freeze,
+    }.freeze
+
+    class << self
+      def generate(algorithm = CANONICAL_ALGORITHM)
+        validate_algorithm!(algorithm)
+        public_key, secret_key = PQCrypto.__send__(:native_sign_keypair)
+        Keypair.new(PublicKey.new(algorithm, public_key), SecretKey.new(algorithm, secret_key))
+      end
+
+      def public_key_from_bytes(algorithm, bytes)
+        validate_algorithm!(algorithm)
+        PublicKey.new(algorithm, bytes)
+      end
+
+      def secret_key_from_bytes(algorithm, bytes)
+        validate_algorithm!(algorithm)
+        SecretKey.new(algorithm, bytes)
+      end
+
+      def public_key_from_pqc_container_der(der, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.public_key_from_pqc_container_der(algorithm, der)
+        validate_algorithm!(resolved_algorithm)
+        PublicKey.new(resolved_algorithm, bytes)
+      end
+
+      def public_key_from_pqc_container_pem(pem, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.public_key_from_pqc_container_pem(algorithm, pem)
+        validate_algorithm!(resolved_algorithm)
+        PublicKey.new(resolved_algorithm, bytes)
+      end
+
+      def secret_key_from_pqc_container_der(der, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.secret_key_from_pqc_container_der(algorithm, der)
+        validate_algorithm!(resolved_algorithm)
+        SecretKey.new(resolved_algorithm, bytes)
+      end
+
+      def secret_key_from_pqc_container_pem(pem, algorithm = nil)
+        resolved_algorithm, bytes = Serialization.secret_key_from_pqc_container_pem(algorithm, pem)
+        validate_algorithm!(resolved_algorithm)
+        SecretKey.new(resolved_algorithm, bytes)
+      end
+
+      def details(algorithm)
+        DETAILS.fetch(validate_algorithm!(algorithm)).dup
+      end
+
+      def supported
+        DETAILS.keys.dup
+      end
+
+      private
+
+      def validate_algorithm!(algorithm)
+        return algorithm if DETAILS.key?(algorithm)
+
+        raise UnsupportedAlgorithmError, "Unsupported signature algorithm: #{algorithm.inspect}"
+      end
+    end
+
+    class Keypair
+      attr_reader :public_key, :secret_key
+
+      def initialize(public_key, secret_key)
+        @public_key = public_key
+        @secret_key = secret_key
+
+        unless @public_key.algorithm == @secret_key.algorithm
+          raise InvalidKeyError, "Signature keypair algorithms do not match"
+        end
+      end
+
+      def algorithm
+        @public_key.algorithm
+      end
+    end
+
+    class PublicKey
+      attr_reader :algorithm
+
+      def initialize(algorithm, bytes)
+        @algorithm = algorithm
+        @bytes = String(bytes).b
+        validate_length!
+      end
+
+      def to_bytes
+        @bytes.dup
+      end
+
+      def to_pqc_container_der
+        Serialization.public_key_to_pqc_container_der(@algorithm, @bytes)
+      end
+
+      def to_pqc_container_pem
+        Serialization.public_key_to_pqc_container_pem(@algorithm, @bytes)
+      end
+
+      def verify(message, signature)
+        PQCrypto.__send__(:native_verify, String(message).b, String(signature).b, @bytes)
+      rescue PQCrypto::VerificationError
+        false
+      rescue ArgumentError => e
+        raise InvalidKeyError, e.message
+      end
+
+      def verify!(message, signature)
+        ok = verify(message, signature)
+        raise PQCrypto::VerificationError, "Verification failed" unless ok
+
+        true
+      end
+
+      def ==(other)
+        other.is_a?(PublicKey) && other.algorithm == algorithm && other.to_bytes == @bytes
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, algorithm, @bytes].hash
+      end
+
+      private
+
+      def validate_length!
+        expected = Signature.details(@algorithm).fetch(:public_key_bytes)
+        raise InvalidKeyError, "Invalid signature public key length" unless @bytes.bytesize == expected
+      end
+    end
+
+    class SecretKey
+      attr_reader :algorithm
+
+      def initialize(algorithm, bytes)
+        @algorithm = algorithm
+        @bytes = String(bytes).b
+        validate_length!
+      end
+
+      def to_bytes
+        @bytes.dup
+      end
+
+      def to_pqc_container_der
+        Serialization.secret_key_to_pqc_container_der(@algorithm, @bytes)
+      end
+
+      def to_pqc_container_pem
+        Serialization.secret_key_to_pqc_container_pem(@algorithm, @bytes)
+      end
+
+      def sign(message)
+        PQCrypto.__send__(:native_sign, String(message).b, @bytes)
+      rescue ArgumentError => e
+        raise InvalidKeyError, e.message
+      end
+
+      def wipe!
+        PQCrypto.secure_wipe(@bytes)
+        self
+      end
+
+      def ==(other)
+        other.is_a?(SecretKey) && other.algorithm == algorithm && other.to_bytes == @bytes
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, algorithm, @bytes].hash
+      end
+
+      private
+
+      def validate_length!
+        expected = Signature.details(@algorithm).fetch(:secret_key_bytes)
+        raise InvalidKeyError, "Invalid signature secret key length" unless @bytes.bytesize == expected
+      end
+    end
+  end
+end

data/lib/pq_crypto/version.rb

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