ff1 1.2.0 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c42e1200976768d8adee07820e93d0281a2487f684df7c10ec5f0be591a28716
-  data.tar.gz: c76fd86787b72671b1fb6de320f5243ba4878471356801f32d568d5f34bc159c
+  metadata.gz: 0b5010b97391cf4b071b1b1d8456a3e1070bc38c885fa1f7d2376955bdfd0afd
+  data.tar.gz: 394daa33fe6d6238c6bd7e183e81d997ac729c02a91dd0bb1321414922b73e86
 SHA512:
-  metadata.gz: 6747aa29273bd6667ec62d5774b1627c6c11a68398c7bbaa4f744867fd66ce14ffa893ac670d970c23269db221d8236b82dcd570b8f1befd0e9dc4324f812b9b
-  data.tar.gz: e0e820f43cf4bcd79e16fbfded42f7faef5368698b385a2c493e17ca87efbf9801ac23ce545a0757a09b3a803393cdf9739b6f9f83342b9502730790c0dec032
+  metadata.gz: '019f223606c49369c2bdf48a1b8d5fd3a32da0e097cb76aa0e03690b4f83ed60f5e744ba4e73f25674d290316cbad6c3b52fe08379c14493e0391a2e494764d1'
+  data.tar.gz: e8c2b73a05050f5c33d8801320c58ab98e26863dd2c6767d173187313c7f71063a384cb83b6afa262f4e33f3a4b16520a0feb6deae1adfc6eb2091de101a16ca

data/README.md

@@ -14,8 +14,12 @@ The FF1 algorithm is one of two methods specified in NIST Special Publication 80
 * **Dual-mode operation**: Reversible and Irreversible encryption
 * Support for any radix from 2 to 65, 536
 * **NEW: Full UTF-8 text encryption support** - encrypt arbitrary text while maintaining FF1 security properties
+* **NEW: Rails/ActiveRecord integration** - seamless database encryption with GDPR compliance
 * Tweak support for additional security
-* GDPR "right to be forgotten" compliance
+* GDPR "right to be forgotten" compliance with soft delete
+* Automatic encryption/decryption in Rails models
+* Rails migration generators and configuration
+* Query scopes for active/deleted records
 * Proper input validation and error handling
 * Comprehensive test suite
 * Thread-safe implementation
@@ -116,6 +120,215 @@ irreversibly_encrypted = irreversible_cipher.encrypt_text(sensitive_data)
 # Cannot decrypt - data is permanently transformed while maintaining consistency
 ```
 
+## ActiveRecord Integration (NEW!)
+
+The gem now includes full Rails/ActiveRecord integration for seamless database encryption with GDPR compliance features.
+
+### Installation for Rails
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'ff1'
+```
+
+Run the generator to create the configuration file:
+
+```bash
+rails generate ff1:install
+```
+
+This creates `config/initializers/ff1.rb` with configuration options.
+
+### Configuration
+
+Configure FF1 in your Rails initializer:
+
+```ruby
+# config/initializers/ff1.rb
+FF1::ActiveRecord.configure do |config|
+  # Required: Set your encryption key (store securely!)
+  config.global_key = Rails.application.credentials.ff1_encryption_key
+  # Or use environment variable:
+  # config.global_key = ENV['FF1_ENCRYPTION_KEY']&.b
+  
+  # Optional: Set default encryption mode
+  config.default_mode = FF1::Modes::REVERSIBLE
+  
+  # Optional: Customize column names for soft delete
+  config.deleted_at_column = :deleted_at
+  config.ff1_deleted_column = :ff1_deleted
+end
+```
+
+### Basic Model Integration
+
+Include `FF1::ActiveRecord` in your models and configure encrypted columns:
+
+```ruby
+class User < ApplicationRecord
+  include FF1::ActiveRecord
+  
+  # Encrypt email and phone with reversible encryption (can decrypt)
+  ff1_encrypt :email, :phone, mode: :reversible
+  
+  # Encrypt SSN with irreversible encryption (cannot decrypt - GDPR compliant)
+  ff1_encrypt :ssn, mode: :irreversible
+end
+```
+
+### Database Migration
+
+Generate and run migration to add soft delete columns:
+
+```bash
+rails generate ff1:install User
+rails db:migrate
+```
+
+This adds `deleted_at` and `ff1_deleted` columns to your users table.
+
+### Usage Examples
+
+```ruby
+# Create user - data is automatically encrypted before saving
+user = User.create!(
+  name: 'John Doe',
+  email: 'john@example.com',
+  phone: '555-1234', 
+  ssn: '123-45-6789'
+)
+
+# Access data - reversible columns decrypt automatically  
+puts user.email  # => 'john@example.com' (decrypted)
+puts user.phone  # => '555-1234' (decrypted)
+puts user.ssn    # => '[ENCRYPTED]' (irreversible, cannot decrypt)
+
+# Data is encrypted in the database
+User.connection.select_value("SELECT email FROM users WHERE id = #{user.id}")
+# => "8224999410799188" (encrypted format)
+```
+
+### GDPR Compliant Soft Delete
+
+The integration provides GDPR-compliant "right to be forgotten" functionality:
+
+```ruby
+# Soft delete with irreversible encryption
+user.destroy  # Encrypts all sensitive data irreversibly, keeps record
+
+# Check deletion status
+user.ff1_deleted?     # => true
+user.ff1_deleted_at   # => 2023-01-01 12:00:00 UTC
+
+# Data is now irreversibly encrypted
+user.email  # => '[ENCRYPTED]'
+user.phone  # => '[ENCRYPTED]' 
+user.ssn    # => '[ENCRYPTED]'
+
+# Restore record (but data remains encrypted)
+user.ff1_restore
+user.ff1_deleted?  # => false
+
+# True hard delete if needed
+user.ff1_hard_destroy!
+```
+
+### Query Scopes
+
+Use built-in scopes to query active vs soft-deleted records:
+
+```ruby
+# Active (non-deleted) users only
+User.ff1_active.count         # => 150
+User.ff1_active.where(...)    # Chain with other scopes
+
+# Soft-deleted users only  
+User.ff1_deleted.count        # => 25
+
+# All users (active + deleted)
+User.ff1_all.count            # => 175
+
+# Recently deleted users
+User.ff1_recently_deleted(within: 30.days)
+
+# Old deleted users (for purging)
+User.ff1_old_deleted(older_than: 1.year)
+```
+
+### Bulk Operations
+
+```ruby
+# Bulk soft delete with encryption
+User.ff1_destroy_all(status: 'inactive')  # Returns count of deleted records
+
+# Purge old soft-deleted records
+User.ff1_purge_deleted(older_than: 2.years)  # Permanent deletion
+
+# Batch encrypt existing data
+User.ff1_encrypt_existing_data!(columns: [:email, :phone])
+
+# Statistics
+User.ff1_stats
+# => {
+#   total_records: 175,
+#   active_records: 150, 
+#   deleted_records: 25,
+#   encrypted_columns: [:email, :phone, :ssn],
+#   deletion_rate: 14.29
+# }
+```
+
+### Advanced Configuration
+
+```ruby
+class User < ApplicationRecord
+  include FF1::ActiveRecord
+  
+  # Per-column configuration
+  ff1_encrypt :email, 
+    mode: :reversible,
+    key: Rails.application.credentials.user_email_key,  # Custom key
+    radix: 256  # For text data
+  
+  ff1_encrypt :credit_card_number,
+    mode: :reversible, 
+    radix: 10   # For numeric data
+    
+  ff1_encrypt :sensitive_notes,
+    mode: :irreversible,  # Cannot be decrypted
+    radix: 256
+end
+```
+
+### Thread Safety
+
+The ActiveRecord integration is thread-safe and caches cipher instances for performance:
+
+```ruby
+# Safe for concurrent access
+User.transaction do
+  User.create!(email: 'user1@example.com')
+  User.create!(email: 'user2@example.com')  
+end
+```
+
+### Performance Considerations
+
+1. **Cipher Caching**: Ciphers are cached per column configuration for performance
+2. **Bulk Operations**: Use `ff1_find_each` for processing large datasets
+3. **Indexing**: Encrypted data cannot be indexed for searching - plan accordingly
+4. **Query Performance**: Use the provided scopes which include proper indexes
+
+### GDPR Compliance Features
+
+The ActiveRecord integration specifically supports GDPR requirements:
+
+1. **Right to be Forgotten**: `destroy` method irreversibly encrypts sensitive data
+2. **Data Minimization**: Only configured columns are encrypted
+3. **Audit Trail**: Soft delete maintains record for compliance tracking
+4. **Data Portability**: Reversible encryption allows data export when legally required
+
 ### Key Requirements
 
 The FF1 algorithm supports AES key lengths:

data/examples/activerecord_usage.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Example of FF1 ActiveRecord integration usage
+# This example demonstrates how to use the FF1 gem with Rails/ActiveRecord
+# for database encryption with GDPR compliance features.
+
+require 'bundler/setup'
+require 'active_record'
+require 'sqlite3'
+require_relative '../lib/ff1'
+
+# Configure ActiveRecord with in-memory SQLite database
+ActiveRecord::Base.establish_connection(
+  adapter: 'sqlite3',
+  database: ':memory:'
+)
+
+# Create test schema
+ActiveRecord::Schema.define do
+  create_table :users do |t|
+    t.string :name
+    t.string :email
+    t.string :phone
+    t.string :ssn
+    t.datetime :deleted_at
+    t.boolean :ff1_deleted, default: false
+    t.timestamps
+  end
+
+  create_table :posts do |t|
+    t.string :title
+    t.text :content
+    t.integer :user_id
+    t.datetime :deleted_at
+    t.boolean :ff1_deleted, default: false
+    t.timestamps
+  end
+end
+
+# Configure FF1
+FF1::ActiveRecord.configure do |config|
+  config.global_key = SecureRandom.bytes(32)
+  config.default_mode = FF1::Modes::REVERSIBLE
+end
+
+# Define models with FF1 encryption
+class User < ActiveRecord::Base
+  include FF1::ActiveRecord
+  
+  # Encrypt email and phone with reversible encryption (can decrypt)
+  ff1_encrypt :email, :phone, mode: :reversible
+  
+  # Encrypt SSN with irreversible encryption (cannot decrypt - GDPR compliant)
+  ff1_encrypt :ssn, mode: :irreversible
+  
+  has_many :posts, dependent: :destroy
+end
+
+class Post < ActiveRecord::Base
+  include FF1::ActiveRecord
+  
+  # Encrypt post content with reversible encryption
+  ff1_encrypt :content, mode: :reversible
+  
+  belongs_to :user
+end
+
+# Demonstration
+puts "🔐 FF1 ActiveRecord Integration Demo"
+puts "=" * 50
+
+# 1. Create a user with encrypted data
+puts "\n1. Creating user with encrypted data..."
+user = User.create!(
+  name: 'John Doe',
+  email: 'john@example.com',
+  phone: '555-1234',
+  ssn: '123-45-6789'
+)
+
+puts "✅ User created: #{user.name}"
+puts "   Email: #{user.email} (decrypted)"
+puts "   Phone: #{user.phone} (decrypted)" 
+puts "   SSN: #{user.ssn} (irreversible - shows placeholder)"
+
+# 2. Show encrypted data in database
+puts "\n2. Data in database (encrypted):"
+raw_data = User.connection.select_one("SELECT email, phone, ssn FROM users WHERE id = #{user.id}")
+puts "   Email in DB: #{raw_data['email']} (encrypted)"
+puts "   Phone in DB: #{raw_data['phone']} (encrypted)"
+puts "   SSN in DB: #{raw_data['ssn']} (encrypted)"
+
+# 3. Create a post with encrypted content
+puts "\n3. Creating post with encrypted content..."
+post = Post.create!(
+  title: 'Public Title',
+  content: 'This is sensitive content that will be encrypted',
+  user: user
+)
+
+puts "✅ Post created: #{post.title}"
+puts "   Content: #{post.content} (decrypted)"
+
+raw_post = Post.connection.select_one("SELECT content FROM posts WHERE id = #{post.id}")
+puts "   Content in DB: #{raw_post['content']} (encrypted)"
+
+# 4. Demonstrate query scopes
+puts "\n4. Query scopes:"
+puts "   Total users: #{User.ff1_all.count}"
+puts "   Active users: #{User.ff1_active.count}"
+puts "   Deleted users: #{User.ff1_deleted.count}"
+
+# 5. GDPR-compliant soft delete
+puts "\n5. GDPR-compliant soft delete..."
+puts "   Before deletion - email: #{user.email}"
+user.destroy
+
+puts "✅ User soft deleted with irreversible encryption"
+puts "   After deletion - email: #{user.email} (now shows [ENCRYPTED])"
+puts "   Deleted status: #{user.ff1_deleted?}"
+puts "   Deleted at: #{user.ff1_deleted_at}"
+
+# 6. Query scopes after deletion
+puts "\n6. Query scopes after deletion:"
+puts "   Total users: #{User.ff1_all.count}"
+puts "   Active users: #{User.ff1_active.count}" 
+puts "   Deleted users: #{User.ff1_deleted.count}"
+
+# 7. Statistics
+puts "\n7. FF1 Statistics:"
+stats = User.ff1_stats
+stats.each do |key, value|
+  puts "   #{key}: #{value}"
+end
+
+# 8. Restore demonstration
+puts "\n8. Restore user (data remains encrypted)..."
+user.ff1_restore
+puts "   Deleted status after restore: #{user.ff1_deleted?}"
+puts "   Email after restore: #{user.email} (still encrypted)"
+
+puts "\n🎉 Demo completed successfully!"
+puts "The FF1 ActiveRecord integration provides seamless encryption"
+puts "with GDPR compliance through irreversible soft deletion."

data/lib/ff1/active_record/base.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module FF1
+  module ActiveRecord
+    # Base functionality for FF1 ActiveRecord integration
+    module Base
+      extend ActiveSupport::Concern if defined?(ActiveSupport::Concern)
+
+      # Thread-safe cipher cache
+      if defined?(Concurrent::Hash)
+        CIPHER_CACHE = Concurrent::Hash.new 
+      else
+        CIPHER_CACHE = {}
+      end
+
+      private
+
+      # Get or create a cipher for the given column configuration
+      def get_cipher_for_column(column, mode = nil)
+        config = ff1_config[column.to_sym]
+        return nil unless config
+
+        mode ||= config[:mode]
+        key = config[:key] || FF1::ActiveRecord.configuration.global_key
+        radix = config[:radix] || determine_radix_for_column(column)
+
+        raise FF1::Error, "No encryption key provided for column #{column}" unless key
+
+        cache_key = "#{self.class.name}:#{column}:#{mode}:#{key.hash}:#{radix}"
+
+        Base::CIPHER_CACHE[cache_key] ||= FF1::Cipher.new(key, radix, mode)
+      end
+
+      # Determine appropriate radix for a column based on its type
+      def determine_radix_for_column(column)
+        column_type = self.class.columns_hash[column.to_s]&.type
+        
+        case column_type
+        when :integer, :bigint, :decimal
+          10  # Numeric columns use base 10
+        when :string, :text
+          256 # Text columns use base 256 for full UTF-8 support
+        else
+          256 # Default to text mode for unknown types
+        end
+      end
+
+      # Generate a tweak for encryption based on model and column
+      def generate_tweak_for_column(column)
+        # Use model and column name only - don't include record ID to ensure consistency
+        # between encryption (before save) and decryption (after save)
+        "#{self.class.name}:#{column}"
+      end
+
+      # Validate encryption key format and length
+      def validate_encryption_key(key)
+        return false unless key.is_a?(String)
+        return false unless [16, 24, 32].include?(key.bytesize)
+        
+        true
+      end
+
+      # Handle errors during encryption/decryption
+      def handle_encryption_error(error, column, operation)
+        Rails.logger.error "FF1 #{operation} error for #{self.class.name}##{column}: #{error.message}" if defined?(Rails) && Rails.respond_to?(:logger)
+        
+        case operation
+        when :encrypt
+          # For encryption errors, we might want to fail fast
+          raise FF1::Error, "Failed to encrypt #{column}: #{error.message}"
+        when :decrypt
+          # For decryption errors, we might want to return nil or the raw value
+          # depending on application requirements
+          Rails.logger.warn "Failed to decrypt #{column}, returning raw value" if defined?(Rails) && Rails.respond_to?(:logger)
+          read_attribute(column)
+        end
+      end
+    end
+  end
+end

data/lib/ff1/active_record/encryption.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module FF1
+  module ActiveRecord
+    # Handles automatic encryption and decryption of configured columns
+    module Encryption
+      extend ActiveSupport::Concern if defined?(ActiveSupport::Concern)
+
+      included do
+        # Hook into ActiveRecord callbacks
+        before_save :encrypt_ff1_columns
+        after_save :clear_ff1_decrypted_cache
+        after_initialize :setup_ff1_attributes
+        after_find :setup_ff1_attributes
+      end
+
+      # Check if an encrypted attribute has changed
+      def ff1_attribute_changed?(attr_name)
+        if ff1_config.key?(attr_name.to_sym)
+          # Check if we have a pending decrypted value (indicating a change)
+          decrypted_var = "@ff1_decrypted_#{attr_name}"
+          instance_variable_defined?(decrypted_var)
+        else
+          false
+        end
+      end
+
+      private
+
+      # Encrypt all configured FF1 columns before saving
+      def encrypt_ff1_columns
+        return unless respond_to?(:ff1_config) && ff1_config
+        
+        ff1_config.each do |column, config|
+          # Check if this attribute needs encryption
+          decrypted_var = "@ff1_decrypted_#{column}"
+          has_decrypted_value = instance_variable_defined?(decrypted_var)
+          decrypted_value = instance_variable_get(decrypted_var) if has_decrypted_value
+          
+          # Only encrypt if we have a decrypted value set or this is a new record with a value
+          if has_decrypted_value && !decrypted_value.nil?
+            encrypted_value = encrypt_attribute_value(column, decrypted_value, config[:mode])
+            write_attribute(column, encrypted_value) if encrypted_value
+          elsif new_record?
+            raw_value = read_attribute(column)
+            if raw_value && !raw_value.empty?
+              encrypted_value = encrypt_attribute_value(column, raw_value, config[:mode])
+              write_attribute(column, encrypted_value) if encrypted_value
+            end
+          end
+        end
+      end
+
+      # Setup decrypted attribute values after initialization
+      def setup_ff1_attributes
+        return unless persisted?
+
+        ff1_config.each do |column, _config|
+          # Store the encrypted value separately so we can access decrypted values
+          encrypted_value = read_attribute(column)
+          instance_variable_set("@ff1_encrypted_#{column}", encrypted_value)
+        end
+      end
+
+      # Clear cached decrypted values after save
+      def clear_ff1_decrypted_cache
+        ff1_config.keys.each do |column|
+          decrypted_var = "@ff1_decrypted_#{column}"
+          remove_instance_variable(decrypted_var) if instance_variable_defined?(decrypted_var)
+        end
+      end
+
+      # Decrypt an attribute value
+      def decrypt_attribute(column)
+        return nil unless ff1_config.key?(column.to_sym)
+
+        config = ff1_config[column.to_sym]
+        decrypted_var = "@ff1_decrypted_#{column}"
+        
+        # If in irreversible mode, always return placeholder
+        if config[:mode] == FF1::Modes::IRREVERSIBLE
+          instance_variable_set(decrypted_var, "[ENCRYPTED]")
+          return "[ENCRYPTED]"
+        end
+
+        # If record is soft-deleted, all data should be treated as irreversible
+        if ff1_deleted?
+          instance_variable_set(decrypted_var, "[ENCRYPTED]")
+          return "[ENCRYPTED]"
+        end
+
+        # Return cached decrypted value if available (only for reversible columns)
+        return instance_variable_get(decrypted_var) if instance_variable_defined?(decrypted_var)
+
+        encrypted_value = read_attribute(column)
+        return nil if encrypted_value.nil?
+        return '' if encrypted_value == ''
+
+        begin
+          cipher = get_cipher_for_column(column, FF1::Modes::REVERSIBLE)
+          tweak = generate_tweak_for_column(column)
+          
+          decrypted_value = if text_column?(column)
+                              cipher.decrypt_text(encrypted_value, tweak)
+                            else
+                              cipher.decrypt(encrypted_value, tweak)
+                            end
+
+          # Cache the decrypted value
+          instance_variable_set(decrypted_var, decrypted_value)
+          decrypted_value
+        rescue FF1::Error => e
+          # If decryption fails (possibly due to irreversible encryption), return placeholder
+          instance_variable_set(decrypted_var, "[ENCRYPTED]")
+          "[ENCRYPTED]"
+        end
+      end
+
+      # Set an encrypted attribute value (stores for later encryption)
+      def set_encrypted_attribute(column, value)
+        # Clear any existing cached decrypted value
+        decrypted_var = "@ff1_decrypted_#{column}"
+        remove_instance_variable(decrypted_var) if instance_variable_defined?(decrypted_var)
+
+        if value.nil?
+          # Handle nil values
+          instance_variable_set(decrypted_var, nil)
+          write_attribute(column, nil)
+        else
+          # Store the plaintext value for immediate access and later encryption
+          instance_variable_set(decrypted_var, value)
+          
+          # Mark the attribute as changed so ActiveRecord knows to save it
+          attribute_will_change!(column.to_s) if respond_to?(:attribute_will_change!)
+        end
+      end
+
+      # Encrypt a single attribute value
+      def encrypt_attribute_value(column, value, mode = nil)
+        return nil if value.nil?
+        return '' if value == ''
+
+        config = ff1_config[column.to_sym]
+        mode ||= config[:mode]
+
+        begin
+          cipher = get_cipher_for_column(column, mode)
+          tweak = generate_tweak_for_column(column)
+
+          if text_column?(column)
+            cipher.encrypt_text(value.to_s, tweak)
+          else
+            cipher.encrypt(value.to_s, tweak)
+          end
+        rescue FF1::Error => e
+          handle_encryption_error(e, column, :encrypt)
+        end
+      end
+
+      # Check if a column is a text-based column
+      def text_column?(column)
+        column_type = self.class.columns_hash[column.to_s]&.type
+        [:string, :text].include?(column_type)
+      end
+    end
+  end
+end