active_enquo 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c0103ba2927e84bdc1c6fda73e7103ffe090316fac200d7d429a95e4f4632f0
-  data.tar.gz: 11d5f5d66a753fe18f79f198c7b243d9fa3b194929c6e2e63c6f4a93ce25ed06
+  metadata.gz: e643c69efa8243d95e44c59a6d49f20c40a23dc3a914da1d79342fa5d3969ca9
+  data.tar.gz: fcb70caad8b2d949fca672198e269e574924cd63748dfa221164ec6a1eb7842d
 SHA512:
-  metadata.gz: 693f14e986cca46c810505664833cd4e211c170cd287d43fbbb429ba7a5ef0e830404d71597a314e97cdde4fe911edf14066f9af446510ce82c05b3e73507c6d
-  data.tar.gz: afba7f08679b1b45f6484f9a3bf1b870fc2a824edec9b8b33483f40b7661c940f55d8135992885011d25a4c57d6c02ecb5f069ebde0bed0d59daec85d6ad301d
+  metadata.gz: 7ce8dd63cae62013d026ddf7200878975471bf30c157e059e50b269124e886a219ebb526581038bed3fed1de00500416bfdee7740497c1af2b775c90c46dfd53
+  data.tar.gz: 02a1944917d45d1517cd5143dbe56c05c28f8c8a2fffe5840f317ce865a944aa563a04560f3e39773eadb7f2ca5a0f54835bdab2f4765e5aacc456c9a88f88b8

data/README.md

@@ -3,12 +3,12 @@ This allows you to keep the data you store safe, by encrypting it, without compr
 
 Sounds like magic?
 Well, maybe a little bit.
-Read our [how it works](https://enquo.org/how-it-works) if you're interested in the details, or read on for how to use it.
+Read our [how it works](https://enquo.org/how-it-works) if you're interested in the gory cryptographic details, or read on for how to use it.
 
 
 # Pre-requisites
 
-In order to make use of this extension, you must be running Postgres 10 or higher, with the [`pg_enquo`](https://github.com/enquo/pg_enquo) extension enabled in the database you're working in.
+In order to make use of ActiveRecord extension, you must be running Postgres 11 or higher, with the [`pg_enquo`](https://github.com/enquo/pg_enquo) extension enabled in the database you're working in.
 See [the `pg_enquo` installation guide](https://github.com/enquo/pg_enquo/tree/main/doc/installation.md) for instructions on how to install `pg_enquo`.
 
 Also, if you're installing this gem from source, you'll need a reasonably recent [Rust](https://rust-lang.org) toolchain installed.
@@ -16,33 +16,41 @@ Also, if you're installing this gem from source, you'll need a reasonably recent
 
 # Installation
 
-It's a gem:
+It's a gem, so the usual methods should work Just Fine:
 
-    gem install active_enquo
-
-There's also the wonders of [the Gemfile](http://bundler.io):
+```sh
+gem install active_enquo
+# OR
+echo "gem 'active_enquo'" >> Gemfile
+```
 
-    gem 'active_enquo'
+On macOS, and Linux `x86-64`/`aarch64`, you'll get a pre-built binary gem that contains everything you need.
+For other platforms, you'll need to have Rust 1.59.0 or later installed in order to build the native code portion of the gem.
 
-If you're the sturdy type that likes to run from git:
 
-    rake install
+# Configuration
 
-Or, if you've eschewed the convenience of Rubygems entirely, then you
-presumably know what to do already.
+The only setting that ActiveEnquo needs is to be given a "root" key, which is used to derive the keys which are used to actually encrypt data.
 
 
-# Configuration
+## Step 1: Generate a Root Key
 
-The only setting that ActiveEnquo needs is to be given a "root" key, which is used to derive the keys which are used to actually encrypt data.
-This key ***MUST*** be generated by a cryptographically-secure random number generator, and must also be 64 hex digits in length.
+The ActiveEnquo root key ***MUST*** be generated by a cryptographically-secure random number generator, and must also be 64 hex digits in length.
 A good way to generate this key is with the `SecureRandom` module:
 
 ```sh
 ruby -r securerandom -e 'puts SecureRandom.hex(32)'
 ```
 
-With this key in hand, you can store it in the Rails credential store, like this:
+
+## Step 2: Configure Your Application
+
+With this key in hand, you need to store it somewhere.
+
+
+### Using Rails Credential Store (Recommended)
+
+The recommended way to store your root key, at present, is in the [Rails credentials store](https://guides.rubyonrails.org/security.html#custom-credentials).
 
 1. Open up the Rails credentials editor:
 
@@ -59,7 +67,11 @@ With this key in hand, you can store it in the Rails credential store, like this
 
 3. Save and exit the editor.  Commit the changes to your revision control system.
 
-This only works if you are using Rails, of course; if you're using ActiveRecord by itself, you must set the root key yourself during application initialization.
+
+### Direct Assignment (Only If You Must)
+
+Using the Rails credential store only works if you are using Rails, of course.
+If you're using ActiveRecord by itself, you must set the root key yourself during application initialization.
 You do this by assigning a `RootKey` to `ActiveEnquo.root_key`, like this:
 
 ```ruby
@@ -67,9 +79,12 @@ You do this by assigning a `RootKey` to `ActiveEnquo.root_key`, like this:
 ActiveEnquo.root_key = ActiveEnquo::RootKey::Static.new("0000000000000000000000000000000000000000000000000000000000000000")
 ```
 
-However, this leaves the key exposed to anyone who comes along and takes a glance at your code.
-Losing control of this root key is catastrophic for the security of your system.
-Instead, you should use a secrets vault of some sort to store the key, and pass it into your initialization code somehow.
+Preferably, you would pass the key into your application via, say, an environment variable, and then immediately clear the environment variable:
+
+```ruby
+ActiveEnquo.root_key = ActiveEnquo::RootKey::Static.new(ENV.fetch("ENQUO_ROOT_KEY"))
+ENV.delete("ENQUO_ROOT_KEY")
+```
 
 Support for cloud keystores, such as AWS KMS, GCP KMS, Azure KeyVault, and HashiCorp Vault, will be implemented sooner or later.
 If you have a burning desire to see that more on the "sooner" end than "later", PRs are welcome.
@@ -77,67 +92,72 @@ If you have a burning desire to see that more on the "sooner" end than "later",
 
 # Usage
 
-Start by creating a column in your database that uses one of the [available enquo types](https://github.com/enquo/pg_enquo/doc/data_types), with a Rails migration:
+We try to make using ActiveEnquo as simple as possible.
+
+
+## Create Your Encrypted Column
+
+Start by creating a column in your database that uses one of the [available `enquo_*` types](https://github.com/enquo/pg_enquo/tree/main/doc/data_types), with a Rails migration:
 
 ```ruby
 class AddEncryptedBigintColumn < ActiveRecord::Migration[6.0]
   def change
-    add_column :users, :age, :enquo_bigint
+    add_column :users, :date_of_birth, :enquo_date
   end
 end
 ```
 
+Apply this migration in the usual fashion (`rails db:migrate`).
+
 
 ## Reading and Writing
 
-You can now use that attribute in your models as you would normally.
-For example, insert a new record:
+You can now, without any further ado, use that attribute in your models as you would normally.
+For example, you can insert a new record:
 
 ```ruby
-User.create!([{name: "Clara Bloggs", username: "cbloggs", age: 42}])
+User.create!([{name: "Clara Bloggs", username: "cbloggs", date_of_birth: Date(1970, 1, 1)}])
 ```
 
 When you retrieve a record, the value is there for you to read:
 
 ```ruby
-User.where(username: "cbloggs").first.age  # => 42
+User.where(username: "cbloggs").first.date_of_birth.to_s  # => "1970-01-01"
 ```
 
-So far, nothing more spectacular than what AR Encryption will get you.
-The fun begins now...
-
 
 ## Querying
 
-You can query for records with an exact age:
+This is where things get *neat*.
+
+Performing a query on Enquo-encrypted data is done the same way as on unencrypted data, with one exception: you need to wrap the values of the query in `<Model>.enquo` calls, as in the examples below.
+
+You can query for records that have the exact value you're looking for:
 
 ```ruby
-User.where(age: User.enquo(:age, 42))
+User.where(age: User.enquo(:date_of_birth, Date(1970, 1, 1)))
 ```
 
-Or you can query for records with an age of less than 50:
+Or you can query for users born less than 50 years ago:
 
 ```ruby
-# This is AR's idiomatic way of saying "less-than"
-User.where(age: User.enquo(:age, ...50))
+User.where(age: User.enquo(:date, Date.today - 50.years)..)
 ```
 
-*However*, if you examine the record in the database, it's encrypted:
+This doesn't seem so magical, until you take a peek in the database, and realise that *all the data is still encrypted*:
 
 ```sh
-psql> SELECT age FROM users WHERE username='cbloggs';
+psql> SELECT date_of_birth FROM users WHERE username='cbloggs';
   age
 -------
- {"ct":[<lots of numbers>],"ore":[<lots and LOTS of numbers>]}
+ {"v1":{"a":[<lots of numbers>],"y":[<lots and LOTS of numbers>],<etc etc>}}
 ```
 
-And that, as they say, is that.
-
 
 ## Indexing and Ordering
 
-To maintain [security](https://enquo.org/about/threat-models#snapshot-security), ActiveEnquo isn't able to `ORDER BY` or index columns.
-This is fine for many situations -- many columns don't need indexes.
+To maintain [security by default](https://enquo.org/about/threat-models#snapshot-security), ActiveEnquo doesn't provide the ability to `ORDER BY` or index columns by default.
+This is fine for many situations -- many columns don't need indexes or to be ordered in a query.
 
 For those columns that *do* need indexes or `ORDER BY` support, you can enable support for them by setting the `enable_reduced_security_operations` flag on the attribute, like this:
 
@@ -148,10 +168,11 @@ class User < ApplicationRecord
 end
 ```
 
-### SECURITY ALERT
+### Security Considerations
 
 As the name implies, "reduced security operations" require that the security of the data in the column be lower than [Enquo's default security properties](https://enquo.org/about/threat-models#snapshot-security).
-In particular, extra data is stored in the value which can be used by an attacker to:
+Specifically, extra data needs to be stored in the value to enable indexing and ordering.
+This extra data can be used by an attacker to:
 
 * Identify all rows which have the same value for the column (although not what that value actually *is*); and
 
@@ -174,22 +195,14 @@ class User < ApplicationRecord
 end
 ```
 
+More accurate indications of the disk space requirements for the supported data types can be found in [the description of each data type](https://github.com/enquo/pg_enquo/tree/main/doc/data_types).
 
-# Future Developments
 
-These are some of the things that are definitely planned to be added to ActiveEnquo in the nearish future.
-
-* **Support for key rotation**: this isn't tricky, just a bit fiddly.
-  Encrypted values have a "key ID" associated with them, so we can find which values are out-of-date, but multiple keys need to useable for decryption.
-  Closely related to this is **support for renaming columns**, which is problematic because keys are derived based on the column name.
-  Again, key IDs (to find values encrypted with the previous column name) and the ability to attempt decryption with a key based on the previous column name sorts this out.
-
-* **Strings**: a great deal of the sensitive data that needs protecting is in the form of strings.
-  Querying strings is somewhat more involved than numeric data, and so the means of encrypting strings such that they're queryable *and* secure are more complex.
-  Enquo cannot be a really useful library for supporting encrypted querying until at least some common string query operations are supported, though, so it is important that this be implemented.
+# Future Developments
 
-* **Other data types**: while you can go a long way with strings and bigints, part of the power of SQL is the sheer variety of interesting data types it has, and the variety of things you can do with them.
-  So more integer types, floats, decimals, dates, times, timestamps, and more, are all on the cards for future development.
+ActiveEnquo is far from finished.
+Many more features are coming in the future.
+See [the Enquo project roadmap](https://enquo.org/roadmap) for details of what we're still intending to implement.
 
 
 # Contributing

data/lib/active_enquo.rb

@@ -29,6 +29,7 @@ module ActiveEnquo
 				if t.is_a?(::ActiveEnquo::Type)
 					relation = self.class.arel_table.name
 					value = @attributes.fetch_value(attr_name, &block)
+					return nil if value.nil?
 					field = ::ActiveEnquo.root.field(relation, attr_name)
 					begin
 						t.decrypt(value, @attributes.fetch_value(@primary_key).to_s, field)
@@ -81,6 +82,20 @@ module ActiveEnquo
 				end
 			end
 		end
+
+		module TableDefinitionExtension
+			def enquo_bigint(name, **options)
+				column(name, :enquo_bigint, **options)
+			end
+
+			def enquo_date(name, **options)
+				column(name, :enquo_date, **options)
+			end
+
+			def enquo_text(name, **options)
+				column(name, :enquo_text, **options)
+			end
+		end
 	end
 
 	module Postgres
@@ -151,17 +166,31 @@ module ActiveEnquo
 			end
 		end
 	end
+
+	if defined?(Rails::Railtie)
+		class Initializer < Rails::Railtie
+			initializer "active_enquo.root_key" do |app|
+				if app
+					if root_key = app.credentials.active_enquo.root_key
+						ActiveEnquo.root_key = Enquo::RootKey::Static.new(root_key)
+					else
+						Rails.warn "Could not initialize ActiveEnquo, as no active_enquo.root_key credential was found for this environment"
+					end
+				end
+			end
+		end
+	end
 end
 
 ActiveSupport.on_load(:active_record) do
 	::ActiveRecord::Base.send :include, ActiveEnquo::ActiveRecord::ModelExtension
 
+	::ActiveRecord::ConnectionAdapters::Table.include ActiveEnquo::ActiveRecord::TableDefinitionExtension
+	::ActiveRecord::ConnectionAdapters::TableDefinition.include ActiveEnquo::ActiveRecord::TableDefinitionExtension
+
 	::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.prepend ActiveEnquo::Postgres::ConnectionAdapter
-#	::ActiveRecord::Type.register(:enquo_bigint, ActiveEnquo::Type::Bigint, adapter: :postgresql)
 
-	unless ActiveRecord::VERSION::MAJOR == 7
-		::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::NATIVE_DATABASE_TYPES[:enquo_bigint] = {}
-		::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::NATIVE_DATABASE_TYPES[:enquo_date] = {}
-		::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::NATIVE_DATABASE_TYPES[:enquo_text] = {}
-	end
+	::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::NATIVE_DATABASE_TYPES[:enquo_bigint] = { name: "enquo_bigint" }
+	::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::NATIVE_DATABASE_TYPES[:enquo_date]   = { name: "enquo_date" }
+	::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::NATIVE_DATABASE_TYPES[:enquo_text]   = { name: "enquo_text" }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_enquo
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Palmer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-10-07 00:00:00.000000000 Z
+date: 2022-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: enquo-core