Your First Secret

6min
HCP
Vault

One of the core features of Vault is the ability to read and write arbitrary secrets securely. Secrets written to Vault are encrypted and then written to the backend storage. Therefore, the backend storage mechanism never sees the unencrypted value and doesn't have the means necessary to decrypt it without Vault.

NOTE: This step assumes that you created and connected to the HCP Vault cluster in the Create a Vault Cluster on HashiCorp Cloud Platform (HCP) step.

Key/Value secrets engine

Key/Value v2 secrets engine is a generic key-value store used to store arbitrary secrets within the configured physical storage for Vault. Secrets written to Vault are encrypted and then written to backend storage. Therefore, the backend storage mechanism never sees the unencrypted value and doesn't have the means necessary to decrypt it without Vault.

Key/Value secrets engine has version 1 and 2. The difference is that v2 provides versioning of secrets and v1 does not.

Use the vault kv <subcommand> [options] [args] command to interact with K/V secrets engine.

Available subcommands:

Subcommand	kv v1	kv v2	Description
delete	x	x	Delete versions of secrets stored in K/V
destroy		x	Permanently remove one or more versions of secrets
enable-versioning		x	Turns on versioning for an existing K/V v1 store
get	x	x	Retrieve data
list	x	x	List data or secrets
metadata		x	Interact with Vault's Key-Value storage
patch		x	Update secrets without overwriting existing secrets
put	x	x	Sets or update secrets (this replaces existing secrets)
rollback		x	Rolls back to a previous version of secrets
undelete		x	Restore the deleted version of secrets

Enable secrets engine

First, enable key/value v2 secrets engine at secret/ path in the admin namespace. Secrets engines are tied to their namespace. Therefore, the secrets you create in the admin namespace are not accessible from other namespaces.

NOTE: If you receive any errors after making a configuration change in the Vault UI, such as 404 page could not be found refresh the page.

In the Vault UI, set the current namespace to admin/.
Select the Secrets tab in the Vault UI.
Click Enable new engine.
Select KV from the list, and then click Next.
Enter secret in the Path field.
Click Enable Engine to complete.
Click secret to explore the new secret engine you enabled.

Now that you have a secret engine enabled, you will create a new secret.

If you did not set the VAULT_ADDR, VAULT_NAMESPACE, and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Verify that the VAULT_NAMESPACE environment variable is set to admin.
```
$ echo $VAULT_NAMESPACE
admin
```
If not, be sure to set it before you continue.
```
$ export VAULT_NAMESPACE=admin
```

Enable key/value v2 secrets engine (kv-v2) at secret/.

$ vault secrets enable -path=secret kv-v2
Success! Enabled the kv-v2 secrets engine at: secret/

Each API request requires the token and Vault address. If you did not set the VAULT_ADDR and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Enable KV v2 at secret/.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin" \
    --request POST \
    --data '{ "type": "kv-v2" }' \
    $VAULT_ADDR/v1/sys/mounts/secret

NOTE: Instead of passing the target namespace using the X-Vault-Namespace header, you can specify the namespace in the API endpoint, /admin/sys/mounts/secret. In that case, the cURL command becomes:

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{ "type": "kv-v2" }' \
    $VAULT_ADDR/v1/admin/sys/mounts/secret

You can choose whichever methods you prefer.

Create secrets

Now that you have enabled a secrets engine, in this scenario the key/value v2 secrets engine, you can store and retrieve secrets from HCP Vault.

Click Create secret. Enter test/webapp in the Path for this secret field.
Under the Secret data section, enter api-key in the key field, and ABC0DEFG9876 in the value field. You can click on the sensitive information toggle to show or hide the entered secret values.
Click Save.
Click the masked input toggle button to review the value for the api-key key.

Store api-key with value ABC0DEFG9876 at the path secret/test/webapp.

$ vault kv put secret/test/webapp api-key="ABC0DEFG9876"

Example output:

Key              Value
---              -----
created_time     2021-06-17T02:48:51.643350733Z
deletion_time    n/a
destroyed        false
version          1

To verify, read back the secret at secret/test/webapp.

$ vault kv get secret/test/webapp

Example output:

====== Metadata ======
Key              Value
---              -----
created_time     2021-06-17T02:48:51.643350733Z
deletion_time    n/a
destroyed        false
version          1

===== Data =====
Key        Value
---        -----
api-key    ABC0DEFG9876

Store api-key with value ABC0DEFG9876 at the path secret/test/webapp.

First, create an API request payload containing the test data.

$ tee payload.json <<EOF
{
  "data": {
    "api-key": "ABC0DEFG9876"
  }
}
EOF

Write the data at secret/test/webapp.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
      --header "X-Vault-Namespace: admin" \
      --data @payload.json \
      $VAULT_ADDR/v1/secret/data/test/webapp | jq -r ".data"

NOTE: This example uses jq to process the JSON output for readability.

Example output:

{
  "created_time": "2021-06-17T03:05:48.70422343Z",
  "deletion_time": "",
  "destroyed": false,
  "version": 1
}

To verify, read back the secret.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --header "X-Vault-Namespace: admin" \
      $VAULT_ADDR/v1/secret/data/test/webapp | jq -r ".data"

Example output:

{
  "data": {
    "api-key": "ABC0DEFG9876"
  },
  "metadata": {
    "created_time": "2021-06-17T03:06:34.063027186Z",
    "deletion_time": "",
    "destroyed": false,
    "version": 1
  }
}

Next steps

This tutorial gave you a brief introduction to the key/value v2 secrets engine. To understand the features it provides, follow the Versioned Key/Value Secrets Engine tutorial. The tutorial is written for a self-managed Vault OSS server. The only difference is that you must set the target namespace when you follow the instruction.

The next step is to go through an introduction to Vault policies.