ejson(1) - manage application secrets in source control via encrypted json

ejson(1)
ejson(1)

NAME

ejson - manage application secrets in source control via encrypted json

SYNOPSIS

ejson [--keydir path] COMMAND [ARGS]

DESCRIPTION

ejson is a utility for managing a collection of secrets in source control. The secrets are encrypted using public key, elliptic curve cryptography. 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.

See ejson(5) for more information on the ejson file format, and read on for a workflow example.

OPTIONS

--keydir=path: Path to directory containing private keys. Defaults to /opt/ejson/keys. Setting EJSON_KEYDIR will also set this value, with lower precedence.

COMMANDS

ejson encrypt ejson-encrypt(1): Encrypt one or more ejson files (alias: ejson e)
ejson decrypt ejson-decrypt(1): Decrypt an ejson file (alias: ejson d)
ejson keygen ejson-keygen(1): Generate an ejson keypair (alias: ejson g)

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 in ejson(5). 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(5) 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(1), which overwrites the specified files, ejson-decrypt(1) only takes one file parameter, and prints the output to stdout:

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

BUGS

Please file bugs at https://github.com/Shopify/ejson