lockbox 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4e87cf5f769166cd6cf534608a6877e5cd9f11931441307d9eca11a3d2c4d18
-  data.tar.gz: c52a2bded1142c80918f79de4317ec948c576c1168fd699dac0f69c7d2ca9b47
+  metadata.gz: af9a23ecd7c1ea6ea696daf88d7830e06dbb9972caa202fc23b214942a84e189
+  data.tar.gz: 5636aeb7e1f37a1b55055bd8bf50d5c0270a4abe9f2d13e62971f1257c9fe9f5
 SHA512:
-  metadata.gz: 9a92f516956fe3d4feb26cc338bf25a5048fc46916bc4c4722a12028b73697e467ceae118733f1dce778a1585e3a4e97fbf9073c3c80fa7d5340d1e0676cb02c
-  data.tar.gz: 60684645d7645b1b66a66a9b5393db04eb690095fc8bfbe16de50e8770225afe46e2236045cf4c0985a9e7b0e86aa7da16294804e0e6cebe2325193761d9965e
+  metadata.gz: 9d1bc707fbbe82a147920f8fc0c1f716620e9ae15fdf3d2583240b1bf32141395b401203d9851da009b7e43a896c25c93dff45ead2149289d58c89233685df37
+  data.tar.gz: cff72e261e485a1fbacd270cb7b5d71044d63ac7982cd1b364801578e7b8a51cdf7650ef841780bc3337ff5663b2632ccf878f6b5b00879a6768072416185bc7

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.2.1
+
+- Added support for types
+- Added support for serialized attributes
+- Added support for padding
+- Added `encode` option for binary columns
+
 ## 0.2.0
 
 - Added `encrypts` method for database fields

data/README.md

@@ -1,6 +1,6 @@
 # Lockbox
 
-:lock: Modern encryption for Rails
+:package: Modern encryption for Rails
 
 - Uses state-of-the-art algorithms
 - Works with database fields, files, and strings
@@ -8,7 +8,7 @@
 - Requires you to only manage a single encryption key
 - Makes migrating existing data and key rotation easy
 
-Check out [this post](https://ankane.org/modern-encryption-rails) for more info on its design, and [this post](https://ankane.org/sensitive-data-rails) for more info on securing sensitive data with Rails
+Learn [the principles behind it](https://ankane.org/modern-encryption-rails), [how to secure emails](https://ankane.org/securing-user-emails-lockbox), and [how to secure sensitive data in Rails](https://ankane.org/sensitive-data-rails)
 
 [![Build Status](https://travis-ci.org/ankane/lockbox.svg?branch=master)](https://travis-ci.org/ankane/lockbox)
 
@@ -72,6 +72,38 @@ User.create!(email: "hi@example.org")
 
 If you need to query encrypted fields, check out [Blind Index](https://github.com/ankane/blind_index).
 
+### Types
+
+Specify the type of a field with:
+
+```ruby
+class User < ApplicationRecord
+  encrypts :born_on, type: :date
+  encrypts :signed_at, type: :datetime
+  encrypts :active, type: :boolean
+  encrypts :salary, type: :integer
+  encrypts :latitude, type: :float
+  encrypts :video, type: :binary
+  encrypts :properties, type: :json
+  encrypts :settings, type: :hash
+end
+```
+
+**Note:** Always use a `text` or `binary` column in migrations, regardless of the type
+
+Lockbox automatically works with serialized fields for maximum compatibility with existing code and libraries.
+
+```ruby
+class User < ApplicationRecord
+  serialize :properties, JSON
+  encrypts :properties
+end
+```
+
+### Validations
+
+Validations work as expected with the exception of uniqueness. Uniqueness validations require a [blind index](https://github.com/ankane/blind_index).
+
 ## Files
 
 ### Active Storage
@@ -364,7 +396,7 @@ end
 
 Make sure `decryption_key` is `nil` on servers that shouldn’t decrypt.
 
-This uses X25519 for key exchange and XSalsa20-Poly1305 for encryption.
+This uses X25519 for key exchange and XSalsa20 for encryption.
 
 ## Key Separation
 
@@ -402,6 +434,36 @@ end
 
 **Note:** KMS Encrypted’s key rotation does not know to rotate encrypted files, so avoid calling `record.rotate_kms_key!` on models with file uploads for now.
 
+## Padding
+
+Add padding to conceal the exact length of messages.
+
+```ruby
+Lockbox.new(padding: true)
+```
+
+The block size for padding is 16 bytes by default. Change this with:
+
+```ruby
+Lockbox.new(padding: 32) # bytes
+```
+
+## Reference
+
+Set default options in an initializer with:
+
+```ruby
+Lockbox.default_options = {algorithm: "xsalsa20"}
+```
+
+For database fields, encrypted data is encoded in Base64. If you use `binary` columns instead of `text` columns, set:
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email, encode: false
+end
+```
+
 ## Compatibility
 
 It’s easy to read encrypted data in another language if needed.

data/lib/lockbox.rb

@@ -22,6 +22,7 @@ end
 class Lockbox
   class Error < StandardError; end
   class DecryptionError < Error; end
+  class PaddingError < Error; end
 
   class << self
     attr_accessor :default_options
@@ -139,6 +140,55 @@ class Lockbox
     str.unpack("H*").first
   end
 
+  PAD_FIRST_BYTE = "\x80".b
+  PAD_ZERO_BYTE = "\x00".b
+
+  # ISO/IEC 7816-4
+  # same as Libsodium
+  # https://libsodium.gitbook.io/doc/padding
+  # apply prior to encryption
+  # note: current implementation does not
+  # try to minimize side channels
+  def self.pad(str, size: 16)
+    raise ArgumentError, "Invalid size" if size < 1
+
+    str = str.dup.force_encoding(Encoding::BINARY)
+
+    pad_length = size - 1
+    pad_length -= str.bytesize % size
+
+    str << PAD_FIRST_BYTE
+    pad_length.times do
+      str << PAD_ZERO_BYTE
+    end
+
+    str
+  end
+
+  # note: current implementation does not
+  # try to minimize side channels
+  def self.unpad(str, size: 16)
+    raise ArgumentError, "Invalid size" if size < 1
+
+    if str.encoding != Encoding::BINARY
+      str = str.dup.force_encoding(Encoding::BINARY)
+    end
+
+    i = 1
+    while i <= size
+      case str[-i]
+      when PAD_ZERO_BYTE
+        i += 1
+      when PAD_FIRST_BYTE
+        return str[0..-(i + 1)]
+      else
+        break
+      end
+    end
+
+    raise Lockbox::PaddingError, "Invalid padding"
+  end
+
   private
 
   def check_string(str, name)

data/lib/lockbox/box.rb

@@ -2,7 +2,7 @@ require "securerandom"
 
 class Lockbox
   class Box
-    def initialize(key: nil, algorithm: nil, encryption_key: nil, decryption_key: nil)
+    def initialize(key: nil, algorithm: nil, encryption_key: nil, decryption_key: nil, padding: false)
       raise ArgumentError, "Cannot pass both key and public/private key" if key && (encryption_key || decryption_key)
 
       key = Lockbox::Utils.decode_key(key) if key
@@ -34,9 +34,11 @@ class Lockbox
       end
 
       @algorithm = algorithm
+      @padding = padding == true ? 16 : padding
     end
 
     def encrypt(message, associated_data: nil)
+      message = Lockbox.pad(message, size: @padding) if @padding
       case @algorithm
       when "hybrid"
         raise ArgumentError, "No public key set" unless @encryption_box
@@ -54,19 +56,22 @@ class Lockbox
     end
 
     def decrypt(ciphertext, associated_data: nil)
-      case @algorithm
-      when "hybrid"
-        raise ArgumentError, "No private key set" unless @decryption_box
-        raise ArgumentError, "Associated data not supported with this algorithm" if associated_data
-        nonce, ciphertext = extract_nonce(@decryption_box, ciphertext)
-        @decryption_box.decrypt(nonce, ciphertext)
-      when "xsalsa20"
-        nonce, ciphertext = extract_nonce(@box, ciphertext)
-        @box.decrypt(nonce, ciphertext)
-      else
-        nonce, ciphertext = extract_nonce(@box, ciphertext)
-        @box.decrypt(nonce, ciphertext, associated_data)
-      end
+      message =
+        case @algorithm
+        when "hybrid"
+          raise ArgumentError, "No private key set" unless @decryption_box
+          raise ArgumentError, "Associated data not supported with this algorithm" if associated_data
+          nonce, ciphertext = extract_nonce(@decryption_box, ciphertext)
+          @decryption_box.decrypt(nonce, ciphertext)
+        when "xsalsa20"
+          nonce, ciphertext = extract_nonce(@box, ciphertext)
+          @box.decrypt(nonce, ciphertext)
+        else
+          nonce, ciphertext = extract_nonce(@box, ciphertext)
+          @box.decrypt(nonce, ciphertext, associated_data)
+        end
+      message = Lockbox.unpad(message, size: @padding) if @padding
+      message
     end
 
     # protect key for xchacha20 and hybrid

data/lib/lockbox/model.rb

@@ -31,7 +31,37 @@ class Lockbox
       end
     end
 
-    def encrypts(*attributes, **options)
+    def encrypts(*attributes, encode: true, **options)
+      # support objects
+      # case options[:type]
+      # when Date
+      #   options[:type] = :date
+      # when Time
+      #   options[:type] = :datetime
+      # when JSON
+      #   options[:type] = :json
+      # when Hash
+      #   options[:type] = :hash
+      # when String
+      #   options[:type] = :string
+      # when Integer
+      #   options[:type] = :integer
+      # when Float
+      #   options[:type] = :float
+      # end
+
+      raise ArgumentError, "Unknown type: #{options[:type]}" unless [nil, :string, :boolean, :date, :datetime, :integer, :float, :binary, :json, :hash].include?(options[:type])
+
+      attribute_type =
+        case options[:type]
+        when nil, :json, :hash
+          :string
+        when :integer
+          ActiveModel::Type::Integer.new(limit: 8)
+        else
+          options[:type]
+        end
+
       attributes.each do |name|
         # add default options
         encrypted_attribute = "#{name}_ciphertext"
@@ -71,7 +101,7 @@ class Lockbox
           end
 
           raise "Duplicate encrypted attribute: #{original_name}" if lockbox_attributes[original_name]
-          @lockbox_attributes[original_name] = options
+          @lockbox_attributes[original_name] = options.merge(encode: encode)
 
           if @lockbox_attributes.size == 1
             def serializable_hash(options = nil)
@@ -89,11 +119,63 @@ class Lockbox
                 end
               "#<#{self.class} #{inspection.join(", ")}>"
             end
+
+            # needed for in-place modifications
+            # assigned attributes are encrypted on assignment
+            # and then again here
+            before_save do
+              self.class.lockbox_attributes.each do |_, lockbox_attribute|
+                attribute = lockbox_attribute[:attribute]
+
+                if changes.include?(attribute) && self.class.attribute_types[attribute].is_a?(ActiveRecord::Type::Serialized)
+                  send("#{attribute}=", send(attribute))
+                end
+              end
+            end
           end
 
-          attribute name, :string
+          serialize name, JSON if options[:type] == :json
+          serialize name, Hash if options[:type] == :hash
+
+          attribute name, attribute_type
 
           define_method("#{name}=") do |message|
+            original_message = message
+
+            unless message.nil?
+              case options[:type]
+              when :boolean
+                message = ActiveRecord::Type::Boolean.new.serialize(message)
+                message = nil if message == "" # for Active Record < 5.2
+                message = message ? "t" : "f" unless message.nil?
+              when :date
+                message = ActiveRecord::Type::Date.new.serialize(message)
+                # strftime should be more stable than to_s(:db)
+                message = message.strftime("%Y-%m-%d") unless message.nil?
+              when :datetime
+                message = ActiveRecord::Type::DateTime.new.serialize(message)
+                message = nil unless message.respond_to?(:iso8601) # for Active Record < 5.2
+                message = message.iso8601(9) unless message.nil?
+              when :integer
+                message = ActiveRecord::Type::Integer.new(limit: 8).serialize(message)
+                message = 0 if message.nil?
+                # signed 64-bit integer, big endian
+                message = [message].pack("q>")
+              when :float
+                message = ActiveRecord::Type::Float.new.serialize(message)
+                # double precision, big endian
+                message = [message].pack("G") unless message.nil?
+              when :string, :binary
+                # do nothing
+                # encrypt will convert to binary
+              else
+                type = self.class.attribute_types[name.to_s]
+                if type.is_a?(ActiveRecord::Type::Serialized)
+                  message = type.serialize(message)
+                end
+              end
+            end
+
             # decrypt first for dirty tracking
             # don't raise error if can't decrypt previous
             begin
@@ -103,28 +185,54 @@ class Lockbox
             end
 
             ciphertext =
-              if message.nil? || message == ""
+              if message.nil? || (message == "" && !options[:padding])
                 message
               else
                 self.class.send(class_method_name, message, context: self)
               end
             send("#{encrypted_attribute}=", ciphertext)
 
-            super(message)
+            super(original_message)
           end
 
           define_method(name) do
             message = super()
+
             unless message
               ciphertext = send(encrypted_attribute)
               message =
-                if ciphertext.nil? || ciphertext == ""
+                if ciphertext.nil? || (ciphertext == "" && !options[:padding])
                   ciphertext
                 else
-                  decoded = Base64.decode64(ciphertext)
-                  Lockbox::Utils.build_box(self, options, self.class.table_name, encrypted_attribute).decrypt(decoded)
+                  ciphertext = Base64.decode64(ciphertext) if encode
+                  Lockbox::Utils.build_box(self, options, self.class.table_name, encrypted_attribute).decrypt(ciphertext)
                 end
 
+              unless message.nil?
+                case options[:type]
+                when :boolean
+                  message = message == "t"
+                when :date
+                  message = ActiveRecord::Type::Date.new.deserialize(message)
+                when :datetime
+                  message = ActiveRecord::Type::DateTime.new.deserialize(message)
+                when :integer
+                  message = ActiveRecord::Type::Integer.new(limit: 8).deserialize(message.unpack("q>").first)
+                when :float
+                  message = ActiveRecord::Type::Float.new.deserialize(message.unpack("G").first)
+                when :string
+                  message = message.encode(Encoding::UTF_8)
+                when :binary
+                  # do nothing
+                  # decrypt returns binary string
+                else
+                  type = self.class.attribute_types[name.to_s]
+                  if type.is_a?(ActiveRecord::Type::Serialized)
+                    message = type.deserialize(message)
+                  end
+                end
+              end
+
               # set previous attribute on first decrypt
               @attributes[name.to_s].instance_variable_set("@value_before_type_cast", message)
 
@@ -135,12 +243,15 @@ class Lockbox
                 raw_write_attribute(name, message)
               end
             end
+
             message
           end
 
           # for fixtures
           define_singleton_method class_method_name do |message, **opts|
-            Base64.strict_encode64(Lockbox::Utils.build_box(opts[:context], options, table_name, encrypted_attribute).encrypt(message))
+            ciphertext = Lockbox::Utils.build_box(opts[:context], options, table_name, encrypted_attribute).encrypt(message)
+            ciphertext = Base64.strict_encode64(ciphertext) if encode
+            ciphertext
           end
         end
       end

data/lib/lockbox/utils.rb

@@ -1,7 +1,7 @@
 class Lockbox
   class Utils
     def self.build_box(context, options, table, attribute)
-      options = options.except(:attribute, :encrypted_attribute, :migrating, :attached)
+      options = options.except(:attribute, :encrypted_attribute, :migrating, :attached, :type, :encode)
       options.each do |k, v|
         if v.is_a?(Proc)
           options[k] = context.instance_exec(&v) if v.respond_to?(:call)

data/lib/lockbox/version.rb

@@ -1,3 +1,3 @@
 class Lockbox
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lockbox
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-08 00:00:00.000000000 Z
+date: 2019-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
   requirement: !ruby/object:Gem::Requirement