hash_redactor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: afc446801a4d9742e40d28954ed609b4cd58aad3
+  data.tar.gz: c959b0bd8e2c8c4193bb2526423ab46ba4495982
+SHA512:
+  metadata.gz: 74b7d907b37f7855c16a45aecc4bd4b6102a2ffb9a2516765a623fc3b7339c805c14b6baa73f20560890c64efaa86ccf9dd6520221c52c14f917c800dfad51ba
+  data.tar.gz: 14cefa25e6f0ed169952e35910d5080ce519d49d5a12467a04350773d297926e16c6c9573e4ab6532444d16b2371002bfd36c8b7e6482b55947e5871b97d95f1

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,13 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3.0
+  - rbx
+matrix:
+  exclude:
+  allow_failures:
+    - rvm: rbx
+  fast_finish: true

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+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. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Chris Jensen
+
+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

@@ -0,0 +1,147 @@
+# HashRedactor
+
+Used to redact a hash by removing, digesting or encrypting keys.
+
+Makes use of [`attr_encrypted`](https://github.com/attr-encrypted/attr_encrypted) to perform encryption.
+
+Useful if you have large JSON objects or similar that are coming in through API calls or elsewhere and you want to scrub the private data before storing it to the database.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hash_redactor'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hash_redactor
+
+## Usage
+
+Initialize the HashRedactor with a set of fields that you want to redact in hashes that get passed to it. 
+
+You can choose 3 ways to redact each field:
+
++ `:remove` - The field is simply deleted
++ `:digest` - The field is passed through a one way hash function (SHA256)
++ `:encrypt` - The field is encrypted
+
+If you plan on using digest or encrypt, then you will need to specify `:digest_salt` or `:encryption_key` respectively in the options.
+
+```ruby
+fields_to_redact = {
+	:ssn => :remove,
+	:email => :digest,
+	:medical_history => :encrypt
+} 
+
+redactor = HashRedactor::HashRedactor.new({
+	redact: fields_to_redact,
+	encryption_key: 'a really secure key no one will ever guess it',
+	digest_salt: 'a secret salt'
+})
+```
+
+Once initialized, you can simply call `#redact` on hashes of data.
+If a key you have specified to redact is missing, HashRedactor will silently ignore it's absence.
+Any key's not specified in your redact hash will be left unchanged.
+
+
+```ruby
+raw_data = {
+	ssn: 'a very personal number',
+	email: 'personal@email.com',
+	medical_history: 'Some very private information'
+	plaintext: 'This will never be changed'
+}
+
+safe_data = redactor.redact(raw_data)
+
+safe_data[:ssn] # nil
+safe_data[:email_digest] # One way hash of the email
+safe_data[:encrypted_medical_history] # Encrypted medical history
+safe_data[:plaintext] # This will never be changed
+```
+
+To retrieve your encrypted data, pass it through decrypt.
+
+```ruby
+loaded_data = redactor.decrypt(safe_data)
+loaded_data[:medical_history] # 'Some very private information'
+```
+
+## Digest method
+
+Digest may be used in cases where you don't want to keep the data due to privacy concerns, but want to compare it.
+For example, maybe you have a large database of people whom you never need to contact by email, but you want to use the email address to check for duplicates.
+
+To enhance protection of the data you should provide a salt in the configuration options and you should not store that salt in your database.
+
+Once the field has been digested, it's key will have _digest appended.
+
+## Encrypt method
+
+Encryption is for fields that you do need to recover, but don't want to store in plaintext in the database.
+
+[`attr_encrypted`](https://github.com/attr-encrypted/attr_encrypted) is used to perform encryption.
+
+Once the field has been encrypted, the original field is removed from the hash, and replaced with `:encrypted_FIELDNAME` and `:encrypted_FIELDNAME_iv` - both these fields must be present in the hash for decrypt to succeed.
+
+For example, if the field you want to encrypt has the key `:email`, then the redacred hash will have the keys `:encrypted_email` and `:encrypted_email_iv`.
+
+## Redacted Hash
+
+From the example above, after running #redact, the safe_data hash would look something like this:
+
+```ruby
+{
+	:email_digest=>"VXJsQeG81HYWOb30XfpBdbqEFH1f4VaFLTqHCdxCmj8=", :encrypted_medical_history=>"2JIN3Yhxvm/m7qlE+n4pMT9yckXuPa+2IlMBFQMcbP1pcwyrG7wy0TP4scgx\n",
+	:encrypted_medical_history_iv=>"tqMQa1aYTdJuMhrD\n",
+	:plaintext => 'This will never be changed'
+}
+```
+
+## Options
+
+Default options are:
+```ruby
+  	  	  digest_salt: 		 "",
+		  encryption_key:	 nil,
+		  encode:            true,
+		  encode_iv:         true,
+		  default_encoding:  'm'
+```
+
+### :digest_salt
+
+Salt to use when applying digest method
+
+### :encryption_key
+
+Key to use for encryption and decryption of values
+
+### :encode, :encode_iv, :default_encoding
+
+Determines how (if at all) to encode the encrypted data and it's iv
+
+The default encoding is m (base64). You can change this by setting encode: `'some encoding'`. See [Arrary#pack](http://ruby-doc.org/core-2.3.0/Array.html#method-i-pack) for more encoding options.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/chrisjensen/hash_redactor/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require File.join('bundler', 'gem_tasks')
+require File.join('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 "hash_redactor"
+
+# 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,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/hash_redactor.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hash_redactor/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hash_redactor"
+  spec.version       = HashRedactor::VERSION
+  spec.authors       = ["Chris Jensen"]
+  spec.email         = ["chris@broadthought.co"]
+
+  spec.summary       = %q{Redact specified values in a hash}
+  spec.description   = %q{Removes, digests or encrypts selected values in a ruby hash}
+  spec.homepage      = "https://github.com/chrisjensen/hash_redactor"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency 'attr_encrypted', '~> 3.0.0'
+
+  spec.add_development_dependency "bundler", "~> 1.8"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency 'rspec', '~> 2.14'
+end

data/lib/hash_redactor/hash_redactor.rb

@@ -0,0 +1,117 @@
+require 'attr_encrypted'
+
+module HashRedactor
+  class HashRedactor
+	  def initialize(opts = {})
+		@options = default_options.merge opts
+
+		@options[:encode] = @options[:default_encoding] if @options[:encode] == true
+		@options[:encode_iv] = @options[:default_encoding] if @options[:encode_iv] == true
+	  end
+  
+  	  def default_options
+  	  	{
+  	  	  digest_salt: 		 "",
+		  encryption_key:	 nil,
+		  encode:            true,
+		  encode_iv:         true,
+		  default_encoding:  'm'
+  	  	}
+  	  end
+  
+	  # Removes, digests or encrypts fields in a hash
+	  # NOTE: This should NOT be used to protect password fields or similar
+	  # The purpose of hashing is to reduce data to a form that can be *quickly*
+	  # compared against other records without revealing the original value.
+	  # To allow for this, all hashes are created using the *same salt* which is
+	  # not secure enough for password protection
+	  # For passwords, use BCrypt
+	  def redact(data, opts = {})
+	    options = @options.merge(opts)
+	    
+  		redact_hash = options[:redact]
+  		
+  		raise "Don't know what to redact. Please configure the redact hash when initializing or pass as an argument to redact." unless redact_hash && redact_hash.any?
+  
+		result = data.clone
+  
+		redact_hash.each do |hash_key,how|
+		  if data.has_key? hash_key
+			case how
+			  when :remove
+				nil
+			  when :digest
+				result_key = (hash_key.to_s + '_digest').to_sym
+
+				result[result_key] = Digest::SHA256.base64digest(
+											result[hash_key] + options[:digest_salt])
+			  when :encrypt
+				raise "No encryption key specified. Please pass :encryption_key in options to new or redact" unless options[:encryption_key]
+			  
+				crypt_key = options[:encryption_key]
+				iv = SecureRandom.random_bytes(12)
+				data_key = ('encrypted_' + hash_key.to_s).to_sym
+				iv_key = ('encrypted_' + hash_key.to_s + '_iv').to_sym
+			
+				encrypted_value = EncryptorInterface.encrypt(:data, result[hash_key], iv: iv, key: crypt_key)
+				
+				encrypted_value = [encrypted_value].pack(options[:encode]) if options[:encode]
+				iv = [iv].pack(options[:encode_iv]) if options[:encode_iv]
+			
+				result[data_key] = encrypted_value
+				result[iv_key] = iv
+			  else
+				raise "redact called with unknown operation on #{hash_key.to_s}: #{how.to_s}"
+			end
+
+			result.delete hash_key
+		  end
+		end
+  
+		result
+	  end
+
+	  def decrypt(data, opts = {})
+	    options = @options.merge opts
+
+  		redact_hash = options[:redact]
+
+  		raise "Don't know what to decrypt. Please configure the redact hash when initializing or pass as an argument to #decrypt." unless redact_hash && redact_hash.any?
+
+		raise "No encryption key specified. Please pass :encryption_key in options to new or decrypt" unless options[:encryption_key]
+  
+		result = data.clone
+  
+		redact_hash.each do |hash_key,how|
+		  if (how == :encrypt)
+			data_key = ('encrypted_' + hash_key.to_s).to_sym
+			iv_key = ('encrypted_' + hash_key.to_s + '_iv').to_sym
+
+			if (data.has_key? data_key)
+			  iv = result[iv_key]
+			  crypt_key = options[:encryption_key]
+
+			  encrypted_value = result[data_key]
+
+			  # Decode if necessary
+			  iv = iv.unpack(options[:encode_iv]).first if options[:encode_iv]
+			  encrypted_value = encrypted_value.unpack(options[:encode]).first if options[:encode]
+
+			  decrypted_value = EncryptorInterface.decrypt(:data, encrypted_value,
+				   iv: iv, key: crypt_key)
+		
+			  result[hash_key] = decrypted_value
+			end
+		  end
+		end
+  
+		result
+	  end
+  end
+
+  class EncryptorInterface
+    extend AttrEncrypted
+    
+    attr_encrypted :data
+  end
+end

data/lib/hash_redactor/version.rb

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

data/lib/hash_redactor.rb

@@ -0,0 +1,2 @@
+require File.join('hash_redactor', 'hash_redactor')
+

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: hash_redactor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Jensen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-07-05 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.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !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: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+description: Removes, digests or encrypts selected values in a ruby hash
+email:
+- chris@broadthought.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- hash_redactor.gemspec
+- lib/hash_redactor.rb
+- lib/hash_redactor/hash_redactor.rb
+- lib/hash_redactor/version.rb
+homepage: https://github.com/chrisjensen/hash_redactor
+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.4.6
+signing_key: 
+specification_version: 4
+summary: Redact specified values in a hash
+test_files: []