json

Documentation

Overview

Package json implements functions to load the Public key data from an EJSON file, and to walk that data file, encrypting or decrypting any keys which, according to the specification, are marked as encryptable (see README.md for details).

It may be non-obvious why this is implemented using a scanner and not by loading the structure, manipulating it, then dumping it. Since Go's maps are explicitly randomized, that would cause the entire structure to be randomized each time the file was written, rendering diffs over time essentially useless.

Index

• Constants
• Variables
• func CollapseMultilineStringLiterals(data []byte) ([]byte, error)
• func ExtractPublicKey(data []byte) (key [32]byte, err error)
• type Walker
  • func (ew *Walker) Walk(data []byte) ([]byte, error)

Constants

const (
	// PublicKeyField is the key name at which the public key should be
	// stored in an EJSON document.
	PublicKeyField = "_public_key"
)

Variables

var ErrPublicKeyInvalid = errors.New("public key has invalid format")

ErrPublicKeyInvalid means that the PublicKeyField key was found, but the value could not be parsed into a valid key.

var ErrPublicKeyMissing = errors.New("public key not present in EJSON file")

ErrPublicKeyMissing indicates that the PublicKeyField key was not found at the top level of the JSON document provided.

Functions

func CollapseMultilineStringLiterals

func CollapseMultilineStringLiterals(data []byte) ([]byte, error)

It's common to want to paste multiline secrets into an EJSON file, and JSON doesn't handle multiline literals, so we cheat here. Our first pass over the file is to replace embedded newlines in string literals with escaped newlines.

func ExtractPublicKey

func ExtractPublicKey(data []byte) (key [32]byte, err error)

ExtractPublicKey finds the _public_key value in an EJSON document and parses it into a key usable with the crypto library.

Types

type Walker

type Walker struct {
	Action func([]byte) ([]byte, error)
}

Walker takes an Action, which will run on fields selected by EJSON for encryption, and provides a Walk method, which iterates on all the fields in a JSON text, running the Action on all selected fields. Fields are selected if they are a Value (not a Key) of type string, and their referencing Key did *not* begin with an Underscore. Note that this underscore-to-disable-encryption syntax does not propagate down the hierarchy to children. That is:

• In {"_a": "b"}, Action will not be run at all.
• In {"a": "b"}, Action will be run with "b", and the return value will replace "b".
• In {"k": {"a": ["b"]}, Action will run on "b".
• In {"_k": {"a": ["b"]}, Action run on "b".
• In {"k": {"_a": ["b"]}, Action will not run.

func (*Walker) Walk

func (ew *Walker) Walk(data []byte) ([]byte, error)

Walk walks an entire JSON structure, running the ejsonWalker.Action on each actionable node. A node is actionable if it's a string *value*, and its referencing key doesn't begin with an underscore. For each actionable node, the contents are replaced with the result of Action. Everything else is unchanged.