From 22135cdd0daa762ff4c63d79cc50ead3f9c9e3e1 Mon Sep 17 00:00:00 2001 From: Soheil Date: Fri, 1 Oct 2021 17:23:56 +0200 Subject: [PATCH] Reflect the latest changes for adding GSM support in the documents (#25) * Reflect the latest changes for adding GSM support in the documents * Fix test --- README.md | 81 +++++++++++++++++++++++++++++++++---------------------- setup.md | 25 ++++++++++------- 2 files changed, 65 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 00fc5f5..c5b7c5b 100644 --- a/README.md +++ b/README.md @@ -2,30 +2,31 @@ -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/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. + +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. + +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 @@ -33,33 +34,48 @@ The bucket stores the encrypted secret value using the label as the storage key. ## 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_ @@ -72,7 +88,7 @@ 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_ @@ -80,7 +96,8 @@ _Note: this will put a secret in your command history; better use copy, see belo 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_ @@ -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")}} diff --git a/setup.md b/setup.md index 028a272..3ca9691 100644 --- a/setup.md +++ b/setup.md @@ -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": { @@ -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