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.

Deploy CredHub with Your Plugin Release

To deploy CredHub with your plugin, you must modify the CredHub BOSH manifest to include the new encryption provider and keys.

You can modify the CredHub BOSH manifest using an ops file. An ops file is a YAML file that includes multiple operations to be applied to a different YAML file, such as a manifest. For more information about how to create an ops file, see Creating Ops Files in the BOSH documentation.

To deploy CredHub with your plugin:

1. Create an ops file. This example modifies the CredHub BOSH manifest to work with sample-credhub-kms-plugin:

   ---
   - type: replace
     path: /releases/-
     value:
       name: sample-credhub-kms-plugin
       version: latest
   
   - type: replace
     path: /instance_groups/name=credhub/jobs/name=credhub/properties/credhub/encryption/keys/-
     value:
       provider_name: sample
       key_properties:
         encryption_key_name: VALUE
       active: true
   
   - type: replace
     path: /instance_groups/name=credhub/jobs/name=credhub/properties/credhub/encryption/providers/-
     value:
       name: sample
       type: kms-plugin
       connection_properties:
         endpoint: /var/vcap/sys/run/kms-plugin/kms-plugin.sock
   
   - type: replace
     path: /instance_groups/name=credhub/jobs/-
     value:
       name: kms-plugin
       release: sample-credhub-kms-plugin
       properties:
         kms-plugin:
           socket_endpoint: /var/vcap/sys/run/kms-plugin/kms-plugin.sock
   
   - type: replace
     path: /instance_groups/name=credhub/jobs/name=credhub/properties/credhub/encryption/keys/provider_name=int/active
     value: false
   

   Where VALUE is your encryption key name.

2. To log in to your BOSH Director, run:

   bosh -e ENV log-in
   

   Where ENV is the name of your BOSH Director environment. For more information, see Commands in the BOSH documentation.

3. To deploy your CredHub with the plugin, run:

   bosh -d DEPLOYMENT-NAME credhub-manifest.yml -o OPS-FILE.yml
   

   Where:

   • DEPLOYMENT-NAME is the name of your CredHub BOSH deployment.
   • OPS-FILE is the name of your ops file.