secretcrypt

README

go-secretcrypt

Utility for keeping your secrets encrypted. Also has a Python version.

For example, you have the following TOML (or any format whose decoder supports TextUnmarshaler interface for custom values) configuration file

MySecret = "VerySecretValue!"

but you can't include that file in VCS because then your secret value would be exposed.

With secretcrypt, you can encrypt your secret using your AWS KMS master key aliased MyKey:

$ encrypt-secret kms alias/MyKey
Enter plaintext: VerySecretValue! # enter
kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE... # shortened for brevity

# --- or --
$ echo "VerySecretValue!" | encrypt-secret kms alias/MyKey
kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE... # shortened for brevity
# only use piping when scripting, otherwise your secrets will be stored
# in your shell's history!

use that secret in my TOML config file:

MySecret = "kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE..."  # shortened for brevity

or YAML:

mysecret: kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE...  # shortened for brevity

or JSON:

{"MySecret": "kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE..."}

Then, you can use that secret in your config struct

type Config struct {
  MySecret secretcrypt.Secret
}

var conf Config
if _, err := toml.Decode(tomlData, &conf); err != nil {
  // handle error
}

and get its plaintext as

plaintext, err := conf.MySecret.Decrypt()
if err != nil {
  // handle error
}

KMS

The KMS option uses AWS Key Management Service. When encrypting and decrypting KMS secrets, you need to provide the AWS region used for encrypting, the default being us-east-1.

So if you use a custom region, you must provide it to secretcrypt:

encrypt-secret kms --region us-west-1 alias/MyKey

Local encryption

This mode is meant for local and/or offline development usage. It generates a local key in your %USER_DATA_DIR% (see appdirs), so that the key cannot be accidentally committed to CVS.

It then uses that key to symmetrically encrypt and decrypt your secrets.

Password encryption - interactive only

The password encryption mode should not be used in your application - it is meant for easily sharing secrets among developers. It interactively prompts the user for a password when encrypting the secret. When decrypting, it prompts for the password again.

Install command-line utilities

You can install command-line utilities encrypt-secret and decrypt-secret via:

go install -i github.com/Zemanta/go-secretcrypt/cmd/...

Documentation

Overview

Package secretcrypt is an utility for keeping your secrets encrypted.

For example, you have the following TOML (or any format whose decoder supports TextUnmarshaler interface for custom values) configuration file

MySecret = "VerySecretValue!"

but you can't include that file in VCS because then your secret value would be exposed.

With secretcrypt, you can encrypt your secret using your AWS KMS master key aliased MyKey:

$ encrypt-secret kms alias/MyKey
Enter plaintext: VerySecretValue! # enter
kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE... # shortened for brevity

# --- or --
$ echo "VerySecretValue!" | encrypt-secret kms alias/MyKey
kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE... # shortened for brevity
# only use piping when scripting, otherwise your secrets will be stored
# in your shell's history!

use that secret in my TOML config file:

MySecret = "kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE..."  # shortened for brevity

or YAML:

mysecret: kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE...  # shortened for brevity

or JSON:

{"MySecret": "kms:region=us-east-1:CiC/SXeuXDGRADRIjc0qcE..."}

Then, you can use that secret in your config struct

type Config struct {
  MySecret secretcrypt.Secret
}

var conf Config
if _, err := toml.Decode(tomlData, &conf); err != nil {
  // handle error
}

and get its plaintext as

plaintext, err := conf.MySecret.Decrypt()
if err != nil {
  // handle error
}

KMS

The KMS option uses AWS Key Management Service. When encrypting and decrypting KMS secrets, you need to provide which AWS region the is to be or was encrypted on, but it defaults to us-east-1.

So if you use a custom region, you must provide it to secretcrypt:

encrypt-secret kms --region us-west-1 alias/MyKey

Local encryption

This mode is meant for local and/or offline development usage. It generates a local key in your user data dir (see appdirs at https://pypi.python.org/pypi/appdirs/1.4.0), so that the key cannot be accidentally committed to CVS.

It then uses that key to symmetrically encrypt and decrypt your secrets.

Index

• type Secret
  • func LoadSecret(textSecret string) (Secret, error)
  • func (s Secret) Get() string
  • func (s Secret) GoString() string
  • func (s Secret) MarshalText() (text []byte, err error)
  • func (s Secret) String() string
  • func (s *Secret) UnmarshalText(text []byte) error
• type StrictSecret
  • func LoadStrictSecret(textStrictSecret string) (StrictSecret, error)
  • func (s *StrictSecret) AppendParameters(decryptParams internal.DecryptParams)
  • func (s *StrictSecret) Decrypt() (string, error)
  • func (s StrictSecret) GoString() string
  • func (s StrictSecret) MarshalText() (text []byte, err error)
  • func (s StrictSecret) String() string
  • func (s *StrictSecret) UnmarshalText(text []byte) error

Types

type Secret

type Secret struct {
	// contains filtered or unexported fields
}

Secret represents a secret that is eagerly decrypted on object creation. After that, using this secret does not incur any side effects.

func LoadSecret

func LoadSecret(textSecret string) (Secret, error)

LoadSecret loads a Secret from a string.

func (Secret) Get

func (s Secret) Get() string

Get returns the secret in plain text. Calling Get() does not incur any side effects.

func (Secret) GoString

func (s Secret) GoString() string

GoString ensures plaintext is not leaked when formatting the Secret object with %#v.

func (Secret) MarshalText

func (s Secret) MarshalText() (text []byte, err error)

MarshalText marshalls the secret into its textual representation.

func (Secret) String

func (s Secret) String() string

String ensures plaintext is not leaked when formatting the Secret object with %s.

func (*Secret) UnmarshalText

func (s *Secret) UnmarshalText(text []byte) error

UnmarshalText loads the secret from its textual representation.

type StrictSecret

type StrictSecret struct {
	// contains filtered or unexported fields
}

StrictSecret represents an encrypted secret that is decrypted on demand. Decrypting this secret may incur a side-effect such as a call to a remote service for decryption.

func LoadStrictSecret

func LoadStrictSecret(textStrictSecret string) (StrictSecret, error)

LoadStrictSecret loads a StrictSecret from a string.

func (*StrictSecret) AppendParameters

func (s *StrictSecret) AppendParameters(decryptParams internal.DecryptParams)

AppendParameters sets given decryption parameters.

func (*StrictSecret) Decrypt

func (s *StrictSecret) Decrypt() (string, error)

Decrypt decrypts the secret and returns the plaintext. Calling Decrypt() may incur side effects such as a call to a remote service for decryption.

func (StrictSecret) GoString

func (s StrictSecret) GoString() string

GoString ensures plaintext is not leaked when formatting the StrictSecret object with %#v.

func (StrictSecret) MarshalText

func (s StrictSecret) MarshalText() (text []byte, err error)

MarshalText marshalls the secret into its textual representation.

func (StrictSecret) String

func (s StrictSecret) String() string

String ensures plaintext is not leaked when formatting the StrictSecret object with %s.

func (*StrictSecret) UnmarshalText

func (s *StrictSecret) UnmarshalText(text []byte) error

UnmarshalText loads the secret from its textual representation.