claude 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4f93a597f1c7aa21cff1a1a6ab4e80d4cef5e3b1
+  data.tar.gz: d8175164c88064ab63d2568a627a6d645bac5f43
+SHA512:
+  metadata.gz: 5ca58757778303242d21495ba62f6c6f49832c3db192b08cc2ee03849b921437207f980fb6a1817912fe1ab945da13a7706b13718ddb49b12c35131d0910575d
+  data.tar.gz: 16f4e73089ce52ce20b2b29b4f78e7f4ee4b20969d91fe55e37e82d8ca3da0832bc2100e842b7d677a72fe2837b8da10eb1da65807a87fe7b27fb64d2d6e0946

data/.gitignore

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

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.2

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,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'sqlite3'
+gem 'byebug'
+
+gem "bundler", "~> 1.9"
+gem "rake",    "~> 10.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Genadi Samokovarov
+
+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,67 @@
+# Claude
+
+Claude transparently encrypts and decrypts sensitive Active Record attributes.
+Nothing magical or fancy, just a simple `OpenSSL::Cipher` wrapper.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'claude'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+## Usage
+
+Say, you have to store sensitive information in your application database. You
+can use `OpenSSL::Cipher` to manually encrypt the value with a secret on write,
+and decrypt it with the same secret when used throughout the code base. This
+may work for a single sensitive attribute, but it gets out of hand if you gotta
+do it regularly.
+
+Claude wraps `OpenSSL::Cipher` and lets you transparently encrypt and decrypt
+the your application sensitive attributes, so you don't have to do it manually
+all the time.
+
+Claude exposes the `encrypt` and `attr_encrypt` class macros to setup an
+attribute encryption.
+
+```ruby
+class Card < ActiveRecord::Base
+  encrypt :pin
+end
+
+>> card = Card.new(pin: "1234")
+=> #<Card id: nil, encrypted_pin: "FNYLjh2q9tWcYH5lG0zkPQ==\n", encrypted_pin_iv: "e4E99V82noXFLHhCfcWwBw==\n">
+>> card.pin
+=> "1234"
+```
+
+The encrypted `pin` dynamic attribute is backed by two database columns.
+`encrypted_pin` and `encrypted_pin_iv`. You have to create them by a migration,
+before using Claude.
+
+The default secret used to encrypt an attribute with is `config.secret_token`
+for Rails 3.2 and `secrets.secret_key_base` for Rails 4. You can use per
+attribute secret or a different global one by setting `config.claude.secret` to
+your likings. Changing it will invalidate all the current encryptions, so
+beware of that.
+
+Read the [`ActiveRecord::Base.encrypt`](https://github.com/gsamokovarov/claude/blob/75d72de1b3fb0f784133b057914d87bdf23a2d4a/lib/claude/extensions.rb#L6-L41)
+and [`ActiveRecord::Base.attr_encrypt`](https://github.com/gsamokovarov/claude/blob/75d72de1b3fb0f784133b057914d87bdf23a2d4a/lib/claude/extensions.rb#L71-L80)
+API documentation for more information.
+
+# Why Claude?
+
+The library is named after [Claude Elwood Shannon]. He is considered to be the
+father of the modern mathematical cryptography.
+
+Why should you use it? Because it makes encryption simple. :-)
+
+[Claude Elwood Shannon]: https://en.wikipedia.org/wiki/Claude_Shannon

data/Rakefile

@@ -0,0 +1,33 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Claude'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+
+load 'rails/tasks/engine.rake'
+load 'rails/tasks/statistics.rake'
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "claude"
+
+# 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/claude.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'claude/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "claude"
+  spec.version       = Claude::VERSION
+  spec.authors       = ["Genadi Samokovarov"]
+  spec.email         = ["gsamokovarov@gmail.com"]
+
+  spec.summary       = "Claude transparently encrypts and decrypts sensitive Active Record attributes."
+  spec.description   = "Claude transparently encrypts and decrypts sensitive Active Record attributes."
+  spec.homepage      = "https://github.com/gsamokovarov/claude"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  rails_version = ">= 3.2"
+
+  spec.add_dependency "railties",     rails_version
+  spec.add_dependency "activerecord", rails_version
+
+  spec.add_development_dependency "rails", rails_version
+end

data/lib/claude.rb

@@ -0,0 +1,18 @@
+require 'claude/version'
+require 'claude/coder'
+require 'claude/railtie'
+
+module Claude
+  # Used to encrypt and decrypt attributes with.
+  mattr_accessor :secret
+
+  # The OpenSSL::Cipher used for the encryption.
+  mattr_accessor :ssl_cipher
+  self.ssl_cipher = 'AES-256-CBC'
+
+  # The coder is used to encode decode the keys and ivs to DB string column
+  # friendly characters. Base64 encoding by default.
+  mattr_accessor :coder
+  self.coder = Coder
+end
+

data/lib/claude/cipher.rb

@@ -0,0 +1,57 @@
+require 'claude/openssl_cipher_builder'
+require 'claude'
+
+module Claude
+  class Cipher
+    class UnsupportedModeError < StandardError
+      def initialize(mode)
+        super("Unsupported mode #{mode}")
+      end
+    end
+
+    class << self
+      def for_encryption(key, iv)
+        builder = OpenSSLCipherBuilder.new(key, iv)
+        mode    = :encrypt
+
+        new(builder.build(mode), mode)
+      end
+
+      def for_decryption(key, iv)
+        builder = OpenSSLCipherBuilder.new(key, iv)
+        mode    = :decrypt
+
+        new(builder.build(mode), mode)
+      end
+    end
+
+    def initialize(cipher, mode, coder = Claude.coder)
+      @cipher = cipher
+      @mode   = mode
+      @coder  = coder
+    end
+
+    def encrypt(value)
+      crypt(value)
+    end
+
+    def decrypt(value)
+      crypt(value)
+    end
+
+    private
+
+    attr_reader :cipher, :mode, :coder
+
+    def crypt(value)
+      case mode
+      when :encrypt
+        coder.encode(cipher.update(value) + cipher.final)
+      when :decrypt
+        cipher.update(coder.decode(value)) + cipher.final
+      else
+        raise UnsupportedModeError, mode
+      end
+    end
+  end
+end

data/lib/claude/coder.rb

@@ -0,0 +1,18 @@
+module Claude
+  # The coder interface is implemented by any object responding to #encode and
+  # #decode.
+  #
+  # The current implementation defaults to Base64 encoding and decoding as the
+  # characters are friendly for RDBMS string types.
+  module Coder
+    extend self
+
+    def encode(value)
+      Base64.encode64(value)
+    end
+
+    def decode(value)
+      Base64.decode64(value)
+    end
+  end
+end

data/lib/claude/extensions.rb

@@ -0,0 +1,89 @@
+require 'claude/random_iv'
+require 'claude/cipher'
+
+module Claude
+  module Extensions
+    # Encrypt the value stored at attr when persisting the value in the
+    # underlying database.
+    #
+    # To encrypt an attr we need to have two extra columns named:
+    #
+    #   * encrypted_attr    - Used internally to store the encrypted value.
+    #   * encrypted_attr_iv - Used internally to encrypt the value above.
+    #
+    # Note that attr is dynamic here. If you wanna encrypt the attribute pin:
+    #
+    #   class Card < ActiveRecord::Base
+    #     encrypt :pin
+    #   end
+    #
+    # The expected columns will be named encrypted_pin and encrypted_pin_iv.
+    #
+    # Encrypt will generate two new instance methods: attr and attr=. Those
+    # are dynamic and compute its value based of encrypted_attr and
+    # decrypted_attr.
+    #
+    # attr decrypt the value from the encrypted_attr.
+    # attr= encrypts the value that is passed to it and saves it to encrypted_attr.
+    #
+    # Most of the time, you won't need to call encrypted_attr and
+    # encrypted_attr_iv manually. Consider them an implementation detail.
+    #
+    # You can pass the following options:
+    #
+    #   * :attr    - The name of the internal encrypted column.
+    #                Defaults to "encrypted_#{attr}".)
+    #
+    #   * :attr_iv - The name of the internal initialization vector column.
+    #                Defaults to "encrypted_#{attr}_iv".
+    #
+    #   * :secret  - The secret used to encrypt the attribute.
+    #                Defaults to config.secret_roken or config.secrets.secret_token.
+    def encrypt(attr, options = {})
+      attr_secret   = options.fetch(:secret, Claude.secret).inspect
+      attr_internal = options.fetch(:attr, "encrypted_#{attr}")
+      attr_iv       = options.fetch(:attr_iv, "encrypted_#{attr}_iv")
+      attr_raw      = "#{attr_internal}_before_type_cast"
+
+      module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{attr}
+          return unless #{attr_raw}
+
+          cipher = Cipher.for_decryption(#{attr_secret}, #{attr_iv})
+          cipher.decrypt(#{attr_raw})
+        end
+
+        def #{attr}=(value)
+          if value
+            iv     = RandomIV.generate
+            cipher = Cipher.for_encryption(#{attr_secret}, iv)
+
+            self.#{attr_iv}       = iv
+            self.#{attr_internal} = cipher.encrypt(value)
+          else
+            self.#{attr_iv}       = nil
+            self.#{attr_internal} = nil
+          end
+        end
+      RUBY
+    end
+
+    # An alias to encrypt that lets you encrypt multiple attributes at once.
+    #
+    # If only one attribute is given, it acts exactly like encrypt does.
+    #
+    # When multiple attributes are given, you can still give options. However,
+    # the :attr and :attr_iv options will be the same for all the attributes.
+    #
+    #   class Card < ActiveRecord::Base
+    #     attr_encrypt :pin, :pan
+    #   end
+    def attr_encrypt(*attrs)
+      options = attrs.extract_options!
+
+      attrs.each do |attr|
+        encrypt attr, options
+      end
+    end
+  end
+end

data/lib/claude/openssl_cipher_builder.rb

@@ -0,0 +1,33 @@
+require 'openssl'
+require 'digest'
+require 'claude'
+
+module Claude
+  class OpenSSLCipherBuilder
+    def initialize(key = nil, iv = nil, ssl_cipher = Claude.ssl_cipher)
+      @key        = key && key.to_s
+      @iv         = hash_if_too_short(iv)
+      @ssl_cipher = ssl_cipher
+    end
+
+    def build(mode)
+      OpenSSL::Cipher.new(ssl_cipher).tap do |cipher|
+        cipher.public_send(mode)
+
+        cipher.key = key if key
+        cipher.iv  = iv  if iv
+      end
+    end
+
+    private
+
+    attr_reader :key, :iv, :ssl_cipher
+
+    # When passing a custom IV column, it can be too short for OpenSSL to work
+    # with. Make sure it isn't.
+    def hash_if_too_short(iv)
+      return if iv.nil?
+      iv.size < 16 ? Digest::SHA1.hexdigest(iv.to_s) : iv.to_s
+    end
+  end
+end

data/lib/claude/railtie.rb

@@ -0,0 +1,23 @@
+require 'claude/extensions'
+
+module Claude
+  class Railtie < ::Rails::Railtie
+    config.claude = Claude
+
+    initializer 'claude.active_record' do
+      ActiveRecord::Base.send(:extend, Extensions)
+    end
+
+    initializer 'claude.default_secret' do |app|
+      # Rails 3 keeps the default secret token Rails.application.config.
+      if config.respond_to?(:secret_token)
+        config.claude.secret ||= config.secret_token
+      end
+
+      # Rails 4 keeps them in Rails.application.secrets.
+      if app.respond_to?(:secrets)
+        config.claude.secret ||= app.secrets.secret_token || app.secrets.secret_key_base
+      end
+    end
+  end
+end

data/lib/claude/random_iv.rb

@@ -0,0 +1,32 @@
+require 'claude'
+require 'claude/openssl_cipher_builder'
+
+module Claude
+  class RandomIV
+    # A shortcut for RandomIV.new(Claude.coder).generate.
+    def self.generate
+      new.generate
+    end
+
+    def initialize(coder = Claude.coder)
+      @coder = coder
+    end
+
+    # Generates a secure random Initialization Vector that can be used for
+    # OpenSSL encryption and decryption.
+    #
+    # It is encoded by a coder, so the IV consists of DB friendly characters.
+    def generate
+      coder.encode(cipher.random_iv)
+    end
+
+    private
+
+    attr_reader :coder
+
+    def cipher
+      builder = OpenSSLCipherBuilder.new
+      builder.build(:encrypt)
+    end
+  end
+end

data/lib/claude/version.rb

@@ -0,0 +1,3 @@
+module Claude
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: claude
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Genadi Samokovarov
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-08-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: Claude transparently encrypts and decrypts sensitive Active Record attributes.
+email:
+- gsamokovarov@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- claude.gemspec
+- lib/claude.rb
+- lib/claude/cipher.rb
+- lib/claude/coder.rb
+- lib/claude/extensions.rb
+- lib/claude/openssl_cipher_builder.rb
+- lib/claude/railtie.rb
+- lib/claude/random_iv.rb
+- lib/claude/version.rb
+homepage: https://github.com/gsamokovarov/claude
+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.5
+signing_key: 
+specification_version: 4
+summary: Claude transparently encrypts and decrypts sensitive Active Record attributes.
+test_files: []