precious_cargo 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.idea
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

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

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2012 Theodore Mills <twmills@twmills.com>
+
+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,52 @@
+# PreciousCargo
+
+Secure large (or small) amounts of data for transfer over web services
+
+### What is it?
+
+PreciousCargo encapsulates a specific best practice when encrypting large (or small) amounts of data, normally to transmit over the wire via a web service. The strategy is not really complex, but it wasn't readily apparent when I was looking for a solution. Therefore I wrote this gem to make it convenient to not only apply this strategy, but to also make this best practice more easily discovered (hopefully).
+
+### The Problem Case
+
+PK encryption is typically the preferred encryption method, but it suffers from the limitation that the size of data being encrypted cannot exceed the key size. To get around this approach, yet still take advantage of the excellent encryption method, the data is first encrypted with AES encryption using a secret passphrase. The secret passphrase is then encrypted using the public key from an RSA keychain and both the encrypted secret and encrypted data are sent together as part of the same payload to the client.
+
+The client decrypts the encrypted secret with their private key from the RSA key pair, then uses the decrypted secret to decrypt the AES encrypted data.
+
+The PreciousCargo module, therefore, provides convenience methods to encapsulate these multi-step encryption and decryption processes. Though it is possible to use a "shared secret" to encrypt the data, for extra security the encrypt method will generate a random secret passphrase if one is not explicitly provided.
+
+## Installation
+
+    gem install precious_cargo
+
+## Examples
+
+```ruby
+@data = "This is my precious cargo."
+@keypair = OpenSSL::PKey::RSA.new(2048)
+
+# With an auto-generated secret (the preferred method):
+@encrypted_payload = PreciousCargo.encrypt!(@data, :public_key => @keypair.public_key)
+#=> { :encrypted_data => [Base64 encoded string of encrypted data], :encrypted_secret => [Base64 encoded string of the encrypted secret] }
+
+PreciousCargo.decrypt!([Base64 encoded string of encrypted data], :keypair => @keypair, :encrypted_secret => [Base64 encoded string of the encrypted secret])
+#=> "This is my precious cargo."
+
+# With a supplied secret:
+@encrypted_payload = PreciousCargo.encrypt!(@data, :secret => 'p@assw0rD', :public_key => @keypair.public_key)
+#=> {:encrypted_data => [Base64 encoded string of encrypted data], :encrypted_secret => [Base64 encoded string of the encrypted secret]}
+
+PreciousCargo.decrypt!([Base64 encoded string of encrypted data], :keypair => @keypair, :encrypted_secret => [Base64 encoded string of the encrypted secret])
+#=> "This is my precious cargo."
+```
+
+## Dependencies
+
+* Ruby compiled with OpenSSL support.
+* The [gibberish gem](https://github.com/mdp/gibberish/).
+
+## How to run the tests
+
+    git clone https://github.com/twmills/precious_cargo.git
+    cd precious_cargo
+    bundle install
+    rspec

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/precious_cargo.rb

@@ -0,0 +1,83 @@
+require "gibberish"
+require "precious_cargo/version"
+require 'precious_cargo/secret'
+require 'precious_cargo/data'
+
+# Public: PreciousCargo encapsulates a specific best practice when encrypting large (or small) amounts of data, normally
+# to transmit over the wire via a web service.
+#
+# PK encryption is typically the preferred encryption method, but it suffers from the limitation that the size of data
+# being encrypted cannot exceed the key size. To get around this approach, yet still take advantage of the excellent
+# encryption method, the data is first encrypted with AES encryption using a secret passphrase. The secret passphrase is
+# then encrypted using the public key from an RSA keychain and both the encrypted secret and encrypted data are sent
+# together as part of the same payload to the client.
+#
+# The client decrypts the encrypted secret with their private key from the RSA key pair, then uses the decrypted
+# secret to decrypt the AES encrypted data.
+#
+# The PreciousCargo module, therefore, provides convenience methods to encapsulate these multi-step encryption and
+# decryption processes. Though it is possible to use a "shared secret" to encrypt the data, for extra security the
+# encrypt method will generate a random secret passphrase if one is not explicitly provided.
+#
+# Examples:
+#
+# @data = "This is my precious cargo."
+# @keypair = OpenSSL::PKey::RSA.new(2048)
+#
+# With an auto-generated secret (the preferred method):
+# @encrypted_payload = PreciousCargo.encrypt!(@data, :public_key => @keypair.public_key)
+# #=> { :encrypted_data => [Base64 encoded string of encrypted data], :encrypted_secret => [Base64 encoded string of the encrypted secret] }
+#
+# PreciousCargo.decrypt!([Base64 encoded string of encrypted data], :keypair => @keypair, :encrypted_secret => [Base64 encoded string of the encrypted secret])
+# #=> "This is my precious cargo."
+#
+# With a supplied secret:
+# @encrypted_payload = PreciousCargo.encrypt!(@data, :secret => 'p@assw0rD', :public_key => @keypair.public_key)
+# #=> {:encrypted_data => [Base64 encoded string of encrypted data], :encrypted_secret => [Base64 encoded string of the encrypted secret]}
+#
+# PreciousCargo.decrypt!([Base64 encoded string of encrypted data], :keypair => @keypair, :encrypted_secret => [Base64 encoded string of the encrypted secret])
+# #=> "This is my precious cargo."
+#
+module PreciousCargo
+
+  class << self
+
+    # Public: Encrypt the supplied data using ASES encryption with a secret pass phrase. The secret will also be
+    # encrypted using an RSA public key object. If a secret is not supplied, then a random secret is generated. It is
+    # generally better to randomly generate a secret every time you encrypt your precious cargo.
+    #
+    # data    - The data to be encrypted.
+    # options - Hash of values used to encrypt the data.
+    #           :secret     - Optional. A secret string. If a secret string is not passed in, then one is randomly
+    #                         generated.
+    #           :public_key - The RSA public key object used to encrypt the secret.
+    #
+    # Returns a hash containing the Base64 encoded encrypted data and Base64 encoded encrypted secret.
+    def encrypt!(data, options = {})
+      options[:secret]  = PreciousCargo::Secret.random unless options.has_key?(:secret)
+      encrypted_data    = PreciousCargo::Data.encrypt!(data, options)
+      encrypted_secret  = PreciousCargo::Secret.encrypt!(options)
+      { :encrypted_secret => encrypted_secret, :encrypted_data => encrypted_data }
+    end
+
+    # Public: Decrypt the supplied Base64 encoded encrypted data using the supplied Base64 encoded encrypted secret. The
+    # secret is first decrypted using the supplied RSA key pair object and is then used to decrypt the AES encrypted
+    # data. Optionally if the secret is known and shared, it can be supplied in lieu of the encrypted secret (though it
+    # rather defeats the purpose of this gem and may be removed at a later date).
+    #
+    # options - Hash of values used to decrypt the secret.
+    #           :encrypted_secret - A Base64 encoded, RSA encrypted secret string.
+    #           :keypair          - The RSA key pair object used to decrypt the secret.
+    #           :secret           - Optional. A plaintext shared secret.
+    #
+    # Returns the decrypted secret.
+    def decrypt!(data, options = {})
+      unless options.has_key?(:secret)
+        options[:secret] = PreciousCargo::Secret.decrypt!(options)
+      end
+
+      PreciousCargo::Data.decrypt!(data, options)
+    end
+  end
+
+end

data/lib/precious_cargo/data.rb

@@ -0,0 +1,34 @@
+module PreciousCargo
+
+  # Public: A collection of methods to encrypt and decrypt data using
+  # a supplied secret.
+  module Data
+    class << self
+
+      # Public: Encrypt the supplied data using a secret string. Currently only supports AES 256 encryption.
+      # data    - The data to be encrypted.
+      # options - Hash of values used to encrypt the secret.
+      #           :secret - A secret string.
+      #
+      # Returns the AES encrypted data.
+      def encrypt!(data, options = {})
+        secret = options[:secret]
+        cipher = Gibberish::AES.new(secret)
+        cipher.encrypt(data)
+      end
+
+      # Public: Decrypt the supplied data using a secret string. Currently only supports AES 256 encryption.
+      # data    - The data to be encrypted.
+      # options - Hash of values used to encrypt the secret.
+      #           :secret - A secret string.
+      #
+      # Returns the AES encrypted data.
+      def decrypt!(encrypted_data, options = {})
+        secret = options[:secret]
+        cipher = Gibberish::AES.new(secret)
+        cipher.decrypt(encrypted_data).strip
+      end
+    end
+  end
+
+end

data/lib/precious_cargo/secret.rb

@@ -0,0 +1,44 @@
+module PreciousCargo
+
+  # Public: A collection of methods to encrypt and decrypt the secret key used to encrypt the payload's data.
+  module Secret
+    class << self
+
+      # Public: Encrypt the supplied secret string using an RSA public key object. If a secret is not supplied, then a
+      # random secret is generated. It is generally better to randomly generate a secret every time you encrypt your
+      # precious cargo.
+      #
+      # options - Hash of values used to encrypt the secret.
+      #           :secret     - A secret string. If a secret string is not passed in, then one is randomly generated.
+      #           :public_key - The RSA public key object used to encrypt the secret.
+      #
+      # Returns the RSA encrypted secret as a Base64 encoded string.
+      def encrypt!(options = {})
+        secret = options[:secret]
+        public_key = options[:public_key]
+        Base64.encode64(public_key.public_encrypt(secret))
+      end
+
+      # Public: Decrypt the supplied Base64 encoded secret string using an RSA key pair object.
+      #
+      # options - Hash of values used to decrypt the secret.
+      #           :encrypted_secret - A Base64 encoded, RSA encrypted secret string.
+      #           :keypair          - The RSA key pair object used to decrypt the secret.
+      #
+      # Returns the decrypted secret.
+      def decrypt!(options = {})
+        encrypted_secret = Base64.decode64(options[:encrypted_secret])
+        keypair = options[:keypair]
+        keypair.private_decrypt(encrypted_secret)
+      end
+
+      # Public: Generates a random 32 character string.
+      #
+      # Returns random 32 character string.
+      def random
+        Array.new(32){rand(36).to_s(36)}.join
+      end
+    end
+  end
+
+end

data/lib/precious_cargo/version.rb

@@ -0,0 +1,3 @@
+module PreciousCargo
+  VERSION = "0.0.1"
+end

data/precious_cargo.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "precious_cargo/version"
+
+Gem::Specification.new do |s|
+  s.name        = "precious_cargo"
+  s.version     = PreciousCargo::VERSION
+  s.authors     = ["Theo Mills"]
+  s.email       = ["twmills@twmills.com"]
+  s.homepage    = "https://github.com/twmills/precious_cargo"
+  s.summary     = %q{Secure large (or small) amounts of data for transfer over web services.}
+  s.description = %q{PreciousCargo encapsulates a specific best practice when encrypting large (or small) amounts of data, normally to transmit over the wire via a web service. The strategy is not really complex, but it wasn't readily apparent when I was looking for a solution. Therefore I wrote this gem to make it convenient to not only apply this strategy, but to also make this best practice more easily discovered (hopefully).}
+
+  s.rubyforge_project = "precious_cargo"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {spec,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "faker"
+  s.add_runtime_dependency "gibberish"
+end

data/spec/core_spec.rb

@@ -0,0 +1,23 @@
+require "spec_helper"
+
+describe PreciousCargo, "#encrypt!" do
+
+  before do
+    @keypair = OpenSSL::PKey::RSA.new(2048)
+    @data = Faker::Lorem.paragraphs.join(" ")
+    @secret = "password"
+  end
+
+  it "encrypts and decrypts data with an auto-generated secret" do
+    payload = subject.encrypt!(@data, :public_key => @keypair.public_key)
+    unencrypted_data = subject.decrypt!(payload.delete(:encrypted_data), payload.merge(:keypair => @keypair))
+    unencrypted_data.should == @data
+  end
+
+  it "encrypts and decrypts data with supplied secret" do
+    payload = subject.encrypt!(@data, :public_key => @keypair.public_key)
+    unencrypted_data = subject.decrypt!(payload.delete(:encrypted_data), payload.merge(:keypair => @keypair))
+    unencrypted_data.should == @data
+  end
+
+end

data/spec/data_spec.rb

@@ -0,0 +1,26 @@
+require "spec_helper"
+
+describe PreciousCargo::Data do
+
+  before do
+    @keypair = OpenSSL::PKey::RSA.new(2048)
+    @data = Faker::Lorem.paragraphs.join(" ")
+    @secret = "password"
+  end
+
+  context "#encrypt!" do
+    it "encrypts data using the supplied secret" do
+      encrypted_data = subject.encrypt!(@data, :secret => @secret)
+      from_openssl = `echo "#{encrypted_data}" | openssl enc -d -aes-256-cbc -a -k password`
+      from_openssl.should == @data
+    end
+  end
+
+  context "#decrypt!" do
+    it "decrypts a secret using the supplied secret" do
+      from_openssl = `echo #{@data} | openssl enc -aes-256-cbc -a -k password`
+      subject.decrypt!(from_openssl, :secret => @secret).should == @data
+    end
+  end
+
+end

data/spec/secret_spec.rb

@@ -0,0 +1,40 @@
+require "spec_helper"
+
+describe PreciousCargo::Secret do
+
+  before do
+    @keypair = OpenSSL::PKey::RSA.new(2048)
+    @public_key = @keypair.public_key
+    @secret = "password"
+  end
+
+  context "#encrypt!" do
+    it "encrypts a secret using the supplied public key" do
+      options = {}
+      options[:secret] = @secret
+      options[:public_key] = @public_key
+      encrypted_secret = subject.encrypt!(options)
+      @keypair.private_decrypt(Base64.decode64(encrypted_secret)).should == @secret
+    end
+  end
+
+  context "#decrypt!" do
+    it "decrypts a secret using the supplied keypair" do
+      options = {}
+      options[:encrypted_secret] = Base64.encode64(@public_key.public_encrypt(@secret))
+      options[:keypair] = @keypair
+      subject.decrypt!(options).should == @secret
+    end
+  end
+
+  context "#random" do
+    it "generates a random string" do
+      subject.random.should_not == subject.random
+    end
+
+    it "generates a random string 32 characters long" do
+      subject.random.length.should == 32
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'faker'
+require 'bundler/setup'
+require 'precious_cargo'
+
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification 
+name: precious_cargo
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Theo Mills
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-22 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: faker
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: gibberish
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+description: PreciousCargo encapsulates a specific best practice when encrypting large (or small) amounts of data, normally to transmit over the wire via a web service. The strategy is not really complex, but it wasn't readily apparent when I was looking for a solution. Therefore I wrote this gem to make it convenient to not only apply this strategy, but to also make this best practice more easily discovered (hopefully).
+email: 
+- twmills@twmills.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/precious_cargo.rb
+- lib/precious_cargo/data.rb
+- lib/precious_cargo/secret.rb
+- lib/precious_cargo/version.rb
+- precious_cargo.gemspec
+- spec/core_spec.rb
+- spec/data_spec.rb
+- spec/secret_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/twmills/precious_cargo
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: precious_cargo
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Secure large (or small) amounts of data for transfer over web services.
+test_files: 
+- spec/core_spec.rb
+- spec/data_spec.rb
+- spec/secret_spec.rb
+- spec/spec_helper.rb