Managing Paths and Secrets

About Managing Paths and Secrets

You can add, edit or delete paths and secrets in your Vault service instance. A path specifies the storage location of your secret. Vault service storage mechanism is similar to virtual file system. When you create an instance of Vault service, the default storage location is defined by a specific path that is equivalent to the home directory in a file system.

You can then add sub paths to the default path to define additional storage locations or nodes. The sub-paths are equivalent to the hierarchy of folders and sub-folders in a file system. The secrets are stored under a path as key value pairs.

You can either use REST APIs to manage the paths or use the Vault dashboard UI. For more information on Vault dashboard, see vault-service-using-dashboard.html#task_aa8e373e-b952-4c12-a9e8-b1114219b0a4.

To construct the URL for Vault service API, you can get the vault_url from your VCAP_SERVICES environment variable. The vault_url contains the root path (as a set of GUIDs) to your vault instance.

The following is an example of the vault_url containing the root path:

https://predix-vault.aws-usw02-pr.ice.predix.io/v1/secret/81f37567-f14c-4289-817b-57b15ee24d2e/078221f7-da65-491c-9185-4d3f47442e9f/6cb25da8-7206-4dd2-944e-9717c04a0a7e

You can use Vault service API to perform the following tasks related to managing paths and secrets:

Additionally, Vault service provides one time secret sharing capability by wrapping the value. To use this capability, you can use the following APIs:

APIs: Creating, Retrieving, and Deleting Paths and Secrets

You can use APIs to manage paths and secrets in Vault.

Storing a Secret

API/secret
DescriptionStores a secret at the specified location.
MethodPOST/PUT
URL/secret/<path>

Where, <path> is the root path to your vault instance plus any sub-path that you create.

Parameterskey

Specify a key name paired with an associated value to be stored at the given path. You can specify multiple key/value pairs. You can retrieve all values using the read operation.

HeaderX-Vault-Token: <token>
ReturnsA 204 response code.

Retrieving a Secret

API/secret
Description

Retrieve the secret at the specified location.

MethodGET
URL/secret/<path>

Where, <path> is the root path to your vault instance plus any sub-path that you create.

ParametersNone
HeaderX-Vault-Token: <token>
Returns 
{
"auth":null,
"data":{
    "foo":"bar"
    },
"lease_duration":2764800,
"lease_id":"",
"renewable":false
}

Retrieving a List of Key Names

API/secret
DescriptionReturns a list of key names at the specified location. Folders are suffixed with /. The input must be a folder; list on a file will not return a value. The values themselves are not accessible via this command.
Note: Policy-based filtering is not performed on keys. Therefore do not encode sensitive information in key names.
MethodLIST/GET
URL/secret/<path> (LIST) or /secret/<path>?list=true (GET)

Where, <path> is the root path to your vault instance plus any sub-path that you create.

ParametersNone
HeaderX-Vault-Token: <token>
Returns

The example below shows output for a query path of secret/ when there are secrets at secret/foo and secret/foo/bar.

{
"auth":null,
"data":{
    "foo":"bar"
    },
"lease_duration":2764800,
"lease_id":"",
"renewable":false
}

Deleting a Secret

API/secret
DescriptionDeletes the secret at the specified location.
MethodDELETE
URL/secret/<path>

Where, <path> is the root path to your vault instance plus any sub-path that you create.

ParametersNone
HeaderX-Vault-Token: <token>
ReturnsA 204 response code.

APIs: One Time Secret Sharing

Vault service provides one time secret sharing capability by wrapping the specified value.

Wrapping a Value in a Response-Wrapped Token

API/sys/wrapping/wrap
DescriptionWraps the user-specified data inside a response-wrapped token.
MethodPOST
URL/sys/wrapping/wrap
Parameters:any (map<string|string>: nil) (required)

Specify keys:value pairs in a JSON object. The exact set of given parameters is contained in the wrapped response.

HeaderX-Vault-Token: <token>
Sample Payload 
{
  "foo": "bar",
  "zip": "zap"
}
Sample Request 
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/sys/wrapping/wrap
Returns 
{
  "request_id": "",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": null,
  "warnings": null,
  "wrap_info": {
    "token": "fb79b9d3-d94e-9eb6-4919-c559311133d6",
    "ttl": 300,
    "creation_time": "2016-09-28T14:41:00.56961496-04:00",
    "wrapped_accessor": ""
  }
}

Returning Wrapping Token Properties

API/sys/wrapping/lookup
DescriptionReturns wrapping token properties.
MethodPOST
URL/sys/wrapping/lookup
Parameterstoken (required)

Specifies the wrapping token Id.

HeaderX-Vault-Token: <token>
Sample Payload 
{
  "token": "abcd1234"
}
Sample Request 
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/sys/wrapping/lookup
Returns 
{
  "request_id": "481320f5-fdf8-885d-8050-65fa767fd19b",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "creation_time": "2016-09-28T14:16:13.07103516-04:00",
    "creation_ttl": 300
  },
  "warnings": null
}

Re-wrapping a Response-Wrapped Token

API/sys/wrapping/rewrap
DescriptionRe-wraps a response-wrapped token. The new token uses the same creation TTL as the original token and contains the same response. The old token is invalidated. This API is useful when you need to store a secret for a long time in a response-wrapped token that requires rotation.
MethodPOST
URL/sys/wrapping/rewrap
Parameterstoken (required)

Specifies the wrapping token Id.

HeaderX-Vault-Token: <token>
Sample Payload 
{
  "token": "abcd1234"
}
Sample Request 
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/sys/wrapping/rewrap
Returns 
{
  "request_id": "",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": null,
  "warnings": null,
  "wrap_info": {
    "token": "3b6f1193-0707-ac17-284d-e41032e74d1f",
    "ttl": 300,
    "creation_time": "2016-09-28T14:22:26.486186607-04:00",
    "wrapped_accessor": ""
  }
}

Unwrapping a Wrapped Response

API/sys/wrapping/unwrap
DescriptionReturns the original response inside the given wrapping token. The API validates the token, returns the original value, and ensures that the response is logged for audit purpose.
MethodPOST
URL/sys/wrapping/unwrap
Parameterstoken (required)

Specifies the wrapping token Id.

This parameter is not required if you use a wrapping token as the client token in the API call. It is required if you use a different token with permissions to access this endpoint.

Note: Do not use the token parameter along with wrapping token as client token. This is considered double use of the token. In such a case, the Vault service revokes the wrapping token and you cannot lookup the value.
HeaderX-Vault-Token: <token>
Sample Payload 
{
  "token": "abcd1234"
}
Sample Request 
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/sys/wrapping/unwrap
Returns 
{
  "request_id": "8e33c808-f86c-cff8-f30a-fbb3ac22c4a8",
  "lease_id": "",
  "lease_duration": 2592000,
  "renewable": false,
  "data": {
    "zip": "zap"
  },
  "warnings": null
}