Envelope Encryption

Overview

Bindplane implements envelope encryption to provide robust security for sensitive data while maintaining optimal performance. This document outlines the envelope encryption implementation in both Bindplane's hosted SaaS environment and self-hosted deployments.

NOTE

Envelope Encryption is enabled by default in the SaaS environment. For self-hosted installations, this feature requires explicit configuration.

Key Concepts and Terminology

Encryption Components

• DEK (Data Encryption Key): A symmetric encryption key generated per account that encrypts and decrypts customer data. DEKs are stored in encrypted form within the database.

• KEK (Key Encryption Key): A master key managed through Google Cloud KMS that encrypts and decrypts DEKs. Each project maintains its own KEK within the organization's key ring.

• Envelope Encryption: A security architecture where data is encrypted with a DEK, and the DEK itself is encrypted with a KEK. This approach provides enhanced security and flexible key management capabilities.

Google Cloud KMS Components

• KMS (Key Management Service): A managed service from Google Cloud that provides cryptographic key creation, storage, and control.

• Key Ring: A logical collection of cryptographic keys in Google Cloud KMS. Each Bindplane organization is assigned a dedicated key ring.

Bindplane Organizational Structure

• Organization: The highest-level entity in the Bindplane hierarchy, associated with a unique KMS key ring.

• Project: A logical container within an organization for grouping related resources. Organizations can contain multiple projects.

• Customer Secret: Any resource within Bindplane that may contain sensitive customer data, including Configurations, Sources, Destinations, and Snapshot Recordings.

Initial Setup Process

The system establishes a key ring for each organization and generates individual keys for each project within that organization. New projects automatically receive their own dedicated key.

Customer Secret Storage Flow

When objects that can contain customer secrets are stored, they are first encrypted with the project's DEK, which must be decrypted with the project's KEK. In order to provide good performance, the decrpyted DEK may be cached, but is never written to persistent disk.

Customer Secret Retrieval Flow

When retrieving objects that may contain customer sensitive data, the data must be decrypted using the project's DEK before the actual value can be used by the platform.

Hardware Security Module (HSM) Integration

Organizations can enhance their security posture by enabling HSM-backed keys for their projects' KEKs. This configuration is available through the Organization Settings interface by enabling the "Use Hardware Key Encryption" option. Upon activation, the system generates new KEKs and re-encrypts all DEKs using the HSM-backed keys.

NOTE

• HSM backed keys are more costly than Software backed keys.

• HSM keys can be toggled off, which will re-encrypt again with a Software backed key.

• This feature is only available to Bindplane Enterprise and Bindplane Enterprise (Google Edition) licenses.

Self-Hosted Encryption Implementation

For self-hosted Bindplane deployments version 1.91.2 or higher, encryption can be enabled by meeting the following requirements:

Prerequisites

• Google Cloud subscription with Google KMS APIs enabled

• Bindplane deployment setup with authentication to Google Cloud

• Service Account with Cloud KMS Admin role assigned.

NOTE

The Cloud KMS Admin role requirement enables Bindplane to perform essential key management operations, including creation, rotation, and deletion of keys and key rings, as well as encryption and decryption operations.

Configuration

To enable encryption in your self-hosted Bindplane environment, configure the encryption settings using one of the following methods:

Using YAML Configuration

Add the following configuration to your Bindplane server configuration YAML file:

store:
    encryptionProvider:
        type: googleKMS
        googleKMS:
            projectID: <projectID> (example: bindplane-dev)
            location: <location> (example:us)
            keyRotationPeriod: <rotation duration> (example: 720h)

Using Environment Variables

Alternatively, configure encryption using the following environment variables:

• BINDPLANE_ENCRYPTIONPROVIDER_TYPE

• BINDPLANE_ENCRYPTIONPROVIDER_GOOGLEKMS_PROJECTID

• BINDPLANE_ENCRYPTIONPROVIDER_GOOGLEKMS_LOCATION

• BINDPLANE_ENCRYPTIONPROVIDER_GOOGLEKMS_KEY_ROTATION_PERIOD