# 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/diagram content="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/diagram content="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/diagram content="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 %}
### 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: (example: bindplane-dev)
location: (example:us)
keyRotationPeriod: (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`
