Using a Key Management Service with CredHub

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 the following 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 the following:

  • 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, follow the procedures in Creating a Release in the BOSH documentation.

Your BOSH release must run the plugin with a defined socket. You will need to 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 sample-credhub-kms-plugin-release 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, do the following:

  1. Create an ops file. See the following example that 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 the following BOSH CLI command:

    bosh -e MY-ENV log-in
    

    Where MY-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 the following command:

    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.
Create a pull request or raise an issue on the source for this page in GitHub