ff1 1.0.0 → 1.1.0

data/lib/ff1/cipher.rb

@@ -1,18 +1,39 @@
+# frozen_string_literal: true
+
 require 'openssl'
 require 'digest'
 
 module FF1
+  # FF1 Format Preserving Encryption Cipher
+  #
+  # Implements NIST SP 800-38G FF1 algorithm with dual-mode operation:
+  # - Reversible mode: Standard FPE that can decrypt back to original
+  # - Irreversible mode: Secure deletion while maintaining format/relationships
+  #
   class Cipher
     ROUNDS = 10
 
+    # Initialize FF1 cipher
+    #
+    # @param key [String] Encryption key (16, 24, or 32 bytes for AES-128/192/256)
+    # @param radix [Integer] Base for the numeral system (2-65536)
+    # @param mode [Symbol] Encryption mode (:reversible or :irreversible)
+    #
     def initialize(key, radix = 10, mode = Modes::REVERSIBLE)
       @key = key
       @radix = radix
       @mode = mode
       @irreversible_salt = generate_irreversible_salt if @mode == Modes::IRREVERSIBLE
+
       validate_parameters
     end
 
+    # Encrypt plaintext using FF1 algorithm
+    #
+    # @param plaintext [String] Data to encrypt (must meet domain size requirements)
+    # @param tweak [String] Additional data for encryption uniqueness (optional)
+    # @return [String] Encrypted data in same format as input
+    #
     def encrypt(plaintext, tweak = '')
       validate_input(plaintext)
 
@@ -23,6 +44,13 @@ module FF1
       end
     end
 
+    # Decrypt ciphertext back to original plaintext
+    #
+    # @param ciphertext [String] Encrypted data to decrypt
+    # @param tweak [String] Same tweak used during encryption
+    # @return [String] Original plaintext
+    # @raise [FF1::Error] If cipher is in irreversible mode
+    #
     def decrypt(ciphertext, tweak = '')
       if @mode == Modes::IRREVERSIBLE
         raise FF1::Error, 'Cannot decrypt in irreversible mode - data is permanently transformed'
@@ -31,18 +59,106 @@ module FF1
       reversible_decrypt(ciphertext, tweak)
     end
 
-    # Check if the cipher is in reversible mode
+    # Check if the cipher can decrypt data
+    # @return [Boolean] true if in reversible mode
     def reversible?
       @mode == Modes::REVERSIBLE
     end
 
-    # Check if the cipher is in irreversible mode
+    # Check if the cipher cannot decrypt data
+    # @return [Boolean] true if in irreversible mode
     def irreversible?
       @mode == Modes::IRREVERSIBLE
     end
 
+    # Encrypt arbitrary text using UTF-8 encoding
+    #
+    # @param text [String] Text to encrypt (any UTF-8 string)
+    # @param tweak [String] Additional data for encryption uniqueness (optional)
+    # @return [String] Encrypted text as base64-encoded string
+    #
+    def encrypt_text(text, tweak = '')
+      raise FF1::Error, 'Text cannot be nil' if text.nil?
+      raise FF1::Error, 'Text cannot be empty' if text.empty?
+
+      # Convert text to bytes and then to radix-256 representation
+      bytes = text.dup.force_encoding('UTF-8').bytes
+
+      # Use radix 256 for full byte support
+      old_radix = @radix
+      @radix = 256
+
+      begin
+        # Convert bytes to string representation for FF1
+        byte_string = bytes.map(&:chr).join
+
+        # Ensure minimum length for domain size (256^2 = 65536 > 100)
+        byte_string += "\x00" * (2 - byte_string.length) if byte_string.length < 2
+
+        # Encrypt using standard FF1
+        encrypted_bytes = if @mode == Modes::IRREVERSIBLE
+                            irreversible_encrypt(byte_string, tweak)
+                          else
+                            reversible_encrypt(byte_string, tweak)
+                          end
+
+        # Return as base64 for safe text representation
+        require 'base64'
+        Base64.strict_encode64(encrypted_bytes)
+      ensure
+        @radix = old_radix
+      end
+    end
+
+    # Decrypt text back to original UTF-8 string
+    #
+    # @param encrypted_text [String] Base64-encoded encrypted text
+    # @param tweak [String] Same tweak used during encryption
+    # @return [String] Original UTF-8 text
+    # @raise [FF1::Error] If cipher is in irreversible mode
+    #
+    def decrypt_text(encrypted_text, tweak = '')
+      if @mode == Modes::IRREVERSIBLE
+        raise FF1::Error, 'Cannot decrypt text in irreversible mode - data is permanently transformed'
+      end
+
+      raise FF1::Error, 'Encrypted text cannot be nil' if encrypted_text.nil?
+      raise FF1::Error, 'Encrypted text cannot be empty' if encrypted_text.empty?
+
+      # Decode from base64
+      require 'base64'
+      begin
+        encrypted_bytes = Base64.strict_decode64(encrypted_text)
+      rescue ArgumentError => e
+        raise FF1::Error, "Invalid base64 encrypted text: #{e.message}"
+      end
+
+      # Use radix 256 for full byte support
+      old_radix = @radix
+      @radix = 256
+
+      begin
+        # Decrypt using standard FF1
+        decrypted_bytes = reversible_decrypt(encrypted_bytes, tweak)
+
+        # Remove any null padding that was added for minimum length
+        decrypted_bytes = decrypted_bytes.sub(/\x00+\z/, '')
+
+        # Convert back to UTF-8 string
+        decrypted_bytes.dup.force_encoding('UTF-8')
+      ensure
+        @radix = old_radix
+      end
+    end
+
     private
 
+    # =========================================================================
+    # REVERSIBLE MODE METHODS
+    # Standard FF1 encryption that can be decrypted back to original
+    # =========================================================================
+
+    # Perform standard FF1 encryption (reversible)
     def reversible_encrypt(plaintext, tweak)
       # Convert string to integer array
       x = string_to_numeral_array(plaintext)
@@ -56,7 +172,7 @@ module FF1
       u = n / 2
       v = n - u
       a = x[0...u]
-      b = x[u..-1]
+      b = x[u..]
 
       # FF1 encryption rounds
       (0...ROUNDS).each do |i|
@@ -83,10 +199,13 @@ module FF1
       numeral_array_to_string(a + b)
     end
 
-    def irreversible_encrypt(plaintext, tweak)
-      # Step 1: Create a deterministic but irreversible transformation
-      # This maintains format and relationships but prevents decryption
+    # =========================================================================
+    # IRREVERSIBLE MODE METHODS
+    # Modified FF1 that cannot be decrypted - for GDPR compliance
+    # =========================================================================
 
+    # Perform irreversible FF1 encryption (cannot be decrypted)
+    def irreversible_encrypt(plaintext, tweak)
       # Convert string to integer array
       x = string_to_numeral_array(plaintext)
       n = x.length
@@ -96,16 +215,18 @@ module FF1
       raise FF1::Error, "Domain size too small (#{domain_size} < 100)" if domain_size < 100
 
       # Create irreversible key by hashing original key + salt + plaintext
-      # This ensures same plaintext always maps to same ciphertext (maintains relationships)
-      # but makes reverse computation impossible
+      # This ensures:
+      # 1. Same plaintext always maps to same ciphertext (maintains relationships)
+      # 2. Reverse computation is mathematically impossible
       irreversible_key = create_irreversible_key(plaintext, tweak)
 
-      # Use modified FF1 with irreversible key and additional entropy destruction
+      # Use modified FF1 with irreversible key and entropy destruction
       result = perform_irreversible_ff1(x, irreversible_key, tweak)
 
       numeral_array_to_string(result)
     end
 
+    # Create one-way irreversible key from inputs
     def create_irreversible_key(plaintext, tweak)
       # Create a one-way hash that includes:
       # - Original key (for uniqueness per cipher instance)
@@ -113,7 +234,13 @@ module FF1
       # - Plaintext (makes each plaintext map consistently)
       # - Tweak (maintains tweak-based differentiation)
 
-      hash_input = @key + @irreversible_salt + plaintext + tweak
+      # Ensure all inputs have compatible encodings
+      key_binary = @key.dup.force_encoding('BINARY')
+      salt_binary = @irreversible_salt.dup.force_encoding('BINARY')
+      plaintext_binary = plaintext.dup.force_encoding('BINARY')
+      tweak_binary = tweak.dup.force_encoding('BINARY')
+
+      hash_input = key_binary + salt_binary + plaintext_binary + tweak_binary
       hashed = Digest::SHA256.digest(hash_input)
 
       # Return same length as original key for AES compatibility
@@ -125,7 +252,7 @@ module FF1
       u = n / 2
       v = n - u
       a = x[0...u]
-      b = x[u..-1]
+      b = x[u..]
 
       # Use same FF1 structure but with irreversible key
       # and entropy-destroying modifications
@@ -138,7 +265,7 @@ module FF1
 
         # Add extra entropy destruction by mixing in round number and salt
         entropy_destroyer = Digest::SHA256.digest(@irreversible_salt + [i].pack('C'))[0...8]
-        y = xor_bytes(y[0...8], entropy_destroyer) + y[8..-1]
+        y = xor_bytes(y[0...8], entropy_destroyer) + y[8..]
 
         @key = old_key # Restore for next operations
 
@@ -158,13 +285,13 @@ module FF1
     def generate_irreversible_salt
       # Generate a unique salt for this cipher instance
       # This prevents rainbow table attacks on irreversible mode
-      Digest::SHA256.digest(@key + 'irreversible_mode')[0...16]
+      Digest::SHA256.digest("#{@key}irreversible_mode")[0...16]
     end
 
     def xor_bytes(bytes1, bytes2)
       result = ''
       [bytes1.bytesize, bytes2.bytesize].min.times do |i|
-        result += [(bytes1.getbyte(i) ^ bytes2.getbyte(i))].pack('C')
+        result += [bytes1.getbyte(i) ^ bytes2.getbyte(i)].pack('C')
       end
       result
     end
@@ -184,7 +311,7 @@ module FF1
       u = n / 2
       v = n - u
       a = x[0...u]
-      b = x[u..-1]
+      b = x[u..]
 
       # FF1 decryption rounds (reverse order)
       (ROUNDS - 1).downto(0) do |i|
@@ -210,21 +337,37 @@ module FF1
       numeral_array_to_string(a + b)
     end
 
+    # =========================================================================
+    # VALIDATION METHODS
+    # Input and parameter validation for security
+    # =========================================================================
+
+    # Validate cipher initialization parameters
     def validate_parameters
-      raise FF1::Error, 'Invalid key length' if @key.bytesize != 16 && @key.bytesize != 24 && @key.bytesize != 32
-      raise FF1::Error, 'Invalid radix' if @radix < 2 || @radix > 65_536
+      raise FF1::Error, 'Invalid key length - must be 16, 24, or 32 bytes' unless [16, 24, 32].include?(@key.bytesize)
+
+      return if (2..65_536).cover?(@radix)
+
+      raise FF1::Error, 'Invalid radix - must be between 2 and 65536'
     end
 
+    # Validate input data for encryption/decryption
     def validate_input(input)
       raise FF1::Error, 'Input cannot be nil' if input.nil?
       raise FF1::Error, 'Input cannot be empty' if input.empty?
       raise FF1::Error, 'Input length must be at least 2' if input.length < 2
     end
 
+    # =========================================================================
+    # CORE FF1 ALGORITHM METHODS
+    # Implementation of NIST SP 800-38G FF1 specification
+    # =========================================================================
+
+    # FF1 round function - core of the algorithm
     def round_function(round, b, tweak)
       # Construct P according to FF1 spec
-      radix_bytes = [@radix].pack('N')[1..-1] # Take 3 bytes of radix
-      p = "\x01\x02\x01" + radix_bytes # 1,2,1 followed by radix in 3 bytes
+      radix_bytes = [@radix].pack('N')[1..] # Take 3 bytes of radix
+      p = "\u0001\u0002\u0001#{radix_bytes}" # 1,2,1 followed by radix in 3 bytes
       p += [0x0a].pack('C') # 10 rounds
       p += [b.length].pack('C') # length of right side
       p += [tweak.bytesize].pack('N') # tweak length in 4 bytes
@@ -262,7 +405,7 @@ module FF1
         # XOR with previous result
         xor_block = ''
         16.times do |j|
-          xor_block += [(block.getbyte(j) ^ result.getbyte(j))].pack('C')
+          xor_block += [block.getbyte(j) ^ result.getbyte(j)].pack('C')
         end
 
         # Encrypt the XOR result
@@ -276,14 +419,22 @@ module FF1
       result
     end
 
+    # =========================================================================
+    # CHARACTER CONVERSION METHODS
+    # Handle different radix systems (binary, decimal, hex, alphanumeric)
+    # =========================================================================
+
+    # Convert string to array of numeric values based on radix
     def string_to_numeral_array(str)
       str.chars.map { |char| char_to_digit(char) }
     end
 
+    # Convert array of numeric values back to string based on radix
     def numeral_array_to_string(array)
       array.map { |digit| digit_to_char(digit) }.join
     end
 
+    # Convert character to digit based on current radix
     def char_to_digit(char)
       case @radix
       when 2..10
@@ -292,17 +443,21 @@ module FF1
 
         raise FF1::Error, "Invalid character '#{char}' for radix #{@radix}"
       when 11..36
-        if char.match?(/\d/)
+        case char
+        when /\d/
           char.to_i
-        elsif char.match?(/[A-Z]/)
+        when /[A-Z]/
           char.ord - 'A'.ord + 10
-        elsif char.match?(/[a-z]/)
+        when /[a-z]/
           char.ord - 'a'.ord + 10
         else
           raise FF1::Error, "Invalid character '#{char}' for radix #{@radix}"
         end
+      when 256
+        # Special case for text encryption - use byte values directly
+        char.ord
       else
-        # For higher radix values, use ASCII values
+        # For other higher radix values, use ASCII values with validation
         digit = char.ord
         raise FF1::Error, "Invalid character '#{char}' for radix #{@radix}" if digit >= @radix
 
@@ -320,11 +475,20 @@ module FF1
         else
           (digit - 10 + 'A'.ord).chr
         end
+      when 256
+        # Special case for text encryption - convert byte values back to characters
+        digit.chr
       else
         digit.chr
       end
     end
 
+    # =========================================================================
+    # MATHEMATICAL UTILITY METHODS
+    # Number base conversions and modular arithmetic
+    # =========================================================================
+
+    # Convert numeral array to integer using specified radix
     def numeral_array_to_integer(array, radix)
       result = 0
       array.each do |digit|
@@ -333,6 +497,7 @@ module FF1
       result
     end
 
+    # Convert integer to numeral array with specified radix and length
     def integer_to_numeral_array(int, radix, length)
       array = []
       length.times do
@@ -342,6 +507,7 @@ module FF1
       array
     end
 
+    # Convert byte string to integer (big-endian)
     def byte_string_to_integer(bytes)
       result = 0
       bytes.each_byte do |byte|

data/lib/ff1/modes.rb

@@ -1,11 +1,30 @@
+# frozen_string_literal: true
+
 module FF1
-  # Encryption modes for different use cases
+  # FF1 Encryption Modes
+  #
+  # Provides two distinct modes of operation for different security requirements:
+  # - Reversible: Standard encryption that can be decrypted
+  # - Irreversible: Secure "deletion" while maintaining data relationships
+  #
   module Modes
-    # Normal reversible encryption - can decrypt back to original
+    # Normal reversible encryption mode
+    #
+    # - Can decrypt back to original plaintext
+    # - Use for active business data that needs to be accessed
+    # - Standard FF1 algorithm implementation
+    # - Perfect for payment processing, customer service, reporting
+    #
     REVERSIBLE = :reversible
 
-    # Irreversible encryption - maintains format and relationships but cannot decrypt
-    # Useful for GDPR "right to be forgotten" compliance
+    # Irreversible encryption mode
+    #
+    # - Cannot decrypt back to original (mathematically impossible)
+    # - Maintains format and data relationships
+    # - Use for GDPR "right to be forgotten" compliance
+    # - Perfect for secure data deletion, employee termination, account closure
+    # - Even with the key, original data cannot be recovered
+    #
     IRREVERSIBLE = :irreversible
   end
 end

data/lib/ff1/version.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 module FF1
-  VERSION = "1.0.0"
-end
+  # Current version of the FF1 gem
+  VERSION = '1.1.0'
+end

data/lib/ff1.rb

@@ -1,7 +1,32 @@
+# frozen_string_literal: true
+
 require_relative 'ff1/version'
 require_relative 'ff1/modes'
 require_relative 'ff1/cipher'
 
+# FF1 Format Preserving Encryption
+#
+# A Ruby implementation of NIST SP 800-38G FF1 algorithm with dual-mode operation.
+# Provides both reversible encryption (standard FPE) and irreversible encryption
+# (secure deletion while maintaining format and relationships).
+#
+# @example Basic Usage
+#   key = SecureRandom.bytes(32)
+#
+#   # Reversible mode (can decrypt)
+#   cipher = FF1::Cipher.new(key, 10, FF1::Modes::REVERSIBLE)
+#   encrypted = cipher.encrypt("1234567890")
+#   decrypted = cipher.decrypt(encrypted)  # => "1234567890"
+#
+#   # Irreversible mode (cannot decrypt - for GDPR compliance)
+#   secure_cipher = FF1::Cipher.new(key, 10, FF1::Modes::IRREVERSIBLE)
+#   secured = secure_cipher.encrypt("1234567890")
+#   # secure_cipher.decrypt(secured)  # Raises FF1::Error
+#
+# @see https://csrc.nist.gov/publications/detail/sp/800-38g/final NIST SP 800-38G
+# @see https://rubygems.org/gems/ff1 RubyGems Page
+#
 module FF1
+  # Base error class for all FF1-related errors
   class Error < StandardError; end
-end
+end