kms-tools 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 36135cba337e0583f02134a249daf299dea7ec5f
+  data.tar.gz: 06877816b0f9bab9a09034271c5fe2e0584c9ade
+SHA512:
+  metadata.gz: 67c1df3ef40a95e59d1331e5628232b32ae51fe9261990f268114553eebc5b20f9c0ae47f5d2afb42b7daa2088311145633bbfb678cb2a913e7e170670db0a6a
+  data.tar.gz: 00083083afa0d09b9b79e71672957a36a4f6fdeacb02ec9fefbe8104a9b1a2b8ec25d6605c044a907eea2e60ce519e015ea033a5be6ab8c751a41ccb5f0055e1

data/.gitignore

@@ -0,0 +1,7 @@
+Gemfile.lock
+.DS_Store
+.idea
+.yardoc
+doc
+.rspec
+spec/examples.txt

data/.octopolo.yml

@@ -0,0 +1,4 @@
+github_repo: sportngin/kms-tools
+semantic_versioning: true
+branches_to_keep:
+- master

data/.soyuz.yml

@@ -0,0 +1,13 @@
+defaults:
+  deploy_cmd: gem push *.gem
+  before_deploy_cmds:
+    - /usr/local/bin/op tag-release
+    - sed -i "" -e "s/\".*/\"$(git tag| sort -n -t. -k1,1 -k2,2 -k3,3 | tail -1 | sed s/v//)\"/" lib/kms-tools/version.rb
+    - git add  lib/kms-tools/version.rb
+    - git commit -m "Version Bump" && git push
+    - gem build kms-tools.gemspec
+  after_deploy_cmds:
+    - rm *.gem
+environments:
+  -
+    rubygems: {}

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+sudo: false
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+script: bundle exec rspec
+
+branches:
+  only:
+    - master

data/CHANGELOG.markdown

@@ -0,0 +1,7 @@
+#### v0.0.1
+#### v0.0.1
+#### 0.0.2
+#### 0.0.1
+#### 0.0.1
+#### 0.1.1
+#### 0.1.0

data/Gemfile

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

data/README.md

@@ -0,0 +1,85 @@
+## KmsTools
+
+[![Build Status](https://travis-ci.com/sportngin/kms-tools.svg?token=CZhBgnU2zo8LVq9DDxQf&branch=master)](https://travis-ci.com/sportngin/kms-tools)
+
+A simplified toolset for encrypting and decrypting data using [Amazon Key Management Service](https://aws.amazon.com/kms/). Since credentials are managed by the [AWS SDK](https://blogs.aws.amazon.com/security/post/Tx3D6U6WSFGOK2H/A-New-and-Standardized-Way-to-Manage-Credentials-in-the-AWS-SDKs), you can use a local credentials file for the CLI and rely on IAM roles to provide access for applications running on AWS instances. This completely removes the need to manage plaintext secret keys even for locally encrypted and decrypted data.
+
+### Local Encryption
+Per the KMS spec, data up to 4KB may be encryptyed with a simple `encrypt` call. Larger blobs of data must be locally encrypted using data keys. KmsTools facilitates this by generating two data keys for each blob encrypted. One is used as the symmetric secret key and the other used as the initialization vector. These two keys are encrypted and then stored along side the encrypted data for later use.
+
+Standard lib OpenSSL is used for local encryption. While any block cipher compiled in to OpenSSL can be used for local encryption, it is important to note that the same cipher must be available on any machine attempting to decrypt the same data. So it is recommended to use commonly available ciphers. `aes-256-cbc` is the default.
+
+### .kms Filetype
+To make storage and recall of encryption metadata easier, the `.kms` filetype was developed. This filetype is used when storing encrypted files with the CLI and by default when using [KmsTools::EncryptedFile](https://github.com/sportngin/kms-tools/blob/master/lib/kms-tools/encrypted_file.rb "KmsTools::EncryptedFile"). `.kms` files are a digital envelope made up of 3 specific parts:
+ 1. A zero-padded 7 byte integer noting total length of metadata stored
+ 2. YAML encoded metadata
+ 3. Encrypted binary data
+```
+ meta-length        metadata                           encrypted binary data
+    INT               YAML                                     BIN
+|-----------|----------------------|---------------------------------------------------------|
+```
+
+While an arbitrary number of metadata elements can be stored as needed, there are a few standard elements
+ * OpenSSL cipher used for encryption `required`
+ * Encrypted encryption key (decypted with KMS prior to using) `required`
+ * Encrypted initialization vector (decypted with KMS prior to using) `required`
+ * Original file extension `required`
+ * Original data checksum `required`
+ * KMS Master Key ARN (Optional but there by default for troubleshooting)
+
+
+### CLI
+The CLI exposes most of the functionality of the gem in a simple interface.
+
+>Keep in mind that the gem uses standard AWS credential management. So if you are using the CLI on a server without a credentials file in place, all activity will be logged in CloudTrail as the role instead of the user taking action. For this reason it is highly recommended that you run some sort of IDS on instances using roles that have access to KMS to ensure that all KMS activity is properly logged.
+
+```
+NAME
+    kms-tools - CLI for encrypting and decrypting information with Amazon KMS
+
+SYNOPSIS
+    kms-tools [global options] command [command options] [arguments...]
+
+VERSION
+    0.0.1
+
+GLOBAL OPTIONS
+    --[no-]color         - Colorize output (default: enabled)
+    -d, --debug          - Debug output (Includes verbose)
+    --help               - Show this message
+    -k, --master_key=arg - Encrypt using the specified key alias or key id as the customer master key (default: none)
+    -p, --profile=arg    - AWS credentials profile to use (default: default)
+    -r, --region=arg     - AWS Region (default: us-east-1)
+    -v, --verbose        - Verbose output
+    --version            - Display the program version
+
+COMMANDS
+    decrypt      - Decrypt a text string or a file
+    encrypt      - Encrypt a text string or a file
+    help         - Shows a list of commands or help for one command
+    list-aliases - List KMS key aliases available to current credentials
+```
+
+Example string encryption/decryption:
+```
+[~/sportngin/kms-tools] (master)$ bundle exec bin/kms-tools encrypt "something secret"
+Choose which key alias to use as the base Customer Master Key:
+1. alias/staging/kms-tools1
+2. alias/staging/kms-tools2
+3. alias/staging/vpn
+? 1
+Encrypted ciphertext (copy all text without surrounding whitespace):
+
+CiAA6CYSKxFRMav+m01ps0d8V5PrVvbPebe2L7LNbrV7NBKXAQEBAgB4AOgmEisRUTGr/ptNabNHfFeT61b2z3m3ti+yzW61ezQAAABuMGwGCSqGSIb3DQEHBqBfMF0CAQAwWAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAwFjvAk2NeDhOGxlUUCARCAK1hO8B+M6RWjiQckqI4RlGnP8mI/gePSfERHcD0KgwvJwhiPP8z+p0m2TkY=
+
+
+[~/sportngin/kms-tools] (master)$ bundle exec bin/kms-tools decrypt CiAA6CYSKxFRMav+m01ps0d8V5PrVvbPebe2L7LNbrV7NBKXAQEBAgB4AOgmEisRUTGr/ptNabNHfFeT61b2z3m3ti+yzW61ezQAAABuMGwGCSqGSIb3DQEHBqBfMF0CAQAwWAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAwFjvAk2NeDhOGxlUUCARCAK1hO8B+M6RWjiQckqI4RlGnP8mI/gePSfERHcD0KgwvJwhiPP8z+p0m2TkY=
+Decrypted string:
+
+something secret
+
+
+[~/sportngin/kms-tools] (master)$
+```
+

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rake/clean'
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rdoc/task'
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc","lib/**/*.rb","bin/**/*")
+  rd.title = 'KMS Tools'
+end
+
+spec = eval(File.read('kms-tools.gemspec'))
+
+Gem::PackageTask.new(spec) do |pkg|
+end

data/bin/kms-tools

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+require 'gli'
+require 'kms-cli'
+
+include GLI::App
+
+program_desc 'CLI for encrypting and decrypting information with Amazon KMS'
+
+version KmsTools::VERSION
+
+subcommand_option_handling :normal
+arguments :strict
+
+switch [:v,:verbose], :desc => 'Verbose output', :negatable => false
+switch [:d,:debug], :desc => 'Debug output (Includes verbose)', :negatable => false
+switch [:color], :desc => 'Colorize output', :default_value => true
+flag [:r,:region], :desc => 'AWS Region', :default_value => 'us-east-1'
+flag [:p,:profile], :desc => 'AWS credentials profile to use', :default_value => 'default'
+flag [:k,:master_key], :desc => 'Encrypt using the specified key alias or key id as the customer master key'
+
+# Load all the command files
+commands_from '../lib/kms-tools/cli/commands'
+
+pre do |global,command,options,args|
+  #KmsTools::VerifyAwsConfig.new
+  $verbose = global[:verbose] || global[:debug]
+  $debug = global[:debug]
+  $color = global[:color]
+  true
+end
+
+post do |global,command,options,args|
+  # Post logic here
+  # Use skips_post before a command to skip this
+  # block on that command only
+end
+
+on_error do |exception|
+  # Error logic here
+  # return false to skip default error handling
+  true
+end
+
+exit run(ARGV)

data/kms-tools.gemspec

@@ -0,0 +1,29 @@
+# Ensure we require the local version and not one we might have installed already
+require './lib/kms-tools/version'
+spec = Gem::Specification.new do |s|
+  s.name = 'kms-tools'
+  s.version = KmsTools::VERSION
+  s.author = 'Matt Krieger'
+  s.email = 'matt.krieger@sportngin.com'
+  s.homepage = 'http://www.sportngin.com'
+  s.platform = Gem::Platform::RUBY
+  s.summary = 'CLI for encrypting and decrypting data using Amazon KMS'
+  s.files = `git ls-files`.split("
+")
+  s.require_paths << 'lib'
+  s.has_rdoc = 'yard'
+  s.bindir = 'bin'
+  s.executables << 'kms-tools'
+
+  s.add_dependency 'aws-sdk'
+  s.add_dependency "highline"
+  s.add_dependency "hashdiff"
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'rspec-core'
+  s.add_development_dependency 'rspec-expectations'
+  s.add_development_dependency 'rspec-mocks'
+
+  s.add_runtime_dependency "gli", "~>2.13.4"
+end

data/lib/kms-cli.rb

@@ -0,0 +1,2 @@
+require 'kms-tools'
+Dir[File.dirname(__FILE__) + '/kms-tools/cli/*.rb'].each {|file| require file }

data/lib/kms-tools.rb

@@ -0,0 +1,5 @@
+require 'aws-sdk'
+Dir[File.dirname(__FILE__) + '/kms-tools/*.rb'].each {|file| require file }
+
+# Chunk size to use when processing streams
+STREAM_CHUNK_SIZE = 1048576

data/lib/kms-tools/base.rb

@@ -0,0 +1,88 @@
+module KmsTools
+  ##
+  # Helper class for {http://docs.aws.amazon.com/sdkforruby/api/Aws/KMS/Client.html Aws::KMS::Client}.
+  class Base
+    # Default region if nothing is provided because we all use N. Virginia, don't we?
+    DEFAULT_REGION = 'us-east-1'
+
+    # Customer master key used for ann encryption operations
+    attr_accessor :master_key
+
+    # InstantiatedAws::KMS::Client object
+    attr_reader :kms
+
+    ##
+    # Instantiates a {http://docs.aws.amazon.com/sdkforruby/api/Aws/KMS/Client.html Aws::KMS::Client} object with provided options.
+    #
+    # @param [Hash] options
+    # @option options [String] :master_key Customer Master Key to use when instantiating the object, this can be a full key ID, an alias, or an ARN
+    # @option options [String] :region Set the region for Aws::KMS::Client to use. Defaults to +DEFAULT_REGION+
+    # @option options [String] :profile Use the specified profile from an AWS credentials file
+    #
+    def initialize(options = {})
+      @master_key = options[:master_key]
+      @region = options[:region]
+      @profile = options[:profile]
+
+      @kms = Aws::KMS::Client.new({
+          :region => region,
+          :profile => @profile,
+          })
+    end
+
+    # Lists all master key aliases available to the current client (Ignores built-aws keys that should not be used by user code).
+    # @return [Array]
+    def available_aliases
+      aliases = kms.list_aliases.aliases.delete_if { |a| a.alias_name.include? "alias/aws/"}
+      aliases.map{ |a| a.alias_name }
+    end
+
+    # Key ARN of the currently selected master key
+    # @return [String] key ARN
+    def master_key_arn
+      master_key ? kms.describe_key({:key_id => master_key}).key_metadata.arn : nil
+    end
+
+    # Returns the key ID of the currently selected master key
+    # @return [String] key id
+    def master_key_id
+      master_key ? kms.describe_key({:key_id => master_key}).key_metadata.key_id : nil
+    end
+
+    # Sets the current master key using a key alias. Verifies that the provided key is available prior to setting.
+    # @param key_alias [String] Key alias to use, must be available with current credentials/role
+    # @return [String]
+    def use_key_alias=(key_alias)
+      if available_aliases.include? key_alias
+        @master_key = key_alias
+      else
+        raise "Requested key alias not available with current credentials!"
+      end
+    end
+
+    # Current client region
+    # @return [String]
+    def region
+      @region ||= DEFAULT_REGION
+    end
+
+    # Short function to encode a blob to Base64
+    # @return [String] Base64 encoded string
+    def to_64(blob)
+      Base64.encode64(blob)
+    end
+
+    # Short function to strict encode a blob to Base64
+    # @return [String] Base64 encoded string without linebreaks
+    def to_s64(blob)
+      Base64.strict_encode64(blob)
+    end
+
+    # Short function to decode a blob from Base64
+    # @return [String] blob
+    def from_64(blob)
+      Base64.decode64(blob)
+    end
+
+  end
+end

data/lib/kms-tools/cli/commands/decrypt.rb

@@ -0,0 +1,15 @@
+desc 'Decrypt a text string or a file'
+
+long_desc %{
+Decrypt a text string or a file.
+
+If an argument is not given, stdin will be used.
+}
+
+arg_name '[plaintext | path]'
+command 'decrypt' do |c|
+  c.action do |global_options,options,args|
+      input = args.first || STDIN.read
+      KmsTools::CLI::Decrypt.new(global_options, options).decrypt(input)
+  end
+end

data/lib/kms-tools/cli/commands/encrypt.rb

@@ -0,0 +1,16 @@
+desc "Encrypt a text string or a file."
+
+long_desc %{
+Encrypt a text string or a file.
+
+If an argument is not given, stdin will be encrypted with the specified key.
+}
+
+arg_name '[plaintext]'
+command 'encrypt' do |c|
+  c.flag ['data-key'], :desc => "Encrypt data with the specified encrypted data key. If a path is provided, the key will be read from that file.\n\nNOTE: Data keys are required to encrypt more than 4KB of data."
+  c.action do |global_options,options,args|
+      input = args.first || STDIN.read
+      KmsTools::CLI::Encrypt.new(global_options, options).encrypt(input)
+  end
+end

data/lib/kms-tools/cli/commands/list_aliases.rb

@@ -0,0 +1,13 @@
+desc 'List KMS key aliases available to current credentials'
+command 'list-aliases' do |c|
+  c.action do |global_options,options,args|
+    num = 0
+    KmsTools::Base.new(
+        { region: global_options[:region],
+          profile: global_options[:profile]
+        }
+    ).available_aliases.each do |a|
+      puts "#{num += 1}. #{a}"
+    end
+  end
+end

data/lib/kms-tools/cli/decrypt.rb

@@ -0,0 +1,55 @@
+module KmsTools
+  module CLI
+    # Class for handling decrypt operations from the CLI
+    class Decrypt
+
+      # Set up decryption handler
+      #
+      # @param [Hash] global_options
+      # @option global_options [String] :master_key Master key to use if provided by CLI options
+      # @option global_options [String] :profile AWS credential profile to us if provided by CLI options
+      # @option global_options [String] :region AWS region to use if provided by CLI options
+      def initialize(global_options, options)
+        @dec = KmsTools::Decrypter.new(global_options)
+        @output = options[:output]
+      end
+
+      # Handle decrypt command
+      #
+      # @param [String] source Encrypted source to decrypt. Can be a string for direct decryption or a path to a KMS file to decrypt
+      # @return [String] Returns plaintext if Base64 encoded ciphertext is provided
+      # @return [String] Returns path to decrypted file if a source path is provided
+      def decrypt(source)
+        if File.file?(source)
+          save_path = decrypt_file(source)
+          Output.say("Decrypted file saved to: #{save_path}")
+        elsif source.is_a?(String)
+          decrypted_response = @dec.decrypt_string(source)
+          if STDIN.tty?
+            Output.say("Decrypted string:\n\n#{decrypted_response}\n\n")
+          else
+            print decrypted_response
+          end
+        else
+          raise "Unknown input to encrypt..."
+        end
+        source = nil
+      end
+
+      # Decrypt a file from source path
+      #
+      # @param [String] source path to file to decrypt
+      # @return [String] path to decrypted file
+      def decrypt_file(source)
+        ef = KmsTools::EncryptedFile.new(path: source)
+        save_path = Helpers::get_save_path({
+          :prompt => "Save decrytped file to",
+          :suggested_path => File.absolute_path(source.sub File.extname(source), ef.original_extension)
+          })
+        ef.save_decrypted(save_path)
+        save_path
+      end
+
+    end
+  end
+end