lockbox 0.4.6 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fb82c6baf0c56ae7f051c8363f7cb52554ebab8180b891d4aa25caf7505cec3
-  data.tar.gz: 64b6bda4259cc3fddd7e5635333b0b7c4a6680c4ff2da31bba735603ea50b010
+  metadata.gz: 3f8c447dd90537203a1a3038c347c10de0e48f5b29795b382a2a77019e6e5764
+  data.tar.gz: 9133e9eb0c2132b7c77c39f8c24a3c27ea9b3cbb1d3d82f7f069b2db9992198f
 SHA512:
-  metadata.gz: e1953d9159c2cb1f1ec55436d925738777ea0b78afedcb32864280f7772d1d9e12a48f65c69385fd6bcdab166668049b3889f1e17e3b316c696705bcb98650dd
-  data.tar.gz: a3559c399a385949526137eed03b73c38baae424bed3b597c89f287222e6e18fd2c5665b2cbba6b20dad71bf680f0840ee2753a68befd3af40fdb522e45e4088
+  metadata.gz: 4396ee4ead0de0592e7a3574b563f98d58f0402198dd8662cbdc374cc5f8a39e629f6397414b498456c665e8a635518db3a532056ecd42154206fde4ab938e5c
+  data.tar.gz: 6057ea6f43db261580a0ee0ae13f1303251d2ee8ef2b1bcdba8399b6a858dca1fdf6c84e25f5da85a059a6d260be7094969e2118ff11a8c1d2565617c48f74cd

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.4.7 (2020-08-18)
+
+- Added `lockbox_options` method to encrypted CarrierWave uploaders
+- Improved attribute loading when no decryption key specified
+
 ## 0.4.6 (2020-07-02)
 
 - Added support for `update_column` and `update_columns`

data/README.md

@@ -190,6 +190,8 @@ end
 
 ## Action Text
 
+**Note:** Action Text uses direct uploads for files, which cannot be encrypted with application-level encryption like Lockbox. This only encrypts the database field.
+
 Create a migration with:
 
 ```ruby
@@ -264,8 +266,9 @@ end
 
 There are a few limitations to be aware of:
 
-- Metadata like image width and height are not extracted when encrypted
-- Direct uploads cannot be encrypted
+- Variants and previews aren’t supported when encrypted
+- Metadata like image width and height aren’t extracted when encrypted
+- Direct uploads can’t be encrypted with application-level encryption like Lockbox, but can use server-side encryption
 
 To serve encrypted files, use a controller action.
 
@@ -508,6 +511,24 @@ Lockbox.rotate(User, attributes: [:email])
 
 Once all records are rotated, you can remove `previous_versions` from the model.
 
+### Action Text
+
+Update your initializer:
+
+```ruby
+Lockbox.encrypts_action_text_body(previous_versions: [{key: previous_key}])
+```
+
+Use `master_key` instead of `key` if passing the master key.
+
+To rotate existing records, use:
+
+```ruby
+Lockbox.rotate(ActionText::RichText, attributes: [:body])
+```
+
+Once all records are rotated, you can remove `previous_versions` from the initializer.
+
 ### Active Storage
 
 Update your model:
@@ -550,6 +571,14 @@ User.find_each do |user|
 end
 ```
 
+For multiple files, use:
+
+```ruby
+User.find_each do |user|
+  user.licenses.map(&:rotate_encryption!)
+end
+```
+
 Once all files are rotated, you can remove `previous_versions` from the model.
 
 ### Local Files & Strings
@@ -734,12 +763,32 @@ end
 
 You can use a key management service to manage your keys with [KMS Encrypted](https://github.com/ankane/kms_encrypted).
 
+For Active Record and Mongoid, use:
+
 ```ruby
 class User < ApplicationRecord
   encrypts :email, key: :kms_key
 end
 ```
 
+For Action Text, use:
+
+```ruby
+ActiveSupport.on_load(:action_text_rich_text) do
+  ActionText::RichText.has_kms_key
+end
+
+Lockbox.encrypts_action_text_body(key: :kms_key)
+```
+
+For Active Storage, use:
+
+```ruby
+class User < ApplicationRecord
+  encrypts_attached :license, key: :kms_key
+end
+```
+
 For CarrierWave, use:
 
 ```ruby
@@ -772,7 +821,7 @@ lockbox.encrypt("clear").bytesize     # 44
 lockbox.encrypt("consider").bytesize  # 44
 ```
 
-The block size for padding is 16 bytes by default. If we have a status larger than 15 bytes, it will have a different length than the others.
+The block size for padding is 16 bytes by default. Lockbox uses [ISO/IEC 7816-4](https://en.wikipedia.org/wiki/Padding_(cryptography)#ISO/IEC_7816-4) padding, which uses at least one byte, so if we have a status larger than 15 bytes, it will have a different length than the others.
 
 ```ruby
 box.encrypt("length15status!").bytesize   # 44
@@ -785,9 +834,25 @@ Change the block size with:
 Lockbox.new(padding: 32) # bytes
 ```
 
+## Associated Data
+
+You can pass extra context during encryption to make sure encrypted data isn’t moved to a different context.
+
+```ruby
+lockbox = Lockbox.new(key: key)
+ciphertext = lockbox.encrypt(message, associated_data: "somecontext")
+```
+
+Without the same context, decryption will fail.
+
+```ruby
+lockbox.decrypt(ciphertext, associated_data: "somecontext")  # success
+lockbox.decrypt(ciphertext, associated_data: "othercontext") # fails
+```
+
 ## Binary Columns
 
-You can use `binary` columns for the ciphertext instead of `text` columns to save space.
+You can use `binary` columns for the ciphertext instead of `text` columns.
 
 ```ruby
 class AddEmailCiphertextToUsers < ActiveRecord::Migration[6.0]
@@ -797,7 +862,7 @@ class AddEmailCiphertextToUsers < ActiveRecord::Migration[6.0]
 end
 ```
 
-You should disable Base64 encoding if you do this.
+Disable Base64 encoding to save space.
 
 ```ruby
 class User < ApplicationRecord

data/lib/lockbox/active_storage_extensions.rb

@@ -1,7 +1,22 @@
-# ideally encrypt and decrypt would happen at the blob/service level
-# however, there isn't really a great place to define encryption settings there
-# instead, we encrypt and decrypt at the attachment level,
-# and we define encryption settings at the model level
+# Ideally encryption and decryption would happen at the blob/service level.
+# However, Active Storage < 6.1 only supports a single service (per environment).
+# This means all attachments need to be encrypted or none of them,
+# which is often not practical.
+#
+# Active Storage 6.1 adds support for multiple services, which changes this.
+# We could have a Lockbox service:
+#
+# lockbox:
+#   service: Lockbox
+#   backend: local    # delegate to another service, like mirror service
+#   key:     ...      # Lockbox options
+#
+# However, the checksum is computed *and stored on the blob*
+# before the file is passed to the service.
+# We don't want the MD5 checksum of the plaintext stored in the database.
+#
+# Instead, we encrypt and decrypt at the attachment level,
+# and we define encryption settings at the model level.
 module Lockbox
   module ActiveStorageExtensions
     module Attached
@@ -95,6 +110,16 @@ module Lockbox
         result
       end
 
+      def variant(*args)
+        raise Lockbox::Error, "Variant not supported for encrypted files" if Utils.encrypted_options(record, name)
+        super
+      end
+
+      def preview(*args)
+        raise Lockbox::Error, "Preview not supported for encrypted files" if Utils.encrypted_options(record, name)
+        super
+      end
+
       if ActiveStorage::VERSION::MAJOR >= 6
         def open(**options)
           blob.open(**options) do |file|

data/lib/lockbox/carrier_wave_extensions.rb

@@ -2,9 +2,22 @@ module Lockbox
   module CarrierWaveExtensions
     def encrypt(**options)
       class_eval do
+        # uses same hook as process (before cache)
+        # processing can be disabled, so better to keep separate
         before :cache, :encrypt
 
+        define_singleton_method :lockbox_options do
+          options
+        end
+
         def encrypt(file)
+          # safety check
+          # see CarrierWave::Uploader::Cache#cache!
+          raise Lockbox::Error, "Expected files to be equal. Please report an issue." unless file && @file && file == @file
+
+          # processors in CarrierWave move updated file to current_path
+          # however, this causes versions to use the processed file
+          # we only want to change the file for the current version
           @file = CarrierWave::SanitizedFile.new(lockbox_notify("encrypt_file") { lockbox.encrypt_io(file) })
         end
 
@@ -14,6 +27,7 @@ module Lockbox
           lockbox_notify("decrypt_file") { lockbox.decrypt(r) } if r
         end
 
+        # use size of plaintext since read and content type use plaintext
         def size
           read.bytesize
         end
@@ -23,6 +37,7 @@ module Lockbox
           MimeMagic.by_magic(read).try(:type) || "invalid/invalid"
         end
 
+        # disable processing since already processed
         def rotate_encryption!
           io = Lockbox::IO.new(read)
           io.original_filename = file.filename
@@ -46,6 +61,8 @@ module Lockbox
           end
         end
 
+        # for mounted uploaders, use mounted name
+        # for others, use uploader name
         def lockbox_name
           if mounted_as
             mounted_as.to_s
@@ -58,6 +75,8 @@ module Lockbox
           end
         end
 
+        # Active Support notifications so it's easier
+        # to see when files are encrypted and decrypted
         def lockbox_notify(type)
           if defined?(ActiveSupport::Notifications)
             name = lockbox_name

data/lib/lockbox/migrator.rb

@@ -116,6 +116,13 @@ module Lockbox
       end
     end
 
+    # there's a small chance for this process to read data,
+    # another process to update the data, and
+    # this process to write the now stale data
+    # this time window can be reduced with smaller batch sizes
+    # locking individual records could eliminate this
+    # one option is: relation.in_batches { |batch| batch.lock }
+    # which runs SELECT ... FOR UPDATE in Postgres
     def migrate_records(records, fields:, blind_indexes:, restart:, rotate:)
       # do computation outside of transaction
       # especially expensive blind index computation

data/lib/lockbox/model.rb

@@ -87,6 +87,9 @@ module Lockbox
                 # essentially a no-op if already loaded
                 # an exception is thrown if decryption fails
                 self.class.lockbox_attributes.each do |_, lockbox_attribute|
+                  # don't try to decrypt if no decryption key given
+                  next if lockbox_attribute[:algorithm] == "hybrid" && lockbox_attribute[:decryption_key].nil?
+
                   # it is possible that the encrypted attribute is not loaded, eg.
                   # if the record was fetched partially (`User.select(:id).first`).
                   # accessing a not loaded attribute raises an `ActiveModel::MissingAttributeError`.
@@ -263,12 +266,13 @@ module Lockbox
           define_method("#{name}=") do |message|
             # decrypt first for dirty tracking
             # don't raise error if can't decrypt previous
-            begin
-              send(name)
-            rescue Lockbox::DecryptionError
-              # this is expected for hybrid cryptography
-              warn "[lockbox] Decrypting previous value failed" unless options[:algorithm] == "hybrid"
-              nil
+            # don't try to decrypt if no decryption key given
+            unless options[:algorithm] == "hybrid" && options[:decryption_key].nil?
+              begin
+                send(name)
+              rescue Lockbox::DecryptionError
+                warn "[lockbox] Decrypting previous value failed"
+              end
             end
 
             send("lockbox_direct_#{name}=", message)

data/lib/lockbox/utils.rb

@@ -16,14 +16,14 @@ module Lockbox
       end
 
       unless options[:key] || options[:encryption_key] || options[:decryption_key]
-        options[:key] = Lockbox.attribute_key(table: table, attribute: attribute, master_key: options.delete(:master_key))
+        options[:key] = Lockbox.attribute_key(table: table, attribute: attribute, master_key: options.delete(:master_key), encode: false)
       end
 
       if options[:previous_versions].is_a?(Array)
         options[:previous_versions] = options[:previous_versions].dup
         options[:previous_versions].each_with_index do |version, i|
           if !(version[:key] || version[:encryption_key] || version[:decryption_key]) && version[:master_key]
-            options[:previous_versions][i] = version.merge(key: Lockbox.attribute_key(table: table, attribute: attribute, master_key: version.delete(:master_key)))
+            options[:previous_versions][i] = version.merge(key: Lockbox.attribute_key(table: table, attribute: attribute, master_key: version.delete(:master_key), encode: false))
           end
         end
       end

data/lib/lockbox/version.rb

@@ -1,3 +1,3 @@
 module Lockbox
-  VERSION = "0.4.6"
+  VERSION = "0.4.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lockbox
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.4.7
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-03 00:00:00.000000000 Z
+date: 2020-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler