Using a key management service with CredHub

Page last updated:

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.

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.

Deploying CredHub with your plug-in release

To deploy CredHub with your plug-in, 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, for example, 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 plug-in:

  1. Create an ops file. The following 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 plug-in, 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.
Create a pull request or raise an issue on the source for this page in GitHub