sequel_vault 0.4 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3049adb333bd60b77bf10308bd4b762c0fe5e074
-  data.tar.gz: 942936b542ea08b4c968d85a000515da9cd1c4f0
+  metadata.gz: 5786aa527d01d7c5bd4df1a1782a5522337c27e2
+  data.tar.gz: dab2b2ca481ca80a15e670635f7267c29e76f931
 SHA512:
-  metadata.gz: ffeab0fb22d2bdb46899ff54599574251b41a55080a8311e08571d7255dd671bed61193f34ce5fd94fceaccf2b962d6a8e597fa168fd6b287dca70338e88178b
-  data.tar.gz: 1ee118a4925797d427da37de478e95e486ba1521f7b4ad06366127d4ecfe4c89e51222f16bccd70f97aaf1f7e3bd94b4bdba1c97e884c21b61b6387891dadfa5
+  metadata.gz: 922ebf91834853e1188f8973d8c655ef2e5d86352626701cd2406b439d45888183ab32c86cce2e41a0e5a71ff0705be0f15764896f8a25ceab1795ff87c3b658
+  data.tar.gz: 862f5d2cbe3ca630807e3cb444d35bbd1157e941130db4379067816fb0af770ed86401726d1c4e05b7ce60834088c1ca13a9fdd00cd481394c6401ce37b4becf

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sequel_vault (0.3)
+    sequel_vault (0.4)
       fernet (~> 2.1, >= 2.1)
       sequel (~> 4.21, >= 4.21.0)
 

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014-2015 Timothée Peignier <timothee.peignier@tryphon.org>
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,13 +1,108 @@
 # Sequel-vault
 
-Use [fernet](https://github.com/fernet/fernet-rb) to encrypt columns values in your Sequel database
+Use [fernet](https://github.com/fernet/fernet-rb) to encrypt columns values in your Sequel database.
+
+## Installation
+
+Install it directly using gem:
+
+```
+gem install sequel_vault
+```
+
+Or adding it to your ``Gemfile``:
+
+```
+gem "sequel_vault"
+```
 
 ## Usage
 
+## Configure
+
+A straightforward example, passing keys and columns that will be encrypted
+transparently:
+
+```ruby
+class Credential < Sequel::Model
+  plugin :vault, ['9cLL4qVO+bkEqGQtcvQX4Cz4uJ1ni9Nb83ipU/9klsw='], :token
+end
+```
+
+Along with a typical migration for this setup:
+
+```ruby
+Sequel.migration do
+  change do
+    alter_table(:credentials) do
+      add_column(:token, :bytea)
+      add_column(:token_digest, :bytea)
+      add_column(:key_id, :smallint)
+    end
+  end
+end
+```
+
+### Keys
+
+Vault use [fernet](https://github.com/fernet/fernet-rb) behind the scene, the
+keys should be 32 bytes of random data, base64-encoded.
+
+To generate one you can use:
+
+```console
+$ dd if=/dev/urandom bs=32 count=1 2>/dev/null | openssl base64
+```
+
+You can specify more than one key to be used. The last keys of the array will
+be used as the default for encryption.
+
+### Keys migration
+
+If a ``key_id`` column is present, vault will set its value to the length of
+the keys array. You can check if a key is still in use using:
+
+```ruby
+Credential.where(key_id: 1).empty?
+```  
+
+You should avoid removing a key when using ``key_id``, unless you proceed to
+migrate its value.
+
+Here is a migration example to add a ``key_id`` column:
+
+```ruby
+Sequel.migration do
+  change do
+    alter_table(:credentials) do
+      add_column(:key_id, :smallint)
+    end
+  end
+end
+```
+
+### Digest lookup
+
+To allow lookup by a know secret, vault allow an optional digest column for each
+encrypted attribute, using the ``_digest`` suffix:
+
 ```ruby
-class AWSCreds < Sequel::Model
-  # attrs :access_key_id, ::access_key_id_digest, :secret_access_key, :secret_access_key_digest :region, :name
-  plugin :vault
-  vault_attributes ['Fernet key','...'], :access_key_id, :secret_access_key
+Sequel.migration do
+  change do
+    alter_table(:credentials) do
+      add_column(:token_digest, :bytea)
+    end
+  end
 end
 ```
+
+You can then lookup using the provided dataset lookup:
+
+```ruby
+Credential.token_lookup('secret')
+```
+
+### Unencrypted data
+
+Vault will return plain-text data if none of the keys can successfully decrypt
+the stored value, effectively allowing encrypt on write migration.

data/lib/sequel_vault.rb

@@ -4,8 +4,6 @@ require "sequel"
 module Sequel
   module Plugins
     module Vault
-      class InvalidCiphertext < Exception; end
-
       def self.apply(model, keys = [], *attrs)
         model.instance_eval do
           @vault_attrs = attrs
@@ -75,16 +73,16 @@ module Sequel
             next unless verifier.valid?
             return verifier.message
           end
-          raise InvalidCiphertext, "Could not decrypt field"
+          cypher # Return cypher has it's probably just plain text
         end
       end
 
       module InstanceMethods
         def []=(attr, plain)
           if model.vault_attrs.include?(attr) && !plain.nil?
-            send("#{attr}_digest=", self.class.digest(model.vault_keys, plain))
+            send("#{attr}_digest=", self.class.digest(model.vault_keys, plain)) if model.columns.include?(:"#{attr}_digest")
+            send("key_id=", model.vault_keys.length) if model.columns.include?(:key_id)
             value = self.class.encrypt(model.vault_keys, plain)
-            super(:key_id, model.vault_keys.length) if model.columns.include?(:key_id)
           end
           super(attr, value || plain)
         end

data/sequel_vault.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "sequel_vault"
   gem.require_paths = ["lib"]
-  gem.version       = '0.4'
+  gem.version       = '0.5'
 
   gem.add_runtime_dependency 'sequel', '~> 4.21', '>= 4.21.0'
   gem.add_runtime_dependency 'fernet', '~> 2.1', '>= 2.1'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel_vault
 version: !ruby/object:Gem::Version
-  version: '0.4'
+  version: '0.5'
 platform: ruby
 authors:
 - Timothée Peignier
@@ -116,6 +116,7 @@ files:
 - ".travis.yml"
 - Gemfile
 - Gemfile.lock
+- LICENSE
 - README.md
 - lib/sequel_vault.rb
 - sequel_vault.gemspec