Skip to content

envato/ejson_wrapper

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

56 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

EJSON Wrapper

Wraps the ejson program to safely execute it and parse the resulting JSON. Additionally it offers a feature to encrypt/decrypt secrets with encrypted private key using AWS KMS.

Prerequisites

  • ejson application
  • Path to ejson binary is included in PATH environment variable

Installation

Add this line to your application's Gemfile:

gem 'ejson_wrapper'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ejson_wrapper

Usage

Decrypting EJSON files

Ensure your application has AWS IAM Permission to decrypt with KMS.

In Ruby code:

# Private key is in /opt/ejson/keys
EJSONWrapper.decrypt('myfile.ejson')
=> { :my_api_key => 'secret' }

# Private key is in /alternate/key/dir
EJSONWrapper.decrypt('myfile.ejson', key_dir: 'alternate/key/dir')
=> { :my_api_key => 'secret' }

# Private key is in memory
EJSONWrapper.decrypt('myfile.ejson', private_key: 'be8597abaa68bbfa23193624b1ed5e2cd6b9a8015e722138b23ecd3c90239b2d')
=> { :my_api_key => 'secret' }

# Private key is stored inside the ejson file itself as _private_key_enc (encrypted with KMS & Base64 encoded)
EJSONWrapper.decrypt('myfile.ejson', use_kms: true, region: 'ap-southeast-2')
=> { :my_api_key => 'secret' }

Command line:

# decrypt all
$ ejson_wrapper decrypt --file file.ejson --region us-east-1
{
  "my_api_key": "[secret]"
}

# decrypt & extract a specific secret
$ ejson_wrapper decrypt --file file.ejson --region us-east-1 --secret my_api_key
[secret]

Generating EJSON files

Ensure your application has AWS IAM Permission to encrypt with KMS.

Firstly, the EJSON is generated to have public key and Base64 encoded & encrypted private key in _public_key and _private_key_enc respectively with:

Using CLI:

$ ejson_wrapper generate --region $AWS_REGION --kms-key-id [key_id] --file myfile.ejson
Generated EJSON file myfile.ejson

OR Ruby code:

# Generate encrypted EJSON file (overwritting the unencrypted EJSON file)
EJSONWrapper.generate(region: ENV['AWS_REGION'], kms_key_id: 'key_id', file: 'myfile.ejson')
=> Generated EJSON file myfile.ejson

Verify to ensure the new file contain the two required keys:

$ cat myfile.ejson
{
  "_public_key": "[public_key]",
  "_private_key_enc":"[base64_encoded_encrypted_private_key]",
}

You now can add secrets into the EJSON file, in following example my_api_key in plaintext entry is added:

# myfile.ejson
{
  "_public_key": "[public_key]",
  "_private_key_enc":"[base64_encoded_encrypted_private_key]",
  "my_api_key": "plaintext"
}

to encrypt the secrets, run following command:

$ ejson encrypt myfile.ejson

Verify to ensure the secret is encrypted correctly:

$ cat myfile.ejson
{
  "_public_key": "[public_key]",
  "_private_key_enc":"[base64_encoded_encrypted_private_key]",
  "my_api_key": "encrypted_secret"
}

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/envato/ejson_wrapper.