eyaml

eyaml is a tool for asymmetric encryption of YAML and JSON files. It's largely based on ejson and backwards compatible with any *.ejson file.

Assymetric encryption is handled by RubyCrypto/rbnacl using a sealed box.

Installation

To install eyaml, run:

gem install eyaml

Or alternatively, you can add it to your Gemfile:

gem 'eyaml'

Dependencies

eyaml depends on libsodium. At least 1.0.0 is required.

For MacOS users, libsodium is available via homebrew and can be installed with:

brew install libsodium

Usage

eyaml requires that a file has a _public_key attribute that corresponds to the value generated by running eyaml keygen. Adding a plaintext value into the file and running eyaml encrypt secrets.eyaml (for a file called secrets.eyaml) will encrypt the value using the public key in the same file. To decrypt, ensure a private key is accessible and run eyaml decrypt secrets.eyaml

eyaml supports both JSON and YAML with the extensions eyaml, eyml, and ejson. It will using the extension to determine the format of its output.

CLI

eyaml is primarily interacted through its CLI.

-> % eyaml help
Commands:
  eyaml decrypt         # Decrypt an EYAML file
  eyaml encrypt         # (Re-)encrypt one or more EYAML files
  eyaml help [COMMAND]  # Describe available commands or one specific command
  eyaml keygen          # Generate a new EYAML keypair

Options:
  -k, [--keydir=KEYDIR]  # Directory containing EYAML keys

eyaml encrypt

(Re-)encrypt one or more EYAML files. This is used whenever you add a new value to the config file.

-> % eyaml encrypt config/secrets.production.eyaml
Wrote 517 bytes to config/secrets.production.eyaml.

eyaml decrypt

Decrypts the provided EYAML file.

-> % eyaml decrypt config/secrets.production.eyaml
_public_key: d1c7ba73c520445c5ba14984da8119f2f7b8df7bcdb3f37f5afe9613b118936a
secret: password

eyaml keygen

Generates the keypair for the encryption flow to work. The public key must be placed into the file at _public_key and the private key must be saved in the default key directory (/opt/ejson/keys) with the filename being the public key and the contents, the private key, a key directory you'll provide later, or just pass the --write flag for eyaml to handle it for you.

-> % eyaml keygen
Public Key: a3dbdef9efd1e52a34588de56a6cf9b03bbc2aaf0edda145cfbd9a6370a0a849
Private Key: b01592942ba10f152bcf7c6b6734f6392554c578ff24cebcc62f9e3da6fcf302

# Or by using the --write flag

-> % eyaml keygen --write
Public Key: a3dbdef9efd1e52a34588de56a6cf9b03bbc2aaf0edda145cfbd9a6370a0a849

-> % cat /opt/ejson/keys/a3dbdef9efd1e52a34588de56a6cf9b03bbc2aaf0edda145cfbd9a6370a0a849
b01592942ba10f152bcf7c6b6734f6392554c578ff24cebcc62f9e3da6fcf302

Rails

eyaml comes with baked in Rails support. It will search for a secrets file in config/, decrypt, and load the first valid one it finds. secrets.{eyaml|eyml|ejson} (e.g. config/secrets.eyaml) then secrets.$env.{eyaml|eyml|ejson} (e.g. secrets.production.eyml).

Instead of needing a private key locally, you can provide it to EYAML by setting EJSON_PRIVATE_KEY and it'll be automatically used for decrypting the secrets file.

Apple M1 Support

If you're using the new Apple M1, you need to ensure that you're using a ffi that is working. We've temporarily been including a fork with a fix in any Gemfile where we've included eyaml:

gem "ffi", github: "cheddar-me/ffi", branch: "apple-m1", submodules: true

Development

To get started, make sure you have a working version of Ruby locally. Then clone the repo, and run bin/setup (this will install libsodium if you're on a Mac and setup bundler). Running bundle exec rake or bundle exec rake spec will run the test suite.