Using a Key Management Service with CredHub

Page last updated:

This topic describes how to connect CredHub to a third-party Key Management Service (KMS) using the Kubernetes API.

Overview

CredHub includes its own internal encryption. However, you may want to use the encryption provided by a KMS instead.

To use a KMS, you must deploy a plugin with CredHub. CredHub is compatible with plugins that implement the KMS provider interface defined in the protobuf format. For more information, see Using a KMS provider for data encryption in the Kubernetes documentation.

The KMS interface comes from Kubernetes, but it is not necessary to use Kubernetes when writing a plugin. For more information, see Language Guide (proto3) in the Google Protocol Buffers documentation.

Any plugin that implements the KMS provider interface should be compatible with CredHub. Consult the documentation for your KMS provider to learn if a plugin exists.

Implement the Plugin

You can implement the KeyManagementService interface in any language. The example below is written in Go. For more information about the KeyManagementService interface, see the sample-credhub-kms-plugin repository on GitHub.

You must implement these three methods:

// This service defines the public APIs for remote KMS provider.
service KeyManagementService {
  // Version returns the runtime name and runtime version of the KMS provider.
  rpc Version(VersionRequest) returns (VersionResponse) {}

  // Execute decryption operation in KMS provider.
  rpc Decrypt(DecryptRequest) returns (DecryptResponse) {}

  // Execute encryption operation in KMS provider.
  rpc Encrypt(EncryptRequest) returns (EncryptResponse) {}
}

For sample plugins, see:

  • Plugin that uses Base64 encoding for encryption in the sample-credhub-kms-plugin GitHub repository

  • Plugin that connects to a fake KMS in the kubernetes GitHub repository

Build a BOSH Release

Because CredHub is deployed using BOSH, you must deploy the plugin as a BOSH release on the same instance group as CredHub.

To create a BOSH release for your plugin, see Creating a Release in the BOSH documentation.

Your BOSH release must run the plugin with a defined socket. You must reference this socket in your CredHub BOSH manifest.

For an example of a BOSH release of a CredHub KMS plugin with a defined socket, see the sample-credhub-kms-plugin-release repository on GitHub.

Build and Install a Tile

To use the KMS plugin with CredHub deployed with Ops Manager or VMware Tanzu Application Service for VMs (TAS for VMs), you must wrap your BOSH release in a tile and install it on the Ops Manager Installation Dashboard.

To build and install a tile:

  1. Install the Tile Generator by doing one of these steps:

    • Download the Tile Generator binary for your platform from the Ops Manager Tile Generator repository on GitHub, then make it executable and available by running:

      chmod +x TILE-BINARY
mv TILE-BINARY /usr/local/bin/tile

      Where: TILE-BINARY is the name of the tile binary file.

    • Use Python 2 and Virtualenv. VMware recommends that you use a virtualenv environment to avoid conflicts with other Python packages. A virtualenv is a directory containing dependencies for a project. When a virtual environment is active, packages install into the virtualenv instead of the system-wide Python installation.

      To use this method, run:

      virtualenv -p python2 tile-generator-env
source tile-generator-env/bin/activate
pip install tile-generator

      This puts the tile and pcf commands in your PATH when the virtualenv is active. To deactivate the virtualenv, run the command deactivate. To upgrade Tile Generator, run pip install tile-generator --upgrade with the virtualenv activated.

  2. Install the BOSH CLI. For more information, see Installing the CLI in the BOSH documentation.

  3. From within the root directory of the project for which you want to create a tile, initialize the directory as a tile repository by running:

    tile init

    This command generates a tile.yml file. This file defines the configuration for your tile.

  4. Modify the tile.yml as needed. At a minimum, you must enter the path to the BOSH release of the KMS plugin on your local machine in packages: path. The example tile.yml file below defines a tile named Sample CredHub KMS Plugin that enables the operator to configure the socket endpoint where the plugin listen for CredHub:

    ---
name: sample-credhub-kms-plugin-tile
icon_file: icon.png
label: Sample CredHub KMS Plugin
description: Sample CredHub KMS Plugin

packages:
- name: my-release-name
  type: bosh-release
  path: releases/MY-BOSH-RELEASE.tgz

forms:
- name: plugin-properties
  label: Plugin Properties
  description: Configure your plugin
  properties:
  - name: socket_endpoint
    type: string
    label: Socket Endpoint

runtime_configs:
- name: some-runtime-config
  runtime_config:
    releases:
    - name: my-release-name
      version: "my-release-version"
    addons:
    - name: some-addon-name
      jobs:
      - name: my-job-name
        release: my-release-name
        properties:
          socket_endpoint: (( .properties.socket_endpoint ))
      include:
        jobs:
        - name: credhub
          release: credhub

    For general information about writing the tile.yml file, see Define Your Tile in tile.yml in Tile Generator in the Ops Manager Tile Developer Guide. For information about enabling operators to use the tile to configure arbitrary properties in the manifest, see Custom Forms and Properties in Tile Generator in the Ops Manager Tile Developer Guide.

  5. In the directory that contains the tile.yml file, build the tile by running:

    tile build

    The tile generator wraps the BOSH release of the KMS plugin into a tile, then places the tile file in the product subdirectory.

  6. Navigate to Ops Manager, log in, and add the tile to the Ops Manager Installation Dashboard. For more information, see Adding and Deleting Products.

  7. Click the tile and complete the configuration.

  8. Return to the Ops Manager Installation Dashboard. Click Review Pending Changes, then Apply Changes to complete the installation.