unicreds

README

unicreds

Unicreds is currently a pretty faithful port of credstash to golang.

overview

This command line utility automates the storage of encrypted secrets in DynamoDB using KMS to encrypt and sign these Credentials. Access to these keys is controlled using IAM.

setup

1. Add and configure a KMS key in IAM with the alias credstash, ensure this is created in the correct region as the user interface for this is quite confusing.
2. Run unicreds setup to create the dynamodb table in your region, ensure you have your credentials configured using the awscli.

usage

usage: unicreds [<flags>] <command> [<args> ...]

A credential/secret storage command line tool.

Flags:
  --help                     Show context-sensitive help (also try --help-long and --help-man).
  --debug                    Enable debug mode.
  --csv                      Enable csv output for table data.
  --alias="alias/credstash"  KMS key alias.
  --version                  Show application version.

Commands:
  help [<command>...]
    Show help.

  setup
    Setup the dynamodb table used to store credentials.

  get <credential>
    Get a credential from the store.

  getall
    Get all credentials from the store.

  list
    List all credentials names and version.

  put <credential> <value> [<version>]
    Put a credential in the store.

  delete <credential>
    Delete a credential from the store.

install

If your on OSX you can install unicreds using homebrew now!

brew tap versent/homebrew-taps
brew install unicreds

Otherwise grab an archive from the github releases page.

why

The number one reason for this port is platform support, getting credstash running on Windows and some older versions of Redhat Enterprise is a pain. Golang enables deployment of tools across a range of platforms with very little friction.

In addition to this we have some ideas about how this tool can be expanded to support some interesting use cases we have internally.

That said we have learnt a lot from how credstash worked and aim to remain compatible with it in the future where possible.

development

I use goconvey to watch my code and run tests on save.

go get github.com/smartystreets/goconvey

todo

• Add the ability to filter list / getall results using DynamoDB filters, at the moment I just use | grep blah.
• Work on the output layout.
• Make it easier to import files

license

This code is Copyright (c) 2015 Versent and released under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.

Documentation

Index

• Constants
• Variables
• func ComputeHmac256(message, secret []byte) string
• func Decode(data map[string]*dynamodb.AttributeValue, rawVal interface{}) error
• func Decrypt(key, ciphertext []byte) ([]byte, error)
• func DeleteSecret(name string) error
• func Encode(rawVal interface{}) (map[string]*dynamodb.AttributeValue, error)
• func Encrypt(key, plaintext []byte) ([]byte, error)
• func GetHighestVersion(name string) (string, error)
• func PutSecret(alias, name, secret, version string) error
• func ResolveVersion(name string, version int) (string, error)
• func SetDynamoDBConfig(config *aws.Config)
• func SetKMSConfig(config *aws.Config)
• func SetRegion(region *string) error
• func Setup() (err error)
• type ByName
  • func (slice ByName) Len() int
  • func (slice ByName) Less(i, j int) bool
  • func (slice ByName) Swap(i, j int)
• type ByVersion
  • func (a ByVersion) Len() int
  • func (a ByVersion) Less(i, j int) bool
  • func (a ByVersion) Swap(i, j int)
• type Credential
  • func ListSecrets(allVersions bool) ([]*Credential, error)
  • func (c *Credential) CreatedAtDate() string
• type DataKey
  • func DecryptDataKey(ciphertext []byte) (*DataKey, error)
  • func GenerateDataKey(alias string, size int) (*DataKey, error)
• type DecryptedCredential
  • func GetAllSecrets(allVersions bool) ([]*DecryptedCredential, error)
  • func GetSecret(name string) (*DecryptedCredential, error)
• type TableWriter
  • func NewTable(wr io.Writer) *TableWriter
  • func (tw *TableWriter) BulkWrite(rows [][]string)
  • func (tw *TableWriter) Render() error
  • func (tw *TableWriter) SetFormat(tableFormat int)
  • func (tw *TableWriter) SetHeaders(headers []string)
  • func (tw *TableWriter) Write(row []string)

Constants

const (
	// TableFormatTerm format the table for a terminal session
	TableFormatTerm = iota // 0
	// TableFormatCSV format the table as CSV
	TableFormatCSV // 1
)

const (
	// Table the name of the dynamodb table
	Table = "credential-store"

	// DefaultKmsKey default KMS key alias name
	DefaultKmsKey = "alias/credstash"

	// CreatedAtNotAvailable returned to indicate the created at field is missing
	// from the secret
	CreatedAtNotAvailable = "Not Available"
)

Variables

var (

	// ErrSecretNotFound returned when unable to find the specified secret in dynamodb
	ErrSecretNotFound = errors.New("Secret Not Found")

	// ErrHmacValidationFailed returned when the hmac signature validation fails
	ErrHmacValidationFailed = errors.New("Secret HMAC validation failed")

	// ErrTimeout timeout occured waiting for dynamodb table to create
	ErrTimeout = errors.New("Timed out waiting for dynamodb table to become active")
)

Functions

func ComputeHmac256

func ComputeHmac256(message, secret []byte) string

ComputeHmac256 compute a hmac256 signature of the supplied message and return the value hex encoded

func Decode

func Decode(data map[string]*dynamodb.AttributeValue, rawVal interface{}) error

Decode decode the supplied struct from the dynamodb result map

NOTE: this function needs a lot more validation and refinement.

func Decrypt

func Decrypt(key, ciphertext []byte) ([]byte, error)

Decrypt AES encryption method which matches the pycrypto package using CTR and AES256. Note this routine seeds the counter/iv with a value of 1 then throws it away?!

func DeleteSecret

func DeleteSecret(name string) error

DeleteSecret delete a secret

func Encode

func Encode(rawVal interface{}) (map[string]*dynamodb.AttributeValue, error)

Encode return the value encoded as a map of dynamo attributes.

NOTE: this function needs a lot more validation and refinement.

func Encrypt

func Encrypt(key, plaintext []byte) ([]byte, error)

Encrypt AES encryption method which matches the pycrypto package using CTR and AES256. Note this routine seeds the counter/iv with a value of 1 then throws it away?!

func GetHighestVersion

func GetHighestVersion(name string) (string, error)

GetHighestVersion look up the highest version for a given name

func PutSecret

func PutSecret(alias, name, secret, version string) error

PutSecret retrieve the secret from dynamodb

func ResolveVersion

func ResolveVersion(name string, version int) (string, error)

ResolveVersion calculate the version given a name and version

func SetDynamoDBConfig

func SetDynamoDBConfig(config *aws.Config)

SetDynamoDBConfig override the default aws configuration

func SetKMSConfig

func SetKMSConfig(config *aws.Config)

SetKMSConfig override the default aws configuration

func SetRegion

func SetRegion(region *string) error

SetRegion configure the AWS region with a fallback for discovery on EC2 hosts.

func Setup

func Setup() (err error)

Setup create the table which stores credentials

Types

type ByName

type ByName []*Credential

ByName sort by name

func (ByName) Len

func (slice ByName) Len() int

func (ByName) Less

func (slice ByName) Less(i, j int) bool

func (ByName) Swap

func (slice ByName) Swap(i, j int)

type ByVersion

type ByVersion []*Credential

ByVersion sort helper for credentials

func (ByVersion) Len

func (a ByVersion) Len() int

func (ByVersion) Less

func (a ByVersion) Less(i, j int) bool

func (ByVersion) Swap

func (a ByVersion) Swap(i, j int)

type Credential

type Credential struct {
	Name      string `ds:"name"`
	Version   string `ds:"version"`
	Key       string `ds:"key"`
	Contents  string `ds:"contents"`
	Hmac      string `ds:"hmac"`
	CreatedAt int64  `ds:"created_at"`
}

Credential managed credential information

func ListSecrets

func ListSecrets(allVersions bool) ([]*Credential, error)

ListSecrets returns a list of all secrets

func (*Credential) CreatedAtDate

func (c *Credential) CreatedAtDate() string

CreatedAtDate convert the timestamp field to a date string

type DataKey

type DataKey struct {
	CiphertextBlob []byte
	Plaintext      []byte
}

DataKey which contains the details of the KMS key

func DecryptDataKey

func DecryptDataKey(ciphertext []byte) (*DataKey, error)

DecryptDataKey ask kms to decrypt the supplied data key

func GenerateDataKey

func GenerateDataKey(alias string, size int) (*DataKey, error)

GenerateDataKey simplified method for generating a datakey with kms

type DecryptedCredential

type DecryptedCredential struct {
	*Credential
	Secret string
}

DecryptedCredential managed credential information

func GetAllSecrets

func GetAllSecrets(allVersions bool) ([]*DecryptedCredential, error)

GetAllSecrets returns a list of all secrets

func GetSecret

func GetSecret(name string) (*DecryptedCredential, error)

GetSecret retrieve the secret from dynamodb using the name

type TableWriter

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

TableWriter enables writing of tables in a variety of formats

func NewTable

func NewTable(wr io.Writer) *TableWriter

NewTable create a new table writer

func (*TableWriter) BulkWrite

func (tw *TableWriter) BulkWrite(rows [][]string)

BulkWrite append an array of rows to the buffer

func (*TableWriter) Render

func (tw *TableWriter) Render() error

Render render the table out to the supplied writer

func (*TableWriter) SetFormat

func (tw *TableWriter) SetFormat(tableFormat int)

SetFormat set the format

func (*TableWriter) SetHeaders

func (tw *TableWriter) SetHeaders(headers []string)

SetHeaders set the column headers

func (*TableWriter) Write

func (tw *TableWriter) Write(row []string)