Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A strategy to secure large (or small) amounts of data for transfer over web services.
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.gitignore
.rspec
Gemfile
LICENSE
README.md
Rakefile
precious_cargo.gemspec

README.md

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

@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

How to run the tests

git clone https://github.com/twmills/precious_cargo.git
cd precious_cargo
bundle install
rspec
Something went wrong with that request. Please try again.