📘

Enterprise Feature

Bring Your Own Key is available on the Scalr enterprise plan.

Introduction

Bring Your Own Key (BYOK) lets you supply your own KMS key to encrypt data stored in Scalr's database: workspace names, variables, provider configurations, and other account metadata. It does not apply to Terraform or OpenTofu state files.

If your goal is to control how your state files are encrypted, use storage profiles instead. Storage profiles redirect state files, run artifacts, and audit logs to a bucket in your own AWS, GCP, or Azure account, where your existing bucket-level encryption and key management policies apply.

BYOK and storage profiles address different concerns and can be used together: BYOK protects your configuration metadata in Scalr's database, while storage profiles give you ownership of where state lives and how it's encrypted.

Overview

Scalr uses a process called envelope encryption. Sensitive data is encrypted with a per-account data encryption key (DEK), which is encrypted (wrapped) with a key encryption key (KEK) from your KMS service. To encrypt or decrypt sensitive data, Scalr calls your KMS to decrypt the DEK then uses it to encrypt or decrypt your data. The KEK never leaves your KMS, Scalr only calls the KMS API to wrap and unwrap the data key as needed.

The DEK is a random 256-bit string that Scalr generates locally when you enable BYOK and encrypts with your KMS. Data is encrypted with the DEK using the AES-256-GCM algorithm.

Revoking your KMS key immediately prevents Scalr from accessing that account's encrypted data.

❗️

Warning

Do not disable or delete your KMS key, or revoke Scalr's access to it, while BYOK is active. If the key becomes inaccessible, Scalr cannot decrypt account data and operations will fail.

Supported Cloud Providers

Enabling BYOK

1. Set up a KMS key with the required permissions in your cloud provider (see provider-specific guides).
2. In Scalr, go to Account Settings > Security > Encryption.
3. Click Enable and select your KMS provider.
4. Fill in the key details and credentials.
5. Scalr verifies access to the key before saving. If the key cannot be reached, the configuration will not be saved.

Disabling BYOK

To disable BYOK, go to Account Settings > Security > Encryption and click Disable. Scalr will re-encrypt the account data key under Scalr's own key. Your KMS key will no longer be used.