Vault Encryption

This guide explains how to use Hashicorp Vault ("Vault") for encrypting and decrypting properties within the Itential Automation Platform (IAP).

Token File

Currently, to use Vault, a vaultProps section is required within the properties.json. If this is not included, it will solely use $ENC encryption, which will be supported for the 2020.2 and 2020.3 release versions. After that, all encryption will be done through Vault, with encrypted strings beginning with $SECRET_ followed by the path inside the Vault Secrets Engine, then a $KEY_ followed by the key for the Vault Object represented by that path.

How to Install Vault

To install Vault:

1. Install yum-config-manager to manage your repositories.

   sudo yum install -y yum-utils

2. Use yum-config-manager to add the official HashiCorp Linux repo.

   sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

3. Install Vault.

   sudo yum -y install vault

4. Verify installation.

   vault –version

Vault Configuration

All vault configuration should go within the vaultProps key inside the properties.json. An example configuration is shown below.

Example: properties.json

   {
     "vaultProps": {
        "url": "http://example.vault.server",
        "token": "/file/path/token.txt",
        "endpoint": "kv/data"
     }
   }

How to Setup Vault

To setup Vault:

1. Navigate to /opt/vault.

2. Create a config.json file with the following:

   {
     "listener": [
       {
         "tcp": {
       "address": "0.0.0.0:8200",
           "tls_disable": 1
         }
       }
     ],
     "api_addr": "http://127.0.0.1:8200",
     "storage": {
       "file": {
         "path": "/opt/vault/data"
       }
     },
     "ui": false
   }

3. Run Vault with config.json. This will start the Vault server with the given configurations.

   vault server -config config.json

4. Unseal the Vault server.

   Reference: For more information, see Generate Root Tokens Using Unseal Keys

   • Run export VAULT_ADDR='http://127.0.0.1:8200'. By default, a new Terminal tab will not know which Vault address to use. This command sets an environment variable for Vault.

   • Run vault operator init. This should retrieve the unseal keys as well as initialize the server itself, which only needs to be done once. Keep track of all unseal keys, as they will be important in later steps. This may create a root token for you as well, which looks like s.McOsVdQvYTUZrq6FgWZUczOL. If it does, you should be able to skip step 4 below, which is generating a root token manually.

   • Run the vault operator $UNSEAL_KEY three (3) times to unseal the server; $UNSEAL_KEY is a unique unseal key. It will look something like this: Jrw4lVwxQbJaQSwEJsdBiWDixjhMBeeQCX33r6OI+7m+.

     Note: Unsealing the server has to be done every time a non-developer server is started. This is the only step that will need to be consistently redone, so it’s important to maintain access to these unseal keys.

5. Get a root token.

   • Run vault operator generate-root -init. This will initialize the process of generating a new root token, and provide you with an OTP that will look something like this: OTP nT6hAaG10BUc4UqgED5gLPRPK.

   • Run vault operator generate-root three (3) times. Each time you will be prompted for a different unseal key. The last time you run this, an encoded token will be generated, which needs to be decrypted. It will look something like this: Encoded Token HXp7Cw4SE1VhNAw3YgIDFnMCUjAWBTEqBCQ.

   • Run vault operator generate-root -decode=$ENCODED_TOKEN -otp=$OTP. This uses the previous OTP from above as well as the encrypted token.

     Example:

     vault operator generate-root -decode=HXp7Cw4SE1VhNAw3YgIDFnMCUjAWBTEqBCQ -otp=nT6hAaG10BUc4UqgED5gLPRPKh

   This will result in getting a root token that looks something like this: s.McOsVdQvYTUZrq6FgWZUczOL.

   Note: Getting a root token is the easiest way to use this locally but not recommended for production, since it’s better to use a specific token under a specific policy than to give root access.

6. Enable the KV secrets engine.

   • Run vault login and enter the root token you just acquired.

   • Run vault secrets enable kv to enable the kv secrets engine.

   Reference: For more information, see KV Secrets Engine - Version 2.

   • Save the root token to a named text file. For example: token.txt.

Creating a Secret within Vault

To create a secret within Vault:

1. Go to the Vault Server that will be connected with IAP, and open the user interface.
2. Open the KV Secrets Engine you have configured. If this does not exist, create one.
3. Click Create Secret.
4. Choose a path for this secret. This must be unique, and it will be important for future steps.
5. In the Version data there are two input boxes that require values.
6. In the key input box on the left, type the value you want to use as a key within that file path. You can include multiple keys within one path.
7. In the value input box, type the unencrypted value you would like to store as a secret within Vault. For example, if you wanted to store a value as a "default_password", and give it the value of "password":
   • Type "default_password" into the path.
   • Type "key" into the key.
   • Type "password" into the value input boxes.
8. Repeat for any additional secrets you would like to store in Vault.

Using a Secret within IAP

For each place where encryption can be used, the provided examples will revolve around a path of "default_password" and a secret of "password", and can be substituted for real data.

Services

To set encryption for Adapters:

1. Go to Admin Essentials, click the Adapters tab, and select an Adapter.
2. Within this Adapter, locate the value you would like to encrypt. This is likely within the properties.properties object. It may currently have a value of "$ENC..."
3. Remove the existing value. Replace it with "$SECRET_" and then the path within Vault to where that secret is stored, followed by " $KEY_" (HINT: there is a space before "$KEY") and the key within that path. An example would be "$SECRET_default_password $KEY_key" which will evaluate to "password".
4. Save the adapter, and it will automatically restart using Vault to decrypt the changed property.

Profiles

To set encryption for Profiles:

1. Go to Admin Essentials, click the Profiles tab, and select the currently running profile.
2. Within this profile, click Configure, and then select one of the profile properties, such as RabbitMQ. Choose a RabbitMQ property to encrypt, such as "password".
3. Remove the existing value. Replace it with "$SECRET_" and then the path within Vault to where that secret is stored, followed by " $KEY_" (HINT: there is a space before "$KEY") and the key within that path. An example would be "$SECRET_default_password $KEY_key" which will evaluate to "password".
4. Save the profile.
5. Restart IAP for these changes to take effect.

Properties.json

Note: It is not possible to encrypt any of the vaultProps within the properties.json.

1. Open the properties.json and select a property to encrypt, such as "mongoProps.credentials.passwd".
2. Remove the existing value. Replace it with "$SECRET_" and then the path within Vault to where that secret is stored, followed by " $KEY_" and the key within that path. An example would be "$SECRET_default_password $KEY_key" which will evaluate to "password".
3. Save the document.
4. Restart IAP for these changes to take effect.