secret_keys 1.0.0.pre → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db4d05a36d5a69f053949e6be11cdedde1203d87d57e41b4609ffbea7118e3b6
-  data.tar.gz: f753189aaed3cae64ef13029a47ee68616a7ca95d309f2607c5427450f7ba63c
+  metadata.gz: d291d004402b3197d72a0210d4586770c7f63e9f1baf70dfb14c5d6d848b52a5
+  data.tar.gz: bbd6e6d3f8e625a31a0502c5099004e9ebbe278d21c39f674ed8a4d0d4c822b5
 SHA512:
-  metadata.gz: 73b58cba572869c1e9a399620ee56b6acdc5b288a1f95337e611bd84ae7231417bbeeaaf3217bc28daec006cec304c79ed62ad6c86ee5acd25513689bfcd8f22
-  data.tar.gz: 9f0c00479cbbfad0d14695f6b446c7427e74865a47f9f05d26e16ad45179405bf82452fc54b283ff73433d93f268998b148eac050fb0583ea0ab58c98f2cf26e
+  metadata.gz: 1d1dae102dd23919a34187b5d6c1c89c8722635aa3937c56777b9dca19cf6a8a765b291bb3c33c792d4c258dc44eb9cf2aa858559171cacc716e73da8d29b24e
+  data.tar.gz: 527a4ab4a67eb63424dae4a284fe9a398efe2d98cf405184eaacfcfbd4f51140d0ffcf389ee35fa3d31202e14aab85ea88df886b3e782f933414fd6ae3de5cd0

data/MIT_LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 Brian Durand
+Copyright (c) 2020 Brian Durand, Winston Durand
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,10 +1,14 @@
 # SecretKeys
 
+[![specs](https://github.com/bdurand/secret_keys/workflows/Run%20tests/badge.svg)](https://github.com/bdurand/secret_keys/actions?query=branch%3Amaster)
+[![code style](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+[![gem version](https://badge.fury.io/rb/secret_keys.svg)](https://badge.fury.io/rb/secret_keys)
+
 This ruby gem handles encrypting values in a JSON or YAML file. It is yet another solution for storing secrets in a ruby project.
 
-The main advantage offered by this gem is that it stores the files in standard JSON format and it can easily store both encrypted and non-encrypted values side-by-side, so easily track all your configurations in one place. After providing your secret key, all values can be easily accessed regardless of whether they were encrypted or plaintext.
+The main advantage offered by this gem is that it stores the files in standard JSON or YAML format and can store both encrypted and non-encrypted values side-by-side, easily tracking all your configurations in one place. After providing your secret key, all values can be easily accessed regardless of whether they were encrypted or plaintext.
 
-Encrypted values are stored using aes-256-gcm, and the key is derived from your password secret and salt using PBKDF2. All security primitives are provided by openssl, based on recommendations put forth in the libsodium crypto suite.
+Encrypted values are stored using AES-256-GCM, and the key is derived from your password secret and a generated salt using PBKDF2. All security primitives are provided by OpenSSL, based on recommendations put forth in the [libsodium](https://doc.libsodium.org/secret-key_cryptography/aead/aes-256-gcm) crypto suite.
 
 ## Usage
 
@@ -17,10 +21,12 @@ secrets = SecretKeys.new("/path/to/file.json", "mysecretkey")
 or a stream
 
 ```ruby
-secrets = SecretKeys.new(File.open("/path/to/file.json"), "mysecretkey")
+stream = File.open("/path/to/file.json")
+secrets = SecretKeys.new(stream, "mysecretkey")
+stream.close
 ```
 
-If you don't supply the encryption key in the constructor, by default it will be read from the `SECRET_KEYS_ENCRYPTION_KEY` environment variable. If that value is not present, then it will attempted to be read from the file path in the `SECRET_KEYS_ENCRYPTION_KEY_FILE` environment variable. As a side note, the empty string (`""`) is not considered a valid secret, so encryption **will** fail if ther is no explicitly passed secret and no ENV variable.
+If you don't supply the encryption key in the constructor, by it will be read from the `SECRET_KEYS_ENCRYPTION_KEY` environment variable. If that value is not present, then it will attempt to be read from the file path in the `SECRET_KEYS_ENCRYPTION_KEY_FILE` environment variable. As a side note, the empty string `""` is not considered a valid secret, so encryption **will** fail if there is no explicitly passed secret and no `ENV` variables.
 
 The `SecretKeys` object delegates to `Hash` and can be treated as a hash for most purposes.
 
@@ -28,7 +34,7 @@ The `SecretKeys` object delegates to `Hash` and can be treated as a hash for mos
 password = secrets["password"]
 ```
 
-You can add values to the hash as well and move keys between being encrypted/unencrypted at rest. The values are always stored unencrypted in memory, but you can save them to a JSON file.
+You can add values to the hash as well and move keys between being encrypted/unencrypted at rest. The values are always stored unencrypted in memory, but you can save them to a JSON or YAML file.
 
 ```ruby
 # api_key is plaintext by default
@@ -39,23 +45,31 @@ secrets.encrypt!("api_key")
 
 # now, when we save, the value for api_key is encrypted
 secrets.save("/path/to/file.json")
+
+# or get a Hash with the encrypted data to handle it yourself
+secrets.encrypted_hash
 ```
 
-Note that since the hash must be serialized to JSON, only JSON compatible keys and values (string, number, boolean, null, array, hash) can be used. The same holds for YAML.
+Note that since the hash must be serialized to JSON, only JSON compatible keys and values (string, number, boolean, null, array, hash) can be used. The same holds for YAML. All keys must be strings.
 
-Only string values can be encrypted. The encryption is recusive, so all strings in an array or hash in the encrypted keys will be encrypted. See the example below.
+**Only string values are encrypted**. The encryption is recursive, so all strings in an array or hash in the encrypted keys will be encrypted. See the example below.
 
-```json
+```javascript
 {
   ".encrypted": {
     "enc_key1": {
-      "num": 1,
-      "rec": ["<encrypted-val>", true],
+      "num": 1, // primitives are not encrypted
+      "null_value": null, // null is not encrypted
+      "rec": [
+        "<encrypted-val>", // we recurse through the array to encrypt its strings
+        true // booleans aren't encrypted either
+      ],
       "thing": "<encrypted-val>"
     },
     "enc_key2": "<encrypted-val>"
   },
-  "unenc_key": "plaintext"
+  "unenc_key": "plaintext",
+  "other_plaintext": "See, you can read my contents!"
 }
 ```
 
@@ -63,52 +77,107 @@ Only string values can be encrypted. The encryption is recusive, so all strings
 
 You can use the `secret_keys` command line tool to manage your JSON files.
 
-You can initialize a new file with the encrypt command.
+```console
+$ secret_keys help
+Usage: secret_keys <command> ...
+
+Commands:
+    encrypt   Encrypt a file
+    decrypt   Decrypt a file
+    read      Read the value of one key in a file
+    edit      Change which values are encrypted, the file's encryption key, delete/add keys, etc.
+    init      Initialize an empty secrets file
+
+    help      Get help for a command
+```
+
+You can initialize a new file with the init command.
+
+```bash
+secret_keys init --secret=mysecret /path/to/new/file.json
+```
+
+Or add the encryption section to an existing file.
 
 ```bash
-secret_keys encrypt --key mysecret /path/to/file.json
+secret_keys encrypt --secret=mysecret --in-place /path/to/file.json
 ```
 
-If you don't specify the `--key` argument, the encryption key will either be read from the STDIN stream or from the `SECRET_KEYS_ENCRYPTION_KEY` environment variable.
+You can also specify the path to a file where the secret is stored with `--secret-file`. If you don't specify the `--secret` or `--secret-file` argument, the secret will be read from the `SECRET_KEYS_ENCRYPTION_KEY` or `SECRET_KEYS_ENCRYPTION_KEY_FILE` environment variable.
+
+You can also specify to read the secret from STDIN with `--secret=-`.
+
+```bash
+# reading from stdin
+$ secret_keys encrypt --secret=- data.json
+Secret Key: <hidden password input>
+
+# or you can pipe in the secret
+$ echo "my_secret" | secret_keys encrypt --secret=- data.json
+```
 
-You can then use your favorite text editor to edit the values in the JSON file. When you are done, you can run the same command again to encrypt the file.
+You can then use your favorite text editor to edit the values in the file and putting any keys you want encrypted in the `".encrypted"` section. When you are done, you can run the same command again to encrypt all new keys in the file. The default behaviour is to output the file to STDOUT, or you can rewrite the file in place by passing `--in-place`.
 
-You can add or modify keys through the command line as well.
+Finally, calling encrypt with `--encrypt-all` will encrypt all keys in a file. You can use this to encrypt all the values in an existing JSON or YAML file.
 
 ```bash
-# add an encrypted key
-secret_keys encrypt --key mysecret --set password /path/to/file.json
+secret_keys encrypt -s mysecret --encrypt-all --in-place data.json
+```
+
+You can also add or modify keys through the command line using `--set-encrypted` or `-e` for short. You can also use "dot syntax" to address nested keys, for example `aws.client_secret` addresses `{"aws":{"client_secret": <value>}}`
+
+```console
+# mark individual keys for encryption
+$ secret_keys edit -s mysecret --set-encrypted password -e other_password /path/to/file.json
+{ ... }
 
 # add an encrypted key with a value
-secret_keys encrypt --key mysecret --set password=value /path/to/file.json
+$ secret_keys edit -s mysecret --set-encrypted password=value /path/to/file.json
+{ ... }
 
-# encrypt all keys in the file
-secret_keys encrypt --key mysecret --all /path/to/file.json
+# edit nested keys (assumes hashes by default)
+# nested keys are split on `.` dots
+$ secret_keys edit -s mysecret -e aws.secret=password data.json
+{
+  ".encrypted": {
+    "aws": {
+      "secret": "<encrypted-value>"
+    },
+    ...
+  }
+}
 ```
 
-You can also decrypt or delete keys.
+You can also decrypt keys by moving them to the plain text section of the file (`--set-decrypted` or `-d`) or remove them altogether (`--remove` or `-r`).
 
 ```bash
-secret_keys encrypt --key mysecret --decrypt username --delete password /path/to/file.json
+secret_keys edit -s mysecret --set-decrypted username --remove password /path/to/file.json
 ```
 
 You can change the encryption key used in the file.
 
 ```bash
-secret_keys encrypt --key mysecret --new-key newsecret /path/to/file.json
+secret_keys encrypt -s mysecret --new-secret-key newsecret /path/to/file.json
 ```
 
 Finally, you can print the unencrypted file to STDOUT.
 
 ```bash
-secret_keys decrypt --key mysecret /path/to/file.json
+# print the decrypted file to stdout
+secret_keys decrypt --secret mysecret /path/to/file.json
+
+# Explicitly output as JSON
+secret_keys decrypt --secret mysecret --format json /path/to/file.json
+
+# Output the data as YAML
+secret_keys decrypt --secret mysecret --format yaml /path/to/file.json
 ```
 
 ## File Format
 
-The data can be stored in a plain old JSON file. Any unencrypted keys will appear under in the special `".encrypted"` key in the hash. The encryption key itself is also stored in the `".key"` key along with the encrypted values. This is used to confirm that the correct key is being used when decrypting the file.
+The data can be stored in a plain old JSON or YAML file. Any unencrypted keys will appear under the special `".encrypted"` key in the hash. A check value (to validate you are using the correct encryption key) is stored under `".key"`. Finally, there is also the `".salt"` which was used for key derivation.
 
-In this example, `key_1` is stored in plain text while `key_2` has been encrypted.
+In this example, `not_encrypted` is stored in plain text while `foo` has been encrypted.
 
 ```json
 {
@@ -124,3 +193,38 @@ In this example, `key_1` is stored in plain text while `key_2` has been encrypte
   "not_encrypted": "plain text value"
 }
 ```
+
+## SecretKeys::Encryptor
+
+This library also comes with a generic encryption tool that can be used on its own as a generic tool for encrypting strings with AES-256-GCM encryption.
+
+```ruby
+secret = "mysecret"
+# The salt is used to generate an encryption key from the secret.
+# You do not need to salt individual values when encrypting them.
+# This will be done by the encryption algorithm itself.
+# The salt must be a hex encoded byte array.
+salt = "deadbeef"
+
+encryptor = SecretKeys::Encryptor.from_passowrd(secret, salt)
+
+encrypted = encryptor.encrypt("foobar") # => "$AES$:345kjwertE345E..."
+encryptor.decrypt(encrypted) # => "foobar"
+encryptor.decrypt("foobar") # => "foobar"
+
+# If the data is corrupted/tampered with, decryption will raise an error.
+# This can also be caused by using the wrong key.
+begin
+  encryptor.decrypt("$AES$:malformed/corrupted data")
+rescue OpenSSL::Cipher::CipherError
+  puts "Bad data/encryption key"
+end
+
+# You can also check if a value looks like an encrypted string.
+SecretKeys::Encryptor.encrypted?("foobar") # => false
+SecretKeys::Encryptor.encrypted?(encrypted) # => true
+```
+
+## Versioning
+
+This code aims to be compliant with [Semantic Verioning 2.0](https://semver.org/). If there is ever a need to change file encryption parameters, those changes will be released as a new major version. Just to be clear, we do not anticipate needing to change these parameters.

data/VERSION

@@ -1 +1 @@
-1.0.0.pre
+1.0.0

data/bin/secret_keys

@@ -1,9 +1,6 @@
 #!/usr/bin/env ruby
 
-# TODO this command tool will be rewritten with better, more consistent options.
-
-require 'optparse'
-require_relative "../lib/secret_keys"
+require_relative "../lib/secret_keys/cli"
 
 # Load enironment variables from .env file in current working directory if available.
 if File.exist?(File.expand_path(".env"))
@@ -14,115 +11,52 @@ if File.exist?(File.expand_path(".env"))
   end
 end
 
-encryption_key = nil
-new_encryption_key = nil
-add_keys = []
-decrypt_keys = []
-delete_keys = []
-add_all = false
-
-options = ARGV.dup
-action = options.shift
-
-parser = OptionParser.new do |opts|
-  opts.banner = "Usage: secret_keys encrypt|decrypt [options] file_path"
-
-  opts.on('--key ENCRYPTION_KEY', String, "Encryption key used to encrypt strings in the JSON file. This value can also be passed in the SECRET_KEYS_ENCRYPTION_KEY environment variable or via STDIN.") do |value|
-    encryption_key = value
-  end
-
-  opts.on('--set JSON_KEY', String, "Add a key to the encrypted elements. You can specify the value as well by using key=value.") do |value|
-    add_keys << value
-  end
-
-  opts.on('--all', "Add all keys to the encrypted elements.") do
-    add_all = true
-  end
-
-  opts.on('--decrypt JSON_KEY', String, "Move a key to the decrypted elements. You can specify the value as well by using key=value.") do |value|
-    decrypt_keys << value
-  end
-
-  opts.on('--delete JSON_KEY', String, "Remove a key.") do |value|
-    delete_keys << value
-  end
-
-  opts.on('--new-key ENCRYPTION_KEY', String, "Set a new encryption key for the file.") do |value|
-    new_encryption_key = value
-  end
+COMMANDS = {
+  "encrypt" => SecretKeys::CLI::Encrypt,
+  "decrypt" => SecretKeys::CLI::Decrypt,
+  "read" => SecretKeys::CLI::Read,
+  "edit" => SecretKeys::CLI::Edit,
+  "init" => SecretKeys::CLI::Init
+}.freeze
+
+argv = ARGV
+action = argv.shift
+command_class = COMMANDS[action]
+unless command_class
+  if action == "help" || action == "--help"
+    if argv.empty?
+      puts <<~HELP
+      Usage: secret_keys <command> ...
+      version #{SecretKeys::VERSION}
+
+      Commands:
+          encrypt   Encrypt a file
+          decrypt   Decrypt a file
+          read      Read the value of one key in a file
+          edit      Change which values are encrypted, the file's encryption key, delete/add keys, etc.
+          init      Initialize an empty secrets file
+
+          help      Get help for a command
+      HELP
+    elsif argv.one? && COMMANDS.include?(argv.first)
+      COMMANDS[argv.first].new(["--help"])
+    else
+      STDERR.puts "Unknown help for #{argv.inspect}."
+      exit 1
+    end
 
-  opts.on("--help", "Prints this help") do
-    puts opts.help
-    exit
+    exit 0
+  else
+    STDERR.puts "Unknow action #{action.inspect}; must be one of #{COMMANDS.keys.join(', ')}"
+    STDERR.puts "Run secret_keys --help for more info"
   end
-end
-parser.parse!(options)
-
-unless ["encrypt", "decrypt"].include?(action)
-  STDERR.puts parser.banner
   exit 1
 end
 
-file_path = options[0]
-unless file_path
-  STDERR.puts parser.banner
-  exit 1
-end
-
-unless encryption_key
-  encryption_key = STDIN.read.chomp if STDIN.ready?
-end
-
-secrets = nil
-if File.exist?(file_path)
-  secrets = SecretKeys.new(file_path, encryption_key)
-else
-  secrets = SecretKeys.new(nil, encryption_key)
-end
-
-if action == "encrypt"
-  secrets.encryption_key = new_encryption_key if new_encryption_key
-
-  if add_all
-    secrets.keys.each do |key|
-      secrets.encrypt!(key)
-    end
-  end
-
-  add_keys.each do |key|
-    if key.include?("=")
-      key, value = key.split("=", 2)
-      secrets[key] = value
-    end
-    secrets[key] = nil unless secrets.include?(key)
-    secrets.encrypt!(key)
-  end
-
-  decrypt_keys.each do |key|
-    if key.include?("=")
-      key, value = key.split("=", 2)
-      secrets[key] = value
-    end
-    secrets[key] = nil unless secrets.include?(key)
-    secrets.decrypt!(key)
-  end
-
-  delete_keys.each do |key|
-    secrets.delete(key)
-  end
-
-  secrets.save(file_path)
-elsif action == "decrypt"
-  if File.exist?(file_path)
-    if file_path.end_with?(".yaml") || file_path.end_with?(".yml")
-      STDOUT.write(YAML.dump(secrets.to_h))
-    else
-      STDOUT.puts(JSON.pretty_generate(secrets.to_h))
-    end
-  else
-    STDERR.puts("File not found: #{file_path}")
-    exit 1
-  end
-else
+begin
+  command = command_class.new(argv)
+  command.run!
+rescue ArgumentError => e
+  STDERR.puts e.message
   exit 1
 end

data/lib/secret_keys.rb

@@ -3,125 +3,42 @@
 require "openssl"
 require "json"
 require "yaml"
-require "securerandom"
 require "delegate"
 require "set"
 require "pathname"
-require "base64"
 
 # Load a JSON file with encrypted values. This value can be used as a hash.
 class SecretKeys < DelegateClass(Hash)
+  # Error if the provided encryption key is invalid for this file
   class EncryptionKeyError < ArgumentError; end
 
-  class << self
-    # 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 returned the value passed in.
-    #
-    # @param [String] str string to encrypt (assumes UTF-8)
-    # @param [String] secret_key 32 byte ASCII-8BIT encryption key
-    # @return [String] Base64 encoded encrypted string with all aes parameters
-    def encrypt(str, secret_key)
-      return str unless str.is_a?(String) && secret_key
-      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 = secret_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`)
-    # @param [String] secret_key 32 byte ASCII-8BIT encryption key
-    # @return [String] decrypted string value
-    def decrypt(encrypted_str, secret_key)
-      return encrypted_str unless encrypted_str.is_a?(String) && secret_key
-      return encrypted_str unless encrypted_str.start_with?(ENCRYPTED_PREFIX)
-
-      decrypt_str = encrypted_str[ENCRYPTED_PREFIX.length..-1]
-      params = decode_aes(decrypt_str)
-
-      cipher = OpenSSL::Cipher.new(CIPHER).decrypt
-
-      cipher.key = secret_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
-
-    private
-
-    # format: <nonce:12>, <auth_tag:16>, <data:*>
-    ENCODING_FORMAT = "a12 a16 a*"
-    ENCRYPTED_PREFIX = "$AES$:"
-    CIPHER = "aes-256-gcm"
-
-    # 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
+  # Error if the crypto version specified in the file is unsupported
+  class VersionError < StandardError; 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
-
-  # Parse a JSON stream or file with encrypted values. Any values in the ".encrypted" key
-  # in the JSON document will be decrypted with the provided encryption key. If values
+  # Parse a JSON or YAML stream or file with encrypted values. Any values in the ".encrypted" key
+  # in the document will be decrypted with the provided encryption key. If values
   # were put into the ".encrypted" key manually and are not yet encrypted, they will be used
   # as is without any decryption.
   #
-  # @param [String, #read, Hash] path_or_stream path to a json/yaml file to load, an IO object, or a Hash (mostly for testing purposes)
+  # @param [String, #read, Hash] path_or_stream path to a JSON/YAML file to load, an IO object, or a Hash (mostly for testing purposes)
   # @param [String] encryption_key secret to use for encryption/decryption
   #
   # @note If no encryption key is passed, this will defautl to env var SECRET_KEYS_ENCRYPTION_KEY
   # or (if that is empty) the value read from the file path in SECRET_KEYS_ENCRYPTION_KEY_FILE.
   def initialize(path_or_stream, encryption_key = nil)
+    @encryption_key = nil
+    @salt = nil
+    @format = :json
+
     encryption_key = read_encryption_key(encryption_key)
     update_secret(key: encryption_key)
     path_or_stream = Pathname.new(path_or_stream) if path_or_stream.is_a?(String)
     load_secrets!(path_or_stream)
-    # if no salt exists, create one.
-    update_secret(salt: SecureRandom.hex(8)) if @salt.nil?
+
     super(@values)
   end
 
-  # Convert the value into an actual Hash object.
+  # Convert into an actual Hash object.
   #
   # @return [Hash]
   def to_h
@@ -155,28 +72,30 @@ class SecretKeys < DelegateClass(Hash)
     @secret_keys.include?(key)
   end
 
-  # Save the JSON to a file at the specified path. Encrypted values in the file
+  # Save the encrypted hash to a file at the specified path. Encrypted values in an existing file
   # will not be updated if the values have not changed (since each call uses a
-  # different initialization vector).
+  # different initialization vector). This can be helpful if you have your secrets in source
+  # control so that only changed keys will actually be changed in the file when it is updated.
   #
-  # @param [String] path Filepath to save to. Supports yaml and json format as the extension
-  # @param [Boolean] update: check to see if values have been changed before overwriting
+  # @param [String, Pathname] path path of the file to save. If the file exists, only changed values will be updated.
+  # @param [String, Symbol] format: output format (YAML or JSON) to use. This will default based on the extension on the file path or the format originally used
   # @return [void]
-  def save(path, update: true)
+  def save(path, format: nil)
     # create a copy of the encrypted hash for working on
     encrypted = encrypted_hash
 
-    if File.exist?(path) && update
-      original_data = File.read(path)
-      original_hash = parse_data(original_data)
-      original_encrypted = original_hash[ENCRYPTED] if original_hash
-      # only check for unchanged keys if the original had encryption with the same key
-      if original_encrypted && encryption_key_matches?(original_encrypted[ENCRYPTION_KEY])
-        restore_unchanged_keys!(encrypted[ENCRYPTED], original_encrypted)
+    if format.nil?
+      if yaml_file?(path)
+        format = :yaml
+      elsif json_file?(path)
+        format = :json
       end
     end
+    format ||= @format
+    format = format.to_s.downcase
 
-    output = (yaml_file?(path) ? YAML.dump(encrypted) : "#{JSON.pretty_generate(encrypted)}#{$/}")
+    output = (format == "yaml" ? YAML.dump(encrypted) : JSON.pretty_generate(encrypted))
+    output << $/ unless output.end_with?($/) # ensure file ends with system dependent new line
     File.open(path, "w") do |file|
       file.write(output)
     end
@@ -184,7 +103,7 @@ class SecretKeys < DelegateClass(Hash)
   end
 
   # Output the keys as a hash that matches the structure that can be loaded by the initalizer.
-  # Note that all encrypted values will be re-salted when they are encrypted.
+  # Values that have not changed will not be re-salted so the encrypted values will remain the same.
   #
   # @return [Hash] An encrypted hash that can be saved/parsed by a new instance of {SecretKeys}
   def encrypted_hash
@@ -199,10 +118,14 @@ class SecretKeys < DelegateClass(Hash)
         hash[key] = value
       end
     end
-    encrypted = {
-      SALT => @salt,
-      ENCRYPTION_KEY => key_dummy_value
-    }.merge(encrypt_values(encrypted))
+
+    unless encryption_key_matches?(@original_encrypted[ENCRYPTION_KEY])
+      @original_encrypted = {}
+    end
+    encrypted.merge!(encrypt_values(encrypted, @original_encrypted))
+    encrypted[SALT] = @salt
+    encrypted[ENCRYPTION_KEY] = (@original_encrypted[ENCRYPTION_KEY] || encrypted_known_value)
+    encrypted[VERSION_KEY] = CRYPTO_VERSION
 
     hash[ENCRYPTED] = encrypted
     hash
@@ -213,22 +136,27 @@ class SecretKeys < DelegateClass(Hash)
   # @param [String] new_encryption_key encryption key to use for future {#save} calls
   # @return [void]
   def encryption_key=(new_encryption_key)
+    @original_encrypted = {}
     update_secret(key: new_encryption_key)
   end
 
+  # Return the data format (:json or :yaml) for the original data. Defaults to :json.
+  #
+  # @return [String]
+  def input_format
+    @format
+  end
+
   private
 
   ENCRYPTED = ".encrypted"
   ENCRYPTION_KEY = ".key"
+  VERSION_KEY = ".version"
   SALT = ".salt"
 
-  # Used as a known dummy value for verifying we have the correct key
+  # Used as a known value for verifying we have the correct key
   # DO NOT CHANGE!!!
-  KNOWN_DUMMY_VALUE = "SECRET_KEY"
-
-  KDF_ITERATIONS = 20_000
-  HASH_FUNC = "sha256"
-  KEY_LENGTH = 32
+  KNOWN_VALUE = "SECRET_KEY"
 
   # Load the JSON data in a file path or stream into a hash, decrypting all the encrypted values.
   #
@@ -236,8 +164,9 @@ class SecretKeys < DelegateClass(Hash)
   def load_secrets!(path_or_stream)
     @secret_keys = Set.new
     @values = {}
+    @original_encrypted = {}
 
-    hash = nil
+    hash = {}
     if path_or_stream.is_a?(Hash)
       # HACK: Perform a marshal dump/load operation to get a deep copy of the hash.
       #       Otherwise, we can end up using destructive `#delete` operations and mess
@@ -247,12 +176,17 @@ class SecretKeys < DelegateClass(Hash)
       data = path_or_stream.read
       hash = parse_data(data)
     end
-    return if hash.nil? || hash.empty?
 
     encrypted_values = hash.delete(ENCRYPTED)
     if encrypted_values
+      @original_encrypted = Marshal.load(Marshal.dump(encrypted_values))
+
+      version = encrypted_values.delete(VERSION_KEY) || CRYPTO_VERSION
+      raise VersionError, "Unsupported file version #{version}. Max supported is #{CRYPTO_VERSION}." if version > CRYPTO_VERSION
+
       file_key = encrypted_values.delete(ENCRYPTION_KEY)
-      update_secret(salt: encrypted_values.delete(SALT))
+      salt = (encrypted_values.delete(SALT) || Encryptor.random_salt)
+      update_secret(salt: salt)
 
       # Check that we are using the right key
       if file_key && !encryption_key_matches?(file_key)
@@ -260,6 +194,9 @@ class SecretKeys < DelegateClass(Hash)
       end
       @secret_keys = encrypted_values.keys
       hash.merge!(decrypt_values(encrypted_values))
+    elsif @salt.nil?
+      # if no salt exists, create one.
+      update_secret(salt: Encryptor.random_salt)
     end
 
     @values = hash
@@ -269,23 +206,37 @@ class SecretKeys < DelegateClass(Hash)
   # @param [String] data file data to parse
   # @return [Hash] data parsed to a hash
   def parse_data(data)
+    @format = :json
+    return {} if data.nil? || data.empty?
     JSON.parse(data)
   rescue JSON::JSONError
+    @format = :yaml
     YAML.safe_load(data)
   end
 
   # Recursively encrypt all values.
-  def encrypt_values(values)
+  def encrypt_values(values, original)
     if values.is_a?(Hash)
       encrypted_hash = {}
-      values.keys.each do |key|
-        encrypted_hash[key.to_s] = encrypt_values(values[key])
+      values.each_key do |key|
+        key = key.to_s
+        original_value = original[key] if original.is_a?(Hash)
+        encrypted_hash[key] = encrypt_values(values[key], original_value)
       end
       encrypted_hash
     elsif values.is_a?(Enumerable)
-      values.collect { |value| encrypt_values(value) }
+      if original.is_a?(Enumerable)
+        values.zip(original).collect { |value, original_value| encrypt_values(value, original_value) }
+      else
+        values.collect { |value| encrypt_values(value, nil) }
+      end
     else
-      encrypt_value(values)
+      decrypted_original = decrypt_value(original)
+      if decrypted_original == values && decrypted_original != original
+        original
+      else
+        encrypt_value(values)
+      end
     end
   end
 
@@ -304,45 +255,14 @@ class SecretKeys < DelegateClass(Hash)
     end
   end
 
-  # Since the encrypted values include a salt, make sure we don't overwrite values in the stored
-  # documents when the decrypted values haven't changed since this would mess up any file history
-  # in a source code repository.
-  def restore_unchanged_keys!(new_hash, old_hash)
-    if new_hash.is_a?(Hash) && old_hash.is_a?(Hash)
-      new_hash.keys.each do |key|
-        new_value = new_hash[key]
-        old_value = old_hash[key]
-        next if new_value == old_value
-
-        if new_value.is_a?(Enumerable) && old_value.is_a?(Enumerable)
-          restore_unchanged_keys!(new_value, old_value)
-        elsif equal_encrypted_values?(new_value, old_value)
-          new_hash[key] = old_value
-        end
-      end
-    elsif new_hash.is_a?(Array) && old_hash.is_a?(Array)
-      new_hash.size.times do |i|
-        new_val = new_hash[i]
-        old_val = old_hash[i]
-        if new_val != old_val
-          if new_val.is_a?(Enumerable) && old_val.is_a?(Enumerable)
-            restore_unchanged_keys!(new_val, old_val)
-          elsif equal_encrypted_values?(new_val, old_val)
-            new_hash[i] = old_val
-          end
-        end
-      end
-    end
-  end
-
   # Helper method to encrypt a value.
   def encrypt_value(value)
-    self.class.encrypt(value, @secret_key)
+    @encryptor.encrypt(value)
   end
 
   # Helper method to decrypt a value.
   def decrypt_value(encrypted_value)
-    self.class.decrypt(encrypted_value, @secret_key)
+    @encryptor.decrypt(encrypted_value)
   end
 
   # Helper method to test if two values are both encrypted, but result in the same decrypted value.
@@ -362,23 +282,14 @@ class SecretKeys < DelegateClass(Hash)
     end
   end
 
-  # Derive a key of given length from a password and salt value.
-  def derive_key(password, salt:, length:)
-    if defined?(OpenSSL::KDF)
-      OpenSSL::KDF.pbkdf2_hmac(password, salt: salt, iterations: KDF_ITERATIONS, length: length, hash: HASH_FUNC)
-    else
-      OpenSSL::PKCS5.pbkdf2_hmac(password, salt, KDF_ITERATIONS, length, HASH_FUNC)
-    end
-  end
-
-  # This is a
-  def key_dummy_value
-    encrypt_value(KNOWN_DUMMY_VALUE)
+  # This is an encrypted known value that can be used determine if the secret has changed.
+  def encrypted_known_value
+    encrypt_value(KNOWN_VALUE)
   end
 
   # Helper to check if our encryption key is correct
   def encryption_key_matches?(encrypted_key)
-    decrypt_value(encrypted_key) == KNOWN_DUMMY_VALUE
+    decrypt_value(encrypted_key) == KNOWN_VALUE
   rescue OpenSSL::Cipher::CipherError
     # If the key fails to decrypt, then it cannot be correct
     false
@@ -389,10 +300,15 @@ class SecretKeys < DelegateClass(Hash)
     ext == "yaml" || ext == "yml"
   end
 
+  def json_file?(path)
+    ext = path.split(".").last.to_s.downcase
+    ext == "json"
+  end
+
   # Update the secret key by updating the salt
   #
-  # @param key: new encryption key
-  # @param salt: salt to use for secret
+  # @param key new encryption key
+  # @param salt salt to use for secret
   # @return [void]
   def update_secret(key: nil, salt: nil)
     @encryption_key = key unless key.nil? || key.empty?
@@ -400,28 +316,36 @@ class SecretKeys < DelegateClass(Hash)
 
     # Only update the secret if encryption key and salt are present
     if !@encryption_key.nil? && !@salt.nil?
-      # Convert the salt to raw byte string
-      salt_bytes = [@salt].pack("H*")
-      @secret_key = derive_key(@encryption_key, salt: salt_bytes, length: KEY_LENGTH)
+      @encryptor = Encryptor.from_password(@encryption_key, @salt)
     end
+
     # Don't accidentally return the secret, dammit
     nil
   end
-  
+
   # Logic to read an encryption key from environment variables if it is not explicitly supplied.
   # If it isn't specified, the value will be read from the SECRET_KEYS_ENCRYPTION_KEY environment
   # variable. Otherwise, it will be tried to read from the file specified by the
   # SECRET_KEYS_ENCRYPTION_KEY_FILE environment variable.
+  # @return [String, nil] the encryption key
   def read_encryption_key(encryption_key)
     return encryption_key if encryption_key && !encryption_key.empty?
-    encryption_key = ENV['SECRET_KEYS_ENCRYPTION_KEY']
+
+    encryption_key = ENV["SECRET_KEYS_ENCRYPTION_KEY"]
     return encryption_key if encryption_key && !encryption_key.empty?
-    encryption_key_file = ENV['SECRET_KEYS_ENCRYPTION_KEY_FILE']
+
+    encryption_key = nil
+    encryption_key_file = ENV["SECRET_KEYS_ENCRYPTION_KEY_FILE"]
     if encryption_key_file && !encryption_key_file.empty? && File.exist?(encryption_key_file)
-      File.read(encryption_key_file).chomp
-    else
-      nil
+      encryption_key = File.read(encryption_key_file).chomp
     end
-  end
 
+    # final check if encryption key was passed in
+    raise EncryptionKeyError.new("Encryption key not specified") if encryption_key.nil? || encryption_key.empty?
+
+    encryption_key
+  end
 end
+
+require_relative "secret_keys/version"
+require_relative "secret_keys/encryptor"