Branch: master
Find file Copy path
be39f93 Jan 13, 2019
2 contributors

Users who have contributed to this file

@omerlh @shaikatz
103 lines (91 sloc) 5.85 KB

Installing Kamus

Kamus has an official helm chart, using it is the simplest way to install Kamus:

helm repo add soluto
helm upgrade --install kamus soluto/kamus

Careful - using this command will deploy Kamus with the default encryption keys. Meaning, anyone could decrypt the data that Kamus encrypt. This is fine for testing and playing with Kamus, but not for production installations. For production usage, please configuration one of the supported Key Management Solutions (KMS).

Supported KMS Providers


AES KMS is the simplest (but less secure) solution. Kamus will use one strong AES key to encrypt all the data. Currently, rolling this key is not supported. To deploy Kamus using AES Key:

  • Generate a strong AES key:
key=$(openssl rand -base64 32 | tr -d '\n')
  • Pass the value when deploying kamus, either using values.yaml or directly in the helm command:
helm upgrade --install kamus soluto/kamus --set keyManager.AES.key=$key

Azure KeyVault KMS

Using Azure KeyVault as the key managment solution is the secure solution when running a cluster on Azure. Azure documentation is far from perfect, so I'm going to reffer to a lot of different guides because there is no one guide documenting the required process.

Start by creating a KeyVault instance. It is recommend to create a KeyVault with HSM backend for additional security. Follow this guide for details on how to create a KeyVault using the CLI. It is recommend to protect the KeyVault with firewall, see this guide for additional details.

After creating a KeyVault instance, Kamus need permissions to access it. You grant Kamus permissions by creating an Azure Active Directory application for Kamus, and granting permissions for this application to access the KeyVault created in the previous step. Creating the required app is covered in 2 parts of the same guide. The first part will guide you through the process of creating the app. The second part will guide you through the process of creating the client id and client secret, that are used by Kamus for authentication. Try to create the client secret for short period, for example 6 months, and rotate it frequently.

Now you should have 3 objects: KeyVault, client id and client secret. The last part is to grant the application the required permissions on the KeyVault. First we need to get the object id of the application:

objectId=$(az ad app show --id <> --output json | jq '.objectId' -r)

Now use the following command to grant access:

az keyvault set-policy --name <> --object-id $objectId --key-permissions get list create encrypt decrypt

Now it's time to deploy Kamus! Use the following settings in your values.yaml file:

  provider: AzureKeyVault
    clientId: <>
    clientSecret: <>
    keyVaultName: <>
    keyType: RSA-HSM //change to RSA if you choosed not to use premium SKU
    keySize: 2048
    maximumDataLength: 214

And now deploy Kamus using the following helm command:

helm upgrade --install kamus soluto/kamus -f <path/to/values.yaml>

Google Cloud KMS

Using Google Cloud KMS as the key managment solution is the secure solution when running a cluster on Google Cloud. For a more secure installation, it is recommended to use a keys that are HSM-protected (see Cloud HSM documentation). Before using Google Cloud KMS, make sure the api is enabled.

To interact with Google Cloud KMS, Kamus needs an existing key ring and a service account. To create a key ring, run the following command:

gcloud kms keyrings create <key ring name> --location <location>

If you plan to use HSM protection, choose a region that is supported - you can find the full list here.

To create a service account, run the following commands:

  • Start by creating a service account: gcloud iam service-accounts create kamus
  • Assing the service account the required permissions:
gcloud projects add-iam-policy-binding <project id> --member "serviceAccount:kamus@<project id>" --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"
gcloud projects add-iam-policy-binding <project id> --member "serviceAccount:kamus@<project id>" --role "roles/cloudkms.admin"

Please note: There is no exact role with all the required permissions for Kamus. It is recommended to create a custom role with the following permissions: cloudkms.cryptoKeys.get, cloudkms.cryptoKeys.create, cloudkms.cryptoKeyVersions.useToEncrypt, cloudkms.cryptoKeyVersions.useToDecrypt.

  • Generate keys for the service:
gcloud iam service-accounts keys create credentials.json --iam-account kamus@[PROJECT_ID]

Now add the following to your values.yaml file:

  provider: GoogleKms
    location: <location>
    keyRing: <key ring name>
    protectionLevelP: HSM

And use the following command to deploy kamus:

 helm upgrade --install kamus soluto/kamus -f values.yaml --set-string keyManagement.googleKms.credentials="$(cat credentials.json | base64)"