ejson 1.0.2

Secret management by encrypting values in a JSON hash with a public/private keypair

Homepage: https://github.com/Shopify/ejson

Platform: Rubygems

Language: Go

License: MIT

View on registry: https://rubygems.org/gems/ejson/versions/1.0.2

Documentation: http://www.rubydoc.info/gems/ejson/1.0.2

Direct download link: https://rubygems.org/downloads/ejson-1.0.2.gem

Install: gem install ejson -v 1.0.2


ejson

ejson is a utility for managing a collection of secrets in source control. The secrets are encrypted using public key, elliptic curve cryptography (NaCl Box: Curve25519 + Salsa20 + Poly1305-AES). Secrets are collected in a JSON file, in which all the string values are encrypted. Public keys are embedded in the file, and the decrypter looks up the corresponding private key from its local filesystem.

demo

The main benefits provided by ejson are:

  • Secrets can be safely stored in a git repo.
  • Changes to secrets are auditable on a line-by-line basis with git blame.
  • Anyone with git commit access has access to write new secrets.
  • Decryption access can easily be locked down to production servers only.
  • Secrets change synchronously with application source (as opposed to secrets provisioned by Configuration Management).
  • Simple, well-tested, easily-auditable source.

See the manpages for more technical documentation.

Installation

You can download the .deb package from Github Releases.

On development machines (64-bit linux or OS X), the recommended installation method is via rubygems:

gem install ejson

Workflow

1: Create the Keydir

By default, EJSON looks for keys in /opt/ejson/keys. You can change this by setting EJSON_KEYDIR or passing the -keydir option.

$ mkdir -p /opt/ejson/keys

2: Generate a keypair

When called with -w, ejson keygen will write the keypair into the keydir and print the public key. Without -w, it will print both keys to stdout. This is useful if you have to distribute the key to multiple servers via configuration management, etc.

$ ejson keygen
Public Key:
63ccf05a9492e68e12eeb1c705888aebdcc0080af7e594fc402beb24cce9d14f
Private Key:
75b80b4a693156eb435f4ed2fe397e583f461f09fd99ec2bd1bdef0a56cf6e64
$ ./ejson keygen -w
53393332c6c7c474af603c078f5696c8fe16677a09a711bba299a6c1c1676a59
$ cat /opt/ejson/keys/5339*
888a4291bef9135729357b8c70e5a62b0bbe104a679d829cdbe56d46a4481aaf

3: Create an ejson file

The format is described in more detail later on. For now, create a file that looks something like this. Fill in the <key> with whatever you got back in step 2.

Create this file as test.ejson:

{
  "_public_key": "<key>",
  "database_password": "1234password"
}

4: Encrypt the file

Running ejson encrypt test.ejson will encrypt any new plaintext keys in the file, and leave any existing encrypted keys untouched:

{
  "_public_key": "63ccf05a9492e68e12eeb1c705888aebdcc0080af7e594fc402beb24cce9d14f",
  "database_password": "EJ[1:WGj2t4znULHT1IRveMEdvvNXqZzNBNMsJ5iZVy6Dvxs=:kA6ekF8ViYR5ZLeSmMXWsdLfWr7wn9qS:fcHQtdt6nqcNOXa97/M278RX6w==]"
}

Try adding another plaintext secret to the file and run ejson encrypt test.ejson again. The database_password field will not be changed, but the new secret will be encrypted.

5: Decrypt the file

To decrypt the file, you must have a file present in the keydir whose name is the 64-byte hex-encoded public key exactly as embedded in the ejson document. The contents of that file must be the similarly-encoded private key. If you used ejson keygen -w, you've already got this covered.

Unlike ejson encrypt, which overwrites the specified files, ejson decrypt only takes one file parameter, and prints the output to stdout:

$ ejson decrypt foo.ejson
{
  "_public_key": "63ccf05a9492e68e12eeb1c705888aebdcc0080af7e594fc402beb24cce9d14f",
  "database_password": "1234password"
}

Format

The ejson document format is simple, but there are a few points to be aware of:

  1. It's just JSON.
  2. There must be a key at the top level named _public_key, whose value is a 32-byte hex-encoded (i.e. 64 ASCII byte) public key as generated by ejson keygen.
  3. Any string literal that isn't an object key will be encrypted by default (ie. in {"a": "b"}, "b" will be encrypted, but "a" will not.
  4. Numbers, booleans, and nulls aren't encrypted.
  5. If a key begins with an underscore, its corresponding value will not be encrypted. This is used to prevent the _public_key field from being encrypted, and is useful for implementing metadata schemes.
  6. Underscores do not propagate downward. For example, in {"_a": {"b": "c"}}, "c" will be encrypted.

See also

  • If you use Capistrano for deployment you can use capistrano-ejson to automatically decrypt the secrets on deploy.

Releases

  • 1.0.2 - October 31, 2016 17:42
  • 1.0.1 - November 09, 2015 16:54
  • 1.0.0 - December 18, 2014 02:37
  • 1.0.0.rc2 - December 11, 2014 17:57
  • 1.0.0.rc1 - November 26, 2014 19:42
  • 0.4.0 - July 17, 2014 21:19
  • 0.3.0 - July 14, 2014 21:18
  • 0.2.2 - April 15, 2014 16:50

Project Statistics

SourceRank 15
Dependencies 0
Dependent projects 5
Dependent repositories 17
Total releases 8
Latest release
First release
Stars 503
Forks 21
Watchers 179
Contributors 10
Repo Size: 2.59 MB

Top Contributors See all

Burke Libbey Clayton Smith Simon Eskildsen Jean Boussier Bryan Eikema Nick Evans André Medeiros Bouke van der Bijl Dylan Thacker-Smith Julian Nadeau

Something wrong with this page? Make a suggestion

Export .ABOUT file for this library

Last synced: 2016-11-15 17:28:00 UTC

Login to resync this project