1. ejson(5)
3. ejson(5)

NAME

ejson - A JSON file with asymmetric-key-encrypted values

SYNOPSIS

An ejson file is syntactically a json file, but with a few minor semantic additions described below.

ejson files are, by convention, saved with the extension ".ejson".

PUBLIC KEY

Each ejson file must have a key at the top level named "_public_key". This implies that the top-level structure must be an object, not an array.

The "_public_key" key must have a string value, which is a hex-encoded 32-byte (totalling 64 ASCII bytes) public key as generated by ejson-keygen(1).

By convention, "_public_key" should be the first key in the file.

ENCRYPTABLE VALUES

A value is considered encryptable if:

1. It is a string literal (numbers, true, false, null all remain unencrypted);
2. It is not an object key (ie. not immediately followed by a ":");
3. Its corresponding object key did not begin with an underscore ("_").

Take special note of point 3. This is the reason "_public_key" isn't encrypted, and can be used to construct metadata schemes. For example, in the excerpt below, only the values for rotation_password and secret will be encrypted.

"my_secret": {
  "_description": "API key for foocorp",
  "_rotation": "https://example.com/foocorp/apikey",
  "_rotation_username": "admin",
  "rotation_password": "password",
  "secret": "123123123123123123123"
}

Also note that this underscore "unencryptable" attribute does not inherit. For example, the password in this excerpt will be encrypted.

"_unencryptable": {
  "password": "encrypted anyway"
}

SECRET SCHEMA

When a value is encrypted, it will be replaced by a relatively long string of the form "EJ[V:P:N:M]". The fields are:

V (decimal-as-string int)

Schema Version, hard-coded to "1" for now

P (base64-encoded 32-byte array)

Public key of an ephemeral keypair used to encrypt this key

N (base64-encoded 24-byte array)

Nonce used to encrypt this key

M (base64-encoded variable-length array)

Raw ciphertext

SEE ALSO

ejson(1) ejson-encrypt(1) ejson-decrypt(1) ejson-keygen(1)

2. November 2014
3. ejson(5)