kiya

README

Kiya

Kiya is a tool to access secrets stored in a Google Bucket and encrypted by Google Key Management Service (KMS).

Introduction

Developing and deploying applications to execution environments (dev,staging,production) requires all kinds of secrets. Both continuous development enviroment and production environment require credentials to access other resources. Examples are passwords, service accounts, TLS certificates, API tokens and Encryption Keys. These secrets should be managed with great care. This means secrets must be stored encrypted on reliable shared storage and its access must controlled by AAA (authentication, authorisation and auditing).

Kiya is a simple tool that mediates between stored encrypted secrets in a bucket and a managed encyrption key in a keyring. It requires an authenticated Google account and permissions for that account to read secrets and perform encryption and decryption.

Labeled secrets

A secret must have a label and a plain text representation of its value. A label is typically composed of a domain or site or application (the parent key) and a secret key, e.g. google.gmail/info@mars.planets. A label must have at least one parent key (lowercase with or without dots). The value must be a string which has a maximum length of 64Kb.

Prerequisites

Kiya uses your authenticated Google account to access the Storage Bucket, KMS and Audit Logging. The bucket stores the encrypted secret value using the label as the storage key.

gcloud auth application-default login

Usage

Read setup.md for detailed instructions how to create a bucket, a keyring, an cryption key and set the permissions.

Configuration

Create a file name .kiya in your home directory with the content for a shareable secrets profile. You can have multiple profiles for different usages.

{
	"teamF1": {
		"projectID": "your-gcp-project",
		"location": "global",
		"keyring": "your-kiya-secrets-keyring",
		"cryptoKey": "your-kiya-secrets-cryptokey",
		"bucket": "your-kiya-secrets"
	}
}

Store a password, put

kiya teamF1 put concourse/cd-pipeline mySecretPassword

In this example, teamF1 refers to the profile in your configuration. concourse refers to the site or domain. cd-pipeline is the username which can be an email address too. mySecretPassword is the plain text password.

If a password was already stored then you will be warned about overwriting it. The -quiet flag can be used to skip the confirmation prompt:

kiya -quiet teamF1 put concourse/cd-pipeline myNewSecretPassword

Note: this will put a secret in your command history; better use paste, see below.

Generate a password, generate

kiya teamF1 generate concourse/cd-pipeline 25

Generate a secret with length 25 store it as secret concourse/cd-pipeline and copy its value to the OS clipboard.

Retrieve a password, get

kiya teamF1 get concourse/cd-pipeline

Note: this will put a secret in your command history; better use copy, see below.

List labels of stored secrets, list

kiya teamF1 list [|filter]

Specifying a filter argument will hide any keys that don't contain the filter string.

Fill a template, template

kiya teamF1 template template-file

Output will be written to stdout.

Example contents of template-file:

bitbucket-password={{kiya "key-to-bitbucket-password"}}

Kiya also provides a builtin function for base64 encoding:

artifatory-hashed-password={{base64 (kiya "key-to-artifatory-password")}}

For accessing OS environment values:

gcp-project={{env "PROJECT"}}

Write a secret to clipboard, copy

kiya teamF1 copy concourse/cd-pipeline

Create secret from clipboard, paste

kiya teamF1 paste google/accounts/someone@gmail.com

Move a secret from one profile to another, move

kiya teamF1 move bitbucket.org/johndoe teamF2

Troubleshooting

1. Error

2017/06/24 22:14:24 google: could not find default credentials. See https://developers.google.com/accounts/docs/application-default-credentials for more information.

Run

gcloud auth application-default login

2. Error

googleapi: Error 403: Caller does not have storage.objects.list access to bucket <some-bucket-name>., forbidden

You do not have access to encrypted secrets from some-bucket-name.

© 2017 kramphub.com. Apache License v2.

Documentation

Index

• Variables
• func CheckSecretExists(storageService *cloudstore.Client, target Profile, key string) bool
• func DeleteSecret(kmsService *cloudkms.Service, storageService *cloudstore.Client, ...) error
• func GenerateSecret(length int, runes []rune) (string, error)
• func GetDecryptedValue(kmsService *cloudkms.Service, target Profile, cipherText string) (string, error)
• func GetEncryptedValue(kmsService *cloudkms.Service, target Profile, plainText string) (string, error)
• func GetValueByKey(kmsService *cloudkms.Service, storageService *cloudstore.Client, key string, ...) (string, error)
• func LoadConfiguration(configFile string)
• func LoadSecret(storageService *cloudstore.Client, target Profile, key string) (string, error)
• func Move(kmsService *cloudkms.Service, storageService *cloudstore.Client, ...) error
• func NewAuthenticatedClient(authLocation string) *http.Client
• func PutSecret(kmsService *cloudkms.Service, storageService *cloudstore.Client, ...) error
• func StoreSecret(storageService *cloudstore.Client, target Profile, key, encryptedValue string) error
• type Key
  • func List(storageService *cloudstore.Client, target Profile) ([]Key, error)
• type Profile

Variables

var Profiles map[string]Profile

Profiles is a collection of profiles as described in the .kiya configuration

Functions

func CheckSecretExists

func CheckSecretExists(storageService *cloudstore.Client, target Profile, key string) bool

func DeleteSecret

func DeleteSecret(kmsService *cloudkms.Service, storageService *cloudstore.Client, target Profile, key string) error

DeleteSecret removes a key from the bucket

func GenerateSecret

func GenerateSecret(length int, runes []rune) (string, error)

GenerateSecret composes a random secrets using runes from a give set.

func GetDecryptedValue

func GetDecryptedValue(kmsService *cloudkms.Service, target Profile, cipherText string) (string, error)

GetDecryptedValue decrypts an encrypted value via Google KMS

func GetEncryptedValue

func GetEncryptedValue(kmsService *cloudkms.Service, target Profile, plainText string) (string, error)

GetEncryptedValue converts a plain text to a Google KMS encrypted text

func GetValueByKey

func GetValueByKey(kmsService *cloudkms.Service, storageService *cloudstore.Client, key string, target Profile) (string, error)

GetValueByKey is very self explanatory :P

func LoadConfiguration

func LoadConfiguration(configFile string)

LoadConfiguration loads the .kiya file

func LoadSecret

func LoadSecret(storageService *cloudstore.Client, target Profile, key string) (string, error)

LoadSecret gets a secret from the bucket

func Move

func Move(kmsService *cloudkms.Service,
	storageService *cloudstore.Client,
	source Profile,
	sourceKey string,
	target Profile,
	targetKey string) error

func NewAuthenticatedClient

func NewAuthenticatedClient(authLocation string) *http.Client

NewAuthenticatedClient creates an authenticated google client

func PutSecret

func PutSecret(kmsService *cloudkms.Service,
	storageService *cloudstore.Client,
	target Profile,
	key,
	value string) error

PutSecret encrypts the given value and stores it

func StoreSecret

func StoreSecret(storageService *cloudstore.Client, target Profile, key, encryptedValue string) error

StoreSecret stores a new secret in a bucket

Types

type Key

type Key struct {
	Name      string
	CreatedAt time.Time
	Owner     string
}

func List

func List(storageService *cloudstore.Client, target Profile) ([]Key, error)

type Profile

type Profile struct {
	Label       string
	ProjectID   string
	Location    string
	Keyring     string
	CryptoKey   string
	Bucket      string
	SecretRunes []rune
}

Profile describes a single profile in a .kiya configuration