Using a key management service with CredHub

You can connect CredHub to a third party Key Management Service (KMS) using Kubernetes API.

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

To use a KMS, you must deploy a plug-in with CredHub. CredHub is compatible with plug-ins that implement the KMS provider interface that is 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’s not necessary to use Kubernetes when you write a plug-in. For more information, see Language Guide (proto3) in the Google Protocol Buffers documentation.

Any plug-in that implements the KMS provider interface can be compatible with CredHub. Consult the documentation for your KMS provider to learn if a plug-in exists.

If a plug-in exists for your KMS provider, see Building a BOSH release.
If a plug-in has not been created for your KMS provider, see Implementing the plug-in.

Implementing the plug-in

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

You must implement the following 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 plug-ins, see:

Plug-in that uses Base64 encoding for encryption in the sample-credhub-kms-plugin GitHub repository
Plug-in that connects to a fake KMS in the kubernetes GitHub repository

Building a BOSH release

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

To create a BOSH release for your plug-in, see Creating a release in the BOSH documentation.

Your BOSH release must run the plug-in 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 plug-in with a defined socket, see the sample-credhub-kms-plugin-release repository on GitHub.

Build and install a tile

To use the KMS plug-in with CredHub deployed with Tanzu Operations 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 Tanzu Operations Manager Installation Dashboard.

To build and install a tile:

Install the Tile Generator by doing one of these steps:
- Download the Tile Generator binary for your platform from the Operations 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.
Install the BOSH CLI. For more information, see Installing the CLI in the BOSH documentation.
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.

Modify the tile.yml as needed. At a minimum, you must enter the path to the BOSH release of the KMS plug-in 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 Operations 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 Operations Manager Tile Developer Guide.

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 plug-in into a tile, then places the tile file in the product subdirectory.
Go to Tanzu Operations Manager, log in, and add the tile to the Tanzu Operations Manager Installation Dashboard. For more information, see Adding and deleting products.
Click the tile and complete the configuration.
Return to the Tanzu Operations Manager Installation Dashboard. Click Review Pending Changes > Apply Changes to complete the installation.