transcryptor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6813eb2a6c0d37ead4decf3e6e1ee7df68a988b8
+  data.tar.gz: 5154be7dd43bc80e31bba691f7e597914697a49a
+SHA512:
+  metadata.gz: 1501fe5d238025d10dc60985956e39905fc1151b1a0d35b0d4e98b04d2ed4e2eabdf6b4543e42d88056e95d451fd1acc22ac1b62b2798fd5aa5537d2f14e3cef
+  data.tar.gz: 497c6bd3468048f641378626d0019f76ac8184f7fa75749a290a4e15814cf1a28ee8e91b91aaea9ef918422ff766df07039f59d154c3136380a85fe4749f07de

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.2
+before_install: gem install bundler -v 1.13.7

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at jeffrey.lau@ribose.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in transcryptor.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Ribose Inc.
+
+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.adoc

@@ -0,0 +1,196 @@
+= Transcryptor
+:source-highlighter: pygments
+
+image:https://img.shields.io/travis/riboseinc/transcryptor/master.svg["Build Status", link="https://travis-ci.org/riboseinc/transcryptor"]
+image:https://img.shields.io/coverity/scan/12786.svg["Coverity Scan Build Status", link="https://scan.coverity.com/projects/riboseinc-transcryptor"]
+
+Transcryptor provides utility functions to help migrate records encrypted with 
+https://github.com/attr-encrypted/attr_encrypted[`attr_encrypted`] from one 
+encryption configuration to another.
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'transcryptor', github: 'riboseinc/transcryptor'
+----
+
+And then execute:
+
+----
+bundle
+----
+
+Or install it yourself as:
+
+----
+gem install transcryptor
+----
+
+== Usage
+
+Given:
+
+. you have already set up tables to be encrypted with `attr_encrypted`,
+. you'd like to migrate your columns from:
++
+(`algorithm~1~`, `iv~1~`, `salt~1~`, `key~1~`)
++
+to
++
+(`algorithm~2~`, `iv~2~`, `salt~2~`, `key~2~`)
++
+where:
++
+.. `algorithm` can be `aes-256-cbc`, `aes-256-gcm` or any others that 
+`attr_encrypted` supports,
+.. `salt` can be optional,
+.. `iv` can be optional (!!).
+
+Then:
+
+. Create a migration like so:
++
+[source,ruby]
+----
+class ReencryptUsersAndDocumentsWithNewKeys < ActiveRecord::Migration
+
+  def transcryptor
+    Transcryptor.init(self)
+  end
+
+  # +keyifier+ mirrors the functionality provided by the :key Proc in
+  # attr_encrypted.
+  # NOTE: Has to return the entire Hash.
+  #
+  def old_keyifier
+    -> opts {
+      opts[:key] = ENV['old_master_encryption_key'] + opts[:key]
+      opts
+    }
+  end
+
+  def new_keyifier
+    -> opts {
+      opts[:key] = ENV['new_master_encryption_key'] + opts[:key]
+      opts
+    }
+  end
+
+  # Define the current DB schema for Transcryptor.
+  # Format:
+  # {
+  #   <table_i>: {
+  #     id_column: <the column name for record id>,
+  #     columns: {
+  #       <column_i>: {
+  #         prefix: <attr_encrypted prefix string (optional)>,
+  #         suffix: <attr_encrypted suffix string (optional)>,
+  #         key: <the column storing the key to encrypt column_i>,
+  #       },
+  #     }
+  #   },
+  # }
+  #
+  def table_column_spec
+    {
+      users:  {
+        id_column: :id,
+        columns: {
+          email: {
+            prefix: 'encrypted_',
+            key: :ekey,
+          },
+          birthday: {
+            prefix: 'encrypted_',
+            key: :ekey,
+          },
+        }
+      },
+      documents:  {
+        id_column: :id,
+        columns: {
+          passphrase: {
+            prefix: 'secret_',
+            key: :enc_key,
+          },
+        }
+      },
+    }
+  end
+
+  #
+  # Run transcryptor.updown_migrate() for both #up and #down.
+  # Give it:
+  # - the table-column specification,
+  # - the old encryption configuration (at least any one of: algorithm, iv, 
+  # salt, key)
+  # - the new encryption configuration (at least any one of: algorithm, iv, 
+  # salt, key)
+  # - optional params-modifying Proc before passing to Encryptor.decrypt (used 
+  # by attr_encrypted)
+  # - optional params-modifying Proc before passing to Encryptor.encrypt (used 
+  # by attr_encrypted)
+  #
+  def up
+    transcryptor.updown_migrate(
+      table_column_spec,
+      {
+        algorithm:      'aes-256-cbc',
+        decode64_value: true,
+      }, {
+        algorithm:      'aes-256-gcm',
+        encode64_iv:    true,
+        encode64_value: true,
+        iv: true,
+      },
+      old_keyifier,
+      new_keyifier,
+    )
+  end
+
+  def down
+    transcryptor.updown_migrate(
+      table_column_spec,
+      {
+        algorithm:      'aes-256-gcm',
+        decode64_iv:    true,
+        decode64_value: true,
+      }, {
+        algorithm:      'aes-256-cbc',
+        iv:             false,
+        salt:           false,
+        encode64_value: true,
+        insecure_mode:  true,
+      },
+      new_keyifier,
+      old_keyifier,
+    )
+  end
+
+----
+. Run `bundle exec db:migrate`
+. Done!
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run 
+`rake spec` to run the tests. You can also run `bin/console` for an interactive 
+prompt that will allow you to experiment.
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at 
+https://github.com/riboseinc/transcryptor. This project is intended to be a 
+safe, welcoming space for collaboration, and contributors are expected to 
+adhere to the http://contributor-covenant.org[Contributor Covenant] code of 
+conduct.
+
+
+== License
+
+The gem is available as open source under the terms of the 
+http://opensource.org/licenses/MIT[MIT License].
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "transcryptor"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/transcryptor.rb

@@ -0,0 +1,545 @@
+# encoding: utf-8
+require "transcryptor/version"
+require "active_support"
+require "active_record"
+require 'encryptor'
+
+# To use Transcryptor, here is a sample migration that showcases this:
+#
+# class ReencryptUsersAndDocumentsWithNewKeys < ActiveRecord::Migration
+#
+#   def transcryptor
+#     Transcryptor.init(self)
+#   end
+#
+#   # +keyifier+ mirrors the functionality provided by the :key Proc in
+#   # attr_encrypted.
+#   # NOTE: Has to return the entire Hash.
+#   #
+#   def old_keyifier
+#     -> opts {
+#       opts[:key] = ENV['old_master_encryption_key'] + opts[:key]
+#       opts
+#     }
+#   end
+#
+#   def new_keyifier
+#     -> opts {
+#       opts[:key] = ENV['new_master_encryption_key'] + opts[:key]
+#       opts
+#     }
+#   end
+#
+#   def table_column_spec
+#     {
+#       users:  {
+#         id_column: :id,
+#         columns: {
+#           email: {
+#             prefix: 'encrypted_',
+#             key: :ekey,
+#           },
+#           birthday: {
+#             prefix: 'encrypted_',
+#             key: :ekey,
+#           },
+#         }
+#       },
+#       documents:  {
+#         id_column: :id,
+#         columns: {
+#           passphrase: {
+#             prefix: 'encrypted_',
+#             key: :ekey,
+#           },
+#         }
+#       },
+#     }
+#   end
+#
+#   def up
+#     transcryptor.updown_migrate(
+#       table_column_spec,
+#       {
+#         algorithm:      'aes-256-cbc',
+#         decode64_value: true,
+#       }, {
+#         algorithm:      'aes-256-gcm',
+#         encode64_iv:    true,
+#         encode64_value: true,
+#         iv: true,
+#       },
+#       old_keyifier,
+#       new_keyifier,
+#     )
+#   end
+#
+#   def down
+#     transcryptor.updown_migrate(
+#       table_column_spec,
+#       {
+#         algorithm:      'aes-256-gcm',
+#         decode64_iv:    true,
+#         decode64_value: true,
+#       }, {
+#         algorithm:      'aes-256-cbc',
+#         iv:             false,
+#         salt:           false,
+#         encode64_value: true,
+#         insecure_mode:  true,
+#       },
+#       new_keyifier,
+#       old_keyifier,
+#     )
+#   end
+#
+module Transcryptor
+
+  # Initialize Transcryptor instance with the migration instance.
+  # This step allows typical migration methods like #execute to be invoked
+  # from this gem.
+  def self.init(migration_instance = Kernel.caller)
+    Instance.new(migration_instance)
+  end
+
+  class Instance
+
+    attr_accessor :migration_instance
+
+    def initialize(migration_instance)
+      self.migration_instance = migration_instance
+    end
+
+    def execute *args
+      puts "\e[38;5;141m"
+      puts puts args
+      puts "\e[0m"
+      migration_instance.execute *args
+    end
+
+    def sanitize(sql_fragment)
+      ActiveRecord::Base.sanitize(sql_fragment)
+    end
+
+    # Meant to be used by both #up and #down.
+    #
+    # table_column_spec:
+    # {
+    #   table1:  {
+    #     id_column: :id,
+    #     columns: {
+    #       column1: {
+    #         prefix: 'encoded_',
+    #         key: :encryption_key_1,
+    #       },
+    #       column2: {
+    #         prefix: 'xXx_en_ing_',
+    #         key: :encryption_key_2,
+    #         suffix: '_crypted_xXx',
+    #       },
+    #     }
+    #   },
+    #   table2:  {
+    #     id_column: :id,
+    #     columns: {
+    #       column3: {
+    #         prefix: 'encoded_',
+    #         key: :encryption_key_3,
+    #       },
+    #       column4: {
+    #         prefix: 'xXx_en_ing_',
+    #         key: :encryption_key_4,
+    #         suffix: '_crypted_xXx',
+    #       },
+    #     }
+    #   },
+    # }
+    def get_column_names_from(table_name, table_spec)
+      id_name      = table_spec[:id_column]
+      column_specs = table_spec[:columns]
+
+      puts "table name is #{table_name}"
+      puts "table psec is #{table_spec}"
+      res = [ id_name ] + column_specs.map do |column_name, column_spec|
+        column_prefix    = column_spec[:prefix]
+        column_key_field = column_spec[:key]
+        column_suffix    = column_spec[:suffix]
+        full_column_name = :"#{column_prefix}#{column_name}#{column_suffix}"
+
+        [ full_column_name, column_key_field ] + %i[iv salt].reduce([]) do |acc, suffix|
+          extra_column_name = :"#{full_column_name}_#{suffix}"
+          acc << extra_column_name if column_exists?(table_name, extra_column_name)
+          acc
+        end
+      end.flatten.compact.uniq
+      pp res
+      res
+    end
+
+    def updown_migrate(table_column_spec, old_spec, new_spec, decrypt_opts_fn, encrypt_opts_fn)
+
+      # puts "table column spec is:"
+      # pp table_column_spec
+
+      table_column_spec.each do |table_name, table_spec|
+        column_specs          = table_spec[:columns]
+        relevant_column_names = get_column_names_from(table_name, table_spec)
+        puts "relevant column names are:"
+        pp relevant_column_names
+
+        execute(
+          "SELECT #{relevant_column_names.join(', ')} FROM `#{table_name}`"
+        ).each do |_db_values|
+          id, _dontcare = _db_values
+
+          puts 'db values'
+          pp _db_values
+          # A map: { :db_field_name => "value" }
+          db_values =
+            Hash[relevant_column_names.map(&:to_sym).zip(_db_values)]
+
+          # Build up reencryption params to pass to reencrypt().
+          encrypted_attrs = column_specs.keys.map do |attr_name|
+
+            column_spec      = column_specs[attr_name]
+            column_prefix    = column_spec[:prefix]
+            column_key_field = column_spec[:key]
+            column_suffix    = column_spec[:suffix]
+            full_column_name = :"#{column_prefix}#{attr_name}#{column_suffix}"
+
+            encrypted_value = db_values[:"#{full_column_name}"]
+            key             = db_values[:"#{column_key_field}"]
+            # +key+ could be nil, but it's OK, since it may be provided via 
+            # other means, e.g. encrypt_opts_fn and decrypt_opts_fn.
+
+            unless encrypted_value.nil? || encrypted_value == ""
+              res = {
+                attr_name: attr_name,
+                key:       key,
+                value:     encrypted_value,
+              }
+
+              # Merge in iv and/or salt as appropriate.
+              %i[iv salt].reduce(res) do |acc, suffix|
+                extra_column_name = :"#{full_column_name}_#{suffix}"
+                if relevant_column_names.include?(extra_column_name)
+                  acc[suffix] = db_values[extra_column_name]
+                end
+                acc
+              end
+            end
+          end.compact
+
+          next if encrypted_attrs.empty?
+
+          re_encrypt(
+            table_name,
+            id,
+            encrypted_attrs.map do |attr|
+              {
+                # These would be in +attr+ as approprate.
+                # salt:      old_salt,
+                # iv:        old_iv,
+                # key:       old_key,
+                # attr_name: attr_name,
+                # value:     encrypted_value,
+                old: attr.merge(old_spec),
+                new: { key: attr[:key], }.merge(new_spec),
+              }
+            end,
+            decrypt_opts_fn,
+            encrypt_opts_fn,
+          )
+        end
+
+      end
+    end
+
+    # +table_name+ is the SQL table name for the record at id = +record_id+.
+    # +attrs_specs+ is an Array like so: [ {
+    #   old: {
+    #     key:       String,
+    #     value:     String,
+    #     attr_name: String,
+    #     algorithm:      String,
+    #     iv:        String | Nil,
+    #     salt:      String | Nil,
+    #   },
+    #   new:         {
+    #     algorithm:      String,
+    #     iv:        String | Bool,
+    #     salt:      String | Bool,
+    #   },
+    # } ]
+    #
+    # Assumptions: Encrypted attribute SQL column names are all prefixed with 
+    # "encrypted_",  and also suffixed with "_iv" & "_salt" for the corresponding 
+    # iv and salt.
+    #
+    def re_encrypt(table_name, record_id, attrs_specs, decrypt_opts_fn, encrypt_opts_fn, column_prefix = 'encrypted_')
+      set_statement =
+        set_clauses_for_re_encrypt(table_name, record_id, attrs_specs, decrypt_opts_fn, encrypt_opts_fn, column_prefix = 'encrypted_').
+        join(', ')
+
+      update_statement = <<-EOF
+        UPDATE `#{table_name}`
+        SET #{set_statement}
+        WHERE id = #{ActiveRecord::Base.sanitize(record_id)}
+      EOF
+
+      puts puts "\e[38;5;42m"
+      puts update_statement
+      puts "\e[0m"
+      execute(update_statement)
+    end
+
+    def set_clauses_for_re_encrypt(table_name, record_id, attrs_specs, decrypt_opts_fn, encrypt_opts_fn, column_prefix = 'encrypted_')
+      # puts "attrs_specs:"
+      # pp attrs_specs
+
+      attrs_specs.map do |attr_spec|
+
+        old_spec = attr_spec[:old]
+        new_spec = attr_spec[:new]
+
+        plain_stuff    = dec(old_spec) do |opts|
+          decrypt_opts_fn.call(opts)
+        end
+        result_stuff   = enc(new_spec.merge(value: plain_stuff[:value])) do |opts|
+          encrypt_opts_fn.call(opts)
+        end
+
+        new_ciphertext = result_stuff[:value]
+        attr_name      = old_spec[:attr_name]
+
+        extra_columns = %i[iv salt].reduce({}) do |acc, suffix|
+          extra_column_name = "#{column_prefix}#{attr_name}_#{suffix}"
+          acc[suffix] = extra_column_name if column_exists?(table_name, extra_column_name)
+
+          # TODO: perhaps these checks could be done at the beginning, in 
+          # a 'validate_params' method.
+          raise Exception.new(
+            "Error: Column #{extra_column_name} doesn't exist " \
+            "but is needed for #{suffix}.  Aborting."
+          ) if result_stuff[suffix] && !acc[suffix]
+          acc
+        end
+
+        (
+          [
+            "`#{column_prefix}#{attr_name}` = #{sanitize(new_ciphertext)}"
+          ] +
+          extra_columns.reduce([]) do |acc, (suffix, extra_column_name)|
+            acc << "`#{extra_column_name}` = #{
+              sanitize(result_stuff[suffix])
+            }"
+            acc
+          end.flatten
+        ).map{|s| s.force_encoding('utf-8')}
+
+      end
+    end
+
+    # XXX: MySQL2 specific! TODO: adapt to different backends
+    # Return +true+ iff column +_column_name+ exists in table +_table_name+.
+    # Cached for performance.
+    def column_exists?(_table_name, _column_name)
+      table_name  = _table_name.to_sym
+      column_name = _column_name.to_sym
+      @column_exists ||= {}
+      @column_exists[table_name] ||= {}
+      exists = @column_exists[table_name][column_name]
+      !exists.nil? ? exists : @column_exists[table_name][column_name] =
+        begin
+          raw_result = execute <<-EOF
+            SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
+            WHERE
+              column_name  = #{sanitize column_name} AND
+              table_name   = #{sanitize table_name} AND
+              TABLE_SCHEMA = DATABASE()
+          EOF
+
+          result = raw_result.to_a.flatten[0] == 1
+          result
+        end
+    end
+
+    class NoKeyException < StandardError ; end
+
+    # +iv+ can be +true+.  If so, we generate IV for you.
+    # If +iv+ is truthy, we use +iv+ directly.
+    # Likewise for +salt+.
+    # Default algorithm is 'aes-256-gcm' as per default of attr_encrypted v3.
+    # You may opt to use 'aes-256-cbc', like in attr_encrypted v1.
+    #
+    # When given a block, the encryptor params can be modified before passing 
+    # over to Encryptor for the encryption process.
+    #
+    # +decode64_iv+
+    #   - if +true+, base64-decodes the given +iv+ before passing to Encryptor.
+    # +decode64_salt+
+    #   - if +true+, base64-decodes the given +salt+ before passing to 
+    #   Encryptor.
+    # +decode64_value+
+    #   - if +true+, base64-decodes the given +value+ before passing to 
+    #   Encryptor.
+    #
+    # +encode64_iv+
+    #   - if +true+, base64-encodes the +iv+ output by Encryptor.
+    # +encode64_salt+
+    #   - if +true+, base64-encodes the +salt+ output by Encryptor.
+    # +encode64_value+
+    #   - if +true+, base64-encodes the +value+ output by Encryptor.
+    #
+    def enc opts
+      value = opts[:value]
+      ek    = opts[:key]
+      algo  = opts[:algorithm] || 'aes-256-gcm'
+
+      iv = opts[:iv]
+      iv = OpenSSL::Cipher.new(algo).random_iv if iv === true
+
+      salt = opts[:salt]
+      salt = SecureRandom.random_bytes if salt === true
+
+      has_iv   = !iv.nil?   &&   iv != ''
+      has_salt = !salt.nil? && salt != ''
+
+      cryptor_opts = {
+        value:         value,
+        key:           ek,
+        algorithm:     algo,
+        value_present: false, # so as to force regenerating of random_iv @ encryptor
+        insecure_mode: !! opts[:insecure_mode] || ! has_iv,
+      }
+
+      puts "in enc: opts = #{opts.pretty_inspect}"
+
+      iv    = Base64.decode64(iv)    if has_iv   && opts.delete(:decode64_iv)
+      salt  = Base64.decode64(salt)  if has_salt && opts.delete(:decode64_salt)
+      value = Base64.decode64(value) if opts.delete(:decode64_value)
+
+      cryptor_opts = cryptor_opts.merge(iv: iv)     if has_iv
+      cryptor_opts = cryptor_opts.merge(salt: salt) if has_salt
+      cryptor_opts = cryptor_opts.merge(value: value)
+
+      if block_given?
+        cryptor_opts = yield cryptor_opts
+        ek             = cryptor_opts[:key]
+      end
+
+      raise NoKeyException.new("encryption :key is nil") if ek.nil?
+
+      puts "cryptor opts:"
+      pp cryptor_opts
+
+      result_stuff = {
+        value: ::Encryptor.encrypt(cryptor_opts),
+        key:   ek,
+      }
+
+      iv    = Base64.encode64(iv)    if has_iv   && opts.delete(:encode64_iv)
+      salt  = Base64.encode64(salt)  if has_salt && opts.delete(:encode64_salt)
+      value = Base64.encode64(result_stuff[:value]) if opts.delete(:encode64_value)
+
+      result_stuff[:value] = value
+
+      # puts "has iv? #{has_iv}     = #{iv.pretty_inspect}"
+      # puts "has salt? #{has_salt} = #{salt.pretty_inspect}"
+
+      result_stuff = result_stuff.merge(iv: iv)     if has_iv
+      result_stuff = result_stuff.merge(salt: salt) if has_salt
+      result_stuff
+    end
+
+    #
+    # When given a block, the encryptor params can be modified before passing 
+    # over to Encryptor for the encryption process.
+    #
+    # +insecure_mode+ is automatically set to +true+ if no +iv+ is provided.
+    # It can also be specified by user but will not be able to override the 
+    # +true+ if no +iv+ is given.  This should match what is expected to work 
+    # in Encryptor.
+    #
+    # +decode64_iv+
+    #   - if +true+, base64-decodes the given +iv+ before passing to Encryptor.
+    # +decode64_salt+
+    #   - if +true+, base64-decodes the given +salt+ before passing to 
+    #   Encryptor.
+    # +decode64_value+
+    #   - if +true+, base64-decodes the given +value+ before passing to 
+    #   Encryptor.
+    #
+    # +encode64_iv+
+    #   - if +true+, base64-encodes the given +iv+ before passing to Encryptor.
+    # +encode64_salt+
+    #   - if +true+, base64-encodes the given +salt+ before passing to 
+    #   Encryptor.
+    # +encode64_value+
+    #   - if +true+, base64-encodes the given +value+ before passing to 
+    #   Encryptor.
+    #
+    # NOTE: The operations decode64-* and encode64-* decribed above may cancel 
+    # each other out.
+    #
+    # This is a design uncertainty and may change in a later version.
+    #
+    def dec opts
+      value = opts[:value]
+      key   = opts[:key]
+      algo  = opts[:algorithm] || 'aes-256-gcm'
+      iv    = opts[:iv]
+      salt  = opts[:salt]
+
+      has_iv   = iv   &&   iv != ''
+      has_salt = salt && salt != ''
+
+      iv    = Base64.decode64(iv)    if has_iv   && opts.delete(:decode64_iv)
+      salt  = Base64.decode64(salt)  if has_salt && opts.delete(:decode64_salt)
+      value = Base64.decode64(value) if opts.delete(:decode64_value)
+
+      iv    = Base64.encode64(iv)    if has_iv   && opts.delete(:encode64_iv)
+      salt  = Base64.encode64(salt)  if has_salt && opts.delete(:encode64_salt)
+      value = Base64.encode64(value) if opts.delete(:encode64_value)
+
+      cryptor_opts = {
+        value:         value,
+        key:           key,
+        iv:            iv,
+        salt:          salt,
+        algorithm:     algo,
+
+        # e.g. key length may be too short
+        insecure_mode: ! has_iv || !! opts[:insecure_mode],
+      }
+
+      # puts "key was: #{key}"
+
+      if block_given?
+        # puts "wow yay block given."
+        cryptor_opts = yield cryptor_opts
+        # puts "new cryptor_opts is:"
+        # pp cryptor_opts
+      end
+
+      key = cryptor_opts[:key]
+
+      key = Base64.encode64(key) if opts.delete(:encode64_key)
+      key = Base64.decode64(key) if opts.delete(:decode64_key)
+
+      cryptor_opts[:key] = key
+
+      # puts "transcryptor#dec,opts=#{cryptor_opts.pretty_inspect}"
+
+      raise NoKeyException.new("encryption :key is nil") if key.nil?
+
+      # puts 'cryptor opts'
+      # pp cryptor_opts
+
+      {
+        value: ::Encryptor.decrypt(cryptor_opts)
+      }
+    end
+
+  end
+end

data/lib/transcryptor/version.rb

@@ -0,0 +1,3 @@
+module Transcryptor
+  VERSION = "0.1.0"
+end

data/transcryptor.gemspec

@@ -0,0 +1,38 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'transcryptor/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "transcryptor"
+  spec.version       = Transcryptor::VERSION
+  spec.authors       = ["Ribose Inc."]
+  spec.email         = ["open.source@ribose.com"]
+
+  spec.summary       = %q{Assists your everyday re-encryption needs, in Rails.}
+  spec.homepage      = "https://github.com/riboseinc/transcryptor"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise "RubyGems 2.0 or newer is required to protect against " \
+  #     "public gem pushes."
+  # end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "attr_encrypted", "~> 3.0"
+  spec.add_dependency "activerecord", "~> 4.0"
+
+  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: transcryptor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-07-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: attr_encrypted
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.adoc
+- Rakefile
+- bin/console
+- bin/setup
+- lib/transcryptor.rb
+- lib/transcryptor/version.rb
+- transcryptor.gemspec
+homepage: https://github.com/riboseinc/transcryptor
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Assists your everyday re-encryption needs, in Rails.
+test_files: []