familia 2.0.0.pre4 → 2.0.0.pre6

data/lib/familia/encryption/providers/aes_gcm_provider.rb

@@ -0,0 +1,123 @@
+# lib/familia/encryption/providers/aes_gcm_provider.rb
+
+# ⚠️  RUBY MEMORY SAFETY WARNING ⚠️
+#
+# This encryption provider, like all Ruby-based cryptographic implementations,
+# stores secrets (keys, plaintext, derived keys) as Ruby strings in memory.
+#
+# SECURITY IMPLICATIONS:
+# - Keys remain in memory after use (garbage collection timing is unpredictable)
+# - Ruby strings cannot be securely wiped from memory
+# - Memory dumps may contain cryptographic secrets
+# - Swap files may persist secrets to disk
+# - String operations create copies that persist in memory
+#
+# Ruby provides NO memory safety guarantees for cryptographic secrets.
+#
+# For production systems handling sensitive data, consider:
+# - Hardware Security Modules (HSMs)
+# - External key management services
+# - Languages with manual memory management
+# - Cryptographic appliances with secure memory
+
+module Familia
+  module Encryption
+    module Providers
+      class AESGCMProvider < Provider
+        ALGORITHM = 'aes-256-gcm'.freeze
+        NONCE_SIZE = 12
+        AUTH_TAG_SIZE = 16
+
+        def self.available?
+          true # OpenSSL is always available
+        end
+
+        def self.priority
+          50 # Fallback option
+        end
+
+        def encrypt(plaintext, key, additional_data = nil)
+          validate_key_length!(key)
+          nonce = generate_nonce
+          cipher = create_cipher(:encrypt)
+          cipher.key = key
+          cipher.iv = nonce
+          cipher.auth_data = additional_data.to_s if additional_data
+
+          ciphertext = cipher.update(plaintext.to_s) + cipher.final
+
+          {
+            ciphertext: ciphertext,
+            auth_tag: cipher.auth_tag,
+            nonce: nonce
+          }
+        end
+
+        def decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil)
+          validate_key_length!(key)
+          cipher = create_cipher(:decrypt)
+          cipher.key = key
+          cipher.iv = nonce
+          cipher.auth_tag = auth_tag
+          cipher.auth_data = additional_data.to_s if additional_data
+
+          cipher.update(ciphertext) + cipher.final
+        rescue OpenSSL::Cipher::CipherError
+          raise EncryptionError, 'Decryption failed - invalid key or corrupted data'
+        end
+
+        def generate_nonce
+          OpenSSL::Random.random_bytes(NONCE_SIZE)
+        end
+
+        def derive_key(master_key, context, personal: nil)
+          validate_key_length!(master_key)
+          info = personal ? "#{context}:#{personal}" : context
+          OpenSSL::KDF.hkdf(
+            master_key,
+            salt: 'FamiliaEncryption',
+            info: info,
+            length: 32,
+            hash: 'SHA256'
+          )
+        end
+
+        # Clear key from memory (no security guarantees in Ruby)
+        def secure_wipe(key)
+          key&.clear
+        end
+
+        def self.nonce_size
+          NONCE_SIZE
+        end
+
+        def self.auth_tag_size
+          AUTH_TAG_SIZE
+        end
+
+        def nonce_size
+          NONCE_SIZE
+        end
+
+        def auth_tag_size
+          AUTH_TAG_SIZE
+        end
+
+        def algorithm
+          ALGORITHM
+        end
+
+        private
+
+        def create_cipher(mode)
+          OpenSSL::Cipher.new('aes-256-gcm').tap { |c| c.public_send(mode) }
+        end
+
+        def validate_key_length!(key)
+          raise EncryptionError, 'Key cannot be nil' if key.nil?
+          raise EncryptionError, 'Key must be at least 32 bytes' if key.bytesize < 32
+        end
+      end
+    end
+  end
+end

data/lib/familia/encryption/providers/secure_xchacha20_poly1305_provider.rb

@@ -0,0 +1,184 @@
+# lib/familia/encryption/providers/secure_xchacha20_poly1305_provider.rb
+
+# ⚠️  PROTOTYPE IMPLEMENTATION - NOT FOR PRODUCTION USE ⚠️
+#
+# This provider is a PROTOTYPE demonstrating alternate memory security practices
+# for handling secrets in Ruby. It is NOT intended for use with actual sensitive
+# data or production systems.
+#
+# LIMITATIONS:
+# - Still relies on Ruby strings internally (unavoidable language constraint)
+# - RbNaCl library stores keys as strings regardless of our efforts
+# - Ruby's garbage collector behavior cannot be fully controlled
+# - No guarantee of complete memory cleanup
+#
+# This implementation serves as:
+# - Educational example of security-conscious programming
+# - Research prototype for future FFI-based implementations
+# - Demonstration of defense-in-depth techniques
+#
+# For actual cryptographic applications, consider:
+# - Hardware Security Modules (HSMs)
+# - Dedicated cryptographic appliances
+# - Languages with manual memory management (C, Rust)
+# - External key management services
+
+begin
+  require 'rbnacl'
+  require 'ffi'
+rescue LoadError
+  # Dependencies not available - provider will report as unavailable
+end
+
+module Familia
+  module Encryption
+    module Providers
+      # Enhanced XChaCha20Poly1305Provider with improved memory security
+      #
+      # While complete avoidance of Ruby strings for secrets is challenging due to
+      # RbNaCl's internal implementation, this provider implements several security
+      # improvements:
+      #
+      # 1. Minimizes key lifetime in memory
+      # 2. Uses immediate secure wiping after operations
+      # 3. Avoids unnecessary key duplication
+      # 4. Uses locked memory where possible (future enhancement)
+      #
+      class SecureXChaCha20Poly1305Provider < Provider
+        ALGORITHM = 'xchacha20poly1305-secure'.freeze
+        NONCE_SIZE = 24
+        AUTH_TAG_SIZE = 16
+
+        def self.available?
+          !!defined?(RbNaCl) && !!defined?(FFI)
+        end
+
+        def self.priority
+          110 # Higher than regular XChaCha20Poly1305Provider
+        end
+
+        def encrypt(plaintext, key, additional_data = nil)
+          validate_key_length!(key)
+
+          # Generate nonce first to avoid holding onto key longer than necessary
+          nonce = generate_nonce
+
+          # Minimize key exposure by performing operation immediately
+          result = perform_encryption(plaintext, key, nonce, additional_data)
+
+          # Attempt to clear the key parameter (if mutable)
+          secure_wipe(key)
+
+          result
+        end
+
+        def decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil)
+          validate_key_length!(key)
+
+          # Minimize key exposure by performing operation immediately
+          begin
+            result = perform_decryption(ciphertext, key, nonce, auth_tag, additional_data)
+          ensure
+            # Attempt to clear the key parameter (if mutable)
+            secure_wipe(key)
+          end
+
+          result
+        end
+
+        def generate_nonce
+          RbNaCl::Random.random_bytes(NONCE_SIZE)
+        end
+
+        # Enhanced key derivation with immediate cleanup
+        def derive_key(master_key, context, personal: nil)
+          validate_key_length!(master_key)
+
+          raw_personal = personal || Familia.config.encryption_personalization
+          if raw_personal.include?("\0")
+            raise EncryptionError, 'Personalization string must not contain null bytes'
+          end
+
+          personal_string = raw_personal.ljust(16, "\0")
+
+          # Perform derivation and immediately clear intermediate values
+          derived_key = RbNaCl::Hash.blake2b(
+            context.force_encoding('BINARY'),
+            key: master_key,
+            digest_size: 32,
+            personal: personal_string
+          )
+
+          # Clear personalization string from memory
+          personal_string.clear
+
+          # Return derived key (caller responsible for secure cleanup)
+          derived_key
+        end
+
+        # Clear key from memory (still no security guarantees in Ruby)
+        def secure_wipe(key)
+          key&.clear
+        end
+
+        private
+
+        def perform_encryption(plaintext, key, nonce, additional_data)
+          # Create AEAD instance (this internally copies the key)
+          box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)
+
+          aad = additional_data.to_s
+          ciphertext_with_tag = box.encrypt(nonce, plaintext.to_s, aad)
+
+          result = {
+            ciphertext: ciphertext_with_tag[0...-16],
+            auth_tag: ciphertext_with_tag[-16..-1],
+            nonce: nonce
+          }
+
+          # Clear intermediate values
+          ciphertext_with_tag.clear
+
+          result
+        ensure
+          # Clear the AEAD instance's internal key if possible
+          clear_aead_instance(box) if box
+        end
+
+        def perform_decryption(ciphertext, key, nonce, auth_tag, additional_data)
+          # Create AEAD instance (this internally copies the key)
+          box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)
+
+          ciphertext_with_tag = ciphertext + auth_tag
+          aad = additional_data.to_s
+
+          result = box.decrypt(nonce, ciphertext_with_tag, aad)
+
+          # Clear intermediate values
+          ciphertext_with_tag.clear
+
+          result
+        rescue RbNaCl::CryptoError
+          raise EncryptionError, 'Decryption failed - invalid key or corrupted data'
+        ensure
+          # Clear the AEAD instance's internal key if possible
+          clear_aead_instance(box) if box
+        end
+
+        def clear_aead_instance(aead_instance)
+          # Attempt to clear RbNaCl's internal key storage
+          # This is a best-effort cleanup since RbNaCl stores keys as strings internally
+          if aead_instance.instance_variable_defined?(:@key)
+            internal_key = aead_instance.instance_variable_get(:@key)
+            secure_wipe(internal_key) if internal_key
+          end
+        end
+
+        def validate_key_length!(key)
+          raise EncryptionError, 'Key cannot be nil' if key.nil?
+          raise EncryptionError, 'Key must be at least 32 bytes' if key.bytesize < 32
+        end
+      end
+    end
+  end
+end

data/lib/familia/encryption/providers/xchacha20_poly1305_provider.rb

@@ -0,0 +1,138 @@
+# lib/familia/encryption/providers/xchacha20_poly1305_provider.rb
+
+# ⚠️  RUBY MEMORY SAFETY WARNING ⚠️
+#
+# This encryption provider, like all Ruby-based cryptographic implementations,
+# stores secrets (keys, plaintext, derived keys) as Ruby strings in memory.
+#
+# SECURITY IMPLICATIONS:
+# - Keys remain in memory after use (garbage collection timing is unpredictable)
+# - Ruby strings cannot be securely wiped from memory
+# - Memory dumps may contain cryptographic secrets
+# - Swap files may persist secrets to disk
+# - String operations create copies that persist in memory
+#
+# Ruby provides NO memory safety guarantees for cryptographic secrets.
+#
+# For production systems handling sensitive data, consider:
+# - Hardware Security Modules (HSMs)
+# - External key management services
+# - Languages with manual memory management
+# - Cryptographic appliances with secure memory
+
+begin
+  require 'rbnacl'
+rescue LoadError
+  # RbNaCl not available - provider will report as unavailable
+  # To add: gem 'rbnacl', '~> 7.1', '>= 7.1.1'
+end
+
+module Familia
+  module Encryption
+    module Providers
+      class XChaCha20Poly1305Provider < Provider
+        ALGORITHM = 'xchacha20poly1305'.freeze
+        NONCE_SIZE = 24
+        AUTH_TAG_SIZE = 16
+
+        def self.available?
+          !!defined?(RbNaCl)
+        end
+
+        def self.priority
+          100 # Highest priority - best in class
+        end
+
+        def encrypt(plaintext, key, additional_data = nil)
+          validate_key_length!(key)
+          nonce = generate_nonce
+          box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)
+
+          aad = additional_data.to_s
+          ciphertext_with_tag = box.encrypt(nonce, plaintext.to_s, aad)
+
+          {
+            ciphertext: ciphertext_with_tag[0...-16],
+            auth_tag: ciphertext_with_tag[-16..-1],
+            nonce: nonce
+          }
+        end
+
+        def decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil)
+          validate_key_length!(key)
+          box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)
+
+          ciphertext_with_tag = ciphertext + auth_tag
+          aad = additional_data.to_s
+
+          box.decrypt(nonce, ciphertext_with_tag, aad)
+        rescue RbNaCl::CryptoError
+          raise EncryptionError, 'Decryption failed - invalid key or corrupted data'
+        end
+
+        def generate_nonce
+          RbNaCl::Random.random_bytes(NONCE_SIZE)
+        end
+
+        # Derives a context-specific encryption key using BLAKE2b.
+        #
+        # The personalization parameter provides cryptographic domain separation,
+        # ensuring that derived keys are unique per application even when using
+        # identical master keys and contexts. This prevents key reuse across
+        # different applications or library versions.
+        #
+        # @param master_key [String] The master key (must be >= 32 bytes)
+        # @param context [String] Context string for key derivation
+        # @param personal [String, nil] Optional personalization override
+        # @return [String] 32-byte derived key
+        def derive_key(master_key, context, personal: nil)
+          validate_key_length!(master_key)
+          raw_personal = personal || Familia.config.encryption_personalization
+          if raw_personal.include?("\0")
+            raise EncryptionError, 'Personalization string must not contain null bytes'
+          end
+          personal_string = raw_personal.ljust(16, "\0")
+
+          RbNaCl::Hash.blake2b(
+            context.force_encoding('BINARY'),
+            key: master_key,
+            digest_size: 32,
+            personal: personal_string
+          )
+        end
+
+        # Clear key from memory (no security guarantees in Ruby)
+        def secure_wipe(key)
+          key&.clear
+        end
+
+        def self.nonce_size
+          NONCE_SIZE
+        end
+
+        def self.auth_tag_size
+          AUTH_TAG_SIZE
+        end
+
+        def nonce_size
+          NONCE_SIZE
+        end
+
+        def auth_tag_size
+          AUTH_TAG_SIZE
+        end
+
+        def algorithm
+          ALGORITHM
+        end
+
+        private
+
+        def validate_key_length!(key)
+          raise EncryptionError, 'Key cannot be nil' if key.nil?
+          raise EncryptionError, 'Key must be at least 32 bytes' if key.bytesize < 32
+        end
+      end
+    end
+  end
+end

data/lib/familia/encryption/registry.rb

@@ -0,0 +1,50 @@
+# lib/familia/encryption/registry.rb
+
+module Familia
+  module Encryption
+    # Registry pattern for managing encryption providers
+    class Registry
+      class << self
+        def providers
+          @providers ||= {}
+        end
+
+        def register(provider_class)
+          return unless provider_class.available?
+
+          providers[provider_class::ALGORITHM] = provider_class
+        end
+
+        def get(algorithm)
+          provider_class = providers[algorithm]
+          raise EncryptionError, "Unsupported algorithm: #{algorithm}" unless provider_class
+
+          provider_class.new
+        end
+
+        def default_provider
+          # Select provider with highest priority
+          @default_provider ||= begin
+            available = providers.values.select(&:available?)
+            available.max_by(&:priority)&.new
+          end
+        end
+
+        def reset_default_provider!
+          @default_provider = nil
+        end
+
+        def available_algorithms
+          providers.keys
+        end
+
+        # Auto-register known providers
+        def setup!
+          register(Providers::XChaCha20Poly1305Provider)
+          register(Providers::AESGCMProvider)
+          # Future: register(Providers::ChaCha20Poly1305Provider)
+        end
+      end
+    end
+  end
+end

data/lib/familia/encryption.rb

@@ -0,0 +1,178 @@
+# lib/familia/encryption.rb
+
+require 'base64'
+require 'json'
+require 'openssl'
+
+# Provider system components
+require_relative 'encryption/provider'
+require_relative 'encryption/providers/xchacha20_poly1305_provider'
+require_relative 'encryption/providers/aes_gcm_provider'
+require_relative 'encryption/registry'
+require_relative 'encryption/manager'
+require_relative 'encryption/encrypted_data'
+
+module Familia
+  class EncryptionError < StandardError; end
+
+  module Encryption
+
+    # Smart facade with provider selection and field-specific encryption
+    #
+    # Usage in EncryptedFieldType can now be more flexible:
+    #
+    #   module Familia
+    #     class EncryptedFieldType < FieldType
+    #       attr_reader :algorithm  # Optional algorithm override
+    #
+    #       def initialize(name, aad_fields: [], algorithm: nil, **options)
+    #         super(name, **options.merge(on_conflict: :raise))
+    #         @aad_fields = Array(aad_fields).freeze
+    #         @algorithm = algorithm  # Use specific algorithm for this field
+    #       end
+    #
+    #       def encrypt_value(record, value)
+    #         context = build_context(record)
+    #         additional_data = build_aad(record)
+    #
+    #         if @algorithm
+    #           # Use specific algorithm for this field
+    #           Familia::Encryption.encrypt_with(@algorithm, value,
+    #             context: context,
+    #             additional_data: additional_data)
+    #         else
+    #           # Use default best algorithm
+    #           Familia::Encryption.encrypt(value,
+    #             context: context,
+    #             additional_data: additional_data)
+    #         end
+    #       end
+    #
+    #       # Decrypt auto-detects algorithm from data, so no change needed
+    #       def decrypt_value(record, encrypted)
+    #         context = build_context(record)
+    #         additional_data = build_aad(record)
+    #
+    #         Familia::Encryption.decrypt(encrypted,
+    #           context: context,
+    #           additional_data: additional_data)
+    #       end
+    #     end
+    #   end
+    class << self
+      # Get or create a manager with specific algorithm
+      def manager(algorithm: nil)
+        @managers ||= {}
+        @managers[algorithm] ||= Manager.new(algorithm: algorithm)
+      end
+
+      # Quick encryption with auto-selected best provider
+      def encrypt(plaintext, context:, additional_data: nil)
+        manager.encrypt(plaintext, context: context, additional_data: additional_data)
+      end
+
+      # Quick decryption (auto-detects algorithm from data)
+      def decrypt(encrypted_json, context:, additional_data: nil)
+        manager.decrypt(encrypted_json, context: context, additional_data: additional_data)
+      end
+
+      # Encrypt with specific algorithm
+      def encrypt_with(algorithm, plaintext, context:, additional_data: nil)
+        manager(algorithm: algorithm).encrypt(
+          plaintext,
+          context: context,
+          additional_data: additional_data
+        )
+      end
+
+      # Derivation counter for monitoring no-caching behavior
+      def derivation_count
+        @derivation_count ||= Concurrent::AtomicFixnum.new(0)
+      end
+
+      def reset_derivation_count!
+        derivation_count.value = 0
+      end
+
+      # Clear key from memory (no security guarantees in Ruby)
+      def secure_wipe(key)
+        key&.clear
+      end
+
+      # Get info about current encryption setup
+      def status
+        Registry.setup! if Registry.providers.empty?
+
+        {
+          default_algorithm: Registry.default_provider&.algorithm,
+          available_algorithms: Registry.available_algorithms,
+          preferred_available: Registry.default_provider&.class&.name,
+          using_hardware: hardware_acceleration?,
+          key_versions: encryption_keys.keys,
+          current_version: current_key_version
+        }
+      end
+
+      # Check if we're using hardware acceleration
+      def hardware_acceleration?
+        provider = Registry.default_provider
+        provider && provider.class.name.include?('Hardware')
+      end
+
+      # Benchmark available providers
+      def benchmark(iterations: 1000)
+        require 'benchmark'
+        test_data = 'x' * 1024 # 1KB test
+        context = 'benchmark:test'
+
+        results = {}
+        Registry.providers.each do |algo, provider_class|
+          next unless provider_class.available?
+
+          mgr = Manager.new(algorithm: algo)
+          time = Benchmark.realtime do
+            iterations.times do
+              encrypted = mgr.encrypt(test_data, context: context)
+              mgr.decrypt(encrypted, context: context)
+            end
+          end
+
+          results[algo] = {
+            time: time,
+            ops_per_sec: (iterations * 2 / time).round,
+            priority: provider_class.priority
+          }
+        end
+
+        results
+      end
+
+      def validate_configuration!
+        raise EncryptionError, 'No encryption keys configured' if encryption_keys.empty?
+        raise EncryptionError, 'No current key version set' unless current_key_version
+
+        current_key = encryption_keys[current_key_version]
+        raise EncryptionError, "Current key version not found: #{current_key_version}" unless current_key
+
+        begin
+          Base64.strict_decode64(current_key)
+        rescue ArgumentError
+          raise EncryptionError, 'Current encryption key is not valid Base64'
+        end
+
+        Registry.setup!
+        raise EncryptionError, 'No encryption providers available' unless Registry.default_provider
+      end
+
+      private
+
+      def encryption_keys
+        Familia.config.encryption_keys || {}
+      end
+
+      def current_key_version
+        Familia.config.current_key_version
+      end
+    end
+  end
+end