Skip to content

Commit

Permalink
Reflect the latest changes for adding GSM support in the documents (#25)
Browse files Browse the repository at this point in the history 
* Reflect the latest changes for adding GSM support in the documents

* Fix test
  • Loading branch information
@soheily98
soheily98 authored Oct 1, 2021
1 parent 64247bc commit 22135cd
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 41 deletions.
81 changes: 49 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,64 +2,80 @@

<img align="right" src="kea.jpg">

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

Kiya is a tool to access secrets stored in Google Secret Manager(GSM) or 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).
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.
**Kiya** is a simple tool that eases the access to the secrets stored in GSM or KMS. 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/[email protected].
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.

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/[email protected]. 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.

Kiya uses your authenticated Google account to access the Secret Manager / 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

## Install

go install github.com/kramphub/kiya/cmd/kiya@latest

## Usage

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

### 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"
}
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. Each profile should either mention `kms` or `gsm` to be used as the `backend`.
If no value is defined for a profile's `backend`, `kms` will be used as a default.

```json
{
"teamF1-on-kms": {
"backend": "kms",
"projectID": "your-gcp-project",
"location": "global",
"keyring": "your-kiya-secrets-keyring",
"cryptoKey": "your-kiya-secrets-cryptokey",
"bucket": "your-kiya-secrets"
},
"teamF2-on-gsm": {
"backend": "gsm",
"projectID": "another-gcp-project"
}
}

```

You should define `location`, `keyring`, `cryptoKey` and `bucket` for KMS based profiles.

For Google Secret Manager based profiles a `projectID` is only enough.

### 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:
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_
Expand All @@ -72,15 +88,16 @@ Generate a secret with length 25 store it as secret `concourse/cd-pipeline` and

kiya teamF1 get concourse/cd-pipeline

_Note: this will put a secret in your command history; better use copy, see below._
_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.

The list command is also used when the command is unknown, e.g. `kiya teamF1 list redbull` shows the same results as `kiya teamF1 redbull`.
The list command is also used when the command is unknown, e.g. `kiya teamF1 list redbull` shows the same results
as `kiya teamF1 redbull`.

### Fill a template, _template_

Expand All @@ -91,7 +108,7 @@ 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")}}
Expand Down
25 changes: 16 additions & 9 deletions setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,38 @@
In order to use kiya, you need a Google Cloud Platform project. See https://console.cloud.google.com.
You will need the project id for a new kiya profile.

## Google KMS
## For Secret Manager based profiles

There's nothing special to take care of. Everything's managed by GSM.
Just make sure that you have enough permissions by looking at [Access control (IAM) | Secret Manager Documentation | Google Cloud](https://cloud.google.com/secret-manager/docs/access-control) for the required roles.

## For Key Management Service based profiles

### Google KMS
kiya uses Google KMS (Key Management Service) to encrypt and decrypt secrets.

### create a keyring
#### create a keyring
In the console, goto IAM & Admin, Encryption keys and create a keyring, e.g. `kiya-keyring`.

### create a crypto key
#### create a crypto key
Create a crypto key for your keyring, e.g. `kiya-cryptokey`.

### set permissions
#### set permissions
Select your crypto key and edit permissions.
Add a member with your google account and role `Cloud KMS CryptoKey Encrypter/Decrypter`.

## Google Storage
### Google Storage
kiya using Google Storage (Buckets) to store encrypted secrets using a label.

### create a bucket
#### create a bucket
In the console, goto Storage Browser and create a bucket, e.g. `your-name-kiya-secrets`.
Must be unique across Cloud Storage.

### set permissions
#### set permissions
Select your bucket and edit permissions.
Add a member with your google account and role `Storage Object Admin` for creating and listing secrets.

## kiya profile
### kiya profile
In your .kiya file, add a new personal profile.

"private": {
Expand All @@ -40,7 +47,7 @@ In your .kiya file, add a new personal profile.
"secretChars": "optionally-specify-secret-generation-chars"
}

### Test
## Test
Authenticate your account with Google.

gcloud auth application-default login
Expand Down

0 comments on commit 22135cd

Please sign in to comment.