Step 4 - Create a Secret

Video Guide

Click to open the video in a new window

Procedure

Two methods for entering secrets are supported: File and Direct Command.

File - The File method uses a file that contains the attributes for secrets that are uploaded in bulk to a path in your vault, using the CLI.
Direct Command - The Direct Command method uses the CLI to individually specify the creation of secrets directly into a path in your vault.

After secrets are created, they can be viewed in the DSV UI Reference in your Home Vault.

Creating Secrets from a File

To create a secret, open a text editor and create and save a file (.json) similar to this example. The JSON is arbitrary, so you can set any number of fields (key-value pairs) for a secret. Files may also be used to enter attributes --attributes or a description --desc

Copy

{
  "host": "server01",
  "username": "administrator",
  "password": "secretp@ssword"
}

Add as many secrets as needed. Save the file and note its location.
Issue a dsv secret create command and specify the path to its storage location.

Every secret correlates uniquely with a specific path that describes the location of the secret in your Home Vault. The idea here is no different than the concept of a path to a file on a hard drive. Paths are also the basis for creating policies to determine who (or what) has which rights to those secrets in your Home Vault.

Linux:

Copy

dsv secret create --path servers:us-east:server01 --data @secret.json

Powershell:

Copy

dsv secret create --path servers:us-east:server01 --data '@secret.json'

CMD:

Copy

dsv secret create --path servers:us-east:server01 --data @secret.json

Outputs:

Copy

{
  "attributes": null,
  "created": "2019-01-03T23:11:48Z",
  "createdBy": "users:thy-one:admin@company.com",
  "data": {
    "host": "server01",
    "password": "secretp@sssword",
    "username": "administrator"
  },
  "description": "",
  "id": "c5239a6c-422e-4f57-b3a6-5167656af852",
  "lastModified": "2019-01-03T23:11:48Z",
  "lastModifiedBy": "users:thy-one:admin@company.com",
  "path": "servers:us-east:server01",
  "version": "0"
}

Creating Secrets from Direct Command

Instead of using a file, the data can be entered as part of the command. The following options are available:

Copy

--data -d      JSON object containing the secret data
--attributes   JSON object containing attributes about the secret
--desc         String with description of the secret
--body         JSON object with 1 or more of the above options
--path -r      Target path to a secret (required)
--help         Help with this command

If the --body option is passed in and any of the other options are also passed in (data, attributes or desc), the body option will be politely ignored.

Linux:

Copy

dsv secret create --path servers:us-east:server01 --data '{"host":"server01","username":"administrator","password":"secretp@sssword"}'

dsv secret create --path servers:us-east:server01 --attributes '{"secretType":"webServer","serverName":"server01","adminLevel":"readOnly"}'

dsv secret create --path servers:us-east:server01 --desc "webserver secret values"

dsv secret create --path servers:us-east:server01 --body '{"data":{"host":"server01","username":"administrator","password":"secretp@sssword"},
"attributes":{"secretType":"webServer","serverName":"server01","adminLevel":"readOnly"},"desc":"webserver secret values"}'

Powershell:

Copy

dsv secret create --path servers:us-east:server01 --data '{\"host\":\"server01\",\"username\":\"administrator\",\"password\":\"secretp@sssword\"}'

dsv secret create --path servers:us-east:server01 --attributes '{\"secretType\":\"webServer\",\"serverName\":\"server01\",\"adminLevel\":\"readOnly\"}'

dsv secret create --path servers:us-east:server01 --desc \"webserver secret values\"

dsv secret create --path servers:us-east:server01 --body '{\"data\":{\"host\":\"server01\",\"username\":\"administrator\",\"password\":\"secretp@sssword\"},
\"attributes\":{\"secretType\":\"webServer\",\"serverName\":\"server01\",\"adminLevel\":\"readOnly\"},\"desc\":\"webserver secret values\"}'

dsv secret create can be replaced with dsv home create.

Outputs:

Copy

{
  "attributes": null,
  "created": "2019-01-03T23:11:48Z",
  "createdBy": "users:thy-one:admin@company.com",
  "data": {
    "host": "server01",
    "password": "secretp@sssword",
    "username": "administrator"
  },
  "description": "",
  "id": "c5239a6c-422e-4f57-b3a6-5167656af852",
  "lastModified": "2019-01-03T23:11:48Z",
  "lastModifiedBy": "users:thy-one:admin@company.com",
  "path": "servers:us-east:server01",
  "version": "0"
}

Retrieve a Secret

To retrieve a secret use the Secret read command and specify the path to the Secret's storage location.

Copy

dsv secret read --path /servers/us-east/server01

Output defaults to JSON:

Copy

{
  "attributes": null,
  "created": "2019-11-08T15:46:14Z",
  "createdBy": "users:thy-one:admin@company.com",
  "data": {
    "host": "server01",
    "password": "secretp@ssword",
    "username": "administrator"
  },
  "description": "",
  "id": "c5239a6c-422e-4f57-b3a6-5167656af852",
  "lastModified": "2020-01-17T15:38:49Z",
  "lastModifiedBy": "users:thy-one:admin@company.com",
  "path": "servers:us-east:server01",
  "version": "0"
}

If you would like the output to be in YAML:

Copy

dsv secret read --path /servers/us-east/server01 -e yaml

Outputs:

Copy

attributes: null
created: "2019-11-08T15:46:14Z"
createdBy: users:thy-one:admin@company.com
data:
  host: server01
  password: secretp@ssword
  username: administrator
description: ""
id: c5239a6c-422e-4f57-b3a6-5167656af852
lastModified: "2020-01-17T15:38:49Z"
lastModifiedBy: users:thy-one:admin@company.com
path: servers:us-east:server01
version: "0"

Filter JSON Command Output for Specific Fields

When you need to locate a specific field in a JSON output, use a JSON filter. An example use case is writing scripts that need to obtain a password but lack the capacity to efficiently parse JSON.

Copy

dsv secret read --path /servers/us-east/server01 -f data.password

Would return just the password.

Separately Update Attributes, Data, and Description

Using the --data, --attributes, and --desc flags, respectively, you can update a Secret's data, attributes, and description separately. For example:

Copy

dsv secret update servers/us-east/server01 --data '{"host": "server01", "password": "badpassword","username": "admin"}' --desc 'update description'  --attributes '{"attr": "add one"}'

Copy

{
  "attributes": {
    "attr": "add one"
  },
  "created": "2019-11-08T15:46:14Z",
  "createdBy": "users:thy-one:admin@company.com",
  "data": {
    "host": "server01",
    "password": "badpassword",
    "username": "admin"
  },
  "description": "update description",
  "id": "4348e941-f945-460d-98e8-2ab659362f51",
  "lastModified": "2020-02-22T20:48:05Z",
  "lastModifiedBy": "users:thy-one:admin@company.com",
  "path": "servers:us-east:server01",
  "version": "1"
}

Refer to Steps 5 Create Users and 6 Provide User Access to create users, user groups and policies that provide the framework for managing the secrets.