secret_keys 1.0.0.pre → 1.0.0

data/lib/secret_keys/cli.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "io/console"
+
+require_relative "../secret_keys.rb"
+
+module SecretKeys::CLI
+  class Base
+    attr_reader :secret_key, :input
+
+    MAX_SUMMARY_LENGTH = 80
+
+    def initialize(argv)
+      # make sure we can only use stdin once
+      @stdin_used = false
+      @secrets = nil
+      parse_options(argv)
+    end
+
+    # Subclasses can override this method to parse additional options beyond the standard set.
+    def parse_additional_options(opts)
+    end
+
+    # @return [SecretKeys] the secrets
+    def secrets
+      @secrets ||= SecretKeys.new(@input, @secret_key)
+    end
+
+    # Subclasses should return the action name for the help banner
+    def action_name
+      "<encrypt|decrypt|read|edit>"
+    end
+
+    # Subclasses must implement this method to execute the logic.
+    def run!
+      raise NotImplementedError
+    end
+
+    # Return the output format.
+    def format
+      return @format if [:json, :yaml].include?(@format)
+      secrets.input_format
+    end
+
+    protected
+
+    def encrypted_file_contents
+      encrypted = secrets.encrypted_hash
+      string = (format == :yaml ? YAML.dump(encrypted) : JSON.pretty_generate(encrypted))
+      string << $/ unless string.end_with?($/) # ensure file ends with system dependent new line
+      string
+    end
+
+    private
+
+    def parse_options(argv)
+      @secret_key = nil
+      @format = nil
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: secret_keys #{action_name} [options] [--] [INFILE|-]"
+
+        opts.separator("\nGlobal options:")
+
+        secret_docs = split(<<~HELP)
+          Encryption key used to encrypt strings in the file.
+          This value can also be passed in the SECRET_KEYS_ENCRYPTION_KEY environment variable or via STDIN by specifying '-'.
+        HELP
+        opts.on("-s", "--secret-key=SECRET", String, *secret_docs) do |value|
+          raise ArgumentError, "You have already passed in the secret key" unless @secret_key.nil?
+          @secret_key = get_secret_key(value)
+        end
+
+        secret_file_docs = split(<<~HELP)
+          Path to a file that contains the encryption key.
+          This value can also be passed in the SECRET_KEYS_ENCRYPTION_KEY_FILE environment variable.
+        HELP
+        opts.on("--secret-key-file=PATH", String, *secret_file_docs) do |value|
+          raise ArgumentError, "You have already passed in the secret key" unless @secret_key.nil?
+          @secret_key = File.read(value).chomp
+        end
+
+        opts.on("-f", "--format FORMAT", [:json, :yaml], "Set the output format. By default this will be the same as the input format.") do |value|
+          @format = value
+        end
+
+        opts.on("-h", "--help", "Prints this help") do
+          puts opts.help
+          exit
+        end
+
+        parse_additional_options(opts)
+      end.order!(argv)
+
+      @input = argv.shift
+      if @input.nil? || @input == "-"
+        can_i_haz_stdin!
+        @input = $stdin
+      end
+
+      raise ArgumentError.new("Too many arguments") unless argv.empty?
+    end
+
+    def get_secret_key(value)
+      if value == "-"
+        can_i_haz_stdin!
+        if $stdin.tty?
+          $stdin.getpass("Secret key: ")
+        else
+          $stdin.gets.chomp
+        end
+      else
+        value
+      end
+    end
+
+    # @return [Array] array of strings from docstring, split at length
+    def split(docstring, length: MAX_SUMMARY_LENGTH)
+      docstring = docstring.strip
+      docstring.gsub!(/\s+/, " ")
+      docstring.scan(/(.{1,#{length}})(?:\s+|\z)/).flatten
+    end
+
+    # Mark that you want to use stdin and raise an exception if it's already been used.
+    def can_i_haz_stdin!
+      raise ArgumentError, "stdin (-) cannot be specified multiple times" if @stdin_used
+      @stdin_used = true
+    end
+
+    # @param parent data structure to recurse over
+    # @param key to access
+    # @yield context of key and parent
+    # @yieldparam parent the parent object
+    # @yieldparam key the last child node
+    def access_key(parent, key, write: false)
+      splits = key.split(".")
+      last_key = splits.length - 1
+      splits.each_with_index do |curr, idx|
+        if parent.is_a?(Array)
+          k = curr.to_i
+          raise ArgumentError, "Array index must be a positive number" if curr != k.to_s || k < 0
+        elsif parent.is_a?(Hash) || parent.is_a?(SecretKeys)
+          k = curr
+        else
+          raise ArgumentError, "No such key: #{key.inspect}"
+        end
+
+        return yield(parent, k) if idx == last_key
+
+        if parent[k].nil?
+          return nil unless write
+          parent[k] = {}
+        end
+        parent = parent[k]
+      end
+    end
+  end
+
+  class Init < Base
+    def action_name
+      "init"
+    end
+
+    def run!
+      @secrets = SecretKeys.new({}, secret_key)
+      if input.is_a?(String)
+        if File.exist?(input)
+          STDERR.puts "Error: Cannot init preexisting file '#{input}'"
+          STDERR.puts "You may want to try calling `secret_keys encrypt/edit` instead"
+          exit 1
+        end
+
+        File.write(input, encrypted_file_contents)
+      else
+        $stdout.write(encrypted_file_contents)
+      end
+    end
+  end
+
+  class Encrypt < Base
+    def action_name
+      "encrypt"
+    end
+
+    def parse_additional_options(opts)
+      opts.separator("\nEncrypt options:")
+
+      @new_secret_key = nil
+      opts.on("--new-secret-key=NEW_SECRET", String, *split(<<~DOC)) do |value|
+        Encryption key used to encrypt strings in the file on output.
+        This option can be used to change the encryption key. If set to '-', read from STDIN.
+      DOC
+        @new_secret_key = get_secret_key(value)
+      end
+
+      @in_place = false
+      opts.on("-i", "--in-place", "Update the input file instead of writing to stdout.") do |value|
+        @in_place = true
+      end
+
+      @encrypt_all = false
+      opts.on("--encrypt-all", "Encrypt all keys in the file") do |value|
+        @encrypt_all = value
+      end
+    end
+
+    def run!
+      if @new_secret_key && !@new_secret_key.empty?
+        secrets.encryption_key = @new_secret_key
+      end
+
+      if @encrypt_all
+        secrets.each_key do |key|
+          secrets.encrypt!(key)
+        end
+      end
+
+      if @in_place
+        raise ArgumentError, "Cannot perform in place editing on streams" unless @input.is_a?(String)
+        # make sure we read the file **before** writing to it.
+        contents = encrypted_file_contents
+        File.open(@input, "w") do |file|
+          file.write(contents)
+        end
+      else
+        $stdout.write(encrypted_file_contents)
+        $stdout.flush
+      end
+    end
+  end
+
+  class Decrypt < Base
+    def action_name
+      "decrypt"
+    end
+
+    def run!
+      decrypted = secrets.to_h
+      string = (format == :yaml ? YAML.dump(decrypted) : JSON.pretty_generate(decrypted))
+      string << $/ unless string.end_with?($/) # ensure file ends with system dependent new line
+      $stdout.write(string)
+      $stdout.flush
+    end
+  end
+
+  class Read < Base
+    attr_reader :key
+
+    def action_name
+      "read"
+    end
+
+    def parse_additional_options(opts)
+      opts.separator("\n Read options:")
+      @key = nil
+      opts.on("-k", "--key KEY", String, "Key from the file to output. You can use dot notation to read a nested key.") do |value|
+        @key = value
+      end
+    end
+
+    def run!
+      raise ArgumentError.new("key is required") if @key.nil? || @key.empty?
+      val = secrets.to_h
+      val = access_key(val, @key) { |parent, key| parent[key] }
+      $stdout.write(val)
+      $stdout.flush
+    end
+  end
+
+  class Edit < Encrypt
+    attr_reader :actions
+
+    def action_name
+      "edit"
+    end
+
+    def parse_additional_options(opts)
+      opts.separator("\nEdit options:")
+
+      @actions = []
+      set_encrypted_docs = split(<<~HELP)
+        Set an encrypted value in the file. You can use dot notation to set a nested value.
+        If no VALUE is specified, the key will be moved to the encrypted keys while keeping any existing value.
+      HELP
+      opts.on("-e", "--set-encrypted KEY[=VALUE]", String, *set_encrypted_docs) do |value|
+        key, val = value.split("=", 2)
+        @actions << [:encrypt, key, val]
+      end
+
+      set_decrypted_docs = split(<<~HELP)
+        Set a plain text value in the file. You can use dot notation to set a nested value. If no VALUE is specified,
+        the key will be moved to the plain text keys while keeping any existing value.
+      HELP
+      opts.on("-d", "--set-decrypted KEY[=VALUE]", String, *set_decrypted_docs) do |value|
+        key, val = value.split("=", 2)
+        @actions << [:decrypt, key, val]
+      end
+
+      opts.on("-r", "--remove KEY", String, "Remove a key from the file. You can use dot notation to remove a nested value.") do |value|
+        @actions << [:remove, value, nil]
+      end
+
+      super
+    end
+
+    def run!
+      @actions.each do |action, key, value|
+        raise ArgumentError.new("cannot set a key beginning with dot") if key.start_with?(".")
+        case action
+        when :encrypt
+          secrets.encrypt!(key.split(".").first)
+          unless value.nil?
+            access_key(secrets, key, write: true) do |parent, child|
+              parent[child] = value
+            end
+          end
+        when :decrypt
+          secrets.decrypt!(key.split(".").first)
+          unless value.nil?
+            access_key(secrets, key, write: true) do |parent, child|
+              parent[child] = value
+            end
+          end
+        when :remove
+          access_key(secrets, key) do |parent, child|
+            if parent.is_a?(Array)
+              parent.delete_at(child)
+            else
+              parent.delete(child)
+            end
+          end
+        end
+      end
+
+      super
+    end
+  end
+end

data/lib/secret_keys/encryptor.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "openssl"
+require "base64"
+
+# Encyption helper for encrypting and decrypting values using AES-256-GCM and returning
+# as Base64 encoded strings. The encrypted values also include a prefix that can be used
+# to detect if a string is an encrypted value.
+class SecretKeys::Encryptor
+  # format: <nonce:12>, <auth_tag:16>, <data:*>
+  ENCODING_FORMAT = "a12 a16 a*"
+  ENCRYPTED_PREFIX = "$AES$:"
+  CIPHER = "aes-256-gcm"
+  KDF_ITERATIONS = 20_000
+  HASH_FUNC = "sha256"
+  KEY_LENGTH = 32
+
+  # Valid salts are hexencoded strings
+  SALT_MATCHER = /\A(\h\h)+\z/.freeze
+
+  class << self
+    # Create an Encryptor from a password and salt. This is a shortcut for generating an Encryptor
+    # with a 32 byte encryption key. The key will be derived from the password and salt.
+    # @param [String] password secret used to encrypt the data
+    # @param [String] salt random hex-encoded byte array for key derivation
+    # @return [SecretKeys::Encryptor] a new encryptor with key derived from password and salt
+    def from_password(password, salt)
+      raise ArgumentError, "Password must be present" if password.nil? || password.empty?
+      raise ArgumentError, "Salt must be a hex encoded value" if salt.nil? || !SALT_MATCHER.match?(salt)
+      # Convert the salt to raw byte string
+      salt_bytes = [salt].pack("H*")
+      derived_key = derive_key(password, salt: salt_bytes)
+
+      new(derived_key)
+    end
+
+    # Detect of the value is a string that was encrypted by this library.
+    def encrypted?(value)
+      value.is_a?(String) && value.start_with?(ENCRYPTED_PREFIX)
+    end
+
+    # Derive a key of given length from a password and salt value.
+    def derive_key(password, salt:, length: KEY_LENGTH, iterations: KDF_ITERATIONS, hash: HASH_FUNC)
+      if defined?(OpenSSL::KDF)
+        OpenSSL::KDF.pbkdf2_hmac(password, salt: salt, iterations: iterations, length: length, hash: hash)
+      else
+        # Ruby 2.4 compatibility
+        OpenSSL::PKCS5.pbkdf2_hmac(password, salt, iterations, length, hash)
+      end
+    end
+
+    # @return [String] hex encoded random bytes
+    def random_salt
+      SecureRandom.hex(16)
+    end
+  end
+
+  # @param [String] raw_key the key directly passed into the encrypt/decrypt functions. This must be exactly {KEY_LENGTH} bytes long.
+  def initialize(raw_key)
+    raise ArgumentError, "key must be #{KEY_LENGTH} bytes long" unless raw_key.bytesize == KEY_LENGTH
+    @derived_key = raw_key
+  end
+
+  # Encrypt a string with the encryption key. Encrypted values are also salted so
+  # calling this function multiple times will result in different values. Only strings
+  # can be encrypted. Any other object type will be return the value passed in.
+  #
+  # @param [String] str string to encrypt (assumes UTF-8)
+  # @return [String] Base64 encoded encrypted string with all aes parameters
+  def encrypt(str)
+    return str unless str.is_a?(String)
+    return "" if str == ""
+
+    cipher = OpenSSL::Cipher.new(CIPHER).encrypt
+
+    # Technically, this is a "bad" way to do things since we could theoretically
+    # get a repeat nonce, compromising the algorithm. That said, it should be safe
+    # from repeats as long as we don't use this key for more than 2^32 encryptions
+    # so... rotate your keys/salt ever 4 billion encryption calls
+    nonce = cipher.random_iv
+    cipher.key = @derived_key
+    cipher.auth_data = ""
+
+    # Make sure the string is encoded as UTF-8. JSON/YAML only support string types
+    # anyways, so if you passed in binary data, it was gonna fail anyways. This ensures
+    # that we can easily decode the string later. If you have UTF-16 or something, deal with it.
+    utf8_str = str.encode(Encoding::UTF_8)
+    encrypted_data = cipher.update(utf8_str) + cipher.final
+    auth_tag = cipher.auth_tag
+
+    params = CipherParams.new(nonce, auth_tag, encrypted_data)
+
+    encode_aes(params).prepend(ENCRYPTED_PREFIX)
+  end
+
+  # Decrypt a string with the encryption key. If the value is not a string or it was
+  # not encrypted with the encryption key, the value itself will be returned.
+  #
+  # @param [String] encrypted_str Base64 encoded encrypted string with aes params (from {#encrypt})
+  # @return [String] decrypted string value
+  # @raise [OpenSSL::Cipher::CipherError] there is something wrong with the encoded data (usually incorrect key)
+  def decrypt(encrypted_str)
+    return encrypted_str unless self.class.encrypted?(encrypted_str)
+
+    decrypt_str = encrypted_str[ENCRYPTED_PREFIX.length..-1]
+    params = decode_aes(decrypt_str)
+
+    cipher = OpenSSL::Cipher.new(CIPHER).decrypt
+
+    cipher.key = @derived_key
+    cipher.iv = params.nonce
+    cipher.auth_tag = params.auth_tag
+    cipher.auth_data = ""
+
+    decoded_str = cipher.update(params.data) + cipher.final
+
+    # force to utf-8 encoding. We already ensured this when we encoded in the first place
+    decoded_str.force_encoding(Encoding::UTF_8)
+  end
+
+  def encrypted?(value)
+    self.class.encrypted?(value)
+  end
+
+  def inspect
+    obj_id = object_id.to_s(16).rjust(16, "0")
+    "#<#{self.class.name}:0x#{obj_id}>"
+  end
+
+  private
+
+  # Basic struct to contain nonce, auth_tag, and data for passing around. Thought
+  # it was better than just passing an Array with positional params.
+  # @private
+  CipherParams = Struct.new(:nonce, :auth_tag, :data)
+
+  # Receive a cipher object (initialized with key) and data
+  def encode_aes(params)
+    encoded = params.values.pack(ENCODING_FORMAT)
+    # encode base64 and get rid of trailing newline and unnecessary =
+    Base64.encode64(encoded).chomp.tr("=", "")
+  end
+
+  # Passed in an aes encoded string and returns a cipher object
+  def decode_aes(str)
+    unpacked_data = Base64.decode64(str).unpack(ENCODING_FORMAT)
+    # Splat the data array apart
+    # nonce, auth_tag, encrypted_data = unpacked_data
+    CipherParams.new(*unpacked_data)
+  end
+end