> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/production-checklist/bindplane/secrets-management/envelope-encryption.md).

# 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 Cloud environment and self-hosted deployments.

{% hint style="info" %}
**NOTE**

Envelope Encryption is enabled by default in the Cloud environment. For self-hosted installations, this feature requires explicit configuration.
{% endhint %}

#### 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.

```mermaid
sequenceDiagram
    participant BP as Bindplane Cloud
    participant KMS as Google Cloud KMS
    participant PG as Database

    Note over BP,KMS: Organization Setup
    BP->>KMS: Create Key Ring for Organization
    KMS-->>BP: Organization Key Ring Created

    Note over BP,KMS: Account Setup (per account in organization)
    loop For each Account
        BP->>KMS: Create KEK for Account
        KMS-->>BP: Account KEK Ready
        BP->>BP: Generate DEK for Account
        BP->>KMS: Encrypt DEK with Account KEK
        KMS-->>BP: Return encrypted DEK
        BP->>PG: Store encrypted DEK for Account
    end

    Note over BP,KMS: Setup Complete - Ready for Customer Secrets
```

#### 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.

```mermaid
sequenceDiagram
    participant Client as Client Application
    participant BP as Bindplane Cloud
    participant Redis as Cache
    participant PG as Database
    participant KMS as Google Cloud KMS

    Client->>BP: Store Customer Secret (Account Context)

    alt Account DEK not in cache
        BP->>Redis: Check for cached Account DEK
        Redis-->>BP: Account DEK not found

        BP->>PG: Query for encrypted Account DEK
        PG-->>BP: Return encrypted Account DEK
        BP->>KMS: Decrypt Account DEK using Account KEK
        KMS-->>BP: Return plaintext Account DEK

        BP->>Redis: Cache plaintext Account DEK
        Redis-->>BP: Account DEK cached
    else Account DEK in cache
        BP->>Redis: Retrieve cached Account DEK
        Redis-->>BP: Return plaintext Account DEK
    end

    BP->>BP: Encrypt customer secret with Account DEK
    BP->>PG: Store encrypted customer secret
    PG-->>BP: Secret stored
    BP-->>Client: Success response
```

#### 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.

```mermaid
sequenceDiagram
    participant Client as Client Application
    participant BP as Bindplane SaaS
    participant Redis as Cache
    participant PG as Database
    participant KMS as Google Cloud KMS

    Client->>BP: Retrieve Customer Secret (Account Context)

    alt Account DEK in cache
        BP->>Redis: Get cached Account DEK
        Redis-->>BP: Return plaintext Account DEK
    else Account DEK not in cache
        BP->>PG: Query for encrypted Account DEK
        PG-->>BP: Return encrypted Account DEK
        BP->>KMS: Decrypt Account DEK using Account KEK
        KMS-->>BP: Return plaintext Account DEK
        BP->>Redis: Cache plaintext Account DEK
        Redis-->>BP: Account DEK cached
    end

    BP->>PG: Retrieve encrypted customer secret
    PG-->>BP: Return encrypted secret
    BP->>BP: Decrypt secret using Account DEK
    BP-->>Client: Return plaintext secret
```

### 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.

{% hint style="info" %}
**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.
  {% endhint %}

<figure><img src="/files/GUFH7X0Nl6N5XHwZG2ti" alt="Bindplane docs - Envelope Encryption - image 1"><figcaption></figcaption></figure>

### 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.

{% hint style="info" %}
**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.
{% endhint %}

#### 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:

```yaml
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`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bindplane.com/production-checklist/bindplane/secrets-management/envelope-encryption.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.