api

Documentation

Overview

This repository provides the gosecret package for encrypting and decrypting all or part of a []byte using AES-256-GCM. gosecret was written to work with tools such as https://github.com/ryanbreen/git2consul, https://github.com/ryanbreen/fsconsul, and https://github.com/hashicorp/envconsul, providing a mechanism for storing and moving secure secrets around the network and decrypting them on target systems via a previously installed key.

gosecret is built on the assumption that only part of any given file should be encrypted: in most configuration files, there are few fields that need to be encrypted and the rest can safely be left as plaintext. gosecret can be used in a mode where the entire file is a single encrypted tag, but you should examine whether there's a good reason to do so.

To signify that you wish a portion of a file to be encrypted, you need to denote that portion of the file with a tag. Imagine that your file contains this bit of JSON:

{ 'dbpassword': 'kadjf454nkklz' }

To have gosecret encrypt just the password, you might create a tag like this:

{ 'dbpassword': '[gosecret|my mongo db password|kadjf454nkklz]' }

The components of the tag are, in order:

1. The gosecret header
2. An auth data string.
3. The plaintext we wish to encrypt.

Note that auth data can be any string (as long as it doesn't contain the pipe character, '|'). This tag is hashed and included as part of the ciphertext. It's helpful if this tag has some semantic meaning describing the encrypted data. Auth data string is not private data. It is hashed and used as part of the ciphertext such that decryption will fail if any of auth data, initialization vector, and key are incorrect for a specific piece of ciphertext. This increases the security of the encryption algorithm by obviating attacks that seek to learn about the key and initialization vector through repeated decryption attempts.

With this tag in place, you can encrypt the file via 'gosecret-cli'. The result will yield something that looks like this, assuming you encrypted it with a keyfile named 'myteamkey-2014-09-19':

{ 'dbpassword': '[gosecret|my mongo db password|TtRotEctptR1LfA5tSn3kAtzjyWjAp+dMOHe6lc=|FJA7qz+dUdubwv9G|myteamkey-2014-09-19]' }

The components of the tag are, in order:

1. The gosecret header
2. The auth data string
3. The ciphertext, in Base64
4. The initialization vector, in Base64
5. The key name

A key may be used any number of times, but a new initialization vector should be created each time the key is used. This is handled for you automatically by gosecret.

When this is decrypted by a system that contains key 'myteamkey-2014-09-19', the key and initialization vector are used to both authenticate the auth data string and (if authentic) decrypt the ciphertext back to plaintext. This will result in the encrypted tag being replaced by the plaintext, returning us to our original form:

{ 'dbpassword': 'kadjf454nkklz' }

A file can contain any number of goscecret tags, or the entire file can be a gosecret tag. It's up to you as the application developer or system maintainer to decide what balance of security vs readability you desire.

Index

• func CreateKey() []byte
• func DecryptTags(content []byte, keyroot string) ([]byte, error)
• func EncryptTags(content []byte, keyname, keyroot string, rotate bool) ([]byte, error)

Functions

func CreateKey

func CreateKey() []byte

Create a random 256-bit array suitable for use as an AES-256 cipher key.

func DecryptTags

func DecryptTags(content []byte, keyroot string) ([]byte, error)

DecryptTags looks for any tagged data of the form [gosecret|authtext|ciphertext|initvector|keyname] in the input content byte array and replaces each with a decrypted version of the ciphertext. Note that the input content must be valid UTF-8. The second parameter is the path to the directory in which keyfiles live. For each |keyname| in a gosecret block, there must be a corresponding file of the same name in the keystore directory. DecryptTags returns a []byte with all [gosecret] blocks replaced by plaintext.

func EncryptTags

func EncryptTags(content []byte, keyname, keyroot string, rotate bool) ([]byte, error)

EncryptTags looks for any tagged data of the form [gosecret|authtext|plaintext] in the input content byte array and replaces each with an encrypted gosecret tag. Note that the input content must be valid UTF-8. The second parameter is the name of the keyfile to use for encrypting all tags in the content, and the third parameter is the 256-bit key itself. EncryptTags returns a []byte with all unencrypted [gosecret] blocks replaced by encrypted gosecret tags.