kuzzleio/kuzzle-vault

Securely share secrets for your application with JSON and cryptography

About

Kuzzle Vault is a system to securely share your API keys and other secrets within your team.

Secrets are saved in an encrypted JSON or YAML file that you can version alongside your code.

You only need to share one encryption key with your team members.

Then you can load and decrypt the contents of the file into your application memory for secure usage.

See the related article on Kuzzle Blog

Implementations are available for the following languages:

• Node.js
• PHP

---

Usage

Encrypt your secrets in a JSON file

With Kourou (NPM package)

First, you need to encrypt your secrets. The easiest way to do that is to use Kourou, the Kuzzle CLI.

$ npm install -g kourou

$ kourou vault:encrypt config/prod/secrets.json --vault-key <password>

 🚀 Kourou - Encrypts an entire file.
 
 [✔] Secrets were successfully encrypted into the file config/prod/secrets.enc.json

Then, you can securely store your secrets inside your repository and share them with you team.

With Bash

Alternatively, you can also use the bash script provided in this repository to encrypt a string in Kuzzle Vault format.

It will give you an encrypted string that you have to put in your JSON file containing encrypted secrets.

Example:

$ bash bin/kuzzle-vault-encrypt-string kuzzle-vault-encrypt-string something_secret vaultKey
cad308c9e857accc2d82dffb70e59dbe1460545372d6c0620dd46136ad16ae44.52a6a6e897696ec45f5715df12818939

Then put the encrypted string in a JSON file:

{
  "secret-key": "cad308c9e857accc2d82dffb70e59dbe1460545372d6c0620dd46136ad16ae44.52a6a6e897696ec45f5715df12818939"
}

The complete script documentation is available with bash bin/kuzzle-vault-encrypt-string --help.

Use encrypted secrets within your application

To load the secrets inside an application, instantiate the Vault with the same password as for the encryption.

Then, use the decrypt method with the path of the encrypted secrets file to load the secrets into the memory.

const vault = new Vault('password');
vault.decrypt('config/prod/secrets.enc.json');
// or
vault.decrypt('config/prod/secrets.enc.yaml');

// secrets are now available
vault.secrets

You can also provide the password with the environment variable KUZZLE_VAULT_KEY.

// process.env.KUZZLE_VAULT_KEY === 'password'

const vault = new Vault();
vault.decrypt('config/prod/secrets.enc.json');

// secrets are now available
vault.secrets

Data encryption

The cipher used is aes-256-cbc with a 16 bytes initialization vector.

The encryption key is hashed with SHA256 and then used with a random initialization vector to encrypt the data.

Encrypted values are represented under the following format <encrypted-data>.<initialization-vector>.

Both <encrypted-data> and <initialization-vector> are in hexadecimal.

Secrets file format

The secrets file is in JSON or YAML format. String values are encrypted but the key names remain the same.

/* secrets.json */
{
  "aws": {
    "secretKeyId": "lfiduras"
  },
  "cloudinaryKey": "ho-chi-minh"
}

aws:
  - secretKeyId: "lfiduras"
  - groups:
    primary
    secondary    

Once encrypted, the file looks like the following:

/* secrets.enc.json */
{
  "aws": {
    "secretKeyId": "81f52891e336c76c82033c38f44d28.81f3214be3836bbb9fa165dfa691071a"
  },
  "cloudinaryKey": "f700cac98100f1266536553f3181ada6.65dfa691071a81f3214be3836bbb9fa1"
}

aws:
  - secretKeyId: "81f52891e336c76c82033c38f44d28.81f3214be3836bbb9fa165dfa691071a"
  - groups:
    "f700cac98100f1266536553f3181ada6.65dfa691071a81f3214be3836bbb9fa1"
    "1266536553ff700cac98100f3181ada6.a81f3214be3865dfa69107136bbb9fa1"    

Vault class

Vault.constructor Vault.decrypt

---

Vault.constructor

The constructor of the Vault class.

Vault(vaultKey: string | undefined);

Arguments

Name	Type	Description
vaultKey	String	The key used to encrypt and decrypt secrets

Usage

const vault = new Vault('my vault key');

---

Vault.decrypt

Decrypts the content of the file designated by encryptedVaultPath and store the decrypted content inside the property secrets of the Vault class.

decrypt(encryptedVaultPath: string);

Usage

const vault = new Vault('my vault key');
vault.decrypt('path/to/secrets.enc.json');

vault.secrets // Contains decrypted secrets

Cryptonomicon class

This class contains the cryptography primitives used to encrypt and decrypt the secrets.

There are 4 methods available:

• decryptObject
• encryptObject
• encryptString
• decryptString

You can use this class to build your own tools to decrypt or encrypt secrets inside your application.

kuzzle-vault's Issues

Objects containing numbers or boolean properties are not encrypted

Expected Behavior

All the properties of all types of objects to be encrypted should be encrypted.

Current Behavior

If a property of the object to be encrypted is not a string, the property doest not get encrypted and it's not added to the encrypted object.

Possible Solution

In the function encryptObject, the function should check if the property is something else than a string.
if it is, cast the property to string and add the type at the end of the string. This way, the property will be encrypted as a string and when decrypting, the type can be restored.

For example:

// Before encryption
{
  "name": "John Cena",
  "age": 30,
  "active": true
}

// What gets encrypted
{
  "name": "John Cena",
  "age": "30+number",
  "active": "true+boolean"
}

So the encryptObject would look like this:

encryptObject (secrets: any): any {
  const encryptedSecrets: any = {};

  for (const key of Object.keys(secrets)) {
    const value: string|any = secrets[key];

    if (value && typeof value === 'object' && !Array.isArray(value)) {
      encryptedSecrets[key] = this.encryptObject(value);
    }
    else if (typeof value === 'string') {
      encryptedSecrets[key] = this.encryptString(value);
    } 
    else if (['boolean','number'].includes(typeof value)) {
      const toBeEncrypted = `${value.toString()}+${typeof value}`;
      encryptedSecrets[key] = this.encryptString(toBeEncrypted);
    }
  }

  return encryptedSecrets;
}

ant the decyptString would look like this:

decryptString (encrypted: string): string {
  const [ encryptedData, ivHex ] = encrypted.split('.');

  if (encryptedData.length === 0) {
    throw new Error(`Invalid encrypted string format "${encryptedData}.${ivHex}"`);
  }

  if (ivHex.length !== 32) {
    throw new Error(`Invalid IV size. (${ivHex.length}, expected 32)`);
  }

  const iv = Buffer.from(ivHex, 'hex');
  const decipher = crypto.createDecipheriv('aes-256-cbc', this.vaultKeyHash, iv);

  try {
    const deciphered: string = decipher.update(encryptedData, 'hex', 'utf8') + decipher.final('utf8');

    const splited = deciphered.split('+');

    if(splited.length > 1){

      const originalType = splited.pop();

      if(originalType === 'number'){
        return Number(splited.join('+'))
      };

      if(originalType === 'boolean'){
        return Boolean(splited.join('+'))
      };
      
    }

    return deciphered;

  }
  catch (error) {
    if (error.message.includes('bad decrypt')) {
      throw new Error('Cannot decrypt encrypted value with the provided key');
    }

    throw new Error(`Encrypted input value format is not a valid: ${error.message}`);
  }
}

Steps to Reproduce

1. Create a secret.json file containg the following content:

{
  "name": "John Cena",
  "age": 30,
  "active": true
}

2. run kourou vault:encrypt secrets.json --vault-key password

Context (Environment)

Kuzzle version: 2.18.1
Node.js version: 16.14.2
SDK version: -
Kourous version: 0.22.0