CredHub Credential Types

Credential Types
Consuming CredHub Types in Releases
Enabling CredHub Automatic Generation in Releases

This topic describes the different credential types supported by CredHub.

CredHub supports different types of credentials to simplify generating and managing multi-part credentials. For example, a TLS certificate contains three parts: the root certificate authority (CA), the certificate, and the private key. CredHub supports all three parts, which helps keep connection requests from being rejected erroneously.

Credential Types

CredHub supports the following credential types:

Value

This type holds a single string value. Use this type for arbitrary configurations and other non-generated or validated strings.

Example:

 json
  {
    "name": "/example/value",
    "type": "value",
    "value": "/var/vcap/jobs/credhub/example.sh",
    "version_created_at": "2016-10-13T20:59:28Z"
  }

JSON

This type holds an arbitrary JSON object. Use this type for static configurations with many values, and when you find separating specific values into typed credentials to be inefficient.

Example:

json
  {
    "name": "/example/value",
    "type": "value",
    "value": {
      "key": 123,
      "key_list": [ "val1", "val2", "val3" ],
      "is_true": true
    },
    "version_created_at": "2016-10-13T20:59:28Z"
  }

Password

This type holds a single string value. Use this type for passwords and other random string credentials. Values for this type can be automatically generated.

Example:

json
  {
    "name": "/example/password",
    "type": "password",
    "value": "nZaowPHTl0CQYVyYA0nV7ayHVulCBU3WTmwJKiZm",
    "version_created_at": "2016-10-13T21:03:42Z"
  }

Certificate

This type holds an object containing a root CA, certificate, and private key. Use this type for key pair applications that utilize a certificate, such as TLS connections. Values for this type can be automatically generated.

Example:

json
  {
    "name": "/example/certificate",
    "type": "certificate",
    "value": {
      "ca": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
      "certificate": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
      "private_key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----"
    },
    "version_created_at": "2016-10-13T21:07:37Z"
  }

SSH

This type holds an object containing an SSH-formatted public key and private key. Use this type for key pairs that establish SSH connections. Values for this type can be automatically generated.

Example:

json
  {
    "name": "/example/ssh",
    "type": "ssh",
    "value": {
      "public_key": "ssh-rsa AAA...PLx user@location",
      "private_key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----"
    },
    "version_created_at": "2016-10-13T21:10:44Z"
  }

RSA

This type holds an object containing an RSA public key and private key. Use this type for RSA key pairs without certificates. Values for this type can be automatically generated.

Example:

json
  {
    "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": "2016-10-13T21:13:41Z"
  }

Consuming CredHub Types in Releases

The BOSH Director interpolates the key value from the credential response for a deployment variable.

For example, in a deployment containing the password credential referenced above, BOSH substitutes "nZaowPHTl0CQYVyYA0nV7ayHVulCBU3WTmwJKiZm" for the variable. The behavior is similar for other credential types as well. For example, if the certificate credential is referenced above, BOSH substitutes the object below:

json
{
  "ca": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "certificate": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----"
}

Similarly, the object could be translated into yaml:

yaml
  ca: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE------
  certificate: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE------
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY------

If you want to leverage a non-string typed credential, update your release to properly consume the new format. The following example shows how to configure a release to accept the certificate credential referenced above. It includes an example to instruct users on how to define the values if they are not using a CredHub credential.

Release Job Spec

yml
---
name: demo

properties:
  demo.tls:
    description: "Certificate and private key for TLS connection to API"
    example: |
        ca: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
        certificate: | 
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
        private_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ...
          -----END RSA PRIVATE KEY-----

Job Template ERB

erb
api-ca=demo.tls.ca
api-certificate=demo.tls.certificate
api-private-key=demo.tls.private_key

Deployment Manifest

yml
---
name: demo-deploy

instance_groups:
  properties:
    demo:
      tls: ((demo-tls))

Updating a release for other types is similar to the example above, being mindful of the key name for each value you wish to consume.

Enabling CredHub Automatic Generation in Releases

CredHub and BOSH are integrated to automatically generate missing credential values on deployment. To enable automatic generation, the release or manifest requires the correct configuration.

The sample below demonstrates how to configure a job release spec to provide generation parameters. When you provide details in a release spec, use attributes that do not vary per deployment, such as type and password attributes.

Release Job Spec

yml
---
name: demo

properties:
  demo.admin_password: 
    description: "Password for admin user"
    type: password
    parameters: 
      length: 40

  demo.tls:
    description: "Certificate and private key for TLS connection to API"
    type: certificate
    parameters: 
      key_length: 4096

You can also define these generation parameters in the deployment itself, as shown in the example below. Use this for generation parameters that are deployment-specific, such as a certificate common name.

Deployment Manifest

yml
---
name: demo-deploy

variables: 
- name: demo-password
  type: password
  options: 
    length: 40
- name: demo-ca
  type: certificate
  options: 
    is_ca: true
    common_name: 'Demo Certificate Authority'
- name: demo-tls
  type: certificate
  options: 
    ca: demo-ca
    common_name: example.com
    alternative_names: 
    - example.com
    - www.example.com
    extended_key_usage: 
    - client_auth

instance_groups:
  properties:
    demo:
      admin-password: ((demo-password))
      tls: ((demo-tls))

Create a pull request or raise an issue on the source for this page in GitHub