kms-tools 0.0.1

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

@@ -0,0 +1,62 @@
+module KmsTools
+  # Namespace for CLI specfic classes in kms-tools
+  module CLI
+    # Class for handling encrypt operations from the CLI
+    class Encrypt
+      # Set up encryption handler
+      #
+      # @param [Hash] global_options
+      # @param [Hash] 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
+      # @option options [String] :data_key Existing data key to use if provided by CLI options
+      def initialize(global_options, options)
+        @enc = KmsTools::Encrypter.new(global_options)
+        @output = options[:output]
+        abort "You must specify a key alias as a flag when encrypting stdin!" unless STDIN.tty? || global_options[:k]
+        @enc.use_key_alias = Helpers.select_key(@enc) if @enc.master_key.nil?
+      end
+
+      # Handle encrypt command
+      #
+      # @param [String] source Plaintext source to encrypt. Can be a string for direct encryption or a path to a file to encrypt
+      # @return [String] Returns Base64 encoded ciphertext if a string is provided
+      # @return [String] Returns path to encrypted file if a source path is provided
+      def encrypt(source)
+        if File.file?(source)
+          save_path = encrypt_file(source)
+          Output.say("Encrypted file saved to: #{save_path}")
+        elsif source.is_a?(String)
+          encrypted_response = @enc.encrypt_string(source)
+          if STDIN.tty?
+            Output.say("Encrypted ciphertext (copy all text without surrounding whitespace):\n\n#{encrypted_response}\n\n")
+          else
+            print encrypted_response
+          end
+        else
+          raise "Unknown input to encrypt..."
+        end
+
+        # clear source from memory for good measure
+        source = nil
+      end
+
+      # Encrypt a file from source path
+      #
+      # @param [String] source path to file to encrypt
+      # @return [String] path to encrypted file
+      def encrypt_file(source)
+        ef = KmsTools::EncryptedFile.new(encrypter: @enc)
+        ef.create_from_file(source)
+        save_path = Helpers::get_save_path({
+          :prompt => "Save encrytped file to",
+          :suggested_path => File.absolute_path(source.sub File.extname(source), ".kms")
+          })
+        ef.save_encrypted(save_path)
+        save_path
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module KmsTools
+  module CLI
+    # General purpose helper functions for the CLI
+    class Helpers
+
+      # Prompts the user to select a key alias from a list of key aliases available to current credentials
+      #
+      # @param [Object] kms KMS client object
+      # @return [String] key alias
+      def self.select_key(kms)
+        Output.select_from_list("Choose which key alias to use as the base Customer Master Key:", kms.available_aliases)
+      end
+
+      # Prompts the user for a path to save a file. Optionally providers a default suggestion.
+      #
+      # @param [Hash] params
+      # @option params [String] :prompt Prompt text to display
+      # @option params [String] :suggested_path Optional path to suggest to user and use a default if no additional input is given
+      # @return [String] path
+      def self.get_save_path(params)
+        prompt = params[:prompt].nil? ? "Save to" : params[:prompt]
+        prompt << " (#{params[:suggested_path]})" if params[:suggested_path]
+        prompt << ": "
+        entered_path = KmsTools::CLI::Output.ask(prompt, String)
+        entered_path.empty? ? params[:suggested_path] : entered_path
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+require 'highline'
+
+module KmsTools
+  module CLI
+    # Helper functions for terminal interaction
+    module Output
+      def self.terminal
+        HighLine.color_scheme = color_scheme
+        @@terminal ||= HighLine.new
+      end
+
+      def self.color_scheme
+        @@color_scheme ||= HighLine::ColorScheme.new(
+            :normal => [],
+            :error => [:bold, :red],
+            :warning => [:bold, :yellow],
+            :verbose => [:bold, :magenta],
+            :debug => [:bold, :cyan],
+            :success => [:bold, :green],
+            :addition => [:bold, :green],
+            :removal => [:bold, :red],
+            :modification => [:bold, :yellow],
+        )
+      end
+
+      def self.say(msg, log_style=:normal)
+        terminal.say format(msg, log_style)
+      end
+
+      def self.format(msg, log_style=:normal)
+        if $color
+          terminal.color(msg.to_s, log_style)
+        else
+          msg
+        end
+      end
+
+      def self.say_verbose(msg)
+        terminal.say format(msg.to_s, 'verbose') if $verbose
+      end
+
+      def self.say_debug(msg, log_style=:debug)
+        terminal.say format(msg.to_s, log_style) if $debug
+      end
+
+      def self.ask(*args, &block)
+        terminal.ask(*args, &block)
+      end
+
+      def self.select_from_list(prompt, options)
+        puts prompt
+        options.each_with_index do |key, index|
+          puts "#{index+1}. #{key}"
+        end
+        choice = Output.ask("? ", Integer) { |q| q.in = 1..options.length }
+        options[choice-1]
+      end
+
+    end
+  end
+end

data/lib/kms-tools/decrypter.rb

@@ -0,0 +1,82 @@
+module KmsTools
+  # Provides low-level decryption functionality for kms-tools
+  #
+  # @author Matt Kriegers
+  class Decrypter < KmsTools::Base
+
+    # Decrypt base64 encoded ciphertext that was encrypted directly with a customer master key
+    # @param str [String] Base64 encoded ciphertext
+    # @return [String] Binary plaintext
+    def decrypt_string(str)
+      kms.decrypt({:ciphertext_blob => from_64(str)}).plaintext
+    end
+
+    # Decrypt a blob using private keys
+    #
+    # @param [Hash] params
+    # @option params [String] :cipher OpenSSL cipher used for encryption
+    # @option params [String] :encrypted_key Encrypted private key
+    # @option params [String] :encrypted_iv Encrypted initialization vector
+    # @option params [String] :encrypted_data Ciphertext data blob
+    # @return [String] Binary plaintext
+    def decrypt_with_data_key(params)
+      cipher = OpenSSL::Cipher.new(params[:cipher])
+      cipher.decrypt
+      cipher.key = decrypt_string(params[:encrypted_key])
+      cipher.iv = decrypt_string(params[:encrypted_iv])
+      decrypted_data = cipher.update(params[:encrypted_data]) + cipher.final
+
+      raise "File integrity check failed!" unless integrity_verified?(decrypted_data, params[:checksum])
+
+      decrypted_data
+    end
+
+    # Decrypt a stream using private keys
+    #
+    # @param [Hash] params
+    # @option params [String] :cipher OpenSSL cipher used for encryption
+    # @option params [String] :encrypted_key Encrypted private key
+    # @option params [String] :encrypted_iv Encrypted initialization vector
+    # @option params [Stream] :in Input stream to read ciphertext data from
+    # @option params [Integer] :position Optional file position marking beginning of ciphertext
+    # @option params [Stream] :out Stream to to write plaintext output to
+    # @option params [String] :checksum Optional SHA1 checksum to verify integrity of decrypted data
+    def stream_decrypt_with_data_key(params)
+      # set up cipher
+      cipher = OpenSSL::Cipher.new(params[:cipher])
+      cipher.decrypt
+      cipher.key = decrypt_string(params[:encrypted_key])
+      cipher.iv = decrypt_string(params[:encrypted_iv])
+
+      sha1 = Digest::SHA1.new if params[:checksum]
+
+      # write the output stream
+      chunk = ""
+      params[:in].seek(params[:position], IO::SEEK_SET) if params[:position]
+      while params[:in].read(STREAM_CHUNK_SIZE, chunk)
+        decrypted_chunk = cipher.update(chunk)
+        sha1.update(decrypted_chunk) if params[:checksum]
+        params[:out] << decrypted_chunk
+      end
+
+      final = cipher.final
+      sha1.update(final) if params[:checksum]
+
+      if params[:checksum]
+        raise "Decrypted data stream failed checksum verification!" unless params[:checksum].eql? sha1.hexdigest
+      end
+
+      params[:out] << final
+      true
+    end
+
+    # Verify data blob against known hash
+    #
+    # @param [String] data Data to verify
+    # @param [String] checksum Known SHA1 hash
+    def integrity_verified?(data, checksum)
+      Digest::SHA1.hexdigest(data).eql? checksum
+    end
+
+  end
+end

data/lib/kms-tools/encrypted_file.rb

@@ -0,0 +1,184 @@
+require 'yaml'
+require 'digest'
+
+module KmsTools
+  # Interacts with files and streams for encryption and decryption of large blobs of data
+  #
+  # @author Matt Krieger
+  class EncryptedFile
+    # Number of bytes allocated at the beginning of a KMS file noting metadata size. 7 bytes limits metadata to 9.9 MB, which is way too much. Don't use that much.
+    META_SIZE_HEADER_LENGTH = 7
+
+    # Default cipher for local encryption
+    DEFAULT_CIPHER = 'aes-256-cbc'
+
+    # Minimum required metadata elements for a KMS file to be valid
+    KMS_REQUIRED_ELEMENTS = %i(encrypted_key encrypted_iv cipher original_extension checksum)
+
+    # Creats an EncryptedFile object.
+    #
+    # @param [Hash] options
+    # @option options [Object] :encrypter existing (Encrypter) object with options set
+    # @option options [String] :path Path to an encrypted file to load on initialization
+    def initialize(options = {})
+      @enc = options[:encrypter] || KmsTools::Encrypter.new
+      @dec = KmsTools::Decrypter.new
+      @kms_meta = {}
+
+      if options[:path]
+        if File.readable?(options[:path])
+          load_encrypted_file(options[:path])
+        else
+          raise "#{options[:path]} is not a readable!"
+        end
+      end
+    end
+
+    # Generate metadata from a plaintext file and prepare for encryption
+    #
+    # @param [String] path Path to plaintext file
+    # @return [Hash] KMS file metadata
+    def create_from_file(path)
+      @decrypted_source = path
+      @kms_meta[:arn] = @enc.master_key_arn
+      @kms_meta[:checksum] = file_sha(path)
+      @kms_meta[:original_extension] = File.extname(path)
+      set_up_encryption_params
+      @kms_meta
+    end
+
+    # Read a KMS encrypted file and populate object metadata from file headers
+    #
+    # @param [String] path Path to encrypted file
+    # @return [Hash] KMS file metadata
+    def load_encrypted_file(path)
+      meta_size = IO.binread(path, META_SIZE_HEADER_LENGTH).to_i
+      kms_yaml = YAML::load(IO.binread(path, meta_size, META_SIZE_HEADER_LENGTH))
+      if is_valid_kms_file?(kms_yaml)
+        @kms_meta = kms_yaml
+        @encrypted_file_path = path
+        @encrypted_data_start = META_SIZE_HEADER_LENGTH + meta_size
+      else
+        raise "#{path} is not a valid KMS file!"
+      end
+      @kms_meta
+    end
+
+    # Get the encrypted key of the current file, generate a new one if not present
+    #
+    # @return [string] Base64 encoded encrypted data key
+    def encrypted_key
+      @kms_meta[:encrypted_key] ||= @enc.new_encrypted_key
+    end
+
+    # Get the encrypted initialization vector of the current file, generate a new one if not present
+    #
+    # @return [string] Base64 encoded encrypted data key
+    def encrypted_iv
+      @kms_meta[:encrypted_iv] ||= @enc.new_encrypted_key
+    end
+
+    # Get the original extension of the encrypted file
+    #
+    # @return [string] file extension
+    def original_extension
+      @kms_meta[:original_extension]
+    end
+
+    def encrypted_data
+      @kms_meta[:encrypted_data]
+    end
+
+    # Get the cipher used for the encrypted file or set the default
+    #
+    # @return [string] OpenSSL cipher
+    def cipher
+      @kms_meta[:cipher] ||= DEFAULT_CIPHER
+    end
+
+    # Get the SHA1 checksum of the decrypted data
+    #
+    # @return [string] hex encoded SHA1 checksum
+    def checksum
+      @kms_meta[:checksum]
+    end
+
+    # Generate encryption key, iv, and cipher if they do not exist
+    # @return [nil]
+    def set_up_encryption_params
+      encrypted_key
+      encrypted_iv
+      cipher
+      return nil
+    end
+
+    # Save encrypted data with KMS headers to the provided path
+    #
+    # @param [String] path Path to save encrypted file
+    # @return [Boolean] returns true on success
+    def save_encrypted(path)
+      kms_yaml = @kms_meta.to_yaml
+      meta_size = kms_yaml.bytesize.to_s.rjust(META_SIZE_HEADER_LENGTH, "0")
+      infile = File.open(@decrypted_source, 'rb')
+      outfile = File.open(path, 'wb+')
+      outfile << meta_size
+      outfile << kms_yaml
+      @enc.stream_encrypt_with_data_key({
+          in: infile,
+          out: outfile,
+          encrypted_iv: encrypted_iv,
+          encrypted_key: encrypted_key,
+          cipher: cipher
+      })
+
+      outfile.close
+      true
+    end
+
+    # Save decrypted data to the provided path
+    #
+    # @param [String] path Path to save decrypted file
+    # @return [Boolean] returns true on success
+    def save_decrypted(path)
+      path << @kms_meta[:original_extension] unless File.extname(path) == @kms_meta[:original_extension]
+      infile = File.open(@encrypted_file_path, 'rb')
+      outfile = File.open(path, 'wb+')
+      @dec.stream_decrypt_with_data_key({
+        in: infile,
+        position: @encrypted_data_start,
+        out: outfile,
+        encrypted_iv: encrypted_iv,
+        encrypted_key: encrypted_key,
+        cipher: cipher,
+        checksum: checksum
+        })
+
+      outfile.close
+      true
+    end
+
+    # Verify YAML header of a KMS file to encure necessary information is present to decrypt
+    #
+    # @param [Object] yaml object containing KMS metadata
+    # @return [Boolean]
+    def is_valid_kms_file?(yaml)
+      KMS_REQUIRED_ELEMENTS.all? { |e| yaml.has_key? e }
+    end
+
+    # Calculate SHA of a given file by chunks
+    #
+    # @param [String] path Path to file
+    # @return [String] Hex encoded SHA1 hash
+    def file_sha(path)
+      sha1 = Digest::SHA1.new
+      file = File.open(path,'rb')
+      chunk = ""
+      while file.read(STREAM_CHUNK_SIZE, chunk)
+        sha1.update(chunk)
+      end
+
+      sha1.hexdigest
+    end
+
+  end
+end

data/lib/kms-tools/encrypter.rb

@@ -0,0 +1,96 @@
+module KmsTools
+  # Provides low-level encryption functionality for kms-tools
+  #
+  # @author Matt Krieger
+  class Encrypter < KmsTools::Base
+    # Size limit for encrypting data directly using {http://docs.aws.amazon.com/sdkforruby/api/Aws/KMS/Client.html#encrypt-instance_method Aws::KMS::Client.encrypt}
+    STRING_SIZE_LIMIT = 4096
+
+    # Key spec to use by default unless overridden
+    DEFAULT_KEY_SPEC = 'AES_256'
+
+    # Encrypt a string up 4KB in size
+    # @param str [String] String to encrypt
+    # @return [String] Base64 encoded ciphertext
+    def encrypt_string(str)
+      to_s64(kms_encrypt(str).ciphertext_blob)
+    end
+
+    # Call {http://docs.aws.amazon.com/sdkforruby/api/Aws/KMS/Client.html#encrypt-instance_method Aws::KMS::Client.encrypt} using object master_key
+    # @param str [String] String to encrypt
+    # @return [Object] {http://docs.aws.amazon.com/sdkforruby/api/Aws/KMS/Types/EncryptResponse.html Aws::KMS::Types::EncryptResponse}
+    def kms_encrypt(str)
+      kms.encrypt({:key_id => master_key, :plaintext => str})
+    end
+
+    # Encrypt a blob using private keys
+    #
+    # @param [Hash] params
+    # @option params [String] :cipher OpenSSL cipher to use for encryption
+    # @option params [String] :encrypted_key Encrypted private key
+    # @option params [String] :encrypted_iv Encrypted initialization vector
+    # @option params [String] :data Plaintext data blob
+    # @return [String] Binary encrypted ciphertext
+    def encrypt_with_data_key(params)
+      d = KmsTools::Decrypter.new()
+      cipher = OpenSSL::Cipher.new(params[:cipher])
+      cipher.encrypt
+      cipher.key = d.decrypt_string(params[:encrypted_key])
+      cipher.iv = d.decrypt_string(params[:encrypted_iv])
+      encrypted_data = cipher.update(params[:data]) + cipher.final
+    end
+
+
+    # Encrypt a stream using private keys
+    #
+    # @param [Hash] params
+    # @option params [String] :cipher OpenSSL cipher to use for encryption
+    # @option params [String] :encrypted_key Encrypted private key
+    # @option params [String] :encrypted_iv Encrypted initialization vector
+    # @option params [Stream] :in Input stream to read plaintext data from
+    # @option params [Stream] :out Stream to to write encrypted output to
+    def stream_encrypt_with_data_key(params)
+      d = KmsTools::Decrypter.new()
+
+      # set up cipher
+      cipher = OpenSSL::Cipher.new(params[:cipher])
+      cipher.encrypt
+      cipher.key = d.decrypt_string(params[:encrypted_key])
+      cipher.iv = d.decrypt_string(params[:encrypted_iv])
+
+      # write the output stream
+      buf = ""
+      params[:in].seek(params[:position], :SET) if params[:position]
+      while params[:in].read(STREAM_CHUNK_SIZE, buf)
+        params[:out] << cipher.update(buf)
+      end
+      params[:out] << cipher.final
+
+      # return true if nothing errored out
+      true
+    end
+
+    # Generate a data key to use for local symmetric encryption
+    # @return [Object] {http://docs.aws.amazon.com/sdkforruby/api/Aws/KMS/Types/GenerateDataKeyResponse.html Aws::KMS::Types::GenerateDataKeyResponse}
+    def new_key
+      kms.generate_data_key({
+        :key_id => master_key,
+        :key_spec => key_spec
+        })
+    end
+
+    # Generate Base64 encoded encrypted data key to use for local symmetric encryption
+    # @return [String] Base64 encoded encrypted data key
+    def new_encrypted_key
+      to_s64(new_key.ciphertext_blob)
+    end
+
+    # Key spec that will be used for data key creation
+    # @return [String] {http://docs.aws.amazon.com/sdkforruby/api/Aws/KMS/Types/GenerateDataKeyRequest.html#key_spec-instance_method AWS Key Spec}
+    def key_spec
+      @key_spec ||= DEFAULT_KEY_SPEC
+    end
+
+
+  end
+end