ipcrypt2 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 417ba3249b6a04ea6f104538af68b7d393f73c3b4b12ca1ca88082b7788b7617
-  data.tar.gz: e03947c5f01df8906342b8730a96f9f3280210951a6829206e9a37c28b5c6e70
+  metadata.gz: b076ab85b1294156c609b76570e2995b9c5f837659f7ad601184871545ccc343
+  data.tar.gz: 23016972e27094071e8e34fd8a26e28874dc83ff66ff174ef243f9191dc19d4a
 SHA512:
-  metadata.gz: 258447b2adc9eb4df871cbbf69f30da0e327ecdf4e01be1ccd82150f7da58f4af816509109c3c3d054f7c67364f27829c4bee888d86999c0dec8cbac690751ab
-  data.tar.gz: fca823b4fd42a7c09c5833d524bc38df494e30f0a623bb5b74e9f748bc9633612d1f3089a0bb42d88190991c1bb0e940219cf2fc0d2ede7391ee589164876245
+  metadata.gz: 7a04c6d8b2a2570a3dc85a7d3e8c2fbf0a81277b9b3ad4670ef56a9baacaa851f28c5eec8341cf3c704274df59a853b5a8880042414bb3c4dd17e4faef53fa34
+  data.tar.gz: d543f0d759ff31482d5d92fbd7a23b1514485f6fa7cc93232056c2bdfa6e95cc357d6f3db7e38447c3e1a4cb9cf69770a257d85672a02bb9047439dfe6e797b8

data/CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2025-09-10
+
+### Added
+- Support for the PFX mode.
+
 ## [1.0.0] - 2025-08-30
 
 Initial public release.

data/README.md

@@ -6,11 +6,13 @@ This gem provides privacy-preserving methods for storing, logging, and analyzing
 
 ## Features
 
-- **Three encryption modes:**
+- **Four encryption modes:**
   - `ipcrypt-deterministic`: Deterministic encryption using AES-128 (same input always produces same output)
+  - `ipcrypt-pfx`: Prefix-preserving encryption that maintains network relationships while encrypting addresses
   - `ipcrypt-nd`: Non-deterministic encryption using KIASU-BC with 8-byte tweak
   - `ipcrypt-ndx`: Non-deterministic encryption using AES-XTS with 16-byte tweak
 - **Full IPv4 and IPv6 support** with automatic conversion to unified 16-byte format
+- **Prefix preservation** with ipcrypt-pfx for network-level analytics while protecting individual addresses
 - **Secure implementations** using OpenSSL for cryptographic operations
 - **Comprehensive test suite** with official test vectors from the specification
 - **Ruby 2.6+ compatibility**
@@ -70,6 +72,24 @@ encrypted_data = IPCrypt::ND.encrypt(ip, key, tweak)  # Specific tweak
 decrypted_ip = IPCrypt::ND.decrypt(encrypted_data, key)
 ```
 
+### Prefix-Preserving Encryption (ipcrypt-pfx)
+
+```ruby
+require 'ipcrypt/pfx'
+
+# 32-byte key (split into two AES-128 keys internally)
+key = "0123456789abcdeffedcba98765432101032547698badcfeefcdab8967452301".scan(/../).map { |x| x.hex }.pack("C*")
+
+# Encrypt IP addresses - addresses from the same network share encrypted prefix
+ip1 = "10.0.0.1"
+ip2 = "10.0.0.2"
+encrypted_ip1 = IPCrypt::Pfx.encrypt(ip1, key)  # "154.135.56.208"
+encrypted_ip2 = IPCrypt::Pfx.encrypt(ip2, key)  # "154.135.56.211" (same /24 prefix)
+
+# Decrypt
+decrypted_ip1 = IPCrypt::Pfx.decrypt(encrypted_ip1, key)  # Returns "10.0.0.1"
+```
+
 ### Non-Deterministic Encryption with AES-XTS (ipcrypt-ndx)
 
 ```ruby
@@ -300,6 +320,7 @@ end
 
 2. **Choose the Right Mode**:
    - Use `deterministic` for logs and analytics where you need to correlate multiple requests from the same IP
+   - Use `pfx` for network-level analytics where you need to preserve subnet relationships while encrypting individual addresses
    - Use `nd` or `ndx` for storage where each encryption should be unique
 
 3. **Performance**: For high-traffic applications, consider caching the key parsing:

data/lib/ipcrypt/pfx.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'openssl'
+
+module IPCrypt
+  # Implementation of ipcrypt-pfx using AES-128 for prefix-preserving encryption
+  class Pfx
+    # Convert an IP address to its 16-byte representation
+    def self.ip_to_bytes(ip)
+      ip_addr = ip.is_a?(String) ? IPAddr.new(ip) : ip
+      if ip_addr.ipv4?
+        # Convert IPv4 to IPv4-mapped IPv6 format (::ffff:0:0/96)
+        bytes = [0] * 10 + [0xff, 0xff] + ip_addr.hton.bytes
+        bytes.pack('C*').force_encoding('BINARY')
+      else
+        ip_addr.hton.force_encoding('BINARY')
+      end
+    end
+
+    # Convert a 16-byte representation back to an IP address
+    def self.bytes_to_ip(bytes16)
+      raise InvalidDataError, 'Input must be 16 bytes' unless bytes16.length == 16
+
+      # Check for IPv4-mapped IPv6 format
+      zero_bytes = [0] * 10
+      ff_bytes = [255, 255]
+
+      if bytes16[0, 10].bytes == zero_bytes && bytes16[10, 2].bytes == ff_bytes
+        IPAddr.new_ntoh(bytes16[12, 4])
+      else
+        IPAddr.new_ntoh(bytes16)
+      end
+    end
+
+    # Check if a 16-byte array has the IPv4-mapped IPv6 prefix (::ffff:0:0/96)
+    def self.ipv4_mapped?(bytes16)
+      return false unless bytes16.length == 16
+
+      # Check for IPv4-mapped prefix: first 10 bytes are 0x00, bytes 10-11 are 0xFF
+      bytes16[0, 10].bytes == [0] * 10 && bytes16[10, 2].bytes == [255, 255]
+    end
+
+    # Extract bit at position from 16-byte array
+    # position: 0 = LSB of byte 15, 127 = MSB of byte 0
+    def self.get_bit(data, position)
+      byte_index = 15 - (position / 8)
+      bit_index = position % 8
+      (data.bytes[byte_index] >> bit_index) & 1
+    end
+
+    # Set bit at position in 16-byte array
+    # position: 0 = LSB of byte 15, 127 = MSB of byte 0
+    def self.set_bit(data, position, value)
+      byte_index = 15 - (position / 8)
+      bit_index = position % 8
+      bytes = data.bytes
+      bytes[byte_index] |= value << bit_index
+      bytes.pack('C*')
+    end
+
+    # Shift a 16-byte array one bit to the left
+    # The most significant bit is lost, and a zero bit is shifted in from the right
+    def self.shift_left_one_bit(data)
+      raise InvalidDataError, 'Input must be 16 bytes' unless data.length == 16
+
+      bytes = data.bytes
+      result = Array.new(16, 0)
+      carry = 0
+
+      # Process from least significant byte (byte 15) to most significant (byte 0)
+      15.downto(0) do |i|
+        # Current byte shifted left by 1, with carry from previous byte
+        result[i] = ((bytes[i] << 1) | carry) & 0xFF
+        # Extract the bit that will be carried to the next byte
+        carry = (bytes[i] >> 7) & 1
+      end
+
+      result.pack('C*')
+    end
+
+    # Pad prefix for prefix_len_bits=0 (IPv6)
+    # Sets separator bit at position 0 (LSB of byte 15)
+    def self.pad_prefix_zero
+      padded = Array.new(16, 0)
+      padded[15] = 0x01 # Set bit at position 0 (LSB of byte 15)
+      padded.pack('C*')
+    end
+
+    # Pad prefix for prefix_len_bits=96 (IPv4)
+    # For IPv4, the data always has format: 00...00 ffff xxxx (IPv4-mapped)
+    # Result: 00000001 00...00 0000ffff (separator at pos 96, then 96 bits)
+    def self.pad_prefix_ninetysix(_data)
+      # The result is always the same for IPv4 addresses since they all have
+      # the same IPv4-mapped prefix (00...00 ffff)
+      padded = Array.new(16, 0)
+      padded[3] = 0x01 # Set bit at position 96 (bit 0 of byte 3)
+      padded[14] = 0xFF
+      padded[15] = 0xFF
+      padded.pack('C*')
+    end
+
+    # Encrypt an IP address using ipcrypt-pfx
+    def self.encrypt(ip, key)
+      raise InvalidKeyError, 'Key must be 32 bytes' unless key.length == 32
+
+      # Split the key into two AES-128 keys
+      k1 = key[0, 16]
+      k2 = key[16, 16]
+
+      # Check that K1 and K2 are different
+      raise InvalidKeyError, 'The two halves of the key must be different' if k1 == k2
+
+      # Convert IP to 16-byte representation
+      bytes16 = ip_to_bytes(ip)
+
+      # Initialize encrypted result with zeros
+      encrypted = Array.new(16, 0)
+
+      # Determine starting point
+      if ipv4_mapped?(bytes16)
+        prefix_start = 96
+        # If IPv4-mapped, copy the IPv4-mapped prefix
+        encrypted[0, 12] = bytes16[0, 12].bytes
+      else
+        prefix_start = 0
+      end
+
+      # Create AES cipher objects
+      cipher1 = OpenSSL::Cipher.new('AES-128-ECB')
+      cipher1.encrypt
+      cipher1.padding = 0
+      cipher1.key = k1
+
+      cipher2 = OpenSSL::Cipher.new('AES-128-ECB')
+      cipher2.encrypt
+      cipher2.padding = 0
+      cipher2.key = k2
+
+      # Initialize padded_prefix for the starting prefix length
+      padded_prefix = if ipv4_mapped?(bytes16)
+                        pad_prefix_ninetysix(bytes16)
+                      else # prefix_start == 0
+                        pad_prefix_zero
+                      end
+
+      # Process each bit position
+      (prefix_start...128).each do |prefix_len_bits|
+        # Compute pseudorandom function with dual AES encryption
+        e1 = cipher1.update(padded_prefix) + cipher1.final
+        e2 = cipher2.update(padded_prefix) + cipher2.final
+
+        # XOR the two encryptions
+        e = e1.bytes.zip(e2.bytes).map { |a, b| a ^ b }.pack('C*')
+        # We only need the least significant bit of byte 15
+        cipher_bit = e.bytes[15] & 1
+
+        # Extract the current bit from the original IP
+        current_bit_pos = 127 - prefix_len_bits
+
+        # Set the bit in the encrypted result
+        original_bit = get_bit(bytes16, current_bit_pos)
+        encrypted_bytes = encrypted.pack('C*')
+        encrypted_bytes = set_bit(encrypted_bytes, current_bit_pos, cipher_bit ^ original_bit)
+        encrypted = encrypted_bytes.bytes
+
+        # Prepare padded_prefix for next iteration
+        # Shift left by 1 bit and insert the next bit from bytes16
+        padded_prefix = shift_left_one_bit(padded_prefix)
+        padded_prefix = set_bit(padded_prefix, 0, original_bit)
+      end
+
+      bytes_to_ip(encrypted.pack('C*'))
+    end
+
+    # Decrypt an IP address using ipcrypt-pfx
+    def self.decrypt(encrypted_ip, key)
+      raise InvalidKeyError, 'Key must be 32 bytes' unless key.length == 32
+
+      # Split the key into two AES-128 keys
+      k1 = key[0, 16]
+      k2 = key[16, 16]
+
+      # Check that K1 and K2 are different
+      raise InvalidKeyError, 'The two halves of the key must be different' if k1 == k2
+
+      # Convert encrypted IP to 16-byte representation
+      encrypted_bytes = ip_to_bytes(encrypted_ip)
+
+      # Initialize decrypted result
+      decrypted = Array.new(16, 0)
+
+      # For decryption, we need to determine if this was originally IPv4-mapped
+      # IPv4-mapped addresses are encrypted with prefix_start=96
+      if ipv4_mapped?(encrypted_bytes)
+        prefix_start = 96
+        # If this was originally IPv4, set up the IPv4-mapped IPv6 prefix
+        decrypted[10] = 0xff
+        decrypted[11] = 0xff
+      else
+        prefix_start = 0
+      end
+
+      # Create AES cipher objects
+      cipher1 = OpenSSL::Cipher.new('AES-128-ECB')
+      cipher1.encrypt
+      cipher1.padding = 0
+      cipher1.key = k1
+
+      cipher2 = OpenSSL::Cipher.new('AES-128-ECB')
+      cipher2.encrypt
+      cipher2.padding = 0
+      cipher2.key = k2
+
+      # Initialize padded_prefix for the starting prefix length
+      padded_prefix = if prefix_start.zero?
+                        pad_prefix_zero
+                      else # prefix_start == 96
+                        pad_prefix_ninetysix(decrypted.pack('C*'))
+                      end
+
+      # Process each bit position
+      (prefix_start...128).each do |prefix_len_bits|
+        # Compute pseudorandom function with dual AES encryption
+        e1 = cipher1.update(padded_prefix) + cipher1.final
+        e2 = cipher2.update(padded_prefix) + cipher2.final
+
+        # XOR the two encryptions
+        e = e1.bytes.zip(e2.bytes).map { |a, b| a ^ b }.pack('C*')
+        # We only need the least significant bit of byte 15
+        cipher_bit = e.bytes[15] & 1
+
+        # Extract the current bit from the encrypted IP
+        current_bit_pos = 127 - prefix_len_bits
+
+        # Set the bit in the decrypted result
+        encrypted_bit = get_bit(encrypted_bytes, current_bit_pos)
+        original_bit = cipher_bit ^ encrypted_bit
+        decrypted_bytes = decrypted.pack('C*')
+        decrypted_bytes = set_bit(decrypted_bytes, current_bit_pos, original_bit)
+        decrypted = decrypted_bytes.bytes
+
+        # Prepare padded_prefix for next iteration
+        # Shift left by 1 bit and insert the next bit from decrypted
+        padded_prefix = shift_left_one_bit(padded_prefix)
+        padded_prefix = set_bit(padded_prefix, 0, original_bit)
+      end
+
+      bytes_to_ip(decrypted.pack('C*'))
+    end
+  end
+end

data/lib/ipcrypt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IPCrypt
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

data/lib/ipcrypt.rb

@@ -7,3 +7,9 @@ module IPCrypt
   class InvalidTweakError < Error; end
   class InvalidDataError < Error; end
 end
+
+require_relative 'ipcrypt/deterministic'
+require_relative 'ipcrypt/nd'
+require_relative 'ipcrypt/ndx'
+require_relative 'ipcrypt/pfx'
+require_relative 'ipcrypt/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ipcrypt2
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Frank Denis
@@ -67,12 +67,12 @@ files:
 - lib/ipcrypt/deterministic.rb
 - lib/ipcrypt/nd.rb
 - lib/ipcrypt/ndx.rb
+- lib/ipcrypt/pfx.rb
 - lib/ipcrypt/version.rb
 homepage: https://github.com/jedisct1/ipcrypt-ruby
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/jedisct1/ipcrypt-ruby
   source_code_uri: https://github.com/jedisct1/ipcrypt-ruby
   changelog_uri: https://github.com/jedisct1/ipcrypt-ruby/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/jedisct1/ipcrypt-ruby/issues