lockbox 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa1a57ca8235a58fd8d638cab1ec624888e72b79f8a3f279588bb358ea8f6cb0
-  data.tar.gz: ffe1edd74efb5e8bf121b73816edd6b9209b8a217590816a2791adf6d1ad3dad
+  metadata.gz: e4dcdb1c1115e0712d5d65dd8302c3d575a74a5456dd245692970d080d221fa0
+  data.tar.gz: 2278b9fe032f0159525a48a9a9c694c28a80bcbac371039a97729e6ec61087d7
 SHA512:
-  metadata.gz: 80b49150b2d01aafceaddf9bd6c47b6412ee4cfb5361ff2f7f11633a65847d1f09dd7377794ef68b58c87f0f29210fe981d4b08a981840b51a553d7fb18ccc66
-  data.tar.gz: b3e8ae7d2395cc13903d80da1e8f8f3f2f0416a9f9ec8b1fa29b6b6eb155f97724f0effd1a7afd7c5162421b1be35494b5a7d4a6a25344de202a1bab0ef15305
+  metadata.gz: 8afe130b6c4231667ea26f1ece4a25e4a577a535ec4930a5f85ac2b53b7b508fe77ec9e4b1720f1aab3f1fe513b03576646d8b24cf27bee3a6c5626c9484c35e
+  data.tar.gz: 6662d25470d89b327b2cddf45d9467cd7d2bd8e3e8664140a71c7ea4cb10f13a156d21c01c17b26f0c2dca928f6f3f0010403ba96e77349442ab185def552d10

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.1.1
+
+- Added support for hybrid cryptography
+- Added support for database fields
+
 ## 0.1.0
 
 - First release

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Andrew Kane
+Copyright (c) 2018-2019 Andrew Kane
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -2,9 +2,13 @@
 
 :lock: File encryption for Ruby and Rails
 
-Supports Active Storage and CarrierWave
+- Supports Active Storage and CarrierWave
+- Uses AES-GCM by default for [authenticated encryption](https://tonyarcieri.com/all-the-crypto-code-youve-ever-written-is-probably-broken)
+- Makes key rotation easy
 
-Uses AES-GCM by default for [authenticated encryption](https://tonyarcieri.com/all-the-crypto-code-youve-ever-written-is-probably-broken)
+Check out [this post](https://ankane.org/sensitive-data-rails) for more info on securing sensitive data with Rails
+
+[![Build Status](https://travis-ci.org/ankane/lockbox.svg?branch=master)](https://travis-ci.org/ankane/lockbox)
 
 ## Installation
 
@@ -16,13 +20,13 @@ gem 'lockbox'
 
 ## Key Generation
 
-Generate an encryption key.
+Generate an encryption key
 
 ```ruby
 SecureRandom.hex(32)
 ```
 
-Store the key with your other secrets (typically Rails secrets or an environment variable).
+Store the key with your other secrets. This is typically Rails credentials or an environment variable ([dotenv](https://github.com/bkeepers/dotenv) is great for this). Be sure to use different keys in development and production. Keys don’t need to be hex-encoded, but it’s often easier to store them this way.
 
 Alternatively, you can use a [key management service](#key-management) to manage your keys.
 
@@ -37,13 +41,13 @@ box = Lockbox.new(key: key)
 Encrypt
 
 ```ruby
-box.encrypt(File.binread("license.jpg"))
+ciphertext = box.encrypt(File.binread("license.jpg"))
 ```
 
 Decrypt
 
 ```ruby
-box.decrypt(File.binread("license.jpg.enc"))
+box.decrypt(ciphertext)
 ```
 
 ## Active Storage
@@ -135,11 +139,11 @@ user.license.rotate_encryption!
 
 ### AES-GCM
 
-The default algorithm is AES-GCM with a 256-bit key. Rotate the key every 2 billion files to minimize the chance of a [nonce collision](https://www.cryptologie.net/article/402/is-symmetric-security-solved/).
+The default algorithm is AES-GCM with a 256-bit key. Rotate the key every 2 billion files to minimize the chance of a [nonce collision](https://www.cryptologie.net/article/402/is-symmetric-security-solved/), which will leak the key.
 
 ### XChaCha20
 
-[Install Libsodium](https://github.com/crypto-rb/rbnacl/wiki/Installing-libsodium) and add [rbnacl](https://github.com/crypto-rb/rbnacl) to your application’s Gemfile:
+[Install Libsodium](https://github.com/crypto-rb/rbnacl/wiki/Installing-libsodium) >= 1.0.12 and add [rbnacl](https://github.com/crypto-rb/rbnacl) to your application’s Gemfile:
 
 ```ruby
 gem 'rbnacl'
@@ -170,6 +174,43 @@ Lockbox.default_options = {algorithm: "xchacha20"}
 
 You can also pass an algorithm to `previous_versions` for key rotation.
 
+## Hybrid Cryptography
+
+[Hybrid cryptography](https://en.wikipedia.org/wiki/Hybrid_cryptosystem) allows servers to encrypt data without being able to decrypt it.
+
+[Install Libsodium](https://github.com/crypto-rb/rbnacl/wiki/Installing-libsodium) and add [rbnacl](https://github.com/crypto-rb/rbnacl) to your application’s Gemfile:
+
+```ruby
+gem 'rbnacl'
+```
+
+Generate a key pair with:
+
+```ruby
+Lockbox.generate_key_pair
+```
+
+Store the keys with your other secrets. Then use:
+
+```ruby
+# files
+box = Lockbox.new(algorithm: "hybrid", encryption_key: encryption_key, decryption_key: decryption_key)
+
+# Active Storage
+class User < ApplicationRecord
+  attached_encrypted :license, algorithm: "hybrid", encryption_key: encryption_key, decryption_key: decryption_key
+end
+
+# CarrierWave
+class LicenseUploader < CarrierWave::Uploader::Base
+  encrypt algorithm: "hybrid", encryption_key: encryption_key, decryption_key: decryption_key
+end
+```
+
+Make sure `decryption_key` is `nil` on servers that shouldn’t decrypt.
+
+This uses X25519 for key exchange and XSalsa20-Poly1305 for encryption.
+
 ## Key Management
 
 You can use a key management service to manage your keys with [KMS Encrypted](https://github.com/ankane/kms_encrypted).
@@ -192,6 +233,65 @@ 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.
 
+## Compatibility
+
+It’s easy to read encrypted files in another language if needed.
+
+Here are [some examples](docs/Compatibility.md).
+
+The format for AES-GCM is:
+
+- nonce (IV) - 12 bytes
+- ciphertext - variable length
+- authentication tag - 16 bytes
+
+For XChaCha20, use the appropriate [Libsodium library](https://libsodium.gitbook.io/doc/bindings_for_other_languages).
+
+## Database Fields
+
+Lockbox can also be used with [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted) for database fields. This gives you:
+
+1. Easy key rotation
+2. XChaCha20
+3. Hybrid cryptography
+4. No need for separate IV columns
+
+Add to your Gemfile:
+
+```ruby
+gem 'attr_encrypted'
+```
+
+Create a migration to add a new column for the encrypted data. We don’t need a separate IV column, as this will be included in the encrypted data.
+
+```ruby
+class AddEncryptedPhoneToUsers < ActiveRecord::Migration[5.2]
+  def change
+    add_column :users, :encrypted_phone, :string
+  end
+end
+```
+
+All Lockbox options are supported.
+
+```ruby
+class User < ApplicationRecord
+  attr_encrypted :phone, encryptor: Lockbox::Encryptor, key: key, algorithm: "xchacha20", previous_versions: [{key: previous_key}]
+
+  attribute :encrypted_phone_iv # prevent attr_encrypted error
+end
+```
+
+For hybrid cryptography, use:
+
+```ruby
+class User < ApplicationRecord
+  attr_encrypted :phone, encryptor: Lockbox::Encryptor, algorithm: "hybrid", encryption_key: encryption_key, decryption_key: decryption_key
+
+  attribute :encrypted_phone_iv # prevent attr_encrypted error
+end
+```
+
 ## Reference
 
 Pass associated data to encryption and decryption

data/lib/lockbox.rb

@@ -1,9 +1,6 @@
-# dependencies
-require "openssl"
-require "securerandom"
-
 # modules
 require "lockbox/box"
+require "lockbox/encryptor"
 require "lockbox/utils"
 require "lockbox/version"
 
@@ -20,26 +17,24 @@ class Lockbox
   end
   self.default_options = {algorithm: "aes-gcm"}
 
-  def initialize(key: nil, algorithm: nil, previous_versions: nil)
-    default_options = self.class.default_options
-    key ||= default_options[:key]
-    algorithm ||= default_options[:algorithm]
-    previous_versions ||= default_options[:previous_versions]
+  def initialize(**options)
+    options = self.class.default_options.merge(options)
+    previous_versions = options.delete(:previous_versions)
 
     @boxes =
-      [Box.new(key, algorithm: algorithm)] +
-      Array(previous_versions).map { |v| Box.new(v[:key], algorithm: v[:algorithm]) }
+      [Box.new(options)] +
+      Array(previous_versions).map { |v| Box.new(v) }
   end
 
-  def encrypt(*args)
-    @boxes.first.encrypt(*args)
+  def encrypt(message, **options)
+    message = check_string(message, "message")
+    @boxes.first.encrypt(message, **options)
   end
 
   def decrypt(ciphertext, **options)
-    raise TypeError, "can't convert ciphertext to string" unless ciphertext.respond_to?(:to_str)
+    ciphertext = check_string(ciphertext, "ciphertext")
 
     # ensure binary
-    ciphertext = ciphertext.to_str
     if ciphertext.encoding != Encoding::BINARY
       # dup to prevent mutation
       ciphertext = ciphertext.dup.force_encoding(Encoding::BINARY)
@@ -48,9 +43,38 @@ class Lockbox
     @boxes.each_with_index do |box, i|
       begin
         return box.decrypt(ciphertext, **options)
-      rescue DecryptionError, RbNaCl::LengthError, RbNaCl::CryptoError
-        raise DecryptionError, "Decryption failed" if i == @boxes.size - 1
+      rescue => e
+        error_classes = [DecryptionError]
+        error_classes << RbNaCl::LengthError if defined?(RbNaCl::LengthError)
+        error_classes << RbNaCl::CryptoError if defined?(RbNaCl::CryptoError)
+        if error_classes.any? { |ec| e.is_a?(ec) }
+          raise DecryptionError, "Decryption failed" if i == @boxes.size - 1
+        else
+          raise e
+        end
       end
     end
   end
+
+  def self.generate_key_pair
+    require "rbnacl"
+    # encryption and decryption servers exchange public keys
+    # this produces smaller ciphertext than sealed box
+    alice = RbNaCl::PrivateKey.generate
+    bob = RbNaCl::PrivateKey.generate
+    # alice is sending message to bob
+    # use bob first in both cases to prevent keys being swappable
+    {
+      encryption_key: (bob.public_key.to_bytes + alice.to_bytes).unpack("H*").first,
+      decryption_key: (bob.to_bytes + alice.public_key.to_bytes).unpack("H*").first
+    }
+  end
+
+  private
+
+  def check_string(str, name)
+    str = str.read if str.respond_to?(:read)
+    raise TypeError, "can't convert #{name} to string" unless str.respond_to?(:to_str)
+    str.to_str
+  end
 end

data/lib/lockbox/active_storage_extensions.rb

@@ -1,3 +1,7 @@
+# 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
 class Lockbox
   module ActiveStorageExtensions
     module Attached
@@ -15,7 +19,7 @@ class Lockbox
 
         case attachable
         when ActiveStorage::Blob
-          raise NotImplemented, "Not supported yet"
+          raise NotImplemented, "Not supported"
         when ActionDispatch::Http::UploadedFile, Rack::Test::UploadedFile
           attachable = {
             io: StringIO.new(box.encrypt(attachable.read)),
@@ -29,7 +33,7 @@ class Lockbox
             content_type: attachable[:content_type]
           }
         when String
-          raise NotImplemented, "Not supported yet"
+          raise NotImplemented, "Not supported"
         else
           nil
         end

data/lib/lockbox/aes_gcm.rb

@@ -1,3 +1,5 @@
+require "openssl"
+
 class Lockbox
   class AES_GCM
     def initialize(key)
@@ -9,6 +11,7 @@ class Lockbox
 
     def encrypt(nonce, message, associated_data)
       cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      # do not change order of operations
       cipher.encrypt
       cipher.key = @key
       cipher.iv = nonce
@@ -31,6 +34,7 @@ class Lockbox
       fail_decryption if ciphertext.to_s.bytesize == 0
 
       cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      # do not change order of operations
       cipher.decrypt
       cipher.key = @key
       cipher.iv = nonce

data/lib/lockbox/box.rb

@@ -1,54 +1,85 @@
+require "securerandom"
+
 class Lockbox
   class Box
-    def initialize(key, algorithm: nil)
-      # decode hex key
-      if key.encoding != Encoding::BINARY && key =~ /\A[0-9a-f]{64}\z/i
-        key = [key].pack("H*")
-      end
+    def initialize(key: nil, algorithm: nil, encryption_key: nil, decryption_key: nil)
+      raise ArgumentError, "Cannot pass both key and public/private key" if key && (encryption_key || decryption_key)
+
+      key = decode_key(key) if key
+      encryption_key = decode_key(encryption_key) if encryption_key
+      decryption_key = decode_key(decryption_key) if decryption_key
 
       algorithm ||= "aes-gcm"
 
       case algorithm
       when "aes-gcm"
+        raise ArgumentError, "Missing key" unless key
         require "lockbox/aes_gcm"
         @box = AES_GCM.new(key)
       when "xchacha20"
+        raise ArgumentError, "Missing key" unless key
         require "rbnacl"
         @box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)
+      when "hybrid"
+        raise ArgumentError, "Missing key" unless encryption_key || decryption_key
+        require "rbnacl"
+        @encryption_box = RbNaCl::Boxes::Curve25519XSalsa20Poly1305.new(encryption_key.slice(0, 32), encryption_key.slice(32..-1)) if encryption_key
+        @decryption_box = RbNaCl::Boxes::Curve25519XSalsa20Poly1305.new(decryption_key.slice(32..-1), decryption_key.slice(0, 32)) if decryption_key
       else
         raise ArgumentError, "Unknown algorithm: #{algorithm}"
       end
+
+      @algorithm = algorithm
     end
 
     def encrypt(message, associated_data: nil)
-      nonce = generate_nonce
-      ciphertext = @box.encrypt(nonce, message, associated_data)
+      if @algorithm == "hybrid"
+        raise ArgumentError, "No public key set" unless @encryption_box
+        raise ArgumentError, "Associated data not supported with this algorithm" if associated_data
+        nonce = generate_nonce(@encryption_box)
+        ciphertext = @encryption_box.encrypt(nonce, message)
+      else
+        nonce = generate_nonce(@box)
+        ciphertext = @box.encrypt(nonce, message, associated_data)
+      end
       nonce + ciphertext
     end
 
     def decrypt(ciphertext, associated_data: nil)
-      nonce, ciphertext = extract_nonce(ciphertext)
-      @box.decrypt(nonce, ciphertext, associated_data)
+      if @algorithm == "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)
+      else
+        nonce, ciphertext = extract_nonce(@box, ciphertext)
+        @box.decrypt(nonce, ciphertext, associated_data)
+      end
     end
 
-    # protect key for xchacha20
+    # protect key for xchacha20 and hybrid
     def inspect
       to_s
     end
 
     private
 
-    def nonce_bytes
-      @box.nonce_bytes
-    end
-
-    def generate_nonce
-      SecureRandom.random_bytes(nonce_bytes)
+    def generate_nonce(box)
+      SecureRandom.random_bytes(box.nonce_bytes)
     end
 
-    def extract_nonce(bytes)
+    def extract_nonce(box, bytes)
+      nonce_bytes = box.nonce_bytes
       nonce = bytes.slice(0, nonce_bytes)
       [nonce, bytes.slice(nonce_bytes..-1)]
     end
+
+    # decode hex key
+    def decode_key(key)
+      if key.encoding != Encoding::BINARY && key =~ /\A[0-9a-f]{64,128}\z/i
+        key = [key].pack("H*")
+      end
+      key
+    end
   end
 end

data/lib/lockbox/encryptor.rb

@@ -0,0 +1,17 @@
+class Lockbox
+  class Encryptor
+    def self.encrypt(options)
+      box(options).encrypt(options[:value])
+    end
+
+    def self.decrypt(options)
+      box(options).decrypt(options[:value])
+    end
+
+    def self.box(options)
+      options = options.slice(:key, :encryption_key, :decryption_key, :algorithm, :previous_versions)
+      options[:algorithm] = "aes-gcm" if options[:algorithm] == "aes-256-gcm"
+      Lockbox.new(options)
+    end
+  end
+end

data/lib/lockbox/version.rb

@@ -1,3 +1,3 @@
 class Lockbox
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lockbox
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-02 00:00:00.000000000 Z
+date: 2019-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -110,6 +110,20 @@ dependencies:
         version: '0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: rbnacl
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -123,7 +137,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rbnacl
+  name: attr_encrypted
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -150,6 +164,7 @@ files:
 - lib/lockbox/aes_gcm.rb
 - lib/lockbox/box.rb
 - lib/lockbox/carrier_wave_extensions.rb
+- lib/lockbox/encryptor.rb
 - lib/lockbox/railtie.rb
 - lib/lockbox/utils.rb
 - lib/lockbox/version.rb