Introduction
CredHub manages credentials like passwords, users, certificates, certificate authorities, ssh keys, rsa keys and arbitrary values (strings and JSON blobs). The following spec details the commands for the CredHub CLI.
Get Credentials
Get by ID
CredHub CLI
user$ credhub get --id 2993f622-cb1e-4e00-a267-4b23c273bf3d
id: 2993f622-cb1e-4e00-a267-4b23c273bf3d
name: /example-password
type: password
value: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
version_created_at: 2017-01-05T01:01:01Z
This request retrieves a credential by ID. Exactly one value will be returned.
Get by Name
CredHub CLI
user$ credhub get --name '/example-password'
id: 2993f622-cb1e-4e00-a267-4b23c273bf3d
name: /example-password
type: password
value: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
version_created_at: 2017-01-05T01:01:01Z
This request returns a credential’s value(s) by name. The current value will be returned unless --versions=<NUMBER OF VERSIONS> is specified. To return only the value of a credential, use the --quiet or -q flags. If you would only like to see one key from the value (i.e. a certificate’s private key), use the -k <NAME OF KEY> or --key=<NAME OF KEY> flags.
Output JSON
CredHub CLI
user$ credhub get --name '/example-json'
{
"id": "b508a5d6-c1ed-4218-8ed3-aca98d8b2c25",
"name": "/example-json",
"type": "json",
"value": {
"is_true": true,
"key": 123,
"key_list": [
"val1",
"val2"
]
},
"version_created_at": "2020-03-10T16:32:37Z"
}
All responses default to YAML unless the -j or --output-json flags are passed in.
Type: Value
CredHub CLI
user$ credhub get --name '/example-value'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-value
type: value
value: sample
version_created_at: 2017-01-01T04:07:18Z
This request returns a credential by name. The example provided shows the request parameters and response structure of a value type credential.
Type: JSON
CredHub CLI
user$ credhub get --name '/example-json'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-json
type: json
value:
key: 123
key_list:
- val1
- val2
is_true: true
version_created_at: 2017-01-01T04:07:18Z
This request returns a credential by name. The example provided shows the request parameters and response structure of a JSON type credential. The response is formatted as YAML by default, but can be formatted as json using the -j flag.
Type: Password
CredHub CLI
user$ credhub get --name '/example-password'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-password
type: password
value: 3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R
version_created_at: 2017-01-01T04:07:18Z
Type: User
CredHub CLI
user$ credhub get --name '/example-user'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-user
type: user
value:
username: FQnwWoxgSrDuqDLmeLpU
password: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
password_hash: $6$h3b3JsG5$MnrPIrF6T3zAWk9uaun64vWY.vaBQ5nTRFZjjVqKuDWccxWXn8n6vstQykXEReamb4GYh2q1HC7vFy11wflXd0
version_created_at: 2017-01-01T04:07:18Z
This request returns a credential by name. The example provided shows the request parameters and response structure of a user type credential.
Type: Certificate
CredHub CLI
user$ credhub get --name '/example-certificate'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-certificate
type: certificate
value:
root: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
certificate: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
This request returns a credential by name. The example provided shows the request parameters and response structure of a certificate type credential.
Type: RSA
CredHub CLI
user$ credhub get --name '/example-rsa'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-rsa
type: rsa
value:
public_key: |
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
This request returns a credential by name. The example provided shows the request parameters and response structure of an RSA type credential.
Type: SSH
CredHub CLI
user$ credhub get --name '/example-ssh'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-ssh
type: ssh
value:
public_key: ssh-rsa AAAAB3Nz...
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
This request returns a credential by name. The example provided shows the request parameters and response structure of an SSH type credential.
Generating Credentials
| Long Flag | Short Flag | Used For Type | Description |
|---|---|---|---|
| –name | -n | All | Name of the credential to generate |
| –type | -t | All | Sets the credential type to generate. Valid types include ‘password’, ‘user’, ‘certificate’, ‘ssh’ and ‘rsa’. |
| –no-overwrite | -O | All | Credential is not modified if stored value already exists |
| –username | -z | User | Sets the username value of the credential |
| –password | -w | User, Password | Sets the password value of the credential |
| –length | -l | User, Password | Length of the generated value (Default: 30) |
| –include-special | -S | User, Password | Include special characters in the generated value |
| –exclude-number | -N | User, Password | Exclude number characters from the generated value |
| –exclude-upper | -U | User, Password | Exclude upper alpha characters from the generated value |
| –exclude-lower | -L | User, Password | Exclude lower alpha characters from the generated value |
| –ssh-comment | -m | SSH | Comment appended to public key to help identify in environment |
| –key-length | -k | SSH, RSA, Certificate | Bit length of the generated key (Default: 2048) |
| –duration | -d | Certificate | Valid duration (in days) of the generated certificate (Default: 365) |
| –common-name | -c | Certificate | Common name of the generated certificate |
| –organization | -o | Certificate | Organization of the generated certificate |
| –organization-unit | -u | Certificate | Organization unit of the generated certificate |
| –locality | -i | Certificate | Locality/city of the generated certificate |
| –state | -s | Certificate | State/province of the generated certificate |
| –country | -y | Certificate | Country of the generated certificate |
| –alternative-name | -a | Certificate | A subject alternative name of the generated certificate (may be specified multiple times) |
| –key-usage | -g | Certificate | Key Usage extensions for the generated certificate (may be specified multiple times) |
| –ext-key-usage | -e | Certificate | Extended Key Usage extensions for the generated certificate (may be specified multiple times) |
| –ca | Certificate | Name of CA used to sign the generated certificate | |
| –is-ca | Certificate | The generated certificate is a certificate authority | |
| –self-sign | Certificate | The generated certificate will be self-signed | |
| –metadata | n/a | All | Sets additional metadata on the credential |
Type: Password
This request generates a password credential based on the provided parameters.
CredHub CLI
user$ credhub generate --type password --name '/example-password'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-password
type: password
value: 3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R
version_created_at: 2017-01-01T04:07:18Z
Type: User
This request generates a user credential based on the provided parameters.
CredHub CLI
user$ credhub generate --type user --name '/example-user'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-user
type: user
value:
username: FQnwWoxgSrDuqDLmeLpU
password: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
password_hash: $6$h3b3JsG5$MnrPIrF6T3zAWk9uaun64vWY.vaBQ5nTRFZjjVqKuDWccxWXn8n6vstQykXEReamb4GYh2q1HC7vFy11wflXd0
version_created_at: 2017-01-01T04:07:18Z
Type: Certificate
This request generates a user credential based on the provided parameters.
CredHub CLI
user$ credhub generate --type certificate --name '/example-certificate' --common-name 'example.com' --ca '/example-ca'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-certificate
type: certificate
value:
root: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
certificate: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
Type: RSA
This request generates an RSA credential based on the provided parameters.
CredHub CLI
user$ credhub generate --type rsa --name '/example-rsa'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-rsa
type: rsa
value:
public_key: |
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
Type: SSH
This request generates an SSH credential based on the provided parameters.
CredHub CLI
user$ credhub generate --type ssh --name '/example-ssh'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-ssh
type: ssh
value:
public_key: ssh-rsa AAAAB3NzaC1y...W9RWFM1
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
Regenerating Credentials
| Long Flag | Short Flag | Used For Type | Description |
|---|---|---|---|
| –name | -n | All | Name of the credential to regenerate |
| –output-json | -j | All | Return response in JSON format |
| –metadata | n/a | All | Sets metadata on the regenerated credential. The existing metadata is persisted by default. To clear the existing metadata, use this flag and pass in an empty json object. |
Regenerate
Set a credential with a generated value using the same attributes as the stored value
CredHub CLI
user$ credhub regenerate --name '/example-password'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-password
type: password
value: 3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R
version_created_at: 2017-01-01T04:07:18Z
Bulk Regenerate
Recursively regenerate all certificates signed by the provided certificate
CredHub CLI
user$ credhub bulk-regenerate --signed-by /bosh-maestro/zookeeper/tom-ca
regenerated_credentials:
- /bosh-maestro/zookeeper/tom-leaf
Set Credentials
| Long Flag | Short Flag | Used For Type | Description |
|---|---|---|---|
| –name | -n | All | Name of the credential to set |
| –type | -t | All | Sets the credential type. Valid types include ‘value’, ‘json’, ‘password’, ‘user’, ‘certificate’, ‘ssh’ and ‘rsa’. |
| –value | -v | Value, Json | Sets the value for the credential |
| –ca-name | -m | Certificate | Sets the root CA to a stored CA credential |
| –root | -r | Certificate | Sets the root CA from file or value |
| –certificate | -c | Certificate | Sets the certificate from file or value |
| –private | -p | Certificate, SSH, RSA | Sets the private key from file or value |
| –public | -u | SSH, RSA | Sets the public key from file or value |
| –username | -z | User | Sets the username value of the credential |
| –password | -w | User, Password | Sets the password value of the credential |
| –output-json | -j | All | Return response in JSON format |
| –metadata | n/a | All | Sets additional metadata on the credential |
Type: Value
CredHub CLI
user$ credhub set --type value --name '/example-value' --password 'sample'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-value
type: value
value: sample
version_created_at: 2017-01-01T04:07:18Z
This request sets a value credential with a user-provided value.
Type: JSON
CredHub CLI
user$ credhub set --type json --name '/example-json' --value '{ "key": 123, "key_list": ["val1","val2"], "is_true": true }'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-json
type: json
value:
key: 123
key_list:
- val1
- val2
is_true: true
version_created_at: 2017-01-01T04:07:18Z
This request sets a json credential with a user-provided value.
Type: Password
CredHub CLI
user$ credhub set --type password --name '/example-password' --password '3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-password
type: password
value: 3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R
version_created_at: 2017-01-01T04:07:18Z
This request sets a password credential with a user-provided value.
Type: User
CredHub CLI
user$ credhub set --type user --name '/example-user' --username 'FQnwWoxgSrDuqDLmeLpU' --password '6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-user
type: user
value:
username: FQnwWoxgSrDuqDLmeLpU
password: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
password_hash: $6$h3b3JsG5$MnrPIrF6T3zAWk9uaun64vWY.vaBQ5nTRFZjjVqKuDWccxWXn8n6vstQykXEReamb4GYh2q1HC7vFy11wflXd0
version_created_at: 2017-01-01T04:07:18Z
This request sets a user credential with a user-provided value.
Type: Certificate
CredHub CLI
user$ credhub set --type certificate --name '/example-certificate' --root ./root.pem --certificate ./cert.pem --private ./private.pem
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-certificate
type: certificate
value:
root: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
certificate: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
This request sets a certificate credential with a user-provided value.
Type: RSA
CredHub CLI
user$ credhub set --type rsa --name '/example-rsa' --public ./public.pem --private ./private.pem
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-rsa
type: rsa
value:
public_key: |
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
This request sets a RSA credential with a user-provided value.
Type: SSH
CredHub CLI
user$ credhub set --type ssh --name '/example-ssh' --public ./public.pem --private ./private.pem
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-ssh
type: ssh
value:
public_key: ssh-rsa AAAAB3NzaC1y...W9RWFM1
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
This request sets a SSH credential with a user-provided value.
Deleting Credentials
This request deletes a credential by name or by path.
CredHub CLI
user$ credhub delete --name '/example-password'
Credential successfully deleted
user$ credhub delete --path '/example-path'
2 out of 2 credentials under the provided path are successfully deleted.
Permissions
Permissions can be defined for namespaces as well as on explicit credential names. Permissions are additive – if any rule exists authorizing a user to take an action, then the action will be permitted.
actor names must be prefixed with the authentication type:
- mtls-app:APP-GUID (i.e. mtls-app:fdbeb2d4-b601-4a0d-91e8-7e38dde426f7)
- uaa-user:USER-GUID (i.e. uaa-user:2ae1621a-bb35-4bb7-946a-4761d3b16a04)
- uaa-client:CLIENT-NAME (i.e. uaa-client:director_to_credhub)
Setting/Updating Permissions
This request sets permissions for a path for an actor. You can add permission for a specific credential on a path, as well as all items under a path by using the * syntax.
| Long Flag | Short Flag | Description |
|---|---|---|
| –actor | -a | Name of the actor to grant permissions for |
| –path | -p | Name of path to grant permissions for |
| –operations | -o | Operations allowed (comma separated list)(options: read, write, delete, read_acl, write_acl) |
CredHub CLI
user$ credhub set-permission -a uaa-user:2ae1621a-bb35-4bb7-946a-4761d3b16a04 -p /some-path/* -o read,write,delete,read_acl,write_acl
actor: uaa-user:2ae1621a-bb35-4bb7-946a-4761d3b16a04
operations:
- read
- write
- delete
- read_acl
- write_acl
path: /some-path/*
uuid: cf395f8e-130f-48d8-849e-2250e2886490
Getting Permissions
This request retrieves a permission given the path and actor.
| Long Flag | Short Flag | Description |
|---|---|---|
| –actor | -a | Name of the actor to get permissions for |
| –path | -p | Name of path to get permissions for |
CredHub CLI
user$ credhub get-permission -a uaa-user:2ae1621a-bb35-4bb7-946a-4761d3b16a04 -p /some-path/*
actor: uaa-user:2ae1621a-bb35-4bb7-946a-4761d3b16a04
operations:
- read
- write
- delete
- read_acl
- write_acl
path: /some-path/*
uuid: cf395f8e-130f-48d8-849e-2250e2886490
Deleting Permissions
Delete permissions for an actor on a given path
| Long Flag | Short Flag | Description |
|---|---|---|
| –actor | -a | Name of the actor to delete permissions for |
| –path | -p | Name of path to delete permissions for |
CredHub CLI
user$ credhub delete-permission -a uaa-user:2ae1621a-bb35-4bb7-946a-4761d3b16a04 -p /some-path/*
actor: uaa-user:2ae1621a-bb35-4bb7-946a-4761d3b16a04
operations:
- read
- write
- delete
- read_acl
- write_acl
path: /some-path/*
uuid: cf395f8e-130f-48d8-849e-2250e2886490
Curl
Make an arbitrary request to the targeted CredHub server
| Long Flag | Short Flag | Description |
|---|---|---|
| –path | -p | The server endpoint to make the request against |
| –fail | -f | Fail silently (no output at all) on HTTP errors |
| -X | HTTP method (default: GET) | |
| -d | HTTP data to include in the request body | |
| -i | Include the response headers in the output |
CredHub CLI
user$ credhub curl -p api/v1/certificates
{
"certificates": [
{
"id": "933cd14f-3d3b-4637-a61b-474648fad0ca",
"name": "/bosh-maestro/zookeeper/tom-leaf",
"signed_by": "/bosh-maestro/zookeeper/tom-ca",
"signs": [],
"versions": [
{
"certificate_authority": false,
"expiry_date": "2021-03-13T15:15:13Z",
"generated": true,
"id": "410148ab-5479-4c26-8036-eb9dfd825c68",
"self_signed": false,
"transitional": false
},
{
"certificate_authority": false,
"expiry_date": "2021-03-12T14:25:06Z",
"generated": true,
"id": "c4432134-79cc-4c70-8932-8d5e911097f5",
"self_signed": false,
"transitional": false
}
]
}
]
}
Authentication
Login
Authenticate with CredHub. UAA password and client credential grants are supported. If client credentials exist in the environment, authentication will be performed automatically without the need to explicitly call this command.
| Long Flag | Short Flag | Description |
|---|---|---|
| –username | -u | Authentication username |
| –password | -p | Authentication password |
| –client-name | Client name for UAA client grant [$CREDHUB_CLIENT] | |
| –client-secret | Client secret for UAA client grant [$CREDHUB_SECRET] | |
| –server | -s | URI of API server to target [$CREDHUB_SERVER] |
| –ca-cert | Trusted CA for API and UAA TLS connections [$CREDHUB_CA_CERT] | |
| –skip-tls-validation | Skip certificate validation of the API endpoint. Not recommended! | |
| –sso | Prompt for a one-time passcode to login | |
| –sso-passcode | One-time passcode |
CredHub CLI
user$ credhub login -s https://10.0.0.6:8844 --client-name=some-name --client-secret=some-secret
Setting the target url: https://10.0.0.6:8844
Login Successful
Api
Get or set the CredHub API target where commands are sent. The api command without any flags will return the current target. If –ca-cert or –skip-tls-validation are provided, these preferences will be cached for future requests.
| Long Flag | Short Flag | Description |
|---|---|---|
| –server | -s | URI of API server to target [$CREDHUB_SERVER] |
| –ca-cert | Trusted CA for API and UAA TLS connections [$CREDHUB_CA_CERT] | |
| –skip-tls-validation | Skip certificate validation of the API endpoint. Not recommended! |
CredHub CLI
user$ credhub api --server https://10.0.0.6:8844
Setting the target url: https://10.0.0.6:8844
Logout
Discard authenticated session. Refresh token revocation will be attempted for password grants.
CredHub CLI
user$ credhub logout
Logout Successful
Interpolating Credentials
Fill a template with values returned from CredHub.
Uses double-paren placeholders in the style of the bosh cli. Example:
something-stored-in-credhub: ((path/to/var))
something-else: static value
In the above example, the whole value of the cred will be inserted.
If you want just the certificate value, you’d need to use ((path/to/var.certificate)), which would only have the specified field. Example:
certificate: ((path/to/var.certificate))
private_key: ((path/to/var.private_key))
If the prefix flag is provided, the given prefix will be prepended to any credentials that do not start with the ‘/’ character.
Note: There cannot be spaces inside the parentheses
| Long Flag | Short Flag | Description |
|---|---|---|
| –file | -f | Path to the file to interpolate |
| –prefix | -p | Prefix to be applied to credential paths. Will not be applied to paths that start with ‘/’ |
| –skip-missing | -s | allow skipping missing params |
CredHub CLI
user$ credhub interpolate -f /tmp/creds.yml
db-password: j8aej715TuQZGzQr8FBdnn5hQT2fOp
Import/Export Credentials
Bulk Export
CredHub CLI
user$ credhub export --file export.yml
This CLI command gets multiple credentials and exports them to either standard out, or a file. The output will be in yaml format, with the key credentials whose value is a list of credential objects. Each credential will contain a name, type and value. An example is shown to the right. This file is compatible with the bulk import process.
Use --file to specify a file to write the export to. Use --path to specify a path, which will restrict the credentials exported to those with a prefix matching the given path.
Bulk Import
CredHub CLI
user$ credhub import --file import.yml
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-ssh
type: ssh
value:
public_key: ssh-rsa AAAAB3NzaC1y...W9RWFM1
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z
id: 2ba73fbd-439e-40ef-b005-0e1db8815063
name: /example-password
type: password
value: SqFcE2c0AuRvet2YhrxdFbPtkBmjiq
version_created_at: 2017-01-01T04:07:28Z
id: 22a1e87b-ba0b-4bc9-bb26-4e5fc5fb1b2f
name: /example-value
type: value
value: sample
version_created_at: 2017-01-01T04:07:38Z
Import complete.
Successfully set: 3
Failed to set: 0
This CLI command sets multiple credentials from an import file. The import file must be in yaml format, with the key credentials whose value is a list of credential objects. Each credential must contain a name, type and value. An example is shown to the right.