gfc64 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f93c96115de165e7cec9824e893e7254b6612c5d254c19d19c14899c7aa68ef1
-  data.tar.gz: 00fc60e41ebe8a82bd7de95386aaa097df8a468ecb13e1ad98c7a4b5a311f59c
+  metadata.gz: 925a9e68e6edfd9f2d40a0e37f7712b56e113382a35f46ed6ff10319518e8bca
+  data.tar.gz: 821817a8b6df2d28e61783676242e7ece64a868b764ce7a10defad2ad58ec6b2
 SHA512:
-  metadata.gz: 2b7b53943801d158fbc1e44c2a9bd6038aa4445047ebfc7de941f3dc583bb55120e9353dbea6d12de4253d1bc67f88c44e4a1c2326a549f4dd13a6a0842e2041
-  data.tar.gz: 6674b80a4457530858aa15b57d89b421431e81313066356d95013292257b160936efde74b27349f410d5cc002dc64bf5dfe9fb00f08af830d72c5dfb2268a617
+  metadata.gz: a8f8f4055326bd37ae278fffbb3ae1f5ba04116dd949686df673fb03466c70da7eea23c31a9303a6b927da63e59d9b777c7fbfea4484cbc8eba03a0b3379d3b3
+  data.tar.gz: 0a9a328a725f9fcd43fdf479e04eaca93f102facf2276a600d206c1369acc107ce94631d342cc92ebfd2e3e34a65d7a48eb310e3e046e6b3e334ce28c4c65c3f

data/README.md

@@ -1,20 +1,39 @@
 # GFC64
 
-Format-preserving Generalized Feistel Cipher for 64-bit integers. Encrypts 64-bit
-integers into... 64-bit integers!
+Encrypt 64-bit integers into other 64-bit integers without collisions.
 
-Very useful for if you have sequential 64-bit integer database primary keys that
-you want to expose in an app, but you don't want to leak count information
-(e.g. `/customers/1`, `/customers/2`, ...), and you don't want to add another
-column to store something auxiliary like a UUID.
+Useful for hiding database auto-incrementing primary keys without needing
+to store additional data (like a UUID field).
 
-For example, with this gem, routes like
+For example, say you have a web app where routes are stored like `/customers/:id`
+so that you have exposed URL paths like this:
 
-`/customers/1` can become something like `/customers/4552956331295818987`, and
+`/customers/1`
 
-`/customers/2` can become something like `/customers/3833777695217202560`
+`/customers/2`
 
-## Usage
+With this gem, you can (at view-time) encrypt the above IDs into different IDs
+so that you get these paths instead, without storing any additional data:
+
+`/customers/4552956331295818987` (the backend decrypts this into `/customers/1`)
+
+`/customers/3833777695217202560` (the backend decrypts this into `/customers/2`)
+
+All while keeping your auto-incrementing, sequential IDs in your database and
+getting all the benefits of a standard database index.
+
+The encryption is achieved by implementing a format-preserving
+[Generalized Feistel Cipher][paper].
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "gfc64"
+```
+
+## General Usage
 
 ```ruby
 key = SecureRandom.hex(32) # => "ffb5e3600fc27924f97dc055440403b10ce97160261f2a87eee576584cf942e5"
@@ -25,6 +44,48 @@ gfc.encrypt(2) # => 3833777695217202560
 gfc.decrypt(3833777695217202560) # => 2
 ```
 
+## Rails Usage
+
+For Rails, there's an ActiveRecord mixin which adds `#gfc_id` and
+`#to_param` methods and a `::find_gfc` class method. By setting `#to_param`,
+resource path helpers like `customer_path(@customer)` automatically use the
+GFC encrypted ID.
+
+Example usage:
+
+```ruby
+# app/models/customer.rb
+
+class Customer < ApplicationRecord
+  include GFC64::ActiveRecord[GFC64.new(ENV['GFC_KEY'])]
+  # or the argument can be a proc/lambda if you need late binding:
+  # include GFC64::ActiveRecord[-> { GFC64.new(ENV['GFC_KEY']) }]
+end
+```
+
+For retrieval, use `::find_gfc`:
+
+```ruby
+# app/controllers/customers_controller.rb
+
+class CustomersController < ApplicationController
+  def show
+    @customer = Customer.find_gfc(params[:id])
+  end
+end
+```
+
+## Potential drawbacks
+
+Ruby's dynamic typing means we're just passing bare Integers around, so it's
+possible to make a mistake where you write something like `Model.find(gfc_id)`
+and return a completely unexpected record because you forgot to decrypt the ID.
+
+With a type system it would be trivial to prevent these errors. However, the
+space of 64-bit integers is very large, and encrypted IDs tend to occupy numbers
+much higher than most web apps will ever reach, so more than likely this sort of
+error would be discovered quickly as queries fail to find anything.
+
 ## Disclaimer
 
 This code has not been vetted by a security audit or a professional

data/lib/gfc64/active_record.rb

@@ -0,0 +1,37 @@
+class GFC64
+  module ActiveRecord
+    def self.[](gfc)
+      Module.new do
+        include ActiveRecord
+
+        define_singleton_method :included do |klass|
+          klass.extend(ClassMethods)
+          klass.send(:include, InstanceMethods)
+          klass.f_gfc = gfc
+        end
+      end
+    end
+
+    module ClassMethods
+      attr_accessor :f_gfc
+
+      def gfc
+        @gfc ||= f_gfc.respond_to?(:call) ? f_gfc.call : f_gfc
+      end
+
+      def find_gfc(gfc_id)
+        find(gfc.decrypt(gfc_id))
+      end
+    end
+
+    module InstanceMethods
+      def gfc_id
+        id && self.class.gfc.encrypt(id)
+      end
+
+      def to_param
+        gfc_id.to_s
+      end
+    end
+  end
+end

data/lib/gfc64.rb

@@ -4,7 +4,7 @@ require "openssl"
 require "securerandom"
 
 class GFC64
-  VERSION = "0.0.2".freeze
+  VERSION = "0.0.3".freeze
 
   attr_reader :rounds, :key, :block_size
 
@@ -55,3 +55,5 @@ class GFC64
     OpenSSL::Digest::SHA256.digest(key + [round].pack('L'))[0...16] # Truncate to 128 bits for AES key
   end
 end
+
+require "gfc64/active_record"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gfc64
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Abe Voelker
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-11-03 00:00:00.000000000 Z
+date: 2023-11-04 00:00:00.000000000 Z
 dependencies: []
 description: Hides sequential primary key counts without resorting to UUIDs or GUIDs.
 email: abe@abevoelker.com
@@ -18,6 +18,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/gfc64.rb
+- lib/gfc64/active_record.rb
 homepage: https://github.com/abevoelker/gfc64
 licenses:
 - MIT
@@ -34,7 +35,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.1.0
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="