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.
If a plugin exists for your KMS provider, see Build a BOSH Release.
If a plugin has not been created for your KMS provider, see Implement the Plugin.
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:
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. Avirtualenv
is a directory containing dependencies for a project. When a virtual environment is active, packages install into thevirtualenv
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
andpcf
commands in yourPATH
when thevirtualenv
is active. To deactivate thevirtualenv
, run the commanddeactivate
. To upgrade Tile Generator, runpip install tile-generator --upgrade
with thevirtualenv
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 plugin on your local machine inpackages: path
. The exampletile.yml
file below defines a tile namedSample 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.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.Navigate to Ops Manager, log in, and add the tile to the Ops Manager Installation Dashboard. For more information, see Adding and Deleting Products.
Click the tile and complete the configuration.
Return to the Ops Manager Installation Dashboard. Click Review Pending Changes, then Apply Changes to complete the installation.