crypto_env_var 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4c377692700f1b2c90560712d95d1e75759e6081
+  data.tar.gz: 5bbbbbb5acaaac302b139763eb1a6c33623e666b
+SHA512:
+  metadata.gz: afe175462500360433166c587d568d75623f8a68d2dbe284dd274a5db678ed1710e4ca1f0e8ef20c83298192029701226c270cc28ae6ae39a8085bc7d490a931
+  data.tar.gz: c2b1d0bd66ce7980fb91d1752f25cd71b6b0d3e03f4097186c68e21e8cee7aa1a3e7d3e822b97ccb82867654d91f57687b182145e910254c7fad7222dc006d05

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,12 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4
+  - 2.3
+  - 2.2
+script: "rspec"
+before_install: gem install bundler -v 1.15.4
+notifications:
+  email:
+    on_success: never
+    on_failure: never

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CryptoEnvVar Changelog
+
+## v1.0.0
+
+* Initial release
+* Asymmetric encryption and decryption functions
+* Helper to seed the ENV of the current Ruby process with an encrypted payload.

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in crypto_env_var.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2017 Tommaso Pavese
+
+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,159 @@
+# CryptoEnvVar
+
+[![Build Status](https://travis-ci.org/deliveroo/crypto_env_var.svg?branch=master)](https://travis-ci.org/deliveroo/crypto_env_var)
+
+**CryptoEnvVar** provides:
+
+* [Asymmetric encryption](#asymmetric-encryption) of JSON-serializable Ruby objects using a RSA keypair.
+* [Secrets management for the Ruby ENV](#secrets-management-for-the-ruby-env).
+
+## Asymmetric Encryption
+
+The gem provides two functions that can be used on their own, even without the ENV management functionality.
+
+Any Ruby object that can be serialized and deserialized with `JSON.dump` nd `JSON.load` is a valid input. This means that you can use a Hash, but that symbols won't be preserved. The output is a base64-encoded string, safe to be stored and transferred as text.
+
+```ruby
+rsa_private_key_string = File.read("path/to/rsa_key.pem")
+rsa_public_key_string  = File.read("path/to/rsa_key.pub.pem")
+
+data = { "foo" => 42, "bar" => [1, 3, 3, 7], "baz" => true }
+
+ciphertext = CryptoEnvVar.encrypt(data, rsa_private_key_string)
+plaintext  = CryptoEnvVar.decrypt(ciphertext, rsa_public_key_string)
+
+data == plaintext # true
+```
+
+While the public key can only be used to decrypt, the private key can be used to both encrypt and decrypt:
+
+```ruby
+a = CryptoEnvVar.decrypt(encrypted, rsa_private_key_string)
+b = CryptoEnvVar.decrypt(encrypted, rsa_public_key_string)
+
+a == b && a == data # true
+```
+
+## Secrets management for the Ruby ENV
+
+A common practice when deploying applications is to customize their runtime behaviour by providing configuration in the system ENV.
+
+Often this means that something, at some point, needs to get the raw configuration values and set them on the machine (or container, or Heroku dyno) that will run the application. Since the configuration usually contains sensitive values, for example database passwords and other auth credentials, this is less than ideal.
+
+A solution is to encrypt the configuration data, set it in the ENV encrypted, and then allow the application to decrypt it when it boots. This library aims to make this pattern easier to adopt.
+
+First off, the app configuration needs to be encrypted. This should ideally be done by an automated tool. For example:
+
+```ruby
+app_config = {
+  "DB_URL" => "postgres://user:password123@thedb.hostname.com:1234/db_name",
+  "CACHE_URL" => "redis://user:password456@another.url.com:5678",
+  "PAYMENTS_GATEWAY_API_TOKEN" => "SECRET_TOKEN_ZOMG",
+}
+
+private_key = File.read("path/to/rsa_key.pem")
+
+File.write("encrypted_env.txt",  CryptoEnvVar.encrypt(app_config, private_key))
+```
+
+Done that, the encrypted configuration and the public key need to be passed to the starting application. By default, `CryptoEnvVar` will try to read them from two ENV variables:
+
+```
+export CRYPTO_ENV='the base64 encrypted configuration generated above'
+export CRYPTO_ENV_DECRYPT_KEY='the public key'
+
+ruby my_app.rb
+```
+
+If you choose the default names, then all you need to do is call `CryptoEnvVar.bootstrap!` early in the application initialization process (for example in `config.ru` for a Rack app), and it will load and decrypt the encrypted env, then copy its data into the `ENV` of the current process.
+
+```ruby
+ENV["DB_URL"]
+# => nil
+
+CryptoEnvVar.bootstrap!
+
+ENV["DB_URL"]
+# => "postgres://user:password123@thedb.hostname.com:1234/db_name"
+```
+
+
+The sources of both the encrypted configuration and the public key can be configured with the `:read_from` and `:decrypt_with` options, respectively. Valid values are strings or callable objects (you can use a proc or lambda or you can implement your own loaders). For example:
+
+```ruby
+CryptoEnvVar.bootstrap!(
+  read_from: -> { File.read(ENV["secrets_file_path"]).chomp },
+  decrypt_with: SecurePublicKeyFetcher.new
+)
+
+class SecurePublicKeyFetcher
+  def call
+    # ...
+  end
+end
+```
+
+
+By default `CryptoEnvVar.bootstrap!` will copy all the decrypted configuration variables into the ENV, overriding any preset value. If you want to disable this, for example because you want any explicitly set ENV variable to have the precence, you can do so with this option:
+
+```ruby
+CryptoEnvVar.bootstrap!(override_env: false)
+```
+
+
+## A note on the RSA keypairs
+
+Only keypairs without passphrase are supported at this stage.
+
+You can create an RSA keypair in a shell with:
+
+```
+openssl genrsa -out private_key.pem 2048
+openssl rsa -pubout -in private_key.pem -out public_key.pem
+```
+
+Please note that the public key is **NOT** the same thing as the SSH public key file [normally generated with `ssh-keygen`](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/). You can still use a private RSA key generated with `ssh-keygen`, but then you have to extract the public key with the `openssl` command shown above.
+
+Alternatively, you can use the [OpenSSL classes](http://ruby-doc.org/stdlib-2.4.1/libdoc/openssl/rdoc/OpenSSL/PKey/RSA.html) from the Ruby standard library:
+
+```ruby
+require "openssl"
+
+new_keypair     = OpenSSL::PKey::RSA.generate(2048)
+new_private_key = new_keypair.to_s
+new_public_key  = new_keypair.public_key.to_s
+
+imported_keypair     = OpenSSL::PKey::RSA.new(File.read("private_rsa_key.pem"))
+imported_private_key = imported_keypair.to_s
+imported_public_key  = imported_keypair.public_key.to_s
+
+imported_private_key == File.read("private_rsa_key.pem") # true
+```
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'crypto_env_var'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install crypto_env_var
+
+
+## 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/[USERNAME]/crypto_env_var.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "pry"
+
+require "crypto_env_var"
+
+require File.expand_path("../../spec/support/shared_helpers.rb", __FILE__)
+include SharedHelpers
+
+Pry.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/crypto_env_var.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "crypto_env_var/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "crypto_env_var"
+  spec.version       = CryptoEnvVar::VERSION
+  spec.authors       = ["Tommaso Pavese"]
+  spec.email         = ["tommaso.pavese@deliveroo.co.uk"]
+
+  spec.summary       = %q{Utilities to protect the application env}
+  spec.description   = <<-EOS
+  Utilities to protect the application env.
+  Use an keypair to encrypt an env Hash to a blob and populate ENV from the encryped blob.
+  EOS
+  spec.homepage      = "https://github.com/deliveroo/crypto_env_var"
+
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'msgpack', '~> 1.1'
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+
+  spec.add_development_dependency 'pry', '~> 0.10.4'
+end

data/lib/crypto_env_var.rb

@@ -0,0 +1,49 @@
+require "crypto_env_var/version"
+require "crypto_env_var/cipher"
+require "crypto_env_var/utils"
+
+
+module CryptoEnvVar
+  CRYPTO_ENV_VAR  = "CRYPTO_ENV"
+  DECRYPT_KEY_VAR = "CRYPTO_ENV_DECRYPT_KEY"
+  CRYPTO_ENV      = lambda { ENV.fetch(CRYPTO_ENV_VAR) }
+  DECRYPT_KEY     = lambda { ENV.fetch(DECRYPT_KEY_VAR) }
+
+
+  class << self
+    def bootstrap!(read_from: CRYPTO_ENV, decrypt_with: DECRYPT_KEY, override_env: true)
+      data = read_value(read_from)
+      key  = read_value(decrypt_with)
+      hash = decrypt(data, key)
+
+      hash.each_pair do |key, value|
+        next if (!override_env && ENV.member?(key))
+        ENV[key] = value
+      end
+    end
+
+
+    def encrypt(data, private_key_string)
+      json = Utils.serialize(data)
+      cipher = Cipher.new(private_key_string)
+      encrypted_data = cipher.encrypt(json)
+      Utils.encode(encrypted_data)
+    end
+
+
+    def decrypt(string, public_key_string)
+      encrypted_data = Utils.decode(string)
+      cipher = Cipher.new(public_key_string)
+      json = cipher.decrypt(encrypted_data)
+      Utils.deserialize(json)
+    end
+
+
+    private
+
+
+    def read_value(source)
+      source.respond_to?(:call) ? source.call() : source
+    end
+  end
+end

data/lib/crypto_env_var/cipher.rb

@@ -0,0 +1,132 @@
+require "openssl"
+require "msgpack"
+
+module CryptoEnvVar
+  class Cipher
+    VERSION = "v1".freeze # To support multiple versions in the future
+
+
+    # Can be initialized with a private or public
+    # RSA key.
+    # - private: encrypt and decrypt.
+    # - public: decrypt only.
+    #
+    def initialize(key_string)
+      @key = OpenSSL::PKey::RSA.new(key_string)
+    end
+
+
+    # Encrypt the plaintext with symmetric AES.
+    #
+    # Encrypt the AES key with the private RSA key.
+    #
+    # Join the encrypted text, the encrypted key and
+    # the initialization vector in a payload string.
+    #
+    # Get a digest of the the payload, then encrypt
+    # it with the private RSA key and append it to
+    # the payload.
+    #
+    def encrypt(plaintext)
+      ciphertext, key, iv = aes_encrypt(plaintext)
+
+      key     = rsa_encrypt(key)
+      payload = [VERSION, key, iv, ciphertext].to_msgpack
+      digest  = rsa_encrypt(sha2_digest(payload))
+
+      [payload, digest].to_msgpack
+    end
+
+
+    # Extract the digest, decrypt it with the RSA
+    # public key, then validate the integrity of the
+    # rest of the payload.
+    #
+    # Decrypt the AES key with the RSA public key.
+    #
+    # Decrypt the ciphertext with symmetric AES.
+    #
+    def decrypt(data)
+      payload, digest = MessagePack.unpack(data)
+
+      digest = rsa_decrypt(digest)
+      validate_digest!(payload, digest)
+
+      _version, key, iv, ciphertext = MessagePack.unpack(payload)
+
+      key = rsa_decrypt(key)
+
+      aes_decrypt(ciphertext, key, iv)
+    end
+
+
+    private
+
+
+    # Plain RSA private key encryption.
+    # It can only encrypt data smaller than the key size.
+    #
+    def rsa_encrypt(plaintext)
+      @key.private_encrypt(plaintext)
+    end
+
+
+    # Plain RDS public key decryption.
+    # It can only decrypt data encrypted with the private
+    # key from the keypair.
+    #
+    def rsa_decrypt(ciphertext)
+      @key.public_decrypt(ciphertext)
+    end
+
+
+    # AES symmetric encryption.
+    #
+    def aes_encrypt(plaintext)
+      cipher = build_aes_ciper
+      cipher.encrypt
+      key = cipher.random_key
+      iv = cipher.random_iv
+
+      ciphertext = cipher.update(plaintext) + cipher.final
+
+      [ciphertext, key, iv]
+    end
+
+
+    # AES symmetric decryption.
+    #
+    def aes_decrypt(ciphertext, key, iv)
+      cipher = build_aes_ciper
+      cipher.decrypt
+      cipher.key = key
+      cipher.iv = iv
+      
+      cipher.update(ciphertext) + cipher.final
+    end
+
+
+    def build_aes_ciper
+      OpenSSL::Cipher::AES256.new(:CBC)
+    end
+
+
+    def sha2_digest(data)
+      OpenSSL::Digest::SHA512.new.digest(data)
+    end
+
+
+    def validate_digest!(plaintext, digest)
+      unless sha2_digest(plaintext) == digest
+        raise DigestVerificationError
+      end
+    end
+
+
+    class DigestVerificationError < StandardError
+      def message
+        "The payload has been tampered with."
+      end
+    end
+  end
+end

data/lib/crypto_env_var/utils.rb

@@ -0,0 +1,24 @@
+require "json"
+require "base64"
+
+module CryptoEnvVar
+  module Utils
+    class << self
+      def serialize(data)
+        JSON.dump(data)
+      end
+
+      def deserialize(string)
+        JSON.load(string)
+      end
+
+      def encode(string)
+        Base64.strict_encode64(string)
+      end
+
+      def decode(string)
+        Base64.strict_decode64(string)
+      end
+    end
+  end
+end

data/lib/crypto_env_var/version.rb

@@ -0,0 +1,3 @@
+module CryptoEnvVar
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: crypto_env_var
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tommaso Pavese
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: msgpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !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: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.4
+description: |2
+    Utilities to protect the application env.
+    Use an keypair to encrypt an env Hash to a blob and populate ENV from the encryped blob.
+email:
+- tommaso.pavese@deliveroo.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- crypto_env_var.gemspec
+- lib/crypto_env_var.rb
+- lib/crypto_env_var/cipher.rb
+- lib/crypto_env_var/utils.rb
+- lib/crypto_env_var/version.rb
+homepage: https://github.com/deliveroo/crypto_env_var
+licenses: []
+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.6.13
+signing_key: 
+specification_version: 4
+summary: Utilities to protect the application env
+test_files: []
+has_rdoc: