SecureStore Go library

This repository/package houses a Go implementation of the cross-platform, language-agnostic SecureStore secrets specification. In particular, this library may be used for interacting with SecureStore secrets containers, providing an easy-to-use and idiomatic interface for loading SecureStore containers and decrypting/retrieving secrets from within your existing go backend/frontend/application code. Implementations are available for other languages and frameworks.

Usage

This Go library is largely intended to be used alongside one of the SecureStore cli companion apps, used to create SecureStore values and manage (add/remove/update) the secrets stored therein. In this example, we'll be using the ssclient cli utility to create a new store.

Creating a secrets vault

Typical SecureStore usage begins by creating a new SecureStore "vault" (an encrypted secrets container) that will store the credentials (usually both usernames and passwords) that your app will need. Begin by compiling or downloading and installing a copy of ssclient, the SecureStore companion cli.

While you can compile it yourself or manually download pre-built binaries for your platform, you might find it easiest to just install it with npm:

~> npm install --global @neosmart/ssclient

after which you can proceed with the following steps:

~> mkdir secure/
~> cd secure/
~> ssclient create --export-key secrets.key
Password: ************
Confirm Password: ************

# Now you can use `ssclient -p` with your password or
# `ssclient -k secrets.key` to encrypt/decrypt with
# the same keys.

Adding secrets

Secrets may be added with your password or the equivalent encryption key file, and may be specified in-line as arguments to ssclient or more securely at a prompt by omitting the value when calling ssclient create:

# ssclient defaults to password-based decryption:
~> ssclient set aws:s3:accessId AKIAV4EXAMPLE7QWERT
Password: *********

similarly:

# Use `-k secrets.key` to load the encryption key and
# skip the prompt for the vault password:
~> ssclient -k secrets.key set aws:s3:accessKey
Value: v1Lp9X7mN2B5vR8zQ4tW1eY6uI0oP3aS5dF7gH9j

Retrieving secrets

Secrets can be retrieved at the commandline with ssclient or programmatically with a SecureStore library for your development language or framework of choice.

This library contains the golang implementation of the SecureStore protocol. The implementation is currently fully contained within the single securestore.go source file with minimal dependencies (only a single unavoidable dependency on the x/crypto module), and published to its own git repo for friendly consumption with go get:

go get github.com/neosmart/securestore-go

// 1. Load decryption keys (or derive them from a password)
key, err := securestore.KeyFromFile("secure/secrets.key")
// OR: key := securestore.KeyFromPassword("sUperDuPERsecret")
if err != nil {
    log.Fatalf("Failed to load encryption key: %v", err)
}

// 2. Load the vault using the key
sman, err := securestore.LoadFile("secure/secrets.json", key)
if err != nil {
    log.Fatalf("Failed to load SecureStore vault: %v", err)
}

// Retrieve and decrypt a specific secret
val, err := sman.Get("aws:s3:accessKey")
if err != nil {
    log.Fatalf("Error retrieving s3 access key: %v", err)
}
fmt.Printf("Decrypted secret: %s\n", val)

// List all available keys in the vault
allKeys := sman.Keys()
fmt.Printf("Vault contains %d keys: %v\n", len(allKeys), allKeys)

While it is strongly recommended to only load secrets programmatically with the encryption key with KeyFromBytes() or KeyFromFile() methods so as to avoid hard-coding any secrets in your code by specifying the path to the encryption key created by ssclient via the --export-key flag or top-level ssclient export-key command, an alternative securestore.KeyFromPassword() interface is also available; this can be used if you're developing an interactive tool using SecureStore (or otherwise securely retrieve the decryption password), for example.

API overview

The SecureStore library provides a high-level interface for decrypting and accessing secrets stored in SecureStore v3 vaults.

SecretsManager

The SecretsManager is the primary interface for interacting with a SecureStore vault.

Initialization

These functions load a vault, initialize the manager, and verify both the vault's integrity and the correctness of the provided decryption key.

Function	Description
LoadFile(path, key)	Loads a SecureStore vault file from disk using a provided Key.
Load(reader, key)	Loads a vault from any io.Reader (useful for embedded vaults or network payloads).

Methods

Once initialized, use these methods to interact with the loaded secrets:

Method	Description
Get(name string) (string, error)	Retrieves a secret by its key/name. Returns ErrSecretNotFound if the key is missing.
Keys() []string	Returns a slice with names (keys) of all secrets in the vault.

---

Key

Key is used to specify how decryption will be performed to unlock a vault and decrypt its secrets, and are forwarded to Load() or LoadFile() methods.

Method	Description
KeyFromPassword(password)	Derives decryption keys from a password per the SecureStore v3 spec.
KeyFromFile(path)	Loads a SecureStore decryption key from the provided path.
KeyFromBytes(key)	Creates a key from a byte slice of the key contents.