HashiCorp Vault Encryption

This guide explains how to install and configure HashiCorp Vault ("Vault"). This application is used for encrypting and decrypting properties within the Itential Automation Platform (IAP).

Install Vault

To install Vault:

1. You must be logged in as root. Using sudo or a different account with the same access as root will not work.

   Figure 1: Root User

   

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

   yum install -y yum-utils

   Figure 2: Install Command

   

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

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

   Figure 3: Add Vault Repo

   

4. Install Vault.

   yum -y install vault

   Figure 4: Install Vault

   

5. Verify installation.

   vault --version

   Figure 5: Verify Install

   

Configure Vault

To configure Vault:

1. Navigate to /opt/vault.

   Figure 6: Change Directory

   

2. Create a config file with an hcl file extension.

   Figure 7: Create Config File

   

3. Edit the config by adding the information below.

   ```storage "raft" {
   path = "/opt/vault/data"
   node_id = "node1"
   }

   listener "tcp" {
   address = "127.0.0.1:8200"
   tls_disable = "true"
   }

   api_addr = "http://127.0.0.1:8200"
   cluster_addr = "https://127.0.0.1:8201"
   ui = true
   ```

   Figure 8: Edit Config File

   

4. Run Vault using the command vault server -config=/opt/vault/config.hcl. This will start the Vault Server using the newly created config file.

   vault server -config=/opt/vault/config.hcl

   Figure 9: Start Vault

   

5. Once the Vault Server is running, open a second terminal window. Do not close the first terminal window as this will stop the Vault Server.

   Figure 10: Vault Server is Running

   

Unseal Vault Server

To unseal the Vault server:

1. In the second terminal window run the following commands:

   export VAULT_ADDR='http://127.0.0.1:8200'
   vault operator init

   Figure 11: Run Commands Second Terminal Window

   

2. Copy the outlined key information from the terminal window into a text file. You will need to use this information more than once.

   Figure 12: Copy Key Information

   

3. Run the unseal command vault operator unseal three (3) times using the unseal key information copied to the text file. You will need to use three (3) different unseals keys. It does not matter which three you use, but make sure each one is different.

   ---

   Note: By default there are five (5) keys with a threshold of three (3) keys. Once three (3) keys are entered the vault is unsealed. The progress of unsealing is outlined in the image below.

   ---

   Figure 13: Unseal Progress

   

4. Login to Vault using the initial root token (it should have been copied to the text file with the unseal keys). Use vault login <INITIAL_ROOT_TOKEN>.

   Figure 14: Login to Vault

   

5. Run the vault operator generate-root -init to obtain a One Time Password (OTP).

   Figure 15: Get OTP

   

6. Run the command vault operator generate-root to obtain the encoded key. This step will need to be performed three (3) times using the unseal keys. You may use the same three keys from before. Copy the encoded key to your text file.

   Figure 16: Get Encoded Key

   

7. Use the command vault operator generate-root -decode=$ENCODED_TOKEN -otp=$OTP to obtain a new root key. Remember to replace the variable with your encoded token and OTP.

   Figure 17: Get New Root Key

   

8. Once the new root key is generated (outlined in the image below), create a token.txt file for storage. The location of the token file should be in /opt/vault directory.

   Figure 18: Store New Root Key

   

Enable KV Secrets Engine

To enable the KV Secrets Engine for Vault:

1. Run the command vault secrets enable kv-v2 to enable the KV Secrets Engine. V2 is the recommended version for Vault.

   Figure 19: Enable KV Engine

   

2. Navigate to /opt/pronghorn/current and edit the properties.json file with the location of the token.txt file. More information on the token file can be found in the Vault properties section below.

   Figure 20: Edit Properties

   

Vault Properties

To use Vault, there must be a vaultProps section within the properties.json file.

Property	Required	Default	Description
url	Yes	http://localhost:8200	The default URL to connect to Vault, including the hostname and port.
token	Yes	/file/path/token.txt	The file path to a document containing a token. The token is used for authentication to access Vault secrets.
endpoint	Yes	secret/data	The endpoint for the Secrets Engine type that is used.

The vaultProps can be configured with the following properties:

"vaultProps": {
    "url": "http://localhost:8200",
    "token": "/opt/vault/token.txt",
    "endpoint": "kv-v2/data"
  }

Since pathing to the Secrets Engine can be whatever you set as a unique endpoint, the following URL sample is presented with v1 as a hard-coded file path in IAP where the actual vault token is stored.

Example: URL Structure

http://localhost:8200/v1/kv-v2/data

For more information on using Vault:

• See the official HashiCorp Vault Secrets Engine documentation.

• Refer to the Secrets Engines tutorial.

Creating a Secret Using the Vault UI

To create a secret within Vault:

1. Go to the Vault Server UI connected with IAP and login.

   Figure 21: Vault UI

   

2. Click anywhere on the KV bar.

   Figure 22: Secrets Engine KV Bar

   

3. Click the Create secret + button.

   Figure 23: Create Secret

   

4. Choose a path from the dropdown or enter manually. This must be unique, and it will be important for future steps.

5. Enter the number of versions to keep for the secret metadata.

6. In the key filed in the secret data section, enter the secret data information. For this example test_pass was used.

7. Click the eye icon (button) to make sure the information was added correctly. You can include multiple keys within one path, or use the Add button to enter additional secret data.

8. Click the Save button when you are finished.

   Figure 24: Save Secret

   

9. Secrets may be entered using JSON. The Version 1 dropdown menu pertains to the iteration of the secret entered not the version of the KV Vault Engine.

   Figure 25: JSON Toggle Switch

   

10. The newly created secret will appear alphabetically in the list. From the dropdown menu a variety of functions maybe peformed, such as deleting and viewing details.

    Figure 26: Secrets List

    

Automatic Property Encryption

For most sensitive properties within IAP, it is no longer necessary to manually create secrets within Vault to handle encryption. Instead, if Vault is configured, these propertes will be automatically encrypted. For example, to create a Vault secret for an IAP profile with a rabbitmq.password property, all that is required is to call the API to create the profile, or create the profile in the UI, and ensure that the rabbitmq.password property is filled out in plaintext. This property will not be stored in the database, but instead stored in Vault. Likewise, to update that password, such as when key rotation is needed, simply calling the update API for profiles, or updating it via the UI, with the plaintext password included in the request body.

Using $ENC or $SECRET syntax for these properties is heavily discouraged, as no "double encryption" will ever be performed on those properties.

Adapters

If an adapter has a property that will be automatically encrypted, this property will display in the form view as a value that is starred out (*****).

Figure 27: Adapter Configuration

If this property already exists, or is being edited, differently-styled stars will appear for the value. From this view it is not possible to see the value that is being typed.

Figure 28: Adapter Configuration Update

In the advanced view, it is possible to see the value being typed, although it will never be starred if it already exists. Instead, it will display as an empty string regardless of the actual value. It will also appear with a different tooltip display indicating it has an encrypted property.

Figure 29: Adapter Configuration Advanced View

Integrations

If an integration has a property that will be automatically encrypted, this property will display in the form view as a starred out value. These encrypted properties are standardized based on the type of authentication used by the integration.

Figure 30: Integrations Configuration

If this property already exists, or is being edited, differently-styled stars will appear for the value. From this view it is not possible to see the value that is being typed.

Figure 31: Integrations Configuration Update

In the advanced view, it is possible to see the value being typed, although it will never be starred if it already exists. Instead, it will always display as an empty string. It will also appear with a different tooltip indicating it has an encrypted property.

Figure 32: Integrations Configuration Advanced View

Applications

While most Itential applications do not have any properties that are configurable, thereby leading to no sensitive properties, it is possible for custom applications to have properties configured in the propertiesDecorators.json to always be encrypted. These will appear the same way as adapters and integrations in the Admin Essentials user interface.

Profiles

If a profile has a property that needs to be automatically encrypted, such as the rabbitmq password, it will display as a starred out value to indicate it is an encrypted property.

Figure 33: Profile Configuration

If this property already exists, or is being edited, differently-styled stars will appear for the value. The difference is subtle but is a visual indication between a pre-configured secret versus a field that hasn't yet been configured with a secret. Please note that from this view, it is not possible to see the value that is being typed.

Figure 34: Profile Configuration Update

Manual Property Encryption

It is still possible to have specific keys encrypted in Vault using the $SECRET syntax. However, this practice is discouraged unless there are no other possibilities, such as for encrypting the properties.json. Property encryption should be performed automatically wherever possible.

Adapters

To set encryption for Adapters:

1. Within Vault, create the path and key name for the item in question. HINT: Be sure to give it a path and key name that is easy to relate back to the targetted item.

2. Go to Admin Essentials, click the Adapters menu, and select an Adapter.

   Figure 35: Select Adapter

   

3. Within the adapter you selected, locate the value you would like to encrypt. Click the Advanced View toggle switch to see the JSON, which may be easier to edit.

   Figure 36: Advanced Configuration View

   

4. 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".

   Figure 37: Edit Adapter

   

5. Click Save and the adapter will automatically restart using Vault to decrypt the changed property.

6. The adapter should appear in the list with a green status indicator and connection icons after restart.

   Figure 38: Adapter Connected

   

Profiles

To set encryption for Profiles:

1. Within Vault, create the path and key name for the item in question. HINT: Be sure to give it a path and key name that is easy to relate back to the targetted item.

2. Go to Admin Essentials, click the Profiles tab, and select the currently running profile.

3. Within this profile, click Configure, and then select one of the profile properties, such as RabbitMQ.

   Figure 39: Edit Profile Properties

   

4. Choose a RabbitMQ property to encrypt, such as "password".

5. 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".

6. Save the profile.

   Figure 40: Save Profile Properties

   

7. Restart IAP for these changes to take effect.

Properties.json

To set encryption for a property:

1. Within Vault, create the path and key name for the item in question. HINT: Be sure to give it a path and key name that is easy to relate back to the targetted item.

2. Open the properties.json and select a property to encrypt, such as "mongoProps.credentials.passwd".

   ---

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

   ---

3. 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".

4. Save the document.

5. Restart IAP for these changes to take effect.