sym-crypt 1.0.0

data/.travis.yml

@@ -0,0 +1,23 @@
+language: ruby
+cache: bundler
+env:
+  CODECLIMATE_REPO_TOKEN=40b229d2d4857d67d832b6e0d5110537accb4e954961a8ce59beebf41e7d79b7
+rvm:
+- 2.2.7
+- 2.3.4
+- 2.4.1
+- jruby-9.1.9.0
+notifications:
+  email:
+    recipients:
+    on_success: change
+    on_failure: always
+  slack:
+    rooms:
+      secure: GcACCHmcmo99lYE5dgt2TmY4YIPMWr75q0Bkm4Lddegq/1eMXgcZDz00j8iHWtnveyJSjEUpZFQ9uyx+P7dvxT7D5gl43arKZEylS4vMRg9QRgZu7/ROrXbJtrUyKulFRUTdFrmOiK9nDKpAzlvLvMKC4kaQnn88Xtu9pYMU8y4n5fCtl29gZM9ZjVbrBBvV/SumnTDLla2oQ7oFgUZdZhQZ1qsevYknxNq4eIcvPDjbon+bovfsIISEVRSNo2C3yjO+mqWKed3jfuCA4taAZ8/aVVFEKURMH10HFms1CiC3lE/gF4YfBXsqKpjnB+bKjBcWox2FQrp96FulMEIfkKQrnuncO96o7MGHX9oNqKSMoycf3+SZFwNa+5Mfq7SBepbHYCoU7/ow31UTyStrc5idG19XzYgI85yjQHdzQN299Xf0O8cGf9q9qAu7rS7JlM3ekR+3rZYO+OxNYTF8rcW1fYIj6GKcbsV8BvuhAVQRFOsk/ibcIb2N7rGVd/ZbU4HAk3RE1ywt+XowinpIHktu2PQUPDNpgRQwM6xqZHO/7s9r7oW0ULmZCMLZ9CMKNjKzrQ9wfh90+v+FiEiUKsaVj4cCwF3PvhVYvxU2AKbCeHtSEb7K6to86+DYNoIKnGH1ryKoyCtyOTZpNMLGFt34Msv7WfEylhG+DpVMvkM=
+addons:
+  code_climate:
+    repo_token: 
+# regular test configuration
+after_success:
+  - bundle exec codeclimate-test-reporter

data/.yardopts

@@ -0,0 +1,4 @@
+--protected
+--no-private
+--embed-mixin ClassMethods
+--embed-mixin Sym::Crypt::Extensions::InstanceMethods

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright © 2016 Konstantin Gredeskoul, all rights reserved.
+
+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

@@ -0,0 +1,121 @@
+# SymCrypt
+
+## Simple Symmetric Encryption Using OpenSSL 
+
+[![Gem Version](https://badge.fury.io/rb/sym-crypt.svg)](https://badge.fury.io/rb/sym-crypt)
+[![Downloads](http://ruby-gem-downloads-badge.herokuapp.com/sym-crypt?type=total)](https://rubygems.org/gems/sym-crypt)
+
+[![Build Status](https://travis-ci.org/kigster/sym-crypt.svg?branch=master)](https://travis-ci.org/kigster/sym-crypt)
+[![Code Climate](https://codeclimate.com/github/kigster/sym-crypt/badges/gpa.svg)](https://codeclimate.com/github/kigster/sym-crypt)
+[![Test Coverage](https://codeclimate.com/github/kigster/sym-crypt/badges/coverage.svg)](https://codeclimate.com/github/kigster/sym-crypt/coverage)
+[![Issue Count](https://codeclimate.com/github/kigster/sym-crypt/badges/issue_count.svg)](https://codeclimate.com/github/kigster/sym-crypt)
+
+[![Gitter](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/kigster/sym)
+
+---
+
+### Summary
+
+The `sym-crypt` core library offers simple wrappers around OpenSSL with the following features:
+
+ * Symmetric data encryption with either:
+   1. A generated or supplied/known 256-bit key, and using the Cipher `AES-256-cBC`, which is the standard Cipher used by the US Government
+   2. A user-provided password is used to construct a 128-bit key, and then encrypt/decrypt  with the `AES-128-CBC` Cipher. 
+ * Automatic compression of the data upon encryption
+ * Automatic base64 encryption to make all encrypted strings fit onto a single line.
+ * This makes the format suitable for YAML or JSON configuration files, where only the values are encrypted.
+ * Note: the generated key is a *base64-encoded* string of about 45 characters long. The *decoded* key is always 32 characters (or 256 bytes) long.
+
+### Usage
+
+This library is a "wrapper" that allows you to take advantage of the
+symmetric encryption functionality provided by the {OpenSSL} gem (and the
+underlying C library). In order to use the library in your ruby classes, you
+should _include_ the module `Sym::Crypt`.
+
+Any class that includes `Sym::Crypt` is decorated with four instance methods `[:encr, :decr, :encr_password, :decr_password]`, and three class methods `[:create_private_key, :private_key, :private_key=]`.
+
+#### Symmetric Encryption with a 256-bit Private Key
+
+In the example below, we read a previously generated key from the environment variable. The key must be stored away from the data for obvious reasons.
+
+```ruby
+require 'sym/crypt'
+
+class TopSecret
+  include Sym::Crypt
+  # read the key from environmant variable and assign to this class.
+  private_key ENV['PRIVATE_KEY']
+
+  def sensitive_value=(value)
+    @sensitive_value = encr(value, self.class.private_key)
+  end
+
+  def sensitive_value
+    decr(@sensitive_value, self.class.private_key)
+  end
+end
+```
+
+#### Symmetric Encryption with a Password
+
+In this example we encrypt sensitive value with a provided password.  Password must not be nil or blank.
+
+```ruby
+require 'sym/crypt'
+
+class SensitiveStuff < Struct.new(:password)
+  include Sym::Crypt  
+  
+  def sensitive_value=(value)
+    @sensitive_value = encr_password(value, password)
+  end
+
+  def sensitive_value
+    decr_password(@sensitive_value, password)
+  end
+end
+```
+
+#### Generating an Encryption Key
+
+You can create a new key within any class that includes `Sym::Crypt` by calling the `#create_private_key` class method, which returns a new key every time it's called.
+ 
+ Classes that include `Sym::Crypt` are also decorated with a class instance variable `@private_key` and corresponding accessors `#private_key` and `#private_key=`. The writer assigns the key passed via the argument, while the reader returns a previously assigned key, or creates a new one, and assigns it. Subsequent calls will, thus, return the same key as the first call. 
+
+## 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.
+
+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`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+#### Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/kigster/sym-crypt](https://github.com/kigster/sym-crypt)
+
+### License
+
+**sym** and **sym-crypt** library is &copy; 2016-2017 Konstantin Gredeskoul.
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT). The library is designed to be a layer on top of [`OpenSSL`](https://www.openssl.org/), distributed under the [Apache Style license](https://www.openssl.org/source/license.txt).
+
+### Acknowledgements
+
+ * The blog post [(Symmetric) Encryption With Ruby (and Rails)](http://stuff-things.net/2015/02/12/symmetric-encryption-with-ruby-and-rails/) provided the inspiration for this gem. 
+ * We'd like to thank [Spike Ilacqua](http://stuff-things.net/spike/), the author of the [strongbox](https://github.com/spikex/strongbox) gem, for providing very easy-to-read code examples of symmetric encryption.
+
+#### Contributors:
+
+Contributions of any kind are very much welcome from anyone. 
+
+Any pull requests will be reviewed promptly. 
+
+Please submit feature requests, bugs, or donations :) 
+
+ * [Konstantin Gredeskoul](http:/kig.re) (primary developer)
+ * [Barry Anderson](https://twitter.com/z3ndrag0n) (sanity checking, review)
+
+ 
+

data/Rakefile

@@ -0,0 +1,28 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+def shell(*args)
+  puts "running: #{args.join(' ')}"
+  system(args.join(' '))
+end
+
+task :permissions do 
+  shell('rm -rf pkg/')
+  shell("chmod -v o+r,g+r * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/*")
+  shell("find . -type d -exec chmod o+x,g+x {} \\;")
+end
+
+task :build => :permissions
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = %w(lib/**/*.rb exe/*.rb - README.md LICENSE)
+  t.options.unshift('--title','"Sym – Symmetric Key Encryption for Your Data"')
+  t.after = ->() { exec('open doc/index.html') }
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'sym-crypt'
+
+# 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/sym/crypt.rb

@@ -0,0 +1,119 @@
+require 'zlib'
+require 'logger'
+
+require 'sym/crypt/configuration'
+require 'sym/crypt/version'
+require 'sym/crypt/errors'
+
+Sym::Crypt::Configuration.configure do |config|
+  config.password_cipher          = 'AES-128-CBC'
+  config.data_cipher              = 'AES-256-CBC'
+  config.private_key_cipher       = config.data_cipher
+  config.compression_enabled      = true
+  config.compression_level        = Zlib::BEST_COMPRESSION
+end
+
+require 'sym/crypt/extensions/class_methods'
+require 'sym/crypt/extensions/instance_methods'
+
+#
+# == Using Sym Library
+#
+# This library is a "wrapper" that allows you to take advantage of the
+# symmetric encryption functionality provided by the {OpenSSL} gem (and the
+# underlying C library). In order to use the library in your ruby classes, you
+# should _include_ the module {Sym}.
+#
+# The including class is decorated with four instance methods from the
+# module {Sym::Crypt::Extensions::InstanceMethods} and two class methods from
+# {Sym::Crypt::Extensions::ClassMethods} – for specifics, please refer there.
+#
+# The two main instance methods are +#encr+ and +#decr+, which as the name
+# implies, perform two-way symmetric encryption and decryption of any Ruby object
+# that can be +marshaled+.
+#
+# Two additional instance methods +#encr_password+ and +#decr_password+ turn on
+# password-based encryption, which actually uses a password to construct a 128-bit
+# long private key, and then uses that in the encryption of the data.
+# You could use them to encrypt data with a password instead of a randomly
+# generated private key.
+#
+# Create a new key with +#create_private_key+ class method, which returns a new
+# key every time it's called, or with +#private_key+ class method, which either
+# assigns, or creates and caches the private key at a class level.
+#
+# == Example
+#
+#     require 'sym/crypt'
+#
+#     class TestClass
+#       include Sym::Crypt
+#       # read the key from environmant variable and assign to this class.
+#       private_key ENV['PRIVATE_KEY']
+#
+#       def sensitive_value=(value)
+#         @sensitive_value = encr(value, self.class.private_key)
+#       end
+#
+#       def sensitive_value
+#         decr(@sensitive_value, self.class.private_key)
+#       end
+#     end
+#
+# == Private Key
+#
+# They private key can be generated by +TestClass.create_private_key+
+# which returns but does not store a new random 256-bit key.
+#
+# The key can be assigned and saved, or auto-generated and saved using the
+# +#private_key+ method on the class that includes the +Sym+ module.
+#
+# Each class including the +Sym+ module would get their own +#private_key#
+# class-instance variable accessor, and a possible value.
+#
+
+module Sym
+  module Crypt
+    NEW_CIPHER_PROC = ->(name) { ::OpenSSL::Cipher.new(name) }
+
+    def self.included(klass)
+      klass.instance_eval do
+        include ::Sym::Crypt::Extensions::InstanceMethods
+        extend ::Sym::Crypt::Extensions::ClassMethods
+        class << self
+          def private_key(value = nil)
+            if value
+              @private_key= value
+            elsif @private_key
+              @private_key
+            else
+              @private_key= self.create_private_key
+            end
+            @private_key
+          end
+        end
+      end
+    end
+
+    class << self
+      def config
+        Sym::Crypt::Configuration.config
+      end
+    end
+  end
+end
+
+
+
+class Object
+  unless self.methods.include?(:present?)
+    def present?
+      return false if self.nil?
+      if self.is_a?(String)
+        return false if self == ''
+      end
+      true
+    end
+  end
+end
+

data/lib/sym/crypt/cipher_handler.rb

@@ -0,0 +1,37 @@
+require 'base64'
+require 'sym/crypt'
+
+module Sym
+  module Crypt
+
+    # {Sym::Crypt::CipherHandler} contains cipher-related utilities necessary to create
+    # ciphers, and seed them with the salt or iV vector. It also defines the
+    # internal structure {Sym::Crypt::CipherHandler::CipherStruct} which is a key
+    # struct used in constructing cipher and saving it with the data packet.
+    module CipherHandler
+
+      CipherStruct = Struct.new(:cipher,
+                                :iv,
+                                :salt)
+
+      def create_cipher(direction:,
+                        cipher_name:,
+                        iv: nil,
+                        salt: nil)
+
+        cipher = NEW_CIPHER_PROC.call(cipher_name)
+        cipher.send(direction)
+        iv        ||= cipher.random_iv
+        cipher.iv = iv
+        CipherStruct.new(cipher, iv, salt)
+      end
+
+      def update_cipher(cipher, value)
+        data = cipher.update(value)
+        data << cipher.final
+        data
+      end
+    end
+  end
+end
+

data/lib/sym/crypt/configuration.rb

@@ -0,0 +1,44 @@
+module Sym
+  module Crypt
+    # This class encapsulates application configuration, and exports
+    # a familiar method +#configure+ for defining configuration in a
+    # block.
+    #
+    # It's values are requested by the library upon encryption or
+    # decryption, or any other operation.
+    #
+    # == Example
+    #
+    # The following is an actual initialization from the code of this
+    # library. You may override any of the value defined below in your
+    # code, but _before_ you _use_ library's encryption methods.
+    #
+    #       Sym::Crypt::Configuration.configure do |config|
+    #         config.password_cipher          = 'AES-128-CBC'
+    #         config.data_cipher              = 'AES-256-CBC'
+    #         config.private_key_cipher       = config.data_cipher
+    #         config.compression_enabled      = true
+    #         config.compression_level        = Zlib::BEST_COMPRESSION
+    #       end
+
+    class Configuration
+      class << self
+        attr_accessor :config
+
+        def configure
+          self.config ||= Configuration.new
+          yield config if block_given?
+        end
+
+        def property(name)
+          self.config.send(name)
+        end
+      end
+
+      # See file +lib/sym/crypt.rb+ where these values are defined.
+
+      attr_accessor :data_cipher, :password_cipher, :private_key_cipher
+      attr_accessor :compression_enabled, :compression_level
+    end
+  end
+end

data/lib/sym/crypt/data.rb

@@ -0,0 +1,24 @@
+require 'base64'
+require 'zlib'
+
+require 'sym/crypt/data/encoder'
+require 'sym/crypt/data/decoder'
+require 'sym/crypt/data/wrapper_struct'
+
+module Sym
+  module Crypt
+    # This module is responsible for taking arbitrary data of any format, and safely compressing
+    # the result of `Marshal.dump(data)` using Zlib, and then doing `#urlsafe_encode64` encoding
+    # to convert it to a string,
+    module Data
+      def encode(data, compress = true)
+        Encoder.new(data, compress).data_encoded
+      end
+
+      def decode(data_encoded, compress = nil)
+        Decoder.new(data_encoded, compress).data
+      end
+    end
+  end
+end
+